A Secret is a collection of private data for use by one or more jobs. In order to maintain the security of the data, the values are usually encrypted, however, data which are not sensitive may be provided unencrypted as well for convenience.
A Secret may only be used by jobs defined within the same project. Note that they can be used by any branch of that project, so if a project’s branches have different access controls, consider whether all branches of that project are equally trusted before using secrets.
To use a secret, a Job must specify the secret in job.secrets. With one exception, secrets are bound to the playbooks associated with the specific job definition where they were declared. Additional pre or post playbooks which appear in child jobs will not have access to the secrets, nor will playbooks which override the main playbook (if any) of the job which declared the secret. This protects against jobs in other repositories declaring a job with a secret as a parent and then exposing that secret.
The exception to the above is if the job.secrets.pass-to-parent attribute is set to true. In that case, the secret is made available not only to the playbooks in the current job definition, but to all playbooks in all parent jobs as well. This allows for jobs which are designed to work with secrets while leaving it up to child jobs to actually supply the secret. Use this option with care, as it may allow the authors of parent jobs to accidentially or intentionally expose secrets. If a secret with pass-to-parent set in a child job has the same name as a secret available to a parent job’s playbook, the secret in the child job will not override the parent, instead it will simply not be available to that playbook (but will remain available to others).
It is possible to use secrets for jobs defined in config
projects as well as untrusted projects, however their use differs slightly. Because
playbooks in a config project which use secrets run in the
trusted execution context where proposed changes are not used
in executing jobs, it is safe for those secrets to be used in all
types of pipelines. However, because playbooks defined in an
untrusted project are run in the untrusted execution context
where proposed changes are used in job execution, it is dangerous to
allow those secrets to be used in pipelines which are used to execute
proposed but unreviewed changes. By default, pipelines are considered
pre-review and will refuse to run jobs which have playbooks that use
secrets in the untrusted execution context (including those subject to
job.secrets.pass-to-parent secrets) in order to protect
against someone proposing a change which exposes a secret. To permit
this (for instance, in a pipeline which only runs after code review),
the pipeline.post-review attribute may be explicitly set to
In some cases, it may be desirable to prevent a job which is defined
in a config project from running in a pre-review pipeline (e.g., a job
used to publish an artifact). In these cases, the
job.post-review attribute may be explicitly set to
indicate the job should only run in post-review pipelines.
If a job with secrets is unsafe to be used by other projects, the job.allowed-projects attribute can be used to restrict the projects which can invoke that job. If a job with secrets is defined in an untrusted-project, allowed-projects is automatically set to that project only, and can not be overridden (though a config-project may still add the job to any project’s pipeline regardless of this setting; do so with caution as other projects may expose the source project’s secrets).
Secrets, like most configuration items, are unique within a tenant, though a secret may be defined on multiple branches of the same project as long as the contents are the same. This is to aid in branch maintenance, so that creating a new branch based on an existing branch will not immediately produce a configuration error.
The following attributes must appear on a secret: