diff --git a/docs/usage/getting-started/running.md b/docs/usage/getting-started/running.md index 47627c45e73922227202a1e82e663ed91dd1b192..b54255aa066f22ed118512a9207a70a4f0d808e8 100644 --- a/docs/usage/getting-started/running.md +++ b/docs/usage/getting-started/running.md @@ -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 diff --git a/lib/modules/platform/azure/index.md b/lib/modules/platform/azure/index.md index d8fadac49eb1b228f35e1c16650096f56633bf32..61e0aa4ad25554aa36b35b03efb88f52e4c79022 100644 --- a/lib/modules/platform/azure/index.md +++ b/lib/modules/platform/azure/index.md @@ -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 diff --git a/lib/modules/platform/bitbucket-server/index.md b/lib/modules/platform/bitbucket-server/index.md index b73b98eeabf3c9f2166522f781ebdf0e7f792b8a..ea768b8a3ba7016033cf57619b3fcf071fd1fd8f 100644 --- a/lib/modules/platform/bitbucket-server/index.md +++ b/lib/modules/platform/bitbucket-server/index.md @@ -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) diff --git a/lib/modules/platform/bitbucket/index.md b/lib/modules/platform/bitbucket/index.md index 5655abc9c04c8aae97e4b260734d1cd6b532c7e1..bb46379afce1a7083ad7950dca2700d1cf9e82d4 100644 --- a/lib/modules/platform/bitbucket/index.md +++ b/lib/modules/platform/bitbucket/index.md @@ -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) diff --git a/lib/modules/platform/gitea/index.md b/lib/modules/platform/gitea/index.md index f79c49a29e3d77bfdfc645e19b5ca04f6fb73404..3484f92f48237b5960c459e7cdd41172026fbadb 100644 --- a/lib/modules/platform/gitea/index.md +++ b/lib/modules/platform/gitea/index.md @@ -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. diff --git a/lib/modules/platform/github/index.md b/lib/modules/platform/github/index.md index b0f378dba227aa8ad1592c54cdebb067b7a2771d..9e9ff428d480c90ec4300907628e3fb499daa818 100644 --- a/lib/modules/platform/github/index.md +++ b/lib/modules/platform/github/index.md @@ -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 diff --git a/lib/modules/platform/gitlab/index.md b/lib/modules/platform/gitlab/index.md index 094ff3e670d8472b9c9b1d975bdda82c2a742254..6bbfd9a020b50ce51f68eab710123df31c54eb68 100644 --- a/lib/modules/platform/gitlab/index.md +++ b/lib/modules/platform/gitlab/index.md @@ -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