GitHub Actions Deployment Protection Rules are automatic controls that can use data from external tools to gate deployments in Actions workflows. Honeycomb provides a deployment protection rule that lets you use Honeycomb query data in tandem with this feature.
The Honeycomb Deployment Protection Rule lets you programmatically define service expectations in your GitHub code to determine when a deployment should proceed. For each GitHub environment in your deployment, you define a Honeycomb query to run in a specific dataset and an allowable threshold for the results.
This rule provides a degree of flexibility that is designed to accommodate numerous use cases. For example, use the Honeycomb Deployment Protection Rule to:
When enabled, the Honeycomb Deployment Protection Rule runs as a check prior to any deployment actions. It determines whether a deployment into the target GitHub environment is allowed to proceed.
Honeycomb deployment protection rules consist of a Honeycomb query, a threshold, and an operator (>, <, or =).
When a deployment is requested in your Actions workflow, the rule sends its payload to Honeycomb for evaluation, where it asks if the deployment is allowed to proceed.
After Honeycomb completes the query evaluation, it returns a pass/fail response.
All deployment protection rules are configured in a .honeycomb.yaml file that must be checked and located in the root directory of your GitHub repository.
Otherwise, Honeycomb does not have permission to access this file.
The .honeycomb.yaml file can contain a configuration block for each GitHub environment that the repository is deployed.
The Honeycomb Deployment Protection Rule is provided via the Honeycomb GitHub App.
To install:
Navigate to the Honeycomb GitHub App.
Select Install.
Then, select which organization to install the Honeycomb GitHub App.
Authorize the Honeycomb GitHub App to your GitHub organization.
An example of requested permissions appears below.
Once the GitHub authorization is complete, you are taken to Honeycomb to continue the installation process.
In Honeycomb, select the Honeycomb team to connect.
Then, confirm which team’s Honeycomb environments and datasets can be queried from your deployment protection rules.
Refer to Troubleshooting if you encounter any issues during installation.
After installing the Honeycomb GitHub App, it must be enabled as an environment protection rule for your various GitHub environments.
To enable:
Navigate to your GitHub repository.
Under Settings > Environments, select the GitHub environment by its name.
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.
Select Save Protection Rules to continue.
Refer to GitHub documentation for more about environment protection rules.
You must create a .honeycomb.yaml file in the root of your repository to configure the queries and thresholds that act as a deployment protection rule for each GitHub environment.
The YAML file must have a configuration block for every environment with a deployment protection rule enabled; otherwise, the stage fails.
.honeycomb.yaml file must be in the root directory of your repository.
Honeycomb cannot access this file in a subdirectory.If the query defined as a deployment protection rule evaluates within the acceptable threshold, it “passes” and the deployment continues. Otherwise, it “fails” and the deployment is blocked.
Honeycomb supports a query specification for defining queries via JSON.
Queries for Honeycomb deployment protection rules can be composed directly as JSON in your .honeycomb.yaml file.
Guidance and resources exist for writing deployment protection queries.
Below is an example of a standard .honeycomb.yaml file.
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
where:
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.To configure GitHub Deployment Protection Rules against Honeycomb Classic:
$classic$ as the environment slug When writing Deployment Protection Queries, remember the following:
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.
Compose the query you wish to use as a deployment protection rule in the Query Builder and select Run Query.
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.
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.
After being configured and merged into your repository, Honeycomb deployment protection rules runs when a deployment is requested and waits to receive a pass/fail status before a deployment can occur to the target GitHub environment.
View the results of the Honeycomb deployment protection rules in the GitHub Actions Workflow run. Examples of passing and failing deployment rules appear below.
Whenever a Honeycomb deployment protection rule runs, it is included in the list of all rules protecting deployments in a particular workflow run. The Honeycomb GitHub App appends a permalink to the exact query results used to protect each environmental deployment during the run. Select that permalink to show the data in Honeycomb that allowed your deployment to pass or fail. If your deployment failed, this link provides a jumping off point to begin your investigation.
To re-run a deployment protection rule, you must re-run the GitHub Actions workflow stage(s).
If the deployment protection rule fails with “GitHub App not authorized to access Honeycomb team”, uninstall and reinstall the GitHub App.
Only one Honeycomb team can be configured during installation of the Honeycomb GitHub App. You cannot change the Honeycomb team where deployment protection rule queries run without re-initializing the authorization flow.
To change the Honeycomb team, you must uninstall and reinstall the GitHub App, and select the desired team during the new installation.
You can use Honeycomb to verify the status of the GitHub App installation. In Honeycomb’s left navigation menu, select Account and then select Team settings. Then, select the Integrations tab. Refer to the Honeycomb + GitHub section to determine the installation status.
GitHub Owners can force a deployment when a deployment protection rule is in a failure state.
Ensure you have the Allow administrators to bypass configured protection rules setting enabled when enabling the Honeycomb Deployment Protection Rule in your GitHub Environment to allow for this.
