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 conditions 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 conditions.
  • Determines if any conditions 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 conditions and start your investigation. Pre-Deploy action in GitHub

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. Project Settings

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! Action report It’s also shown in the Actions tab on the GitHub page.

When you click the Lightstep link, you’re taken to the Conditions view in Lightstep where you can start your investigation by clicking the violated condition. Conditions view

In the Stream, you can view the number of exemplar spans that are in the violation range.Stream with violation

Click one of the dots to open a trace and start your investigation.Trace view

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.