Skip to main content

Managing Dependabot on self-hosted runners

You can configure GitHub Actions self-hosted runners that Dependabot uses to access your private registries and internal network resources.

Who can use this feature?

Organization owners and repository administrators can configure Dependabot to run on self-hosted runners.

Note

You must opt in to run Dependabot on GitHub Actions. Future releases of GitHub Enterprise Cloud will remove the ability to opt in and always run Dependabot on GitHub Actions. For more information, see "About Dependabot on GitHub Actions runners."

About Dependabot on GitHub Actions self-hosted runners

You can help users of your organization and repositories to create and maintain secure code by setting up Dependabot security and version updates. With Dependabot updates, developers can configure repositories so that their dependencies are updated and kept secure automatically. Running Dependabot on GitHub Actions allows for better performance, and increased visibility and control of Dependabot jobs.

To have greater control over Dependabot access to your private registries and internal network resources, you can configure Dependabot to run on GitHub Actions self-hosted runners.

For security reasons, when running Dependabot on GitHub Actions self-hosted runners, Dependabot updates will not be run on public repositories.

For more information about configuring Dependabot access to private registries when using GitHub-hosted runners, see "Guidance for the configuration of private registries for Dependabot." For information about which ecosystems are supported as private registries, see "Removing Dependabot access to public registries."

Prerequisites

You must have Dependabot installed and enabled, and GitHub Actions enabled and in use. The "Dependabot on GitHub Actions Runners" setting for your organization should also be enabled. For more information, see "About Dependabot on GitHub Actions runners."

If GitHub Actions is not enabled for your organization or repository, then the organization or repository level setting to enable "Dependabot on GitHub Actions runners" will not be visible in the web UI.

Your organization may have configured a policy to restrict actions and self-hosted runners from running in specific repositories, which in turn will not allow Dependabot to run on GitHub Actions self-hosted runners. In this case, the organization or repository level setting to enable "Dependabot on self-hosted runners" will not be visible in the web UI. For more information, see "Disabling or limiting GitHub Actions for your organization."

When you enforce a policy to only allow actions and reusable workflows from your enterprise, and you enable Dependabot on GitHub Actions, Dependabot will not run. To enable Dependabot to run with your enterprise actions and reusable workflows, you should choose either to allow actions created by GitHub, or allow specified actions and reusable workflows. For more information, see "Enforcing policies for GitHub Actions in your enterprise."

Configuring self-hosted runners for Dependabot updates

After you configure your organization or repository to run Dependabot on GitHub Actions, and before you enable Dependabot on self-hosted runners, you need to configure self-hosted runners for Dependabot updates.

System requirements for Dependabot runners

Any virtual machine (VM) that you use for Dependabot runners must meet the requirements for self-hosted runners. In addition, they must meet the following requirements.

  • Linux operating system

  • x64 architecture

  • Docker installed with access for the runner users:

    • We recommend installing Docker in rootless mode and configuring the runners to access Docker without root privileges.
    • Alternatively, install Docker and give the runner users raised privileges to run Docker.

The CPU and memory requirements will depend on the number of concurrent runners you deploy on a given VM. As guidance, we have successfully set up 20 runners on a single 2 CPU 8GB machine, but ultimately, your CPU and memory requirements will heavily depend on the repositories being updated. Some ecosystems will require more resources than others.

If you specify more than 14 concurrent runners on a VM, you must also update the Docker /etc/docker/daemon.json configuration to increase the default number of networks Docker can create.

{
  "default-address-pools": [
    {"base":"10.10.0.0/16","size":24}
  ]
}

Network requirements for Dependabot runners

Dependabot runners require access to the public internet, GitHub.com, and any internal registries that will be used in Dependabot updates. To minimize the risk to your internal network, you should limit access from the Virtual Machine (VM) to your internal network. This reduces the potential for damage to internal systems if a runner were to download a hijacked dependency.

Certificate configuration for Dependabot runners

If Dependabot needs to interact with registries that use self-signed certificates, those certificates must also be installed on the self-hosted runners that run Dependabot jobs. This security hardens the connection. You must also configure Node.js to use the certificate, because most actions are written in JavaScript and run using Node.js, which does not use the operating system certificate store.

Adding self-hosted runners for Dependabot updates

  1. Provision self-hosted runners, at the repository or organization level. For more information, see "About self-hosted runners" and "Adding self-hosted runners."

  2. Set up the self-hosted runners with the requirements described above. For example, on a VM running Ubuntu 20.04 you would:

  3. Assign a dependabot label to each runner you want Dependabot to use. For more information, see "Using labels with self-hosted runners."

  4. Optionally, enable workflows triggered by Dependabot to use more than read-only permissions and to have access to any secrets that are normally available. For more information, see "Automating Dependabot with GitHub Actions."

Enabling self-hosted runners for Dependabot updates

Once you have configured self-hosted runners for Dependabot updates, you can enable or disable Dependabot updates on self-hosted runners at the organization or repository level.

Note, disabling and re-enabling the "Dependabot on self-hosted runners" settings will not trigger a new Dependabot run.

Enabling or disabling for your repository

You can manage Dependabot on self-hosted runners for your private or internal repository.

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. In the "Security" section of the sidebar, click Code security and analysis.

  4. Under "Dependabot", to the right of "Dependabot on self-hosted runners", click Enable to enable the feature or Disable to disable it.

Enabling or disabling for your organization

You can use the organization settings page for "Code security and analysis" to enable Dependabot on self-hosted runners for all existing private or internal repositories in an organization. Only repositories already configured to run Dependabot on GitHub Actions will be updated to run Dependabot on self-hosted runners the next time a Dependabot job is triggered.

Note

You need to enable self-hosted runners for your organization if you use larger runners. For more information, see "About Dependabot on GitHub Actions runners."

  1. In the upper-right corner of GitHub, select your profile photo, then click Your organizations.

  2. Next to the organization, click Settings.

  3. In the "Security" section of the sidebar, click Code security and analysis.

    Note

    If your organization is enrolled in the security configurations and global settings public beta, instead of "Code security and analysis", you will see a "Code security" dropdown menu. Select Code security, then click Global settings. For next steps on enabling Dependabot on self-hosted runners and other security features at scale with security configurations, see "Applying the GitHub-recommended security configuration in your organization."

  4. Under "Code security", select "Global settings".

  5. Under "Dependabot", select "Dependabot on self-hosted runners" to enable the feature or deselect to disable it. This action enables or disables the feature for all new repositories in the organization.