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
.
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.
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 yourpull_request
. - You aren't trying to access secrets from within a Dependabot-triggered
pull_request
,pull_request_review
,pull_request_review_comment
, orpush
event. - You aren't trying to perform any
write
actions from within a Dependabot-triggeredpull_request
,pull_request_review
,pull_request_review_comment
, orpush
event.
For information on writing and debugging GitHub Actions, see "Learning GitHub Actions."