Automating Dependabot with GitHub Actions

About Dependabot and GitHub Actions

Dependabot creates pull requests to keep your dependencies up to date, and you can use GitHub Actions to perform automated tasks when these pull requests are created. For example, fetch additional artifacts, add labels, run tests, or otherwise modifying the pull request.

Responding to events

Dependabot is able to trigger GitHub Actions workflows on its pull requests and comments; however, due to "GitHub Actions: Workflows triggered by Dependabot PRs will run with read-only permissions", certain events are treated differently.

For workflows initiated by Dependabot (github.actor == "dependabot[bot]") using the pull_request, pull_request_review, pull_request_review_comment, and push events, the following restrictions apply:

• GITHUB_TOKEN has read-only permissions.
• Secrets are inaccessible.

For more information, see "Keeping your GitHub Actions and workflows secure: Preventing pwn requests".

Handling pull_request events

If your workflow needs access to secrets or a GITHUB_TOKEN with write permissions, you have two options: using pull_request_target, or using two separate workflows. We will detail using pull_request_target in this section, and using two workflows below in "Handling push events."

Below is a simple example of a pull_request workflow that might now be failing:

### This workflow now has no secrets and a read-only token
name: Dependabot Workflow
on:
  pull_request

jobs:
  dependabot:
    runs-on: ubuntu-latest
    # Always check the actor is Dependabot to prevent your workflow from failing on non-Dependabot PRs
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - uses: actions/checkout@v2

You can replace pull_request with pull_request_target, which is used for pull requests from forks, and explicitly check out the pull request HEAD.

### This workflow has access to secrets and a read-write token
name: Dependabot Workflow
on:
  pull_request_target
  
permissions:
  # Downscope as necessary, since you now have a read-write token

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - uses: actions/checkout@v2
        with:
          # Check out the pull request HEAD
          ref: ${{ github.event.pull_request.head.sha }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

It is also strongly recommended that you downscope the permissions granted to the GITHUB_TOKEN in order to avoid leaking a token with more privilege than necessary. For more information, see "Permissions for the GITHUB_TOKEN."

Handling push events

As there is no pull_request_target equivalent for push events, you will have to use two workflows: one untrusted workflow that ends by uploading artifacts, which triggers a second trusted workflow that downloads artifacts and continues processing.

The first workflow performs any untrusted work:

### This workflow doesn't have access to secrets and has a read-only token
name: Dependabot Untrusted Workflow
on:
  push

jobs:
  check-dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - uses: ...

The second workflow performs trusted work after the first workflow completes successfully:

### This workflow has access to secrets and a read-write token
name: Dependabot Trusted Workflow
on:
  workflow_run:
    workflows: ["Dependabot Untrusted Workflow"]
    types: 
      - completed

permissions:
  # Downscope as necessary, since you now have a read-write token

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - uses: ...

Manually re-running a workflow

You can also manually re-run a failed Dependabot workflow, and it will run with a read-write token and access to secrets. Before manually re-running a failed workflow, you should always check the dependency being updated to ensure that the change doesn't introduce any malicious or unintended behavior.

Common Dependabot automations

Here are several common scenarios that can be automated using GitHub Actions.

Fetch metadata about a pull request

A large amount of automation requires knowing information about the contents of the pull request: what the dependency name was, if it's a production dependency, and if it's a major, minor, or patch update.

The dependabot/fetch-metadata action provides all that information for you:

name: Dependabot auto-label
on: pull_request_target

permissions:
  pull-requests: write
  issues: write
  repository-projects: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - name: Dependabot metadata
        id: metadata
        uses: dependabot/[email protected]
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
      # The following properties are now available:
      #  - steps.metadata.outputs.dependency-names
      #  - steps.metadata.outputs.dependency-type
      #  - steps.metadata.outputs.update-type      

For more information, see the dependabot/fetch-metadata repository.

Label a pull request

If you have other automation or triage workflows based on GitHub labels, you can configure an action to assign labels based on the metadata provided.

For example, if you want to flag all production dependency updates with a label:

name: Dependabot auto-label
on: pull_request_target

permissions:
  pull-requests: write
  issues: write
  repository-projects: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - name: Dependabot metadata
        id: metadata
        uses: dependabot/[email protected]
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
      - name: Add a label for all production dependencies
        if: ${{ steps.metadata.outputs.dependency-type == 'direct:production' }}
        run: gh pr edit "$PR_URL" --add-label "production"
        env:
          PR_URL: ${{github.event.pull_request.html_url}}

Approve a pull request

If you want to automatically approve Dependabot pull requests, you can use the GitHub CLI in a workflow:

name: Dependabot auto-approve
on: pull_request_target

permissions:
  pull-requests: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - name: Dependabot metadata
        id: metadata
        uses: dependabot/[email protected]
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
      - name: Approve a PR
        run: gh pr review --approve "$PR_URL"
        env:
          PR_URL: ${{github.event.pull_request.html_url}}
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Enable auto-merge on a pull request

If you want to auto-merge your pull requests, you can use GitHub's auto-merge functionality. This enables the pull request to be merged when all required tests and approvals are successfully met. For more information on auto-merge, see "Automatically merging a pull request"."

Here is an example of enabling auto-merge for all patch updates to my-dependency:

name: Dependabot auto-merge
on: pull_request_target

permissions:
  pull-requests: write
  contents: write

jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - name: Dependabot metadata
        id: metadata
        uses: dependabot/[email protected]
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
      - name: Enable auto-merge for Dependabot PRs
        if: ${{contains(steps.metadata.outputs.dependency-names, 'my-dependency') && steps.metadata.outputs.update-type == 'version-update:semver-patch'}}
        run: gh pr merge --auto --merge "$PR_URL"
        env:
          PR_URL: ${{github.event.pull_request.html_url}}
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Troubleshooting failed workflow runs

If your workflow run fails, check the following:

• You are running the workflow only when the correct actor triggers it.
• You are checking out the correct ref for your pull_request.
• You aren't trying to access secrets from within a Dependabot-triggered pull_request, pull_request_review, pull_request_review_comment, or push event.
• You aren't trying to perform any write actions from within a Dependabot-triggered pull_request, pull_request_review, pull_request_review_comment, or push event.

For information on writing and debugging GitHub Actions, see "Learning GitHub Actions."