diff --git a/docs/configuration-options.md b/docs/configuration-options.md index 845b59b7..bacc8e50 100644 --- a/docs/configuration-options.md +++ b/docs/configuration-options.md @@ -67,6 +67,15 @@ It needs only read-only access privileges. Not required if SCM is GitHub.com. **`MEND_RNV_WEBHOOK_SECRET`**: Optional: Defaults to `renovate` +**`MEND_RNV_WEBHOOK_URL`**: [GitLab, Bitbucket Data Center only] Optional. +When set, webhooks will be installed on repos when Renovate is enabled. +The URL of the Renovate Server plus '/webhook'. (e.g. `http://renovate.yourcompany.com:8080/webhook` or `https://1.2.3.4/webhook`) +Must be accessible to receive incoming calls from the BitBucket Data Center. + +**`MEND_RNV_ADMIN_TOKEN`**: [GitLab, Bitbucket Data Center only] Optional: A token used for searching/add/removing repository webhooks. +Defaults to the primary Renovate user PAT when not provided in GitLab config. +Important: Webhooks will be only installed on repos that the account has at least `Maintainer` access to. + **`MEND_RNV_SERVER_API_SECRET`**: [Required if APIs enabled. Required on Renovate Enterprise Server] Set an API secret. Must match the Worker instances and Admin APIs for communicating with the Server. **`MEND_RNV_ADMIN_API_ENABLED`**: Optional: Set to 'true' to enable Admin APIs. Defaults to 'false'. diff --git a/docs/images/gitlab_webhook_details.png b/docs/images/gitlab_webhook_details.png new file mode 100644 index 00000000..e4cd404c Binary files /dev/null and b/docs/images/gitlab_webhook_details.png differ diff --git a/docs/images/gitlab_webhook_triggers.png b/docs/images/gitlab_webhook_triggers.png new file mode 100644 index 00000000..4d87a299 Binary files /dev/null and b/docs/images/gitlab_webhook_triggers.png differ diff --git a/docs/setup-for-gitlab.md b/docs/setup-for-gitlab.md index e9d4e1e6..8f4c6ab5 100644 --- a/docs/setup-for-gitlab.md +++ b/docs/setup-for-gitlab.md @@ -2,54 +2,127 @@ ## Configure Renovate Bot Account on GitLab -### Renovate Bot Account +Two main parts to Bot setup: + +1. **Create the Renovate Bot user account** on GitLab - and get the **PAT** + +Personal Access Token (PAT) for the user account will used by your Renovate server for interacting with your repos on GitLab. + +2. **Create Webhooks** to respond to activity on the repo. + +Without webhooks, Renovate jobs will run only on the configured schedule, or by API call. +Jobs triggered by webhooks jump the queue, and are scheduled to run as soon as possible. + +### Step 1a: Renovate Bot user Account + +In GitLab, the "Renovate Bot" is not an App or Plugin; it's a GitLab user account that's been given the right permissions on the repository. Create a GitLab user account to act as the "Renovate Bot". -If you are running your own instance of GitLab, it's suggested to name the account "Renovate Bot" with username "renovate-bot". -Note: In GitLab, the "Renovate Bot" is not an App or Plugin; it's a GitLab user account that's been given the right permissions and System Hooks. -You should use a dedicated "bot account" for Renovate, instead of using someone's personal user account. -Apart from reducing the chance of conflicts, it is better for teams if the actions they see from Renovate are clearly marked as coming from a dedicated bot account and not from a teammate's account, which could be confusing at times. -e.g. Did the bot automerge that PR, or did a human do it? +> [!NOTE] +> +> You should use a dedicated "bot account" for Renovate, instead of using someone's personal user account. +> +> Apart from reducing the chance of conflicts, it is better for teams if the actions they see from Renovate are clearly marked as coming from a dedicated bot account and not from a teammate's account, which could be confusing at times. +> e.g. Did the bot automerge that PR, or did a human do it? + +#### Self-hosted GitLab: +- If you are running your own instance of GitLab, it's suggested to name the account "Renovate Bot" with username "renovate-bot". + +#### GitLab Cloud: +- If your repos are on GitLab.com, create a new user account on GitLab cloud. +You will need a globally unique name for the bot, for instance "yourcompany-renovate". -### Personal Access Token +### Step 1b: Generate a Personal Access Token (PAT) -Once the account is created, create a Personal Access Token for it with the following permissions: +Once the account is created, [create a Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for the new Renovate user account. + +Assign the following permissions: * `api` * `read_user` * `write_repository` -### System Hook +Keep the PAT handy for the Configuration of the Renovate Self-Hosted App to set `MEND_RNV_GITLAB_PAT`. -To activate Mend Renovate's webhook ability, create a System Hook that points to the Renovate installation. +### Step 2: Add Webhooks -Create a System Hook (in Admin area) +Webhooks allow GitLab to ping your Renovate server whenever an activity occurs on the designated repositories or groups. +Activities like a new commit, a merged PR, a change to a package file, etc will trigger Renovate to run a new job on that repo. +Renovate can also respond to checkbox activities in PRs and the Dependency Dashboard. -1. Set the webhook URL to point to the Renovate server url followed by `/webhook`. (e.g. `http://renovate.yourcompany.com:8080/webhook` or `https://1.2.3.4/webhook`) -2. Set the webhook secret to the same value configured for `MEND_RNV_WEBHOOK_SECRET` (defaults to `renovate`) -3. Set Hook triggers for: - * `Push events` - * `Merge request events` +> [!NOTE] +> +> You can still run Renovate without webhooks. +> - Renovate Jobs will run on a schedule, which is highly configurable. +> - The Admin APIs can be used to trigger App Sync and to run a Renovate job on a single repo. + +You can enable webhooks on your GitLab repos manually, or with automation. + +#### Option: Automatic webhook creation + +When enabled, will automatically install webhooks for all repos that are enabled with Renovate. Attempts are made to remove webhooks when repos are uninstalled. + +Webhook installation requires an admin user account that has `Maintainer` access to the repos. + +> [!NOTE] +> +> This admin account used for webhooks can be the repo owner account, or it can be another account that has more limited access to the repos. +> +> The Renovate user account can be used, but it would require an upgrade in minimum permissions (from `Developer` to `Maintainer`) on the repos it manages webhooks on. + +To enable automatic webhook creation: + +Set `MEND_RNV_WEBHOOK_URL`: +- When set, webhooks will be installed on repos when Renovate is enabled. +- Set the webhook URL to point to the Renovate server url followed by `/webhook`. (e.g. `http://renovate.yourcompany.com:8080/webhook` or `https://1.2.3.4/webhook`) + +Set `MEND_RNV_ADMIN_TOKEN`: [Optional] +- Could be repo owner account, or special high-privilege account. +- Defaults to the primary Renovate user PAT when not provided. +- Important: Webhooks will be only installed on repos that the account has at least `Maintainer` access to. + +#### Option: Manually add webhooks + +Add a **Group webhook** to each GitLab Group that you want webhooks triggered on. +- This is an easy way to cover webhooks for all repos in the group. +- Webhooks coming from Repositories that haven't enabled Renovate will be ignored. -Remember: Renovate's webhook listener binds to port 8080 inside its container, but you can map it (using Docker) to whatever external port you require, including port 80. +You can add **Repo webhooks** to each individual repo that you want webhooks enabled for. +- This might be suitable if you are only installing Renovate on a small number of repos or don't have access to Group webhooks. +- A good option if you want fine-grained control over which repos trigger webhooks to your Renovate server. -Set the "Secret Token" to the same value configured for `MEND_RNV_WEBHOOK_SECRET`, or set it to `"renovate"` if you left it as default. +> [!WARNING] +> +> Avoid using **Server hooks** because there they will not trigger `Issues events`, such as using checkboxes in the Dependency Dashboard issue. -Once your System Hook is added, Renovate's webhook handler will receive events from _all_ repositories. -Therefore, Renovate maintains a list of all repositories it has access to and discards events from all others. +**Set webhook properties as shown below:** -### Repo Webhooks +![GitLab webhook details](images/gitlab_webhook_details.png) -Because Issue events aren't included in System hooks, a webhook must be individually configured for each repository in which you want the Dependency Dashboard issue to be interactive. +##### URL +- Set the webhook URL to point to the Renovate server url followed by `/webhook`. (e.g. `http://renovate.yourcompany.com:8080/webhook` or `https://1.2.3.4/webhook`) -In the Repository settings, create a Webhook with the following settings: -1. Set the webhook URL - same as System Hook URL -2. Set the webhook secret - same as System Hook secret -3. Set Hook triggers for: - * `Issue events` +##### Name (Optional) +- You can set a name for the webhook: ie. "renovate" -This will need to be repeated for every repository that is onboarded to the Renovate Bot account. -It is usually easiest to create the repo webhook while adding the Renovate Bot account to a repo. +> [!TIP] +> +> Renovate's webhook listener binds to port 8080 inside its container, but you can map it (using Docker) to whatever external port you require, including port 80. + +##### Secret token +- Set the webhook secret to the same value configured for `MEND_RNV_WEBHOOK_SECRET` (defaults to `renovate`) + +##### Trigger +- Set event triggers for: + * `Push events` (All branches) + * `Issues events` + * `Merge request events` + +![GitLab webhook triggers](images/gitlab_webhook_triggers.png) + +##### SSL Verification + +- Diasble SSL verification unless required by your server ## Run Mend Renovate Self-hosted App @@ -90,7 +163,7 @@ You can run Mend Renovate Self-hosted App from a Docker command line prompt, or **`MEND_RNV_SERVER_PORT`**: The port on which the server listens for webhooks and api requests. Defaults to 8080. -**`MEND_RNV_GITLAB_PAT`**: Personal Access Token for the GitLab bot account. +**`MEND_RNV_GITLAB_PAT`**: Personal Access Token (PAT) for the GitLab bot account. **`MEND_RNV_ADMIN_API_ENABLED`**: Set to 'true' to enable Admin APIs. Defaults to 'false'. @@ -98,6 +171,10 @@ You can run Mend Renovate Self-hosted App from a Docker command line prompt, or **`MEND_RNV_WEBHOOK_SECRET`**: Must match the secret sent by the GitLab webhooks. Defaults to 'renovate'. +**`MEND_RNV_WEBHOOK_URL`**: [Optional] Set to the URL of your webhook handler to enable automatic webhook creation. (eg. `http://renovate.yourcompany.com:8080/webhook`) + +**`MEND_RNV_ADMIN_TOKEN`**: [Optional] Used when automatically adding webhooks. Provide a PAT for a user with `Maintainer` access to repos. + **`GITHUB_COM_TOKEN`**: A Personal Access Token for a user account on github.com **Additional Configuration options**