Step 3: Add the Lightstep Pre-Deploy Action to Your Workflow

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 or unknown) 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.

1. In the root directory of your repo, create a YAML file named .lightstep.yml

2. Add the following to your file:

   1
   2
    organization: <YOUR_ORGANIZATION_NAME>
    project: <YOUR_PROJECT_NAME>
   

   Your organization name and project 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.

3. 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 the selected_condition_id parameter.

   Add that ID to conditions, after project.

   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).

1. 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 the runs-on property in the jobs section.
   If you don’t already have a step for checking out the repo, add that before the Pre-Deploy step.

2. 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 } }
   

3. 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.