Gate Deployments with GitHub Actions Deployment Protection Rules

• gate deployments based on error rates introduced by the current build.
• run automated performance checks in blue/green style deployments.
• drive canary release patterns.
• check SLI error rates in staging before promoting to production.
• prevent automated deployments during an ongoing incident.
• ensure that deployments are sensitive to the current service status in any environment.

​

How It Works

​

Prerequisites and Limitations

• GitHub Actions Deployment Protection Rules are only available to GitHub Enterprise Cloud customers.
• Completing the GitHub App installation requires a GitHub Owner to grant authorization and allows Honeycomb access to your GitHub organization and its repositories.
• Linking GitHub to a Honeycomb team requires Honeycomb Team Owner permissions in Honeycomb.
• Maximum Honeycomb query limits exist.
• Deployment protection rules only work with GitHub Actions workflows that use GitHub environments as part of deployments.

​

Installation and Setup

​

Install the Honeycomb GitHub App

1. Navigate to the Honeycomb GitHub App.
   1. If using the Honeycomb US instance accessed via ui.honeycomb.io
   2. If using the Honeycomb EU instance accessed via ui.eu1.honeycomb.io
2. Select Install.
3. Then, select which organization to install the Honeycomb GitHub App.
   The GitHub App installation flow requires a GitHub Owner to grant authorization that allows Honeycomb access to your GitHub organization and its repositories.
4. Authorize the Honeycomb GitHub App to your GitHub organization. An example of requested permissions appears below.
   
5. Once the GitHub authorization is complete, you are taken to Honeycomb to continue the installation process.
6. In Honeycomb, select the Honeycomb team to connect.
   The Honeycomb team selection flow requires Honeycomb Team Owner permissions to complete.
7. Then, confirm which team’s Honeycomb environments and datasets can be queried from your deployment protection rules.

​

Enable the Honeycomb Deployment Protection Rule in Each GitHub Environment

1. Navigate to your GitHub repository.
2. Under Settings > Environments, select the GitHub environment by its name.
3. Next, under Deployment protection rules, select the Honeycomb.io option. Optionally, select Allow administrators to bypass configured protection rules to allow GitHub Owners the ability to force a deployment when a deployment protection rule is in a failure state.
4. Select Save Protection Rules to continue.
   

​

Configure Honeycomb Deployment Protection Rules

version: 1

honeycomb_team: my-team # the honeycomb team where queries for all deployment protection rules runs

deployment_protection_rules:
  staging: # name of github environment where a deployment occurs
    queries:
      - honeycomb_environment: qa # honeycomb environment where the query runs
        honeycomb_dataset: my-cool-application # (optional, but necessary when using Honeycomb Classic) When left empty, an environment-wide Honeycomb query runs, which is not supported by Honeycomb Classic. 
        spec: &queryspec '{
            "time_range": 1800,
            "calculations": [
              {
                  "op": "COUNT"
              }
            ],
            "filters": [
              {
                  "column": "status_code",
                  "op": "=",
                  "value": "500"
              },
              {
                  "column": "build_id",
                  "op": "=",
                  "value": ${GITHUB_RUN_ID}  # NOTE: when deployment protection rules run, they can map the special GITHUB_RUN_ID variable
              }
            ],
            "filter_combination": "AND"
          }'
        threshold:
          operator: '>'
          value: 3

  production: # name of github environment where a deployment occurs
    queries:
      - honeycomb_environment: staging # honeycomb environment where the query runs
        honeycomb_dataset: my-cool-application # (optional, but necessary when using Honeycomb Classic) When left empty, an environment-wide Honeycomb query runs, which is not supported by Honeycomb Classic. 
        spec: *queryspec # example of a YAML alias to reuse a query spec created for a different deployment protection rule
        threshold:
          operator: '>'
          value: 1

• honeycomb_team must be the team where queries for all deployment protection rules runs. This is checked against the team authorized when installing the GitHub App.
• GITHUB_RUN_ID is a special variable interpolated by the GitHub App as the unique identifier of the GitHub Actions workflow run.

​

Writing Deployment Protection Queries

• They operate similar to Triggers. The same queries and thresholds used to define Triggers can be used in deployment protection rules. For inspiration, visit our Trigger Examples.
• Use the Query Builder UI to generate Query Spec JSON. As an alternative to composing JSON directly, you can use Honeycomb’s Query Builder to create the JSON for you. To write a deployment protection query:
  1. Compose the query you wish to use as a deployment protection rule in the Query Builder and select Run Query.
  2. After you are satisfied with the query results that appear, select the three-dot overflow menu, located to the left of Run Query. Then, select View Query Definition for API.
     
  3. A modal appears with the Query JSON. Use the copy button to copy the content, and paste it into the spec of your .honeycomb.yaml file.
     
• Deployment Protection Queries can be extremely versatile. The only constraint is that query results must be evaluated against a numeric threshold. Otherwise, deployment protection rules can be used to extract very granular data about the state of your application and its systems. For detailed information on queries, refer to Honeycomb Query Builder documentation.

​

View the Result of Your Actions Workflow Deployments

• Passing deployment rule example
• Failing deployment rule example

​

Troubleshooting

​

GitHub App not Authorized

​

Changing the Honeycomb Team

​

Checking GitHub App Permissions

​

Forcing a Deployment

​

Maximum Query Limits

• Honeycomb deployment protection rules may only query up to the past 24 hours of data
• No more than one Honeycomb query may be defined per GitHub environment in your deployment