Configuration (.github/deploy.yml)

Deliverybot controls deployments based on a configuration file. Targets are the top level resource for this file which house configuration to trigger a list of deployments depending on specific conditions. Documentation for those conditions and fields is provided below.

Deliverybot only reads .github/deploy.yml; other paths such as .github/deploy.yaml are ignored.

# .github/deploy.yml
production:
  environment: name 

• <target>.auto_deploy_on
• <target>.transient_environment
• <target>.production_environment
• <target>.required_contexts
• <target>.environment
• <target>.description
• <target>.task
• <target>.auto_merge
• <target>.payload

<target>.auto_deploy_on

Deploys automatically when a push matches this ref. Use the full ref name, such as refs/heads/master for a branch or refs/tags/v1.0.0 for a tag; a short name like master never matches.

# .github/deploy.yml
production:
  auto_deploy_on: refs/heads/master

The ref is matched as a glob. A * matches any characters, ? matches a single character and [0-9] matches one character from a set ([^0-9] one character outside it). So refs/tags/* deploys every tag, refs/heads/* deploys every branch and refs/tags/v*-rc* deploys release candidate tags such as v1.2.0-rc1:

  auto_deploy_on: refs/tags/v*-rc*

It also takes a list of patterns. A ref deploys when it matches any pattern, unless it matches a pattern starting with !. This deploys every version tag except release candidates:

  auto_deploy_on:
    - refs/tags/v*
    - "!refs/tags/v*-rc*"

To deploy when a release is published, match its tag. Publishing a release with a new tag pushes that tag, so refs/tags/* (or a narrower pattern) deploys it.

Set it to pr to deploy automatically when a pull request is opened and on every push to it.

An automatic deployment waits for the required_contexts to pass. If a newer commit is pushed to the ref in the meantime, only the newer commit is deployed.

Automatic deployments use the deploy.yml on the repository’s default branch, both to decide which targets deploy and for the target’s settings. A branch that adds or changes an automatic target only takes effect once it is merged. Manual deployments from the dashboard or a /deploy comment use the deploy.yml on the branch being deployed.

Anyone who can push a branch can also change its deploy.yml and deploy it by hand, so don’t rely on deploy.yml alone to protect production. When your deployments run in GitHub Actions, give the deploy job its environment and add environment protection rules, such as required reviewers or allowed deployment branches, to the environments that matter.

<target>.transient_environment

Specifies if the given environment is specific to the deployment and will no longer exist at some point in the future. Default: false

If this value is true, Deliverybot marks the deployments of a pull request inactive when the pull request is closed.

<target>.production_environment

Specifies if the given environment is one that end-users directly interact with. Default: false

<target>.required_contexts

The commit statuses and check runs that must pass before GitHub accepts the deployment, for example ["ci"]. Default: [], which means nothing is checked and every deployment goes out straight away.

Automatic deployments wait until these pass. A manual deployment from the dashboard or a /deploy comment is refused while they haven’t passed; the dashboard’s Force option deploys anyway.

<target>.environment

The name of the environment to deploy to (e.g., staging or production). It can use variables. Default: production

<target>.description

A short description shown with the deployment on GitHub. It can use variables. Default: none

<target>.task

The name of the task for the deployment (e.g., deploy or deploy:migrations). Default: deploy

<target>.auto_merge

Attempts to automatically merge the default branch into the requested ref, if it’s behind the default branch. Default: false

<target>.payload

Payload with extra information about the deployment. It can use variables. Deliverybot always adds a target field with the target’s name. Default: {}

Variables

The following variables are available using ${{ }} syntax when evaluating deployment targets:

• ref: The ref being deployed: the branch name for a /deploy comment, the pushed ref (such as refs/heads/master) for an automatic deployment (heads/<branch> with auto_deploy_on: pr), or the commit sha for a deployment from the dashboard.
• short_sha: Short git sha. The full sha is commit.sha.
• pr: Pr number, if this deployment is kicked off in a PR.
• target: Current target name.
• owner: Owner name.
• repo: Repo name.
• pull_request: GitHub pull request object.
• commit: GitHub commit object.

An example usage of this:

# .github/deploy.yml
review:
  # Dynamic environment name. The environment will look like pr123.
  environment: pr${{ pr }}