# Secrets

Copia Actions supports **secrets** for sensitive information like API keys, tokens, and passwords.

## Secrets

Secrets store sensitive information that should not be exposed in logs or workflow files. Common uses include API keys, database passwords, registry credentials, and access tokens.

Secrets are encrypted at rest and are masked in job logs — if a secret value appears in the log output, it is replaced with `***`.

### Creating Secrets

{% stepper %}
{% step %}

### Organization level

Go to your organization on Copia, then **Settings > Actions > Secrets**. These secrets are available to all repositories in the organization. Your account must have Owner permissions in order to view or modify Org-level secrets.
{% endstep %}

{% step %}

### Repository level

Go to your repository, then **Settings > Actions > Secrets**. These secrets are available only to workflows in that repository. Your account must have Admin permissions for the repository in order to view or modify repo-level Secrets.
{% endstep %}
{% endstepper %}

<figure><img src="/files/7WjSzFWposU5H0IkY9MS" alt=""><figcaption></figcaption></figure>

### Naming Rules

Secret names follow the same rules as variable names:

* Only alphanumeric characters and underscores. No spaces.
* Must not start with a number.
* Must not start with `COPIA_`, `GITHUB_`, `GITEA_`, or `CI`.
* Case-insensitive.
* Must be unique at the level where they are created.

### Using Secrets in Workflows

{% code title="workflow example" %}

```yaml
steps:
  - name: Deploy with API key
    run: ./deploy.sh
    env:
      API_KEY: ${{ secrets.DEPLOY_API_KEY }}
```

{% endcode %}

{% hint style="danger" %}
Security note: Never echo or print secrets directly in your workflow steps. While Copia masks known secret values in logs, derived values (such as substrings or encoded forms of a secret) may not be masked.
{% endhint %}

### Precedence

If a secret with the same name exists at both the organization and repository level, the **repository-level** secret takes precedence.

## Best Practices

* Use secrets for anything sensitive. API keys, tokens, passwords, and certificates should always be stored as secrets, not variables. Never hard-code sensitive values in workflow files.
* Use variables for environment-specific configuration. Values like deployment targets, feature flags, and non-sensitive URLs are good candidates for variables.
* Prefer repository-level scope when possible. This limits exposure and makes it clear which repositories depend on which configuration values.
* Rotate secrets regularly. If a secret may have been exposed (for example, through a misconfigured workflow step), replace it immediately.
* Name consistently. Use a clear naming convention like `DEPLOY_API_KEY`, `STAGING_DB_URL`, or `REGISTRY_PASSWORD` so that the purpose is obvious.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.copia.io/docs/actions/secrets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.