What are GitHub Actions?

GitHub Actions are used for many different purposes. We use them to run tests in CI, validate PRs are in an expected state, and automate processes.

• Overview of GitHub Actions
• What's a workflow?
• GitHub Actions guides

Where do actions and workflows live

We try to maintain actions that are shared across repositories in a single place so that necesary changes can be made in a single place.

dbt-labs/actions is the central repository of actions and workflows we use across repositories.

GitHub Actions also live locally within a repository. The workflows can be found at .github/workflows from the root of the repository. These should be specific to that code base.

Note: We are actively moving actions into the central Action repository so there is currently some duplication across repositories.

General Standards

Permissions

• By default, workflows have read permissions in the repository for the contents scope only when no permissions are explicitly set.
• It is best practice to always define the permissions explicitly. This will allow actions to continue to work when the default permissions on the repository are changed. It also allows explicit grants of the least permissions possible.
• There are a lot of permissions available. Read up on them if you're unsure what to use.

permissions:
  contents: read
  pull-requests: write

Secrets

• When to use a Personal Access Token (PAT) vs the GITHUB_TOKEN generated for the action?

  The GITHUB_TOKEN is used by default. In most cases it is sufficient for what you need.

  If you expect the workflow to result in a commit to that should retrigger workflows, you will need to use a Personal Access Token for the bot to commit the file. When using the GITHUB_TOKEN, the resulting commit will not trigger another GitHub Actions Workflow run. This is due to limitations set by GitHub. See the docs for a more detailed explanation.

  For example, we must use a PAT in our workflow to commit a new changelog yaml file for bot PRs. Once the file has been committed to the branch, it should retrigger the check to validate that a changelog exists on the PR. Otherwise, it would stay in a failed state since the check would never retrigger.

Triggers

You can configure your workflows to run when specific activity on GitHub happens, at a scheduled time, or when an event outside of GitHub occurs. Read more details in the GitHub docs.

These triggers are under the on key of the workflow and more than one can be listed.

on:
  push:
    branches:
      - "main"
      - "*.latest"
      - "releases/*"
  pull_request:
    # catch when the PR is opened with the label or when the label is added
    types: [opened, labeled]
  workflow_dispatch:

Some triggers of note that we use:

• push - Runs your workflow when you push a commit or tag.
• pull_request - Runs your workflow when activity on a pull request in the workflow's repository occurs. Takes in a list of activity types (opened, labeled, etc) if appropriate.
• pull_request_target - Same as pull_request but runs in the context of the PR target branch.
• workflow_call - used with reusable workflows. Triggered by another workflow calling it.
• workflow_dispatch - Gives the ability to manually trigger a workflow from the GitHub API, GitHub CLI, or GitHub browser interface.

General Formatting

• Add a description of what your workflow does at the top in this format

  # **what?**
  # Describe what the action does.  
  
  # **why?**
  # Why does this action exist?
  
  # **when?**
  # How/when will it be triggered?
  

• Leave blank lines between steps and jobs

  jobs:
    dependency_changelog:
      runs-on: ubuntu-latest
  
      steps:
      - name: Get File Name Timestamp
        id: filename_time
        uses: nanzm/[email protected]
        with:
          format: 'YYYYMMDD-HHmmss'
  
      - name: Get File Content Timestamp
        id: file_content_time
        uses: nanzm/[email protected]
        with:
          format: 'YYYY-MM-DDTHH:mm:ss.000000-05:00'
  
      - name: Generate Filepath
        id: fp
        run: |
          FILEPATH=.changes/unreleased/Dependencies-${{ steps.filename_time.outputs.time }}.yaml
          echo "::set-output name=FILEPATH::$FILEPATH"

• Print out all variables you will reference as the first step of a job. This allows for easier debugging. The first job should log all inputs. Subsequent jobs should reference outputs of other jobs, if present.

  When possible, generate variables at the top of your workflow in a single place to reference later. This is not always strictly possible since you may generate a value to be used lated mid-workflow.

  job1:
    - name: [DEBUG] Print Variables
      run: |
        echo "all variables defined as inputs"
        echo The last commit sha in the release: ${{ inputs.sha }}
        echo The release version number:         ${{ inputs.version_number }}
        echo The changelog_path:                 ${{ inputs.changelog_path }}
        echo The build_script_path:              ${{ inputs.build_script_path }}
        echo The s3_bucket_name:                 ${{ inputs.s3_bucket_name }}
        echo The package_test_command:           ${{ inputs.package_test_command }}
      
    # collect all the variables that need to be used in subsequent jobs
    - name: Set Variables
      id: variables
      run: |
        echo "::set-output name=important_path::'performance/runner/Cargo.toml'"
        echo "::set-output name=release_id::${{github.event.inputs.release_id}}"
        echo "::set-output name=open_prs::${{github.event.inputs.open_prs}}"
  
  job2:
    needs: [job1]
      - name: '[DEBUG] Print Variables'
      run: |
        echo "all variables defined in job1 > Set Variables > outputs"
        echo "important_path: ${{ needs.job1.outputs.important_path }}"
        echo "release_id:     ${{ needs.job1.outputs.release_id }}"
        echo "open_prs:       ${{ needs.job1.outputs.open_prs }}"

Tips

Context

• The GitHub CLI is available in the default runners
• Actions run in your context. ie, using an action from the marketplace that uses the GITHUB_TOKEN uses the GITHUB_TOKEN generated by your workflow run.

Actions from the Marketplace

• Don’t use external actions for things that can easily be accomplished manually.
• Always read through what an external action does before using it! Often an action in the GitHub Actions Marketplace can be replaced with a few lines in bash. This is much more maintainable (and won’t change under us) and clear as to what’s actually happening. It also prevents any
• Pin actions we don't control to tags.

Connecting to AWS

• Authenticate with the aws managed workflow

  - name: Configure AWS credentials from Test account
    uses: aws-actions/configure-aws-credentials@v1
    with:
      aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
      aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      aws-region: us-east-1

• Then access with the aws command that comes installed on the action runner machines

  - name: Copy Artifacts from S3 via CLI
    run: aws s3 cp ${{ env.s3_bucket }} . --recursive 

Testing

• Depending on what your action does, you may be able to use act to test the action locally. Some features of GitHub Actions do not work with act, among those are reusable workflows. If you can't use act, you'll have to push your changes up before being able to test. This can be slow.

• View all action output from the Actions tab. Workflow results last 1 year.

• View the action output for your PR in the Checks tab of the PR. This only shows the most recent run.