Updated GitLab webhook instructions (#585)

* Added new page for GitHub setup instructions * Updates to the Config Options page * Updates to the GitHub setup page * Updates to the GitHub setup page * Added setup doc for GitLab * Update to GitLab setup doc * Added setup doc for Bitbucket * Updates to Bitbucket setup doc * Update product name to "Mend Renovate Self-hosted" * Add link to Enterprise Edition Docker images on ghcr.io * Updated configuration docs with Setup Guides. Provided information about the 10-repo license key. * Updated configuration docs with Setup Guides. Provided information about the 10-repo license key. * Removed 10-repo licence key information * Apply suggestions from code review Co-authored-by: Rhys Arkins <[email protected]> * Updated all product references to "Mend Renovate Self-hosted App". Updated all references to Bitbucket to "Bitbucket Data Center" * Restored info about the 10-repo license key for Renovate CE * Added "App" to text for link to configuration options page * Use headings instead of bolding * Added new page for GitHub setup instructions * Updates to the Config Options page * Updates to the GitHub setup page * Updates to the GitHub setup page * Added setup doc for GitLab * Update to GitLab setup doc * Added setup doc for Bitbucket * Updates to Bitbucket setup doc * Update product name to "Mend Renovate Self-hosted" * Add link to Enterprise Edition Docker images on ghcr.io * Updated configuration docs with Setup Guides. Provided information about the 10-repo license key. * Updated configuration docs with Setup Guides. Provided information about the 10-repo license key. * Removed 10-repo licence key information * Apply suggestions from code review Co-authored-by: Rhys Arkins <[email protected]> * Updated all product references to "Mend Renovate Self-hosted App". Updated all references to Bitbucket to "Bitbucket Data Center" * Restored info about the 10-repo license key for Renovate CE * Added "App" to text for link to configuration options page * Use headings instead of bolding * Removed old configure-renovate files * Removed old configure-renovate files * Updated GitLab webhook guide. Included automatic webhooks. * Updated manual webhook section * Fixes and minor updates * Repositioned images of webhook setup * Added Webhook properties to the essential config list * Reordered configuration properties * Updated manual webhook section * Fixes and minor updates * Repositioned images of webhook setup * Added Webhook properties to the essential config list * Reordered configuration properties * Added Webhook properties to the essential config list * Added more instructions for using Renovate Bot user PAT in GitLab config * Added configuration options for Mend_RNV_WEBHOOK_URL and MEND_RNV_ADMIN_TOKEN --------- Co-authored-by: Rhys Arkins <[email protected]>
mend · Oct 9, 2024 · d9315f9 · d9315f9
1 parent 7aaff84
commit d9315f9
Show file tree

Hide file tree

Showing 4 changed files with 116 additions and 30 deletions.
diff --git 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
diff --git a/docs/images/gitlab_webhook_triggers.png b/docs/images/gitlab_webhook_triggers.png
diff --git 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,14 +163,18 @@ 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'.
 
 **`MEND_RNV_SERVER_API_SECRET`**: Required if Admin APIs are enabled, or if running Enterprise Edition.
 
 **`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**