renovatebot · rarkins · Aug 12, 2021 · Aug 10, 2021 · Aug 10, 2021 · Aug 10, 2021
diff --git a/docs/usage/configure-renovate.md b/docs/usage/configure-renovate.md
diff --git a/docs/usage/self-hosting.md → docs/usage/examples/self-hosting.md b/docs/usage/self-hosting.md → docs/usage/examples/self-hosting.md
@@ -1,4 +1,4 @@
-# Self-Hosting Renovate
+# Self-Hosting Examples
 
 ## Installing Renovate OSS CLI
 
@@ -182,6 +182,20 @@ workflows:
                   - main
 ```
 
+#### Renovate config file validation when using CircleCI
+
+How to validate your config as part of your workflow:
+
+```yml
+version: '2.1'
+orbs:
+  renovate: daniel-shuy/renovate@2.1
+workflows:
+  lint:
+    jobs:
+      - renovate/validate-config
+```
+
 ### GitLab CI/CD pipeline
 
 For GitLab pipelines we recommend you use the [renovate-runner project on GitLab](https://gitlab.com/renovate-bot/renovate-runner).
@@ -190,124 +204,6 @@ You can also find the configuration steps there.
 
 For self-hosted GitLab clone/import the [renovate-runner](https://gitlab.com/renovate-bot/renovate-runner) project to your instance.
 
-## Configuration
-
-Self-hosted Renovate can be configured using any of the following (or a combination):
-
-- A `config.js` file (can also be named `config.json`, but you can't have both at the same time)
-- CLI parameters
-- Environment variables
-
-Note that some Renovate configuration options are _only_ available for self-hosting, and so can only be configured using one of the above methods.
-These are described in the [Self-hosted Configuration](./self-hosted-configuration.md) doc.
-
-If you are configuring using environment variables, there are two possibilities:
-
-- Upper-cased, camel-cased, `RENOVATE_`-prefixed single config options like `RENOVATE_TOKEN=abc123` or `RENOVATE_GIT_AUTHOR=a@b.com`
-- Set `RENOVATE_CONFIG` to a [stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) version of the full JSON config, e.g. `RENOVATE_CONFIG='{"token":"abc123","gitAuthor":"a@b.com"}'`
-
-If you combine both of the above then any single config option in the environment variable will override what's in `RENOVATE_CONFIG`.
-
-Note: it's also possible to change the default prefix from `RENOVATE_` using `ENV_PREFIX`. e.g. `ENV_PREFIX=RNV_ RNV_TOKEN=abc123 renovate`.
-
-## Authentication
-
-Regardless of platform, you need to select a user account for `renovate` to assume the identity of, and generate a Personal Access Token.
-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)
-
-First, [create a personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) for the bot account (select "repo" permissions).
-Configure it either as `token` in your `config.js` file, or in environment variable `RENOVATE_TOKEN`, or via CLI `--token=`.
-
-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 and 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
-
-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 contain 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).
-**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.
-Auto discovery does not work with a GitHub App.
-Alternatively as comma-seperated 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 CE/EE
-
-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).
-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://confluence.atlassian.com/bitbucket/app-passwords-828781300.html) for the bot account.
-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/integrate/get-started/authentication/pats) 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 a 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.
-
-## GitHub.com token for release notes
-
-If you are running on any platform except github.com, it's important to also configure the environment variable `GITHUB_COM_TOKEN` containing a personal access token for github.com.
-This account can actually be _any_ account on GitHub, and needs only read-only access.
-It's used when fetching release notes for repositories in order to increase the hourly API limit.
-It's also OK to configure the same as a host rule instead, if you prefer that.
-
-**Note:** If you're using Renovate in a project where dependencies are loaded from github.com (such as Go modules hosted on GitHub) it is highly recommended to add a token as you will run in the rate limit from the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies.
-
 ## File/directory usage
 
 By default, Renovate stores all files in the `renovate/` subdirectory of the operating system's temporary directory, e.g. `/tmp/renovate/`.

diff --git a/docs/usage/getting-started/installing-onboarding.md b/docs/usage/getting-started/installing-onboarding.md
@@ -0,0 +1,133 @@
+# Installing and onboarding Renovate into repositories
+
+## Repository installation
+
+Renovate administrators can configure Renovate to either "autodiscover" installed repositories, or configure a fixed list of repository names to operate on.
+
+If the adminstrator has configured a fixed list of repositories then the only way to "install" Renovate on an additional repository is for it to be manually added for the next run or restart.
+
+Otherwise, the process for adding new repositories to a Renovate installation can vary:
+
+- Most commonly, you run Renovate as a dedicated "bot user" with global config option `autodiscover` set to `true`, meaning that it will run on every repository which it's been granted access to
+- If using a GitHub App (including WhiteSource Renovate on `github.com`) then you can install the app into a user or organization account and select either "All repositories", or "Select repositories" and pick them manually
+
+### Hosted GitHub.com App
+
+Installing/enabling WhiteSource's Renovate GitHub App is simple.
+
+First, navigate to [https://github.com/apps/renovate](https://github.com/apps/renovate) and click the Install button:
+
+![Github App Install button](assets/images/github-app-install.png)
+
+The only choice you need to make is whether to run Renovate on all repositories or on selected repositories:
+
+![Github App repositories](assets/images/github-app-choose-repos.png)
+
+Renovate will ignore any repositories that don't have known package files, as well as any forks, so you can enable Renovate for all your repositories with no problems.
+That said, most people run Renovate on selected repositories.
+Unfortunately GitHub doesn't offer a "select all except X,Y,Z" option, so you must select each repository where you want Renovate to run.
+
+Once you're done selecting repositories for Renovate to run on, click the green Install button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process.
+
+Note: if you are using the WhiteSource Renovate App then it has a custom behavior for forked repositories.
+If you choose "All repositories" when installing then forked repositories will be skipped by default, while if you choose "Select repositories" then they will be processed by Renovate even if they're a fork.
+
+### Hosted GitLab.com App
+
+Unfortunately WhiteSource's hosted GitLab app needed to be taken offline indefinitely until a viable security model for bots on GitLab.com is available.
+For more details on GitLab security for bots, please see the [GitLab Bot Security](../gitlab-bot-security.md) doc.
+
+## Repository onboarding
+
+Once you have enabled Renovate on a repository, you will receive a "Configure Renovate" Pull Request looking something like this:
+
+![Onboarding](assets/images/onboarding.png)
+
+### No risk onboarding
+
+Conveniently, Renovate will not make any changes to your repository or raise any further Pull Requests until after you _merge_ the onboarding Pull Request.
+If there is anything about the Pull Request that you don't like or understand, take your time to read the [documentation](https://docs.renovatebot.com) or ask questions on the [discussions forum on GitHub](https://github.com/renovatebot/renovate/discussions) and merge the PR only once you're satisfied with the result.
+
+You can edit your Renovate configuration **within the `renovate/configure` branch** and Renovate will keep updating the description in the PR to match, so you can work on the config until you're satisfied with the results.
+
+### Check for warnings
+
+If you have any Warnings or Errors listed, see if you need or want to make any changes to address them.
+Warnings and errors should be fixed on the base branch (e.g. `main`) so that Renovate can recreate its Configure Renovate PR on its next cycle.
+
+### Configuration location
+
+The "Configure Renovate" PR will include a `renovate.json` file in the root directory, with suggested default settings.
+If you don't want a `renovate.json` file in your repository you can use one of the following files instead:
+
+- `renovate.json5`
+- `.github/renovate.json`
+- `.github/renovate.json5`
+- `.gitlab/renovate.json`
+- `.gitlab/renovate.json5`
+- `.renovaterc`
+- `.renovaterc.json`
+- `package.json` (deprecated)
+
+#### package.json
+
+Note: this approach has been deprecated and will be removed in a future release.
+
+You can add the same settings to a `"renovate"` section in your `package.json` file instead.
+The `package.json` file must be located at the root of your repository.
+This is handy if you are already using a `package.json` file anyway, e.g. when you're working on a JavaScript project.
+The configuration in your `package.json` will apply to the whole project (this includes other, nested `package.json` files).
+
+### Customised defaults
+
+Renovate provides a `renovate.json` file, with default settings that will work for most cases.
+Sometimes Renovate detects that a override to these defaults is needed, and will add this override automatically, such as:
+
+- Automatically enabling Angular-style semantic commits if your repository uses them
+- Determining whether to use dependency range pinning depending on the detected project type (app vs library)
+
+### Common overrides
+
+Please check the docs on this website for an exhaustive Configuration Reference.
+To help you get started, here are some of the most commonly changed (overridden) configuration settings:
+
+- **rangeStrategy**: By default (with zero config) it's `"replace"` however the `"config:base"` preset overrides it to `"auto"`. If you don't want to pin dependency versions and retain ranges, add the `":preserveSemverRanges"` preset to the `extends` array
+- **labels**: Labels to assign to Pull Requests
+- **assignees**: GitHub user(s) to assign the Pull Requests to
+
+Renovate will update your PR description each time it finds changes.
+
+### Merge
+
+Once you're done checking and configuring in your Configure Renovate PR, it's time to merge it to enable the real Pull Requests to begin.
+
+## Repository re-configuration
+
+There will be times when you need to change your Renovate config.
+There are two recommended approaches:
+
+- Reconfigure via PR
+- Nuke the config and re-onboard
+
+### Reconfigure via PR
+
+If you want to make config edits directly, follow these steps:
+
+1. Create a new Git branch to work on
+1. Install or update the `renovate` package globally (`npm i -g renovate` or `yarn global add renovate`) to get the `renovate-config-validator` program
+1. Edit your Renovate configuration file
+1. Validate your config by running `renovate-config-validator`
+1. If the improved config passes the validation, merge the branch into your mainline branch
+
+### Nuke config and re-onboard
+
+Perhaps you really liked the interactive onboarding PR and want to use it again.
+You can follow the steps below to nuke the config and get a new PR.
+Any existing Renovate PRs will be closed after you've completed these steps.
+
+1. Find your original `Configure Renovate` PR
+1. Rename the original PR to something else, e.g. `Configure Renovate - old`
+1. Remove the current Renovate configuration file (e.g. `renovate.json`) from your mainline branch
+
+Following these steps will trick Renovate into thinking that your repository was _never_ onboarded, and will trigger a new "Configure Renovate" PR.
+If you're using the hosted WhiteSource Renovate App and you don't receive a new onboarding PR within a few hours, then please create a Discussions post to request staff trigger it manually.