Skip to content

GitHub and GitHub Enterprise Server

Authentication

First, create a classic Personal Access Token for the bot account, select repo scope. Fine-grained Personal Access Tokens do not support the GitHub GraphQL API and cannot be used with Renovate.

Let Renovate use your PAT by doing one of the following:

  • Set your PAT as a token in your config.js file
  • Set your PAT as an environment variable RENOVATE_TOKEN
  • Set your PAT when you run Renovate in the CLI with --token=

Remember to set platform=github somewhere in your Renovate config file.

If you use GitHub Enterprise Server then endpoint must point to https://github.enterprise.com/api/v3/. You can choose where you want to set endpoint:

  • In your config.js file
  • In a environment variable
  • In a CLI parameter

Labels and forking mode

If you're self-hosting Renovate on GitHub.com with GitHub Actions in forking mode, and want Renovate to apply labels then you must give the PAT triage level rights on issues. The triage level allows the PAT to apply/dismiss existing labels.

Running as a GitHub App

Instead of a bot account with a Personal Access Token you can run renovate as a self-hosted GitHub App.

When creating the GitHub App give it the following permissions:

Permission Scope
Checks read + write
Commit statuses read + write
Contents read + write
Issues read + write
Pull requests read + write
Workflows read + write
Administration read
Dependabot alerts read
Members read
Metadata read

Other values like Homepage URL, User authorization callback URL and webhooks can be disabled or filled with dummy values.

Inside your config.js you need to set the following values, assuming the name of your app is self-hosted-renovate:

token:"ghs_123exampletoken"

You must use a GitHub App Installation token.

Previously, the token had to be prefixed with x-access-token:. We recommend you replace any prefixed tokens with normal tokens. We will drop support for prefixed tokens in the future.

Any tokens that do not start with ghs_ (for example tokens from GitHub Enterprise Server versions before version 3.2) must be prefixed with x-access-token:.

Note

The installation tokens expire after 1 hour and need to be regenerated regularly. Alternatively as environment variable RENOVATE_TOKEN, or via CLI --token=.

Third-party tools to regenerate installation tokens

If you're self-hosting Renovate within a GitHub Actions workflow, then you can use the jnwng/github-app-installation-token-action or tibdex/github-app-token actions. If you use Node.js/CLI, then you can use the github-app-installation-token package. If you use Docker, then you can use the mshekow/github-app-installation-token image.

repositories: ["orgname/repo-1","orgname/repo-2"]

List of repositories to run on. Alternatively as comma-separated environment variable RENOVATE_REPOSITORIES. The GitHub App installation token is scoped at most to a single organization and running on multiple organizations requires multiple invocations of renovate with different token and repositories parameters.

username:"self-hosted-renovate[bot]" (optional, autodetected if not supplied)

The slug name of your app with [bot] appended

gitAuthor:"Self-hosted Renovate Bot <123456+self-hosted-renovate[bot]@users.noreply.github.enterprise.com>" (optional, autodetected if not supplied)

The GitHub App associated email to match commits to the bot. It needs to have the user id and the username followed by the users.noreply.-domain of either github.com or the GitHub Enterprise Server. A way to get the user id of a GitHub app is to query the user API at api.github.com/users/self-hosted-renovate[bot] (github.com) or github.enterprise.com/api/v3/users/self-hosted-renovate[bot] (GitHub Enterprise Server).

Features awaiting implementation

  • The automergeStrategy configuration option has not been implemented for this platform, and all values behave as if the value auto was used. Renovate will use the merge strategy configured in the GitHub repository itself, and this cannot be overridden yet

Open items

The below list of features and bugs were current when this page was generated on September 22, 2023.

Feature requests

  • Use GitHub block quotes extension #24550
  • Allow user to set a certain commit body when enabling auto-merge on a PR #21451
  • Long-term caching for GitHub issues list #16079
  • Implement the explicit automergeStrategy for the GitHub platform. #10869
  • Allow assignees option to be a github team #7368
  • Add the ability to assign PRs to a github project board #3616

Bug reports

  • GitHub: Renovate recreates autoclosed branch out of schedule even with updateNotScheduled: false #24539