Secrets

Crow CI provides an integrated secret store. These secrets can be passed securely to individual steps using the from_secret keyword.

Secrets List/Creation Dialog

Levels

Three different levels of secrets are available:

1. Repository secrets: Available to all workflows of a repository.
2. Organization secrets: Available to all workflows of an organization.
3. Global secrets: Global secret are available to all pipelines of the entire Crow CI instance. Can only be set by instance administrators.

Note

If a secret is defined at multiple levels, repository secrets take precedence over organization secrets, which in turn override global secrets, following this hierarchy.

Tip

In addition to native secrets, Crow CI supports external secret store integrations such as HashiCorp Vault and OpenBao. These allow you to fetch secrets directly from your existing secret management infrastructure during pipeline execution.

Note

Crow CI automatically masks both native secrets and external secrets (from integrations like Vault) in the log output.

Defining secrets

Secrets are defined using the from_secret: keyword in the environment: section:

steps:
  - name: 'step name'
    image: registry/repo/image:tag
    commands:
      - echo "The secret is $TOKEN_ENV"
    environment:
      TOKEN_ENV:
        from_secret: secret_token

Secrets names can be uppercase or lowercase. The same applies to the environment variables they are assigned to.

Secrets can also be used for settings: in plugins:

steps:
  - name: 'step name'
    image: registry/repo/image:tag
    commands:
      - echo "The secret is $TOKEN_ENV"
    settings:
      TOKEN:
        from_secret: secret_token

Caution

Parameter expressions like secrets undergo pre-processing, meaning they are evaluated before the workflow starts. If secrets are to be used in commands directly, they must be properly escaped (using $$) to ensure correct handling.

steps:
  - name: docker
    image: docker
    commands:
      - echo $${TOKEN_ENV}
    environment:
      TOKEN_ENV:
        from_secret: secret_token

Filtering

To prevent secrets from potential abuse in arbitrary steps, they can be limited to specific plugins in the repository settings.

Plugins offer the advantage of not being able to execute arbitrary commands (in contrast to normal steps), and by this inherently prohibit the possibility of exposing secrets in any kind of way.

Caution

Filtering only works for plugins, not for arbitrary images. Applying it to the latter would not make sense as malicious actors could simply use the specified image to exploit the secret.

Adding secrets via CLI

Secrets can also be added via the CLI.

By default, secrets will be available without any restriction:

crow-cli repo secret add \
  --repository octocat/hello-world \
  --name my_secret \
  --value <value>

Limit it to a specific plugin:

crow-cli secret add \
  --repository octocat/hello-world \
  --image woodpeckerci/plugin-s3 \
  --name aws_access_key_id \
  --value <value>

The --image can also be passed multiple times.

Limit to specific events:

crow-cli repo secret add \
  --repository octocat/hello-world \
  --image woodpeckerci/plugin-s3 \
  --event pull_request \
  --event push \
  --event tag \
  --name aws_access_key_id \
  --value <value>

Secret can also be loaded from a file on disk. This can be useful for multi-line secrets like SSH keys:

crow-cli repo secret add \
  --repository octocat/hello-world \
  --name ssh_key \
  --value @/root/ssh/id_rsa

Sharing secrets across repos and orgs

A secret can be shared with multiple repositories and organizations without duplicating its value. Every secret has a single first owner — the repo, org, or global scope where it was originally created. Additional repos and orgs can be added as sharing targets, granting them read access to the secret during pipeline execution.

Resolution priority

When a pipeline resolves secrets, the following priority order applies (highest first):

1. Repository-level secrets
2. Organization-level secrets
3. Global secrets
4. Shared secrets

If a repo has its own secret named DEPLOY_KEY and also receives a shared secret with the same name, the repo’s own secret takes precedence.

Conflict prevention

The system prevents assigning two different secrets with the same name to the same repo or org. If you attempt to share a second secret whose name conflicts with an already-shared (or natively owned) secret at that target, the request will be rejected.

Ownership transfer

The first owner of a secret can be transferred to any other repo or org. When transferring ownership, the previous owner can optionally be retained as a sharing target so it keeps access to the secret.

API reference

The following API endpoints manage secret sharing:

Method	Path	Description
GET	/api/v1/secret-targets/{secret_id}/targets	List all sharing targets for a secret
POST	/api/v1/secret-targets/{secret_id}/targets	Share a secret with a repo or org
DELETE	/api/v1/secret-targets/{secret_id}/targets/{target_id}	Remove a sharing target
PATCH	/api/v1/secret-targets/{secret_id}/owner	Transfer ownership to another repo or org