Branch Deploy Action 🚀

A GitHub Action to enable branch deployments using IssueOps!

ship-it

This Action does the heavy lifting for you to enable branch deployments:

🔍 Detects when IssueOps commands are used on a pull request
✏️ Configurable - Choose your command syntax, environment, noop trigger, base branch, reaction, and more
✔️ Respects your branch protection settings configured for the repo
🗨️ Comments and reacts to your IssueOps commands
🚀 Triggers GitHub deployments for you with simple configuration
🔓 Deploy locks to prevent multiple deployments from clashing

Available Commands 💬

.deploy - Deploy a pull request
.noop - Deploy a pull request in noop mode
.deploy to <environment> - Deploy a pull request to a specific environment
.deploy <stable_branch> - Trigger a rollback deploy to your stable branch (main, master, etc)
.lock - Create a deployment lock for the default environment
.lock --reason <text> - Create a deployment lock for the default environment with a custom reason
.lock --details - View details about a deployment lock
.lock <environment> - Create a deployment lock for a specific environment
.lock --global - Create a global deployment lock
.unlock - Remove a deployment lock
.unlock <environment> - Remove a deployment lock for a specific environment
.unlock --global - Remove a global deployment lock
.help - Get help with IssueOps commands with this Action

These commands are all fully customizable and are just an example using this Action's defaults

For the full command usage, check out the usage document

Alternate command syntax and shortcuts can be found at the bottom of this readme here

Demo 🎥

A video demo showing how IssueOps on a pull request works using this Action

https://github.com/github/branch-deploy/assets/23362539/887cb1d3-e600-4d4c-ae0a-959b206e4513

Turbo Quickstart ⚡

A quick section to get you started with this Action

Usage 📝

Basic usage assuming all defaults:

- name: branch-deploy
  id: branch-deploy
  uses: github/branch-deploy@vX.X.X

Advanced usage with custom configuration:

- name: branch-deploy
  id: branch-deploy
  uses: github/branch-deploy@vX.X.X
  with:
    trigger: ".deploy"
    noop_trigger: ".noop"
    reaction: "eyes"
    environment: "production"
    stable_branch: "main"

Example 📚

Check out a super simple workflow example using this Action to quickly get up and running with branch deployments

name: "branch deploy demo"

# The workflow to execute on is comments that are newly created
on:
  issue_comment:
    types: [created]

# Permissions needed for reacting and adding comments for IssueOps commands
permissions:
  pull-requests: write
  deployments: write
  contents: write
  checks: read
  statuses: read

jobs:
  demo:
    if: ${{ github.event.issue.pull_request }} # only run on pull request comments
    runs-on: ubuntu-latest
    steps:
      # Execute IssueOps branch deployment logic, hooray!
      # This will be used to "gate" all future steps below and conditionally trigger steps/deployments
      - uses: github/branch-deploy@vX.X.X
        id: branch-deploy
        with:
          trigger: ".deploy"

      # Run your deployment logic for your project here - examples seen below

      # Checkout your projects repository based on the ref provided by the branch-deploy step
      - uses: actions/checkout@v4
        with:
          ref: ${{ steps.branch-deploy.outputs.ref }}

      # Do some fake "noop" deployment logic here
      # conditionally run a noop deployment
      - name: fake noop deploy
        if: ${{ steps.branch-deploy.outputs.continue == 'true' && steps.branch-deploy.outputs.noop == 'true' }}
        run: echo "I am doing a fake noop deploy"

      # Do some fake "regular" deployment logic here
      # conditionally run a regular deployment
      - name: fake regular deploy
        if: ${{ steps.branch-deploy.outputs.continue == 'true' && steps.branch-deploy.outputs.noop != 'true' }}
        run: echo "I am doing a fake regular deploy"

Keep reading to learn more about this Action! Even further details about how this Action works can be found below as well

You can check out further examples by checking out our examples documentation

About 💡

Before we get into details, let's first define a few key terms below:

IssueOps - Its like ChatOps but instead of using a chat bot, commands are invoked by commenting on a pull request (PRs are issues under the hood) - Example: commenting .deploy on a pull request
Branch Deployment - A branch deploy is a deployment methodology that enables you to deploy a branch (or pull request) to a desired environment before merging to main or master - More on this below
PR - Short for pull request

IssueOps 🗨️

The best way to define IssueOps is to compare it to something similar, ChatOps. You may be familiar with the concept ChatOps already but in case you aren't here is a quick definition below:

ChatOps is the process of interacting with a chat bot to execute commands directly in a chat platform. For example, with ChatOps you might do something like .ping example.org to check the status of a website

IssueOps adopts the same mindset but through a different medium. Rather than using a chat service to invoke the commands we use comments on a GitHub Issue or Pull Request. GitHub Actions is the runtime which executes our desired logic

Branch Deployments 🌲

Branch deployments are a battle tested way of deploying your changes to a given environment for a variety of reasons. Branch deployments allow you to do the following:

Deploy your changes to production before merging
Deploy changes to a staging, QA, or non-production environment

Branch Deployment Core Concepts ⭐

Note: The main branch is considered the base repository branch for all examples below

The main branch is always considered to be a stable and deployable branch
All changes are deployed to production before they are merged to the main branch
To roll back a branch deployment, you deploy the main branch
noop deployments should not make changes but rather report what they "would" have done

Why use branch deployments?

To put the merge -> deploy model in the past!

What if your changes are bad and you broke production with the merge -> deploy model? Well now you have to revert your PR, get passing CI/builds, and then re-merge your changes to get back to a stable environment. With the branch deploy model, this is almost never the case. The main branch is considered to be always safe and stable

How does it work? 📚

This section will go into detail about how this Action works and hopefully inspire you on ways you can leverage it in your own projects

Let's walk through a GitHub Action workflow using this Action line by line:

# The name of the workflow, it can be anything you wish
name: "branch deploy demo"

# The workflow to execute on is comments that are newly created
on:
  issue_comment:
    types: [created]

It is important to note that the workflow we want to run IssueOps on is issue_comment and created. This means we will not run under any other contexts for this workflow. You can edit this as you wish but it does change how this model ultimately works. For example, issue_comment workflows only use files found on main to run. If you do something like on: pull_request you could open yourself up to issues as a user could alter a file in a PR and exfil your secrets for example. Only using issue_comment is the suggested workflow type

# Permissions needed for reacting and adding comments for IssueOps commands
permissions:
  pull-requests: write # Required for commenting on PRs
  deployments: write # Required for updating deployment statuses
  contents: write # Required for reading/writing the lock file
  checks: read # Required for checking if the CI checks have passed in order to deploy the PR
  statuses: read # Required for checking if all commit statuses are "success" in order to deploy the PR

These are the minimum permissions you need to run this Action. If you need further assistance with permissions within GitHub Actions, please review the following documentation.

jobs:
  demo:
    if: ${{ github.event.issue.pull_request }} # only run on pull request comments
    runs-on: ubuntu-latest
    steps:
      # Checkout your projects repository
      - uses: actions/checkout@v4

Sets up your demo job, uses an ubuntu runner, and checks out your repo - Just some standard setup for a general Action. We also add an if: statement here to only run this workflow on pull request comments to make it a little cleaner

Note: The Action will check the context for us anyways but this can save us a bit of CI time by using the if: condition

      # Execute IssueOps branch deployment logic, hooray!
      - uses: github/branch-deploy@vX.X.X
        id: branch-deploy
        with:
          trigger: ".deploy"

Note: It is important to set an id: for this job so we can reference its outputs in subsequent steps

The core of this Action takes place here. This block of code will trigger the branch deploy action to run. It will do the following:

Check the comment which invoked the workflow for the trigger: phrase (.deploy) defined here
If the trigger phrase is found, it will proceed with a deployment
It will start by reacting to your message to let you know it is running
The Action will post a comment with a link to the running Actions workflow for you to follow its progress
A deployment will be started and attached to your pull request - You'll get a nice little yellow rocket which tells you a deployment is in progress
Outputs will be exported by this job for later reference in other jobs as well

      # Do some fake "noop" deployment logic here
      # conditionally run a noop deployment
      - name: fake noop deploy
        if: ${{ steps.branch-deploy.outputs.continue == 'true' && steps.branch-deploy.outputs.noop == 'true' }}
        run: echo "I am doing a fake noop deploy"

      # Do some fake "regular" deployment logic here
      # conditionally run a regular deployment
      - name: fake regular deploy
        if: ${{ steps.branch-deploy.outputs.continue == 'true' && steps.branch-deploy.outputs.noop != 'true' }}
        run: echo "I am doing a fake regular deploy"

As seen above, we have two steps. One for a noop deploy, and one for a regular deploy. For example, the noop deploy could trigger a terraform plan and the regular deploy could be a terraform apply. These steps are conditionally gated by two variables:

steps.branch-deploy.outputs.continue == 'true' - The continue variable is only set to true when a deployment should continue
steps.branch-deploy.outputs.noop == 'true' - The noop variable is only set to true when a noop deployment should be run

Example: You comment .noop on a pull request. A noop deployment is detected so this action outputs the noop variable to true. You also have the correct permissions to execute the IssueOps command so the action also outputs the continue variable to true. This will allow the "fake noop deploy" step seen above to run and the "fake regular deploy" step will be skipped

Inputs 📥

Input	Required?	Default	Description
`github_token`	`true`	`${{ github.token }}`	The GitHub token used to create an authenticated client - Provided for you by default!
`status`	`true`	`${{ job.status }}`	The status of the GitHub Actions - For use in the post run workflow - Provided for you by default!
`reaction`	`false`	`eyes`	If set, the specified emoji "reaction" is put on the comment to indicate that the trigger was detected. For example, "rocket" or "eyes"
`trigger`	`false`	`.deploy`	The string to look for in comments as an IssueOps trigger. Example: ".deploy"
`noop_trigger`	`false`	`.noop`	The string to look for in comments as an IssueOps noop trigger. Example: ".noop" - The usage would then be ".noop"
`lock_trigger`	`false`	`.lock`	The string to look for in comments as an IssueOps lock trigger. Used for locking branch deployments on a specific branch. Example: ".lock"
`unlock_trigger`	`false`	`.unlock`	The string to look for in comments as an IssueOps unlock trigger. Used for unlocking branch deployments. Example: ".unlock"
`help_trigger`	`false`	`.help`	The string to look for in comments as an IssueOps help trigger. Example: ".help"
`lock_info_alias`	`false`	`.wcid`	An alias or shortcut to get details about the current lock (if it exists) Example: ".info" - Hubbers will find the ".wcid" default helpful ("where can I deploy")
`permissions`	`true`	`write,maintain,admin`	The allowed GitHub permissions an actor can have to invoke IssueOps commands - Example: "write,maintain,admin"
`param_separator`	`false`	`\|`	The separator to use for parsing parameters in comments in deployment requests. Parameters will are saved as outputs and can be used in subsequent steps - See Parameters for additional details
`global_lock_flag`	`false`	`--global`	The flag to pass into the lock command to lock all environments. Example: "--global"
`environment`	`false`	`production`	The name of the default environment to deploy to. Example: by default, if you type `.deploy`, it will assume "production" as the default environment
`environment_targets`	`false`	`production,development,staging`	Optional (or additional) target environments to select for use with deployments. Example, "production,development,staging". Example usage: `.deploy to development`, `.deploy to production`, `.deploy to staging`
`environment_urls`	`false`	`""`	Optional target environment URLs to use with deployments. This input option is a mapping of environment names to URLs and the environment names must match the `environment_targets` input option. This option is a comma separated list with pipes (`\|`) separating the environment from the URL. Note: `disabled` is a special keyword to disable an environment url if you enable this option. Format: `"<environment1>\|<url1>,<environment2>\|<url2>,etc"` Example: `"production\|https://myapp.com,development\|https://dev.myapp.com,staging\|disabled"` - See the environment urls section for more details
`draft_permitted_targets`	`false`	`""`	Optional environments which can allow "draft" pull requests to be deployed. By default, this input option is empty and no environments allow deployments sourced from a pull request in a "draft" state. Examples: `"development,staging"`
`environment_url_in_comment`	`false`	`"true`	If the `environment_url` detected in the deployment should be appended to the successful deployment comment or not. Examples: `"true"` or `"false"` - See the environment urls section for more details
`production_environments`	`false`	`production`	A comma separated list of environments that should be treated as "production". GitHub defines "production" as an environment that end users or systems interact with. Example: "production,production-eu". By default, GitHub will set the "production_environment" to "true" if the environment name is "production". This option allows you to override that behavior so you can use "prod", "prd", "main", "production-eu", etc. as your production environment name. ref: #208
`stable_branch`	`false`	`main`	The name of a stable branch to deploy to (rollbacks). Example: "main"
`update_branch`	`false`	`warn`	Determine how you want this Action to