Automating Dependabot with GitHub Actions

Note: Dependabot security and version updates are currently in private beta and subject to change. Please contact your account management team for instructions on enabling Dependabot updates.

Note: Your site administrator must set up Dependabot updates for your GitHub Enterprise Server instance before you can use this feature. For more information, see "Enabling Dependabot for your enterprise."

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, certain events are treated differently.

GITHUB_TOKEN has read-only permissions, unless your administrator has removed restrictions.
Secrets are inaccessible, unless your administrator has removed restrictions.

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

Note: Your site administrator can override these restrictions for your GitHub Enterprise Server instance. For more information, see "Troubleshooting GitHub Actions for your enterprise."

If the restrictions are removed, when a workflow is triggered by Dependabot it will have access to GitHub Actions secrets and can use the permissions term to increase the default scope of the GITHUB_TOKEN from read-only access. You can ignore the specific steps in the "Handling pull_request events" and "Handling push events" sections, as it no longer applies.

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.

Warning: Using pull_request_target as a substitute for pull_request exposes you to insecure behavior. We recommend you use the two workflow method, as described below in "Handling push events."

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

Note: If your site administrator has overridden restrictions for Dependabot on your GitHub Enterprise Server instance, you can use pull_request instead of pull_request_target in the following workflows.

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 fetch metadata
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: dependabot-metadata
        uses: dependabot/fetch-metadata@v1.1.1
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
      # The following properties are now available:
      #  - steps.dependabot-metadata.outputs.dependency-names
      #  - steps.dependabot-metadata.outputs.dependency-type
      #  - steps.dependabot-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: dependabot-metadata
        uses: dependabot/fetch-metadata@v1.1.1
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
      - name: Add a label for all production dependencies
        if: ${{ steps.dependabot-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: dependabot-metadata
        uses: dependabot/fetch-metadata@v1.1.1
        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 allow maintainers to mark certain pull requests for auto-merge, you can use GitHub's auto-merge functionality. This enables the pull request to be merged when any tests and approvals required by the branch protection rules are successfully met. For more information, see "Automatically merging a pull request" and "Managing a branch protection rule."

Note: If you use status checks to test pull requests, you should enable Require status checks to pass before merging for the target branch for Dependabot pull requests. This branch protection rule ensures that pull requests are not merged unless all the required status checks pass. For more information, see "Managing a branch protection rule."

You can instead use GitHub Actions and the GitHub CLI. Here is an example that auto merges all patch updates to my-dependency:

name: Dependabot auto-merge
on: pull_request_target

permissions:
  contents: write
  pull-requests: write
  
jobs:
  dependabot:
    runs-on: ubuntu-latest
    if: ${{ github.actor == 'dependabot[bot]' }}
    steps:
      - name: Dependabot metadata
        id: dependabot-metadata
        uses: dependabot/fetch-metadata@v1.1.1
        with:
          github-token: "${{ secrets.GITHUB_TOKEN }}"
      - name: Enable auto-merge for Dependabot PRs
        if: ${{contains(steps.dependabot-metadata.outputs.dependency-names, 'my-dependency') && steps.dependabot-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."