Skip to content

Commit

Permalink
docs(running renovate): move authentication info into platform readmes (
Browse files Browse the repository at this point in the history 
#14654)
  • Loading branch information
@HonkingGoose
HonkingGoose committed Apr 10, 2022
1 parent 3e910bb commit f3e0462
Show file tree
Hide file tree
Showing 7 changed files with 160 additions and 92 deletions.
100 changes: 8 additions & 92 deletions docs/usage/getting-started/running.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -153,100 +153,16 @@ Regardless of platform, you need to select a user account for `renovate` to assu
It is recommended to be `@renovate-bot` if you are using a self-hosted server with free choice of usernames.
It is also recommended that you configure `config.gitAuthor` with the same identity as your Renovate user, e.g. like `"gitAuthor": "Renovate Bot <renovate@whitesourcesoftware.com>"`.

#### GitHub (Enterprise Server)
#### Docs

First, [create a Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for the bot account (select "repo" scope).
Configure it either as `token` in your `config.js` file, or in environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.
Read the platform-specific docs to learn how to setup authentication on your platform:

For GitHub Enterprise Server set the `endpoint` in your `config.js` to `https://github.enterprise.com/api/v3/`.

##### 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](https://docs.github.com/en/developers/apps/getting-started-with-apps).

When creating the GitHub App give it the following permissions:

- Checks: Read & write
- Contents: Read & write
- Issues: Read & write
- Metadata: Read-only
- Pull requests: Read & write
- Commit statuses: Read & write
- Dependabot alerts: Read-only
- Workflows: Read & write
- Members: 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`:

**`username:"self-hosted-renovate[bot]"`**

The slug name of your app with `[bot]` appended

**`gitAuthor:"Self-hosted Renovate Bot <123456+self-hosted-renovate[bot]@users.noreply.github.enterprise.com>"`**

The [GitHub App associated email](https://github.community/t/logging-into-git-as-a-github-app/115916/2) 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](https://docs.github.com/en/rest/reference/users#get-a-user) at `api.github.com/user/self-hosted-renovate[bot]` (github.com) or `github.enterprise.com/api/v3/uer/self-hosted-renovate[bot]` (GitHub Enterprise Server).

**`token:"x-access-token:${github-app-installation}"`**

The token needs to be prefixed with `x-access-token` and be a [GitHub App Installation token](https://docs.github.com/en/developers/apps/building-github-apps/authenticating-with-github-apps#authenticating-as-an-installation).

<!-- prettier-ignore -->
!!! note
The installation tokens expire after 1 hour and need to be regenerated regularly.
Alternatively as environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.

**`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.

#### GitLab

First, [create a personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for the bot account (select `read_user`, `api` and `write_repository` scopes, or `read_user`, `read_api` and `read_repository` for dry runs).
Configure it either as `token` in your `config.js` file, or in environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.
Don't forget to configure `platform=gitlab` somewhere in config.

#### Bitbucket Cloud

First, [create an AppPassword](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) for the bot account.
Give the bot App password the following permission scopes:

- [`account`](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#account) (Account: Read)
- [`team`](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#team) (Workspace membership: Read)
- [`issue:write`](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#issue-write) (Issues: Write)
- [`pullrequest:write`](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#pullrequest-write) (Pull requests: Write)

The bot also needs to be able to validate the workspace membership status of pull-request reviewers, for that, [create a new user group](https://support.atlassian.com/bitbucket-cloud/docs/organize-workspace-members-into-groups/) in the workspace with the **Create repositories** permission and add the bot user to it.

Configure it as `password` in your `config.js` file, or in environment variable `RENOVATE_PASSWORD`, or via CLI `--password=`.
Also be sure to configure the `username` for your bot account too.
Don't forget to configure `platform=bitbucket` somewhere in config.

#### Bitbucket Server

Create a [Personal Access Token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) for your bot account.
Configure it as `password` in your `config.js` file, or in environment variable `RENOVATE_PASSWORD`, or via CLI `--password=`.
Also configure the `username` for your bot account too, if you decided not to name it `@renovate-bot`.
Don't forget to configure `platform=bitbucket-server` somewhere in config.

If you use MySQL or MariaDB you must set `unicodeEmoji` to `false` in the bot config (`RENOVATE_CONFIG_FILE`) to prevent issues with emojis.

#### Azure DevOps

First, [create a Personal Access Token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page) for the bot account.
Configure it either as `token` in your `config.js` file, or in environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.
Don't forget to configure `platform=azure` somewhere in config.

#### Gitea

First, [create an access token](https://docs.gitea.io/en-us/api-usage/#authentication-via-the-api) for your bot account.
Configure it as `token` in your `config.js` file, or in environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.
Don't forget to configure `platform=gitea` somewhere in config.
- [Azure DevOps](https://docs.renovatebot.com/modules/platform/azure/)
- [Bitbucket Cloud](https://docs.renovatebot.com/modules/platform/bitbucket/)
- [Bitbucket Server](https://docs.renovatebot.com/modules/platform/bitbucket-server/)
- [Gitea](https://docs.renovatebot.com/modules/platform/gitea/)
- [github.com and GitHub Enterprise Server](https://docs.renovatebot.com/modules/platform/github/)
- [GitLab](https://docs.renovatebot.com/modules/platform/gitlab/)

### GitHub.com token for release notes

Expand Down
11 changes: 11 additions & 0 deletions lib/modules/platform/azure/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
# Azure DevOps and Azure DevOps Server

## Authentication

First, [create a Personal Access Token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page) for the bot account.
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=azure` somewhere in your Renovate config file.

## 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 Azure Repos repository itself, and this cannot be overridden yet
15 changes: 15 additions & 0 deletions lib/modules/platform/bitbucket-server/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,20 @@
# Bitbucket Server Support

## Authentication

First, create a [HTTP access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) for the bot account.
Let Renovate use your HTTP access token by doing _one_ of the following:

- Set your HTTP access token as a `password` in your `config.js` file
- Set your HTTP access token as an environment variable `RENOVATE_PASSWORD`
- Set your HTTP access token when you run Renovate in the CLI with `--password=`

Remember to set `platform=bitbucket-server` somewhere in your Renovate config file.

If you're not using `@renovate-bot` as username then set your custom `username` for the bot account.

If you use MySQL or MariaDB you must set `unicodeEmoji` to `false` in the bot config (`RENOVATE_CONFIG_FILE`) to prevent issues with emojis.

## Unsupported platform features/concepts

- Adding assignees to PRs not supported (does not seem to be a Bitbucket concept)
Expand Down
25 changes: 25 additions & 0 deletions lib/modules/platform/bitbucket/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,30 @@
# Bitbucket Cloud

## Authentication

First, [create an app password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) for the bot account.
Give the bot app password the following permission scopes:

| Permission | Scope |
| ---------------------------------------------------------------------------------------------------- | -------------------------- |
| [`account`](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#account) | Account: Read |
| [`team`](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#team) | Workspace membership: Read |
| [`issue:write`](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#issue-write) | Issues: Write |
| [`pullrequest:write`](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#pullrequest-write) | Pull requests: Write |

The bot also needs to validate the workspace membership status of pull-request reviewers, for that, [create a new user group](https://support.atlassian.com/bitbucket-cloud/docs/organize-workspace-members-into-groups/) in the workspace with the **Create repositories** permission and add the bot user to it.

Let Renovate use your app password by doing _one_ of the following:

- Set your app password as a `password` in your `config.js` file
- Set your app password as an environment variable `RENOVATE_PASSWORD`
- Set your app password when you run Renovate in the CLI with `--password=`

Remember to:

- Set the `username` for the bot account
- Set `platform=bitbucket` somewhere in your Renovate config file

## Unsupported platform features/concepts

- Adding assignees to PRs not supported (does not seem to be a Bitbucket concept)
Expand Down
11 changes: 11 additions & 0 deletions lib/modules/platform/gitea/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,17 @@ Renovate uses modern Git upload filters to suppress large blob downloads.
For Gitea you need to manually enable upload filters.
Read the official [Gitea docs](https://docs.gitea.io/en-us/clone-filters/) for more information.

## Authentication

First, [create a Personal Access Token](https://docs.gitea.io/en-us/api-usage/#authentication) for the bot account.
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=gitea` somewhere in your Renovate config file.

## Unsupported platform features/concepts

- **Adding reviewers to PRs not supported**: Gitea versions older than v1.14.0 do not have the required API.
Expand Down
66 changes: 66 additions & 0 deletions lib/modules/platform/github/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,71 @@
# GitHub and GitHub Enterprise

## Authentication

First, [create a Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) for the bot account, select `repo` scope.

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

## 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](https://docs.github.com/en/developers/apps/getting-started-with-apps).

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` |
| 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`:

**`username:"self-hosted-renovate[bot]"`**

The slug name of your app with `[bot]` appended

**`gitAuthor:"Self-hosted Renovate Bot <123456+self-hosted-renovate[bot]@users.noreply.github.enterprise.com>"`**

The [GitHub App associated email](https://github.community/t/logging-into-git-as-a-github-app/115916/2) 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](https://docs.github.com/en/rest/reference/users#get-a-user) at `api.github.com/user/self-hosted-renovate[bot]` (github.com) or `github.enterprise.com/api/v3/uer/self-hosted-renovate[bot]` (GitHub Enterprise Server).

**`token:"x-access-token:${github-app-installation}"`**

The token needs to be prefixed with `x-access-token` and be a [GitHub App Installation token](https://docs.github.com/en/developers/apps/building-github-apps/authenticating-with-github-apps#authenticating-as-an-installation).

<!-- prettier-ignore -->
!!! note
The installation tokens expire after 1 hour and need to be regenerated regularly.
Alternatively as environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.

**`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.

## 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
24 changes: 24 additions & 0 deletions lib/modules/platform/gitlab/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,29 @@
# GitLab

## Authentication

First, [create a Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for the bot account.

For real runs, give the PAT these scopes:

- `read_user`
- `api`
- `write_repository`

For dry runs, give the PAT these scopes:

- `read_user`
- `read_api`
- `read_repository`

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=gitlab` somewhere in your Renovate config file.

## 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 accept the Merge Request without further configuration, and respect the strategy defined in the Merge Request, and this cannot be overridden yet
Expand Down

0 comments on commit f3e0462

Please sign in to comment.