GitHub workflows let you automate your software development life cycle processes directly within GitHub. You configure them to run based on an event in a repository, like a pull-request or a merge. When workflows are run, they pull what is in the repo onto a virtual machine (of your choice) and execute all the actions configured for it. The Pre-Deploy Check action posts any violated alerts it found when the workflow was run and posts it to the Actions tab in GitHub as well as to the pull request.
You configure the workflow and the actions in it using a YAML file.
The workflow should have a step before the Pre-Deploy action that checks out the repository to a virtual machine.
The Pre-Deploy action does the following:
- Uses the Lightstep API to retrieve all existing alerts.
- Determines if any alerts are in violation.
- Adds the report to your pull request. You can see the status of the check (
ok
,warn
,error
orunknown
) with a link into Lightstep to view violated alerts and start your investigation.
Before you add the action to your workflow, you need to create a Lightstep-specific configuration file that provides your Lightstep organization and product names.
Create the Lightstep YAML File
This file provides your Lightstep organization and project name.
-
In the root directory of your repo, create a YAML file named
.lightstep.yml
- Add the following to your file:
1 2
organization: <YOUR_ORGANIZATION_NAME> project: <YOUR_PROJECT_NAME>
Your
organization name
andproject name
can be found on the Project Settings page.By default, the action queries all alerts in your system, looking for violations. You can instead have it query specific alerts.
-
To query only specified alerts, add the ID of the alert as an option to the configuration.
To find the ID, in Lightstep, select the alert from the Alerts page. The ID is the value of theselected_condition_id
parameter.Add that ID to
conditions
, afterproject
.1 2 3 4 5 6
organization: -13ac9ef7 project: hipster-shop # optional - specifiy specific alerts to check conditions: - WWfBYwZk
Now you can add the Pre-Deploy action to your workflow.
Add the Pre-Deploy Action to a GitHub Workflow
In this step, we’ll add the Pre-Deploy action to a workflow for when a pull request is submitted for review (but you can add it to any workflow).
-
Open your workflow’s YAML file. If you don’t already have one, read GitHub’s docs to create one, or use the full example below.
The Pre-Deploy action uses the
ubuntu-latest
GitHub Actions runner. Be sure that is configured for theruns-on
property in thejobs
section.
If you don’t already have a step for checking out the repo, add that before the Pre-Deploy step. -
Add a step for the Pre-Deploy action.
You need to have set a Lightstep API key for your account as a GitHub secret.
1 2 3 4 5 6 7 8
steps: - name: Checkout uses: actions/checkout@v2 - name: Lightstep Pre-Deploy Check uses: lightstep/lightstep-action-predeploy with: lightstep_api_key: ${ { secrets.LIGHTSTEP_API_KEY } }
-
To report the findings of the action, create a step that adds the reported status. In this example, we’ll add it as a pull request comment.
You need to have set GitHub token as a secret
1 2 3 4 5 6 7 8
# Output status as PR comment - name: Add PR Comment uses: unsplash/comment-on-pr@master env: GITHUB_TOKEN: ${ { secrets.GITHUB_TOKEN } } with: msg: ${ { steps.lightstep-predeploy.outputs.lightstep_predeploy_md } } check_for_duplicate_msg: true
Here’s a full example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
on:
pull_request_review:
types: [submitted]
jobs:
deploy_check_job:
runs-on: ubuntu-latest
name: Verify Pre-Deploy Status
steps:
- name: Checkout
uses: actions/checkout@v2
# Run checks
- name: Lightstep Pre-Deploy Check
id: lightstep-predeploy
uses: lightstep/lightstep-action-predeploy
with:
lightstep_api_key: ${ { secrets.LIGHTSTEP_API_KEY } }
# Output status as PR comment
- name: Add PR Comment
uses: unsplash/comment-on-pr@master
env:
GITHUB_TOKEN: ${ { secrets.GITHUB_TOKEN } }
with:
msg: ${ { steps.lightstep-predeploy.outputs.lightstep_predeploy_md } }
check_for_duplicate_msg: true
Your workflow is now configured to work whenever a review for a pull request is initiated! It’s also shown in the Actions tab on the GitHub page.
When you click the Lightstep link, you’re taken to the Alerts view in Lightstep where you can start your investigation by clicking the violated alert.
In the Stream, you can view the number of exemplar spans that are in the violation range.
Click one of the dots to open a trace and start your investigation.
In the next step, you’ll learn how to integrate Rollbar to report on error status and PagerDuty to provide on-call details.
What Did We Learn?
- Each action requires a YAML file stored at the root directory to provide project-specific information.
- Actions are embedded as steps into a GitHub workflow.