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