diff --git a/docs/README.md b/docs/README.md index f947d100..64aaac41 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,8 @@ -# Mend Renovate Community Edition and Enterprise Edition Documentation +# Mend Renovate Self-hosted App Documentation -This repository provides documentation specific to Mend Renovate Community Edition (Renovate CE) and Enterprise Edition (Renovate EE), and does not duplicate anything that is relevant and can be found in the [Renovate OSS repository](https://github.com/renovatebot/renovate). +This repository provides documentation specific to the Mend Renovate Self-hosted Apps - Community Edition (Renovate CE) and Enterprise Edition (Renovate EE), and does not duplicate anything that is relevant and can be found in the [Renovate OSS repository](https://github.com/renovatebot/renovate). -Mend Renovate CE was formerly known as "Mend Renovate On-Premises". +Mend Renovate Community Edition was formerly known as "Mend Renovate On-Premises". ## Supported platforms @@ -10,16 +10,20 @@ The following platforms are supported by Mend Renovate Community Edition and Ent - GitHub.com - GitHub Enterprise Server - GitLab Enterprise Edition -- Bitbucket Server/Datacenter (in beta) +- Bitbucket Data Center (in beta) ## Documentation contents 1. [Overview](./overview.md) 1. Installation ([Helm](./installation-helm.md)) +1. Getting Started + - [Setup guide for GitHub](setup-for-github.md) + - [Setup guide for GitLab](setup-for-gitlab.md) + - [Setup guide for Bitbucket Data Center](setup-for-bitbucket-data-center.md) 1. Configuration - - Renovate Community Edition - ([GitHub](./configure-renovate-ce-github.md), [GitLab](./configure-renovate-ce-gitlab.md)) - - Renovate Enterprise Edition - ([GitHub](./configure-renovate-ee-github.md), [GitLab](./configure-renovate-ee-gitlab.md)) - - Configuration - [Environment variables](configuration-options.md) + - [Self-hosted App configuration options](configuration-options.md) + - [Configure PostgreSQL DB](configure-postgres-db.md) + - [Configure High Server Availability](high-server-availability.md) 1. Migration ([Renovate On-Premises to Renovate Community](./migrating-to-renovate-ce.md)) 1. API Documentation - [Admin APIs](./api.md) diff --git a/docs/configuration-options.md b/docs/configuration-options.md index 1d3ef4fa..845b59b7 100644 --- a/docs/configuration-options.md +++ b/docs/configuration-options.md @@ -1,4 +1,4 @@ -# Mend Renovate Configuration Options +# Mend Renovate Self-hosted App Configuration Options Mend Renovate Enterprise Edition runs with one or more **_Server_** containers and one or more **_Worker_** containers. Mend Renovate Community Edition runs on a single Server container that also performs the Worker actions. @@ -11,7 +11,7 @@ Separately, you can provide configuration for the Renovate Core. See the end of The following environment variables apply to **Mend Renovate Community Edition** and the **Mend Renovate Enterprise Edition Server**. Environment variables for the **Mend Renovate Enterprise Worker** are in the next section. -### Mend licensing config +### Mend Licensing Config **`MEND_RNV_ACCEPT_TOS`**: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). @@ -29,34 +29,44 @@ Environment variables for the **Mend Renovate Enterprise Worker** are in the nex **`MEND_RNV_MC_TOKEN`**: [Enterprise only] The authentication token required when using Merge Confidence Workflows. Set this to 'auto' (default), or provide the value of a merge confidence API token. -### Source code management (SCM) connection details +### Connection to the Source Code Management (SCM) This section contains configuration variables for connecting to your source code repository. Use the appropriate settings to define connection details to your specific SCM. **`MEND_RNV_PLATFORM`**: The type of SCM. Options: `github`, `gitlab`, `bitbucket-server`. -**`MEND_RNV_ENDPOINT`**: This is the API endpoint for your SCM. Required for self-hosted SCMs; not for GitHub.com. Include the trailing slash. +**`MEND_RNV_ENDPOINT`**: This is the API endpoint for your SCM. Not required for GitHub.com. Include the trailing slash. -**`MEND_RNV_GITHUB_APP_ID`**: [GitHub only] The GitHub App ID of the provisioned Renovate app on GitHub. +#### GitHub connection variables -**`MEND_RNV_GITHUB_APP_KEY`**: [GitHub only] A string representation of the private key of the provisioned Renovate app on GitHub. To insert the value directly into a Docker Compose environment variable, open the PEM file in a text editor and replace all new lines with "\n" so that the entire key is on one line. Alternatively, you can skip setting this key as an environment variable and instead mount it as a file to the path specified by `RNV_GITHUB_PEM_FILE_PATH`, as shown in the example Docker Compose file. +**`MEND_RNV_GITHUB_APP_ID`**: The GitHub App ID of the provisioned Renovate app on GitHub. -**`RNV_GITHUB_PEM_FILE_PATH`**: [GitHub only] The file path for GitHub app key. Defaults to `/usr/src/app/renovate.private-key.pem`. +**`MEND_RNV_GITHUB_APP_KEY`**: A string representation of the private key of the provisioned Renovate app on GitHub. To insert the value directly into a Docker Compose environment variable, open the PEM file in a text editor and replace all new lines with "\n" so that the entire key is on one line. Alternatively, you can skip setting this key as an environment variable and instead mount it as a file to the path specified by `RNV_GITHUB_PEM_FILE_PATH`, as shown in the example Docker Compose file. -**`MEND_RNV_GITHUB_BOT_USER_ID`**: [GitHub only] Optional: The bot user ID that will be used in `gitAuthor` (example author `myBotName[bot] <123456+myBotName[bot]@users.noreply.github.com` and the user id is `123456`). The value can be found by calling `https://api.github.com/users/{appName}[bot]` under the `id` key (replace the `{appName}` with the actual app name). +**`RNV_GITHUB_PEM_FILE_PATH`**: The file path for GitHub app key. Defaults to `/usr/src/app/renovate.private-key.pem`. + +**`MEND_RNV_GITHUB_BOT_USER_ID`**: Optional: The bot user ID that will be used in `gitAuthor` (example author `myBotName[bot] <123456+myBotName[bot]@users.noreply.github.com` and the user id is `123456`). The value can be found by calling `https://api.github.com/users/{appName}[bot]` under the `id` key (replace the `{appName}` with the actual app name). Note: By default Renovate server will attempt to call this endpoint once during startup (both CE and EE server) and it does not require authentication. If you wish to skip this call for any reason you will need to provide the value in `MEND_RNV_GITHUB_BOT_USER_ID=` -**`MEND_RNV_GITLAB_PAT`**: [GitLab only] Personal Access Token for the GitLab bot account. +#### GitLab connection variables -**`MEND_RNV_WEBHOOK_SECRET`**: Optional: Defaults to `renovate` +**`MEND_RNV_GITLAB_PAT`**: Personal Access Token for the GitLab bot account. + +#### Bitbucket connection variables + +**`MEND_RNV_BITBUCKET_USER`**: Renovate Bot user account (“Bitbucket User” access only) + +**`MEND_RNV_BITBUCKET_PAT`**: BitBucket access token for the bot user `MEND_RNV_BITBUCKET_USER` -### Optional Mend Renovate configuration +### Server Config Options **`GITHUB_COM_TOKEN`**: A Personal Access Token for a user account on github.com (i.e. _not_ an account on your GitHub Enterprise instance). This is used for retrieving changelogs and release notes from repositories hosted on github.com and it does not matter who it belongs to. It needs only read-only access privileges. Not required if SCM is GitHub.com. +**`MEND_RNV_WEBHOOK_SECRET`**: Optional: Defaults to `renovate` + **`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'. @@ -234,7 +244,6 @@ Escalation is reset when no mismatching versions are found during the version ch Note: You can inspect the `Renovate-EE-Version` in the response header of any Renovate API call to see the current version of the responding Server. - **`MEND_RENOVATE_FORKS_PROCESSING`**: controls the value of Renovate `forkProcessing` in the worker. valid values - `disabled`: sets Renovate `forkProcessing=disabled` for all jobs @@ -246,14 +255,12 @@ Note: You can inspect the `Renovate-EE-Version` in the response header of any Re - `forkProcessing=disabled` if "All repositories" - others platforms: `forkProcessing=disabled` - **`MEND_RNV_MERGE_CONFIDENCE_ENDPOINT`**: [Enterprise only] defines the endpoint used to retrieve Merge Confidence data by querying this API. this config option only need to be defined in the server, and it will be passed to the worker automatically. defaults to https://developer.mend.io/. Notes: This option overrides the deprecated `RENOVATE_X_MERGE_CONFIDENCE_API_BASE_URL` flag. - ### Postgres DB Configuration To configure Mend Renovate to use a PostgreSQL database, the following environment variables should be supplied to the Server containers (not required for Worker environment config). diff --git a/docs/configure-renovate-ce-github.md b/docs/configure-renovate-ce-github.md deleted file mode 100644 index 4be0a283..00000000 --- a/docs/configure-renovate-ce-github.md +++ /dev/null @@ -1,189 +0,0 @@ -# Configuration - Mend Renovate Community Edition for GitHub - -## Create and Configure the GitHub App (bot) - -Before running Mend Renovate, you need to provision it as an App on GitHub, and retrieve the ID + private key provided. - -If you're running a self-hosted instance of GitHub Enterprise, it is suggested to name the app "Renovate" so that it shows up as easily recognizable as "renovate[bot]" in Pull Requests. -If you're running against `github.com` then the name Renovate is already taken by the hosted Mend Renovate app, so you will need something else like "YourCompany Renovate". - -The App requires the following permissions: - -- Repository permissions - - Administration: Read-only - - Checks: Read & write - - Commit statuses: Read & write - - Contents: Read & write - - Dependabot alerts: Read-only (optional) - - Issues: Read & write - - Metadata: Read-only - - Pull Requests: Read & write - - Workflows: Read & write -- Organization permissions - - Members: Read-only - -The App should also subscribe to the following webhook events: - -- Security Advisory -- Check run -- Check suite -- Issues -- Pull request -- Push -- Repository -- Status - -Description, Homepage, User authorization callback URL, and Setup URL are all unimportant so you may set them to whatever you like. - -The Mend Renovate webhook listener binds to port 8080 by default, however it will bind to `process.env.PORT` instead if that is defined. -Note: The Mend Renovate image takes care of exposing port 8080 of the container, so if you change this port then you will need to take care of any exposing/mapping of ports yourself. -In the [Docker Compose example config](https://github.com/mend/renovate-cc-ee/tree/main/examples/), the default port 8080 is used and then mapped to port 80 on the host. - -For the Webhook URL field, point it to `/webhook` on port 80 (or whatever port you mapped to) of the server that you will run Mend Renovate on, e.g. http://1.2.3.4/webhook -Be sure to enter a webhook secret too. -If you don't care about the value, then enter 'renovate' as that is the default secret that the webhook handler process uses. - -You can use the [Renovate icon](https://docs.renovatebot.com/assets/images/logo.png) for the app/bot if you desire. - -## Configure Mend Renovate CE - -### Mend Renovate environment variables - -Mend Renovate requires configuration via environment variables in addition to Renovate OSS's regular configuration: - -**`MEND_RNV_ACCEPT_TOS`**: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). - -**`MEND_RNV_LICENSE_KEY`**: Provide a valid license key for Renovate Community Edition. - -> [!Note] -> -> To run Renovate Community Edition with **up to 10 repositories**, you can use this unregistered license key: -> -> `eyJsaW1pdCI6IjEwIn0=.30440220457941b71ea8eb345c729031718b692169f0ce2cf020095fd328812f4d7d5bc1022022648d1a29e71d486f89f27bdc8754dfd6df0ddda64a23155000a61a105da2a1` -> -> For a free license key for an **unrestricted number of repositories** on Renovate Community Edition, register with the form on the [Renovate Community Edition web page](https://www.mend.io/mend-renovate-community/). - -**`MEND_RNV_PLATFORM`**: Set this to `github`. - -**`MEND_RNV_ENDPOINT`**: This is the API endpoint for your GitHub Enterprise installation. Required for GitHub Enterprise Server; not for GitHub.com. Include the trailing slash. - -**`MEND_RNV_GITHUB_APP_ID`**: The GitHub App ID of the provisioned Renovate app on GitHub. - -**`MEND_RNV_GITHUB_APP_KEY`**: A string representation of the private key of the provisioned Renovate app on GitHub. To insert the value directly into a Docker Compose environment variable, open the PEM file in a text editor and replace all new lines with "\n" so that the entire key is on one line. Alternatively, you can skip setting this key as an environment variable and instead mount it as a file to the path specified by `RNV_GITHUB_PEM_FILE_PATH`, as shown in the example Docker Compose file. - -**`RNV_GITHUB_PEM_FILE_PATH`**: The file path for GitHub app key. Defaults to `/usr/src/app/renovate.private-key.pem`. - -**`MEND_RNV_WEBHOOK_SECRET`**: Optional: Defaults to `renovate` - -**`MEND_RNV_ADMIN_API_ENABLED`**: Optional: Set to 'true' to enable Admin APIs. Defaults to 'false'. - -**`MEND_RNV_SERVER_API_SECRET`**: Required if Admin APIs are enabled. - -**`MEND_RNV_SERVER_PORT`**: The port on which the server listens for webhooks and api requests. Defaults to 8080. - -**`MEND_RNV_SQLITE_FILE_PATH`**: Optional: Provide a path to persist the database. (eg. '/db/renovate-ce.sqlite', where 'db' is defined as a volume) - -> [!IMPORTANT] -> The container running the Renovate CE service requires read, write, and execute (rwx) permissions for the parent folder of the SQLite file. Additionally, the process inside the container executes with uid=1000 (ubuntu) and gid=0 (root). - -The [sqlite3](https://sqlite.org/cli.html) CLI tool is preinstalled in the Renovate CE/EE(server) images, allowing direct interaction with the underlying SQLite database. - -For example, Let `MEND_RNV_SQLITE_FILE_PATH=/db/renovate-ce.sqlite`: -```shell -ubuntu@23cf5aaa72ed:/usr/src/app$ sqlite3 -SQLite version 3.31.1 2020-01-27 19:55:54 -Enter ".help" for usage hints. -Connected to a transient in-memory database. -Use ".open FILENAME" to reopen on a persistent database. -sqlite> .open -readonly /db/renovate-ce.sqlite -sqlite> .tables -job_queue migrations org repo task_queue -sqlite> -``` - -**`MEND_RNV_CRON_JOB_SCHEDULER`**: Optional: Accepts a 5-part cron schedule. Defaults to `0 * * * *` (i.e. once per hour exactly on the hour). This cron job triggers the Renovate bot against the projects in the SQLite database. If decreasing the interval then be careful that you do not exhaust the available hourly rate limit of the app on GitHub server or cause too much load. - -**`MEND_RNV_CRON_APP_SYNC`**: Optional: Accepts a 5-part cron schedule. Defaults to `0 0,4,8,12,16,20 * * *` (every 4 hours, on the hour). This cron job performs autodiscovery against the platform and fills the SQLite database with projects. - -**`GITHUB_COM_TOKEN`**: A Personal Access Token for a user account on github.com (i.e. _not_ an account on your GitHub Enterprise instance). This is used for retrieving changelogs and release notes from repositories hosted on github.com and it does not matter who it belongs to. It needs only read-only access privileges. Note: This is required if you are using a self-hosted GitHub Enterprise or GitLab instance but should not be configured if your `RENOVATE_ENDPOINT` is `https://api.github.com`. - -**`MEND_RNV_AUTODISCOVER_FILTER`**: a string of a comma separated values. (e.g. `org1/*, org2/test*, org2/test*`). Same behavior as Renovate [autodiscoverFilter](https://docs.renovatebot.com/self-hosted-configuration/#autodiscoverfilter) - -> [!WARNING] -> The Renovate CLI [autodiscover](https://docs.renovatebot.com/self-hosted-configuration/#autodiscover) configuration option is disabled at the client level. Repository filtering should solely rely on server-side filtering using `MEND_RNV_AUTODISCOVER_FILTER`. - -**`MEND_RNV_ENQUEUE_JOBS_ON_STARTUP`**: The job enqueue behavior on start (or restart). Defaults to `discovered`. (Note that the behavior can be different if the database is persisted or not) -- `enabled`: enqueue a job for all available repositories -- `discovered`: enqueue a job only for newly discovered repositories -- `disabled`: No jobs are enqueued - -**`MEND_RNV_LOG_HISTORY_DIR`**: Optional: Specify a directory path to save Renovate job log files, recommended to be an external volume to preserve history. Log files will be saved in a `./ORG_NAME/REPO_NAME/` hierarchy under the specified folder. Log file name structure is as follows: `(_.log)`. - -Where: -- ``: timestamp in the format `YYYYMMDD_HHmmss` local time -- ``: random 10 character alphanumeric string used as - [Renovate log context](https://docs.renovatebot.com/self-hosted-configuration/#logcontext) for cross referencing logs. - -For Example: -Let `MEND_RNV_LOG_HISTORY_DIR=/home/renovate/logs`, repository=`org/repo` - -The corresponding Renovate job log file will be saved as: - -``` -/home/renovate/logs/org/repo/20231025_104229_6e4ecdc343.log -``` - -> [!IMPORTANT] -> Logs are saved by the Renovate OSS cli, so the corresponding folder must exist in the CE/EE-Worker container. - -**`MEND_RNV_LOG_HISTORY_TTL_DAYS`**: Optional: The number of days to save log files. Defaults to 30. - -**`MEND_RNV_LOG_HISTORY_CLEANUP_CRON`**: Optional: Specifies a 5-part cron schedule. Defaults to `0 0 * * *` (every midnight). This cron job cleans up log history in the directory defined by `MEND_RNV_LOG_HISTORY_DIR`. It deletes any log file that exceeds the `MEND_RNV_LOG_HISTORY_TTL_DAYS` value. - -**`MEND_RNV_WORKER_EXECUTION_TIMEOUT`**: Optional: Sets the maximum execution duration of a Renovate CLI scan in minutes. Defaults to 60. - -### Core Renovate Configuration - -The core Renovate OSS functionality can be configured using environment variables (e.g. `RENOVATE_XXXXXX`) or via a `config.js` file that you mount inside the Mend Renovate container to `/usr/src/app/config.js`. - -**npm Registry** If using your own npm registry, you may find it easiest to update your Docker Compose file to include a volume that maps an `.npmrc` file to `/home/ubuntu/.npmrc`. The RC file should contain `registry=...` with the registry URL your company uses internally. This will allow Renovate to find shared configs and other internally published packages. - -## Run Mend Renovate - -You can run Mend Renovate from a Docker command line prompt, or by using a Docker Compose file. An example is provided below. - -**Docker Compose File**: Renovate CE on GitHub - -```yaml -version: "3.6" -services: - renovate: - image: ghcr.io/mend/renovate-ce:-full - restart: on-failure - ports: - - "80:8080" # Receive webhooks on port 80 - environment: - # Optional: Define log level. Set to Debug for more verbose output - # - LOG_LEVEL=DEBUG - # Provide Mend License and accept Terms of Service - - MEND_RNV_ACCEPT_TOS # Set to 'y' to accept the Mend Renovate Terms of Service - - MEND_RNV_LICENSE_KEY # Set this to the key you received by email - # Provide connection details for the GitHub App - - MEND_RNV_PLATFORM=github - - MEND_RNV_ENDPOINT # Required for GitHub Enterprise Server; not for GitHub.com. Include the trailing slash. - - MEND_RNV_GITHUB_APP_ID # GitHub App ID - - MEND_RNV_GITHUB_APP_KEY # GitHub App Key (PEM file). Alternatively mount as a volume below - - MEND_RNV_WEBHOOK_SECRET # Optional: defaults to 'renovate' - # Optional settings for Mend Renovate - # - MEND_RNV_ADMIN_API_ENABLED # Optional: Set to 'true' to enable Admin APIs. Defaults to 'false'. - # - MEND_RNV_SERVER_API_SECRET # Required if Admin APIs are enabled - # - MEND_RNV_SQLITE_FILE_PATH=/db/renovate-ce.sqlite # Optional: Provide a path to persist the database. Needs 'db' volume defined (below). - # - MEND_RNV_CRON_JOB_SCHEDULER # Optional Job enqueue schedule: defaults to '0 * * * *' (hourly, on the hour) - # - MEND_RNV_CRON_APP_SYNC # Optional AppSync schedule: defaults to '0 0,4,8,12,16,20 * * *' (every 4 hours, on the hour) - # Core Renovate settings - # - GITHUB_COM_TOKEN # Personal Access Token for github.com (used for retrieving changelogs) - # volumes: - # Optional: You can use a file mount to persist the database between sessions - # - "/tmp/db/:/db/" # Unix-style file mounting for the db - # - "C:\\tmp/db/:/db/" # Windows-style file mounting for the db -``` diff --git a/docs/configure-renovate-ce-gitlab.md b/docs/configure-renovate-ce-gitlab.md deleted file mode 100644 index 798489dc..00000000 --- a/docs/configure-renovate-ce-gitlab.md +++ /dev/null @@ -1,200 +0,0 @@ -# Configuration - Mend Renovate Community Edition for GitLab - -## Configure Renovate Bot Account on GitLab - -### Renovate Bot Account - -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? - -### Personal Access Token - -Once the account is created, create a Personal Access Token for it with the following permissions: - * `api` - * `read_user` - * `write_repository` - -### System Hook - -To activate Mend Renovate's webhook ability, create a System Hook that points to the Renovate installation. - -Create a System Hook (in Admin area) - -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` - -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. - -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. - -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. - -### Repo Webhooks - -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. - -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` - -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. - - -## Configure Mend Renovate CE - -### Mend Renovate environment variables - -Mend Renovate requires configuration via environment variables in addition to Renovate OSS's regular configuration: - -**`MEND_RNV_ACCEPT_TOS`**: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). - -**`MEND_RNV_LICENSE_KEY`**: Provide a valid license key for Renovate Community Edition. - -> [!Note] -> -> To run Renovate Community Edition with **up to 10 repositories**, you can use this unregistered license key: -> -> `eyJsaW1pdCI6IjEwIn0=.30440220457941b71ea8eb345c729031718b692169f0ce2cf020095fd328812f4d7d5bc1022022648d1a29e71d486f89f27bdc8754dfd6df0ddda64a23155000a61a105da2a1` -> -> For a free license key for an **unrestricted number of repositories** on Renovate Community Edition, register with the form on the [Renovate Community Edition web page](https://www.mend.io/mend-renovate-community/). - -**`MEND_RNV_PLATFORM`**: Set this to `gitlab`. - -**`MEND_RNV_ENDPOINT`**: This is the API endpoint for your GitLab host. e.g. like `https://gitlab.company.com/api/v4/`. Include the trailing slash. - -**`MEND_RNV_GITLAB_PAT`**: Personal Access Token for the GitLab bot account. - -**`MEND_RNV_WEBHOOK_SECRET`**: Optional: Defaults to `renovate` - -**`MEND_RNV_ADMIN_API_ENABLED`**: Optional: Set to 'true' to enable Admin APIs. Defaults to 'false'. - -**`MEND_RNV_SERVER_API_SECRET`**: Required if Admin APIs are enabled. - -**`MEND_RNV_SERVER_PORT`**: The port on which the server listens for webhooks and api requests. Defaults to 8080. - -**`MEND_RNV_SQLITE_FILE_PATH`**: Optional: Provide a path to persist the database. (eg. '/db/renovate-ce.sqlite', where 'db' is defined as a volume) - -> [!IMPORTANT] -> The container running the Renovate CE service requires read, write, and execute (rwx) permissions for the parent folder of the SQLite file. Additionally, the process inside the container executes with uid=1000 (ubuntu) and gid=0 (root). - -The [sqlite3](https://sqlite.org/cli.html) CLI tool is preinstalled in the Renovate CE/EE(server) images, allowing direct interaction with the underlying SQLite database. - -For example, Let `MEND_RNV_SQLITE_FILE_PATH=/db/renovate-ce.sqlite`: -```shell -ubuntu@23cf5aaa72ed:/usr/src/app$ sqlite3 -SQLite version 3.31.1 2020-01-27 19:55:54 -Enter ".help" for usage hints. -Connected to a transient in-memory database. -Use ".open FILENAME" to reopen on a persistent database. -sqlite> .open -readonly /db/renovate-ce.sqlite -sqlite> .tables -job_queue migrations org repo task_queue -sqlite> -``` - -**`MEND_RNV_CRON_JOB_SCHEDULER`**: Optional: Accepts a 5-part cron schedule. Defaults to `0 * * * *` (i.e. once per hour exactly on the hour). This cron job triggers the Renovate bot against the projects in the SQLite database. If decreasing the interval then be careful that you do not cause too much load. - -**`MEND_RNV_CRON_APP_SYNC`**: Optional: Accepts a 5-part cron schedule. Defaults to `0 0,4,8,12,16,20 * * *` (every 4 hours, on the hour). This cron job performs autodiscovery against the platform and fills the SQLite database with projects. - -**`GITHUB_COM_TOKEN`**: A Personal Access Token for a user account on github.com (i.e. _not_ an account on your GitHub Enterprise instance). This is used for retrieving changelogs and release notes from repositories hosted on github.com and it does not matter who it belongs to. It needs only read-only access privileges. Note: This is required if you are using a self-hosted GitHub Enterprise or GitLab instance but should not be configured if your `RENOVATE_ENDPOINT` is `https://api.github.com`. - -**`MEND_RNV_AUTODISCOVER_FILTER`**: a string of a comma separated values (e.g. `org1/*, org2/test*, org2/test*`). Same behavior as Renovate [autodiscoverFilter](https://docs.renovatebot.com/self-hosted-configuration/#autodiscoverfilter) - -> [!WARNING] -> The Renovate CLI [autodiscover](https://docs.renovatebot.com/self-hosted-configuration/#autodiscover) configuration option is disabled at the client level. Repository filtering should solely rely on server-side filtering using `MEND_RNV_AUTODISCOVER_FILTER`. - -**`MEND_RNV_ENQUEUE_JOBS_ON_STARTUP`**: The job enqueue behavior on start (or restart). Defaults to `discovered`. (Note that the behavior can be different if the database is persisted or not) -- `enabled`: enqueue a job for all available repositories -- `discovered`: enqueue a job only for newly discovered repositories -- `disabled`: No jobs are enqueued - -**`MEND_RNV_LOG_HISTORY_DIR`**: Optional: Specify a directory path to save Renovate job log files, recommended to be an external volume to preserve history. Log files will be saved in a `./ORG_NAME/REPO_NAME/` hierarchy under the specified folder. Log file name structure is as follows: `(_.log)`. - -Where: -- ``: timestamp in the format `YYYYMMDD_HHmmss` local time -- ``: random 10 character alphanumeric string used as - [Renovate log context](https://docs.renovatebot.com/self-hosted-configuration/#logcontext) for cross referencing logs. - -For Example: -Let `MEND_RNV_LOG_HISTORY_DIR=/home/renovate/logs`, repository=`org/repo` - -The corresponding Renovate job log file will be saved as: - -``` -/home/renovate/logs/org/repo/20231025_104229_6e4ecdc343.log -``` - -> [!IMPORTANT] -> Logs are saved by the Renovate OSS cli, so the corresponding folder must exist in the CE/EE-Worker container. - -**`MEND_RNV_LOG_HISTORY_TTL_DAYS`**: Optional: The number of days to save log files. Defaults to 30. - -**`MEND_RNV_LOG_HISTORY_CLEANUP_CRON`**: Optional: Specifies a 5-part cron schedule. Defaults to `0 0 * * *` (every midnight). This cron job cleans up log history in the directory defined by `MEND_RNV_LOG_HISTORY_DIR`. It deletes any log file that exceeds the `MEND_RNV_LOG_HISTORY_TTL_DAYS` value. - -**`MEND_RNV_WORKER_EXECUTION_TIMEOUT`**: Optional: Sets the maximum execution duration of a Renovate CLI scan in minutes. Defaults to 60. - -### Core Renovate Configuration - -The core Renovate OSS functionality can be configured using environment variables (e.g. `RENOVATE_XXXXXX`) or via a `config.js` file that you mount inside the Mend Renovate container to `/usr/src/app/config.js`. - -**npm Registry** If using your own npm registry, you may find it easiest to update your `docker-compose.yml` to include a volume that maps an `.npmrc` file to `/home/ubuntu/.npmrc`. The RC file should contain `registry=...` with the registry URL your company uses internally. This will allow Renovate to find shared configs and other internally published packages. - -## Enabling Renovate on Repositories - -To enable Renovate on a repository, in the project's _Settings -> Members_ section, add the bot user and give it `Developer` permissions. - -Remember to add a webhook with "Issue events" to the repository if you wish to enable interactive dashboard issues. (See _Create Repo Webhooks_ above) - -Adding Renovate as a Developer to a repository cause a system hook to be sent to Renovate which in turn enqueues a job for the Renovate Worker. -The repository should receive an onboarding PR immediately after. - -## Run Mend Renovate - -You can run Mend Renovate from a Docker command line prompt, or by using a Docker Compose file. An example is provided below. - -**Docker Compose File**: Renovate CE on GitLab - -```yaml -version: "3.6" -services: - renovate: - image: ghcr.io/mend/renovate-ce:-full - restart: on-failure - environment: - # Optional: Define log level. Set to Debug for more verbose output - # - LOG_LEVEL=DEBUG - # Provide Mend License and accept Terms of Service - - MEND_RNV_ACCEPT_TOS # Set to 'y' to accept the Mend Renovate Terms of Service - - MEND_RNV_LICENSE_KEY # Set this to the key you received by email - # Provide connection details for the GitLab Bot - - MEND_RNV_PLATFORM=gitlab - - MEND_RNV_ENDPOINT # GitLab endpoint, include trailing slash - - MEND_RNV_GITLAB_PAT # Personal Access Token for bot account - - MEND_RNV_WEBHOOK_SECRET # Optional: defaults to 'renovate' - # Optional settings for Mend Renovate - # - MEND_RNV_ADMIN_API_ENABLED # Optional: Set to 'true' to enable Admin APIs. Defaults to 'false'. - # - MEND_RNV_SERVER_API_SECRET # Required if Admin APIs are enabled - # - MEND_RNV_SQLITE_FILE_PATH=/db/renovate-ce.sqlite # Optional: Provide a path to persist the database. Needs 'db' volume defined (below). - # - MEND_RNV_CRON_JOB_SCHEDULER # Optional Job enqueue schedule: defaults to '0 * * * *' (hourly, on the hour) - # - MEND_RNV_CRON_APP_SYNC # Optional AppSync schedule: defaults to '0 0,4,8,12,16,20 * * *' (every 4 hours, on the hour) - # Core Renovate settings - # - GITHUB_COM_TOKEN # Personal Access Token for github.com (used for retrieving changelogs) - ports: - - "80:8080" # Receive webhooks on port 80 - # volumes: - # Optional: You can use a file mount to persist the database between sessions - # - "/tmp/db/:/db/" # Unix-style file mounting for the db - # - "C:\\tmp/db/:/db/" # Windows-style file mounting for the db -``` diff --git a/docs/configure-renovate-ee-github.md b/docs/configure-renovate-ee-github.md deleted file mode 100644 index 0d3ff077..00000000 --- a/docs/configure-renovate-ee-github.md +++ /dev/null @@ -1,217 +0,0 @@ -# Configuration - Mend Renovate Enterprise Edition for GitHub - -## Create and Configure the GitHub App (bot) - -Before running Mend Renovate, you need to provision it as an App on GitHub, and retrieve the ID + private key provided. - -If you're running a self-hosted instance of GitHub Enterprise, it is suggested to name the app "Renovate" so that it shows up as easily recognizable as "renovate[bot]" in Pull Requests. -If you're running against `github.com` then the name Renovate is already taken by the hosted Mend Renovate app, so you will need something else like "YourCompany Renovate". - -The App requires the following permissions: - -- Repository permissions - - Administration: Read-only - - Checks: Read & write - - Contents: Read & write - - Issues: Read & write - - Metadata: Read-only - - Pull Requests: Read & write - - Commit statuses: Read & write - - Dependabot alerts: Read-only (optional) - - Workflows: Read & write -- Organization permissions - - Members: Read-only - -The App should also subscribe to the following webhook events: - -- Security Advisory -- Check run -- Check suite -- Issues -- Pull request -- Push -- Repository -- Status - -Description, Homepage, User authorization callback URL, and Setup URL are all unimportant so you may set them to whatever you like. - -The Mend Renovate webhook listener binds to port 8080 by default, however it will bind to `process.env.PORT` instead if that is defined. -Note: The Mend Renovate image takes care of exposing port 8080 of the container, so if you change this port then you will need to take care of any exposing/mapping of ports yourself. -In the [Docker Compose example config](https://github.com/mend/renovate-cc-ee/tree/main/examples/), the default port 8080 is used and then mapped to port 80 on the host. - -For the Webhook URL field, point it to `/webhook` on port 80 (or whatever port you mapped to) of the server that you will run Mend Renovate on, e.g. http://1.2.3.4/webhook -Be sure to enter a webhook secret too. -If you don't care about the value, then enter 'renovate' as that is the default secret that the webhook handler process uses. - -You can use the [Renovate icon](https://docs.renovatebot.com/assets/images/logo.png) for the app/bot if you desire. - -## Configure Mend Renovate EE - -Renovate Enterprise runs with one **_Server_** container and one or more **_Worker_** containers. -See below for a list of environment variables that relate to each. - -### Environment variables - Renovate Enterprise Server - -**`MEND_RNV_ACCEPT_TOS`**: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). - -**`MEND_RNV_LICENSE_KEY`**: For a Renovate Enterprise license key, contact Mend via the [Renovate Enterprise webpage](https://www.mend.io/renovate-enterprise/). - -**`MEND_RNV_PLATFORM`**: Set this to `github`. - -**`MEND_RNV_ENDPOINT`**: This is the API endpoint for your GitHub Enterprise installation. Required for GitHub Enterprise Server; not for GitHub.com. Include the trailing slash. - -**`MEND_RNV_GITHUB_APP_ID`**: The GitHub App ID of the provisioned Renovate app on GitHub. - -**`MEND_RNV_GITHUB_APP_KEY`**: A string representation of the private key of the provisioned Renovate app on GitHub. To insert the value directly into a Docker Compose environment variable, open the PEM file in a text editor and replace all new lines with "\n" so that the entire key is on one line. Alternatively, you can skip setting this key as an environment variable and instead mount it as a file to the path specified by `RNV_GITHUB_PEM_FILE_PATH`, as shown in the example Docker Compose file. - -**`RNV_GITHUB_PEM_FILE_PATH`**: The file path for GitHub app key. Defaults to `/usr/src/app/renovate.private-key.pem`. - -**`MEND_RNV_WEBHOOK_SECRET`**: Optional: Defaults to `renovate` - -**`MEND_RNV_SERVER_API_SECRET`**: 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'. - -**`MEND_RNV_SERVER_PORT`**: The port on which the server listens for webhooks and api requests. Defaults to 8080. - -**`MEND_RNV_SQLITE_FILE_PATH`**: Optional: Provide a path to persist the database. (eg. '/db/renovate-ce.sqlite', where 'db' is defined as a volume) - -> [!IMPORTANT] -> The container running the Renovate EE server service requires read, write, and execute (rwx) permissions for the parent folder of the SQLite file. Additionally, the process inside the container executes with uid=1000 (node) and gid=1000 (node). - -The [sqlite3](https://sqlite.org/cli.html) CLI tool is preinstalled in the Renovate CE/EE(server) images, allowing direct interaction with the underlying SQLite database. - -For example, Let `MEND_RNV_SQLITE_FILE_PATH=/db/renovate-ce.sqlite`: -```shell -ubuntu@23cf5aaa72ed:/usr/src/app$ sqlite3 -SQLite version 3.31.1 2020-01-27 19:55:54 -Enter ".help" for usage hints. -Connected to a transient in-memory database. -Use ".open FILENAME" to reopen on a persistent database. -sqlite> .open -readonly /db/renovate-ce.sqlite -sqlite> .tables -job_queue migrations org repo task_queue -sqlite> -``` - -**`MEND_RNV_CRON_JOB_SCHEDULER`**: Optional: Accepts a 5-part cron schedule. Defaults to `0 * * * *` (i.e. once per hour exactly on the hour). This cron job triggers the Renovate bot against the projects in the SQLite database. If decreasing the interval then be careful that you do not exhaust the available hourly rate limit of the app on GitHub server or cause too much load. - -**`MEND_RNV_CRON_APP_SYNC`**: Optional: Accepts a 5-part cron schedule. Defaults to `0 0,4,8,12,16,20 * * *` (every 4 hours, on the hour). This cron job performs autodiscovery against the platform and fills the SQLite database with projects. - -**`GITHUB_COM_TOKEN`**: A Personal Access Token for a user account on github.com (i.e. _not_ an account on your GitHub Enterprise instance). This is used for retrieving changelogs and release notes from repositories hosted on github.com and it does not matter who it belongs to. It needs only read-only access privileges. Note: This is required if you are using a self-hosted GitHub Enterprise instance but should not be configured if your `RENOVATE_ENDPOINT` is `https://api.github.com`. - -**`MEND_RNV_AUTODISCOVER_FILTER`**: a string of a comma separated values (e.g. `org1/*, org2/test*, org2/test*`). Same behavior as Renovate [autodiscoverFilter](https://docs.renovatebot.com/self-hosted-configuration/#autodiscoverfilter) - -> [!WARNING] -> The Renovate CLI [autodiscover](https://docs.renovatebot.com/self-hosted-configuration/#autodiscover) configuration option is disabled at the client level. Repository filtering should solely rely on server-side filtering using `MEND_RNV_AUTODISCOVER_FILTER`. - -**`MEND_RNV_ENQUEUE_JOBS_ON_STARTUP`**: The job enqueue behavior on start (or restart). Defaults to `discovered`. (Note that the behavior can be different if the database is persisted or not) -- `enabled`: enqueue a job for all available repositories -- `discovered`: enqueue a job only for newly discovered repositories -- `disabled`: No jobs are enqueued - -**`MEND_RNV_MC_TOKEN`**: The merge confidence token used for Smart-Merge-Control authentication - -**`MEND_RNV_LOG_HISTORY_DIR`**: Optional: Specify a directory path to save Renovate job log files, recommended to be an external volume to preserve history between multiple workers. Log files will be saved in a `./ORG_NAME/REPO_NAME/` hierarchy under the specified folder. Log file name structure is as follows: `(_.log)`. - -Where: -- ``: timestamp in the format `YYYYMMDD_HHmmss` local time -- ``: random 10 character alphanumeric string used as - [Renovate log context](https://docs.renovatebot.com/self-hosted-configuration/#logcontext) for cross referencing logs. - -For Example: -Let `MEND_RNV_LOG_HISTORY_DIR=/home/renovate/logs`, repository=`org/repo` - -The corresponding Renovate job log file will be saved as: - -``` -/home/renovate/logs/org/repo/20231025_104229_6e4ecdc343.log -``` - -**`MEND_RNV_LOG_HISTORY_TTL_DAYS`**: Optional: The number of days to save log files. Defaults to 30. - -**`MEND_RNV_LOG_HISTORY_CLEANUP_CRON`**: Optional: Specifies a 5-part cron schedule. Defaults to `0 0 * * *` (every midnight). This cron job cleans up log history in the directory defined by `MEND_RNV_LOG_HISTORY_DIR`. It deletes any log file that exceeds the `MEND_RNV_LOG_HISTORY_TTL_DAYS` value. - -> [!IMPORTANT] -> Logs are saved by the Renovate OSS cli, so the corresponding folder must exist in the CE/EE-Worker container. - -### Environment variables - Renovate Enterprise Worker - -The Worker container needs to define only the following variables: - -* **`MEND_RNV_SERVER_HOSTNAME`**: The hostname of the Renovate Enterprise `server` container (eg. http://renovate-ee-server:8080) -* **`MEND_RNV_SERVER_API_SECRET`**: Set to same as Server -* **`MEND_RNV_ACCEPT_TOS`**: Set to same as Server -* **`MEND_RNV_LICENSE_KEY`**: Set to same as Server -* **`MEND_RNV_WORKER_EXECUTION_TIMEOUT`**: Optional: Sets the maximum execution duration of a Renovate CLI scan in minutes. Defaults to 60. - -## Configure Renovate Core - -The core Renovate OSS functionality can be configured using environment variables (e.g. `RENOVATE_XXXXXX`) or via a `config.js` file that you mount inside the Mend Renovate container to `/usr/src/app/config.js`. Both settings should be done in the worker. - -**npm Registry** If using your own npm registry, you may find it easiest to update your Docker Compose file to include a volume that maps an `.npmrc` file to `/home/ubuntu/.npmrc`. The RC file should contain `registry=...` with the registry URL your company uses internally. This will allow Renovate to find shared configs and other internally published packages. - -## Run Mend Renovate - -You can run Mend Renovate from a Docker command line prompt, or by using a Docker Compose file. An example is provided below. - -**Docker Compose File**: Renovate EE on GitHub - -```yaml -version: '3.6' - -x-controller-shared-variables: &variables-controller - MEND_RNV_SERVER_HOSTNAME: http://renovate-ee-server:8080 - MEND_RNV_SERVER_API_SECRET: # This secret will be used by the Worker and by Admin APIs - # Provide Mend License and accept Terms of Service - MEND_RNV_ACCEPT_TOS: # Set to 'y' to accept the Mend Renovate Terms of Service - MEND_RNV_LICENSE_KEY: # Set this to the Renovate Enterprise key obtained from Mend - -services: - renovate-ee-server: - restart: on-failure - image: ghcr.io/mend/renovate-ee-server: - ports: - - "80:8080" # Receive webhooks on port 80 - environment: - <<: *variables-controller - # Optional: Define log level. Set to Debug for more verbose output - # LOG_LEVEL: debug - # Provide connection details for the Renovate Bot/App - MEND_RNV_PLATFORM: # Set to `github` or `gitlab` - MEND_RNV_ENDPOINT: # Required for GitLab or GitHub Enterprise Server; not for GitHub.com. Include the trailing slash. - MEND_RNV_GITHUB_APP_ID: # GitHub Only! GitHub App ID - MEND_RNV_GITHUB_APP_KEY: # GitHub Only! GitHub App Key (PEM file). Alternatively mount as a volume below - MEND_RNV_WEBHOOK_SECRET: # Optional: defaults to 'renovate' - # Optional settings for Mend Renovate - # MEND_RNV_ADMIN_API_ENABLED: # Optional: Set to 'true' to enable Admin APIs. Defaults to 'false'. - # MEND_RNV_SQLITE_FILE_PATH: /db/renovate-ee.sqlite # Optional: Provide a path to persist the database. Needs 'db' volume defined (below). - # MEND_RNV_CRON_JOB_SCHEDULER: # Optional Job enqueue schedule: defaults to '0 * * * *' (hourly, on the hour) - # MEND_RNV_CRON_APP_SYNC: # Optional AppSync schedule: defaults to '0 0,4,8,12,16,20 * * *' (every 4 hours, on the hour) - # Core Renovate settings - # GITHUB_COM_TOKEN: # Personal Access Token for github.com (used for retrieving changelogs) - # volumes: - # Optional: You can use a file mount to persist the database between sessions - # - "/tmp/db/:/db/" # Unix-style file mounting for the db - # - "C:\\tmp/db/:/db/" # Windows-style file mounting for the db - healthcheck: - test: curl --fail http://renovate-ee-server:8080/health || exit 1 - interval: 60s - retries: 5 - start_period: 20s - timeout: 10s - - renovate-ee-worker: - restart: on-failure - deploy: - # Post deploy: - # $ docker-compose -f docker-compose-renovate-ee.yml up --scale renovate-ee-worker=3 -d --no-recreate - replicas: 2 - image: ghcr.io/mend/renovate-ee-worker:-full - depends_on: - - renovate-ee-server - environment: - <<: *variables-controller - # Optional: Define log level. Set to Debug for more verbose output - # LOG_LEVEL: debug -``` diff --git a/docs/configure-renovate-ee-gitlab.md b/docs/configure-renovate-ee-gitlab.md deleted file mode 100644 index 4589192d..00000000 --- a/docs/configure-renovate-ee-gitlab.md +++ /dev/null @@ -1,219 +0,0 @@ -# Configuration - Mend Renovate Enterprise Edition for GitLab - -## Configure Renovate Bot Account on GitLab - -### Renovate Bot Account - -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? - -### Personal Access Token - -Once the account is created, create a Personal Access Token for it with the following permissions: - * `api` - * `read_user` - * `write_repository` - -### System Hook - -To activate Mend Renovate's webhook ability, create a System Hook that points to the Renovate installation. - -Create a System Hook (in Admin area) - -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` - -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. - -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. - -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. - -### Repo Webhooks - -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. - -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` - -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. - - -## Configure Mend Renovate EE - -Renovate Enterprise runs with one **_Server_** container and one or more **_Worker_** containers. -See below for a list of environment variables that relate to each. - -### Environment variables - Renovate Enterprise Server - -**`MEND_RNV_ACCEPT_TOS`**: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). - -**`MEND_RNV_LICENSE_KEY`**: For a Renovate Enterprise license key, contact Mend via the [Renovate Enterprise webpage](https://www.mend.io/renovate-enterprise/). - -**`MEND_RNV_PLATFORM`**: Set this to `gitlab`. - -**`MEND_RNV_ENDPOINT`**: This is the API endpoint for your self-hosted GitLab instance installation. Include the trailing slash. (eg. `https://1.2.3.4/api/v4`) - -**`MEND_RNV_GITLAB_PAT`**: Personal Access Token for the GitLab bot account. - -**`MEND_RNV_WEBHOOK_SECRET`**: Optional: Defaults to `renovate` - -**`MEND_RNV_SERVER_API_SECRET`**: 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'. - -**`MEND_RNV_SERVER_PORT`**: The port on which the server listens for webhooks and api requests. Defaults to 8080. - -**`MEND_RNV_SQLITE_FILE_PATH`**: Optional: Provide a path to persist the database. (eg. '/db/renovate-ce.sqlite', where 'db' is defined as a volume) - -> [!IMPORTANT] -> The container running the Renovate EE server service requires read, write, and execute (rwx) permissions for the parent folder of the SQLite file. Additionally, the process inside the container executes with uid=1000 (node) and gid=1000 (node). - -The [sqlite3](https://sqlite.org/cli.html) CLI tool is preinstalled in the Renovate CE/EE(server) images, allowing direct interaction with the underlying SQLite database. - -For example, Let `MEND_RNV_SQLITE_FILE_PATH=/db/renovate-ce.sqlite`: -```shell -ubuntu@23cf5aaa72ed:/usr/src/app$ sqlite3 -SQLite version 3.31.1 2020-01-27 19:55:54 -Enter ".help" for usage hints. -Connected to a transient in-memory database. -Use ".open FILENAME" to reopen on a persistent database. -sqlite> .open -readonly /db/renovate-ce.sqlite -sqlite> .tables -job_queue migrations org repo task_queue -sqlite> -``` - -**`MEND_RNV_CRON_JOB_SCHEDULER`**: Optional: Accepts a 5-part cron schedule. Defaults to `0 * * * *` (i.e. once per hour exactly on the hour). This cron job triggers the Renovate bot against the projects in the SQLite database. If decreasing the interval then be careful that you do not cause too much load. - -**`MEND_RNV_CRON_APP_SYNC`**: Optional: Accepts a 5-part cron schedule. Defaults to `0 0,4,8,12,16,20 * * *` (every 4 hours, on the hour). This cron job performs autodiscovery against the platform and fills the SQLite database with projects. - -**`GITHUB_COM_TOKEN`**: A Personal Access Token for a user account on github.com (i.e. _not_ an account on your GitHub Enterprise instance). This is used for retrieving changelogs and release notes from repositories hosted on github.com and it does not matter who it belongs to. It needs only read-only access privileges. - -**`MEND_RNV_AUTODISCOVER_FILTER`**: a string of a comma separated values (e.g. `org1/*, org2/test*, org2/test*`). Same behavior as Renovate [autodiscoverFilter](https://docs.renovatebot.com/self-hosted-configuration/#autodiscoverfilter) - -> [!WARNING] -> The Renovate CLI [autodiscover](https://docs.renovatebot.com/self-hosted-configuration/#autodiscover) configuration option is disabled at the client level. Repository filtering should solely rely on server-side filtering using `MEND_RNV_AUTODISCOVER_FILTER`. - -**`MEND_RNV_ENQUEUE_JOBS_ON_STARTUP`**: The job enqueue behavior on start (or restart). Defaults to `discovered`. (Note that the behavior can be different if the database is persisted or not) -- `enabled`: enqueue a job for all available repositories -- `discovered`: enqueue a job only for newly discovered repositories -- `disabled`: No jobs are enqueued - -**`MEND_RNV_MC_TOKEN`**: The merge confidence token used for Smart-Merge-Control authentication - -**`MEND_RNV_LOG_HISTORY_DIR`**: Optional: Specify a directory path to save Renovate job log files, recommended to be an external volume to preserve history between multiple workers. Log files will be saved in a `./ORG_NAME/REPO_NAME/` hierarchy under the specified folder. Log file name structure is as follows: `(_.log)`. - -Where: -- ``: timestamp in the format `YYYYMMDD_HHmmss` local time -- ``: random 10 character alphanumeric string used as - [Renovate log context](https://docs.renovatebot.com/self-hosted-configuration/#logcontext) for cross referencing logs. - -For Example: -Let `MEND_RNV_LOG_HISTORY_DIR=/home/renovate/logs`, repository=`org/repo` - -The corresponding Renovate job log file will be saved as: - -``` -/home/renovate/logs/org/repo/20231025_104229_6e4ecdc343.log -``` - -_> [!IMPORTANT] -> Logs are saved by the Renovate OSS cli, so the corresponding folder must exist in the CE/EE-Worker container._ - -**`MEND_RNV_LOG_HISTORY_TTL_DAYS`**: Optional: The number of days to save log files. Defaults to 30. - -**`MEND_RNV_LOG_HISTORY_CLEANUP_CRON`**: Optional: Specifies a 5-part cron schedule. Defaults to `0 0 * * *` (every midnight). This cron job cleans up log history in the directory defined by `MEND_RNV_LOG_HISTORY_DIR`. It deletes any log file that exceeds the `MEND_RNV_LOG_HISTORY_TTL_DAYS` value. - -### Environment variables - Renovate Enterprise Worker - -The Worker container needs to define only the following variables: - -* **`MEND_RNV_SERVER_HOSTNAME`**: The hostname of the Renovate Enterprise `server` container (eg. http://renovate-ee-server:8080) -* **`MEND_RNV_SERVER_API_SECRET`**: Set to same as Server -* **`MEND_RNV_ACCEPT_TOS`**: Set to same as Server -* **`MEND_RNV_LICENSE_KEY`**: Set to same as Server -* **`MEND_RNV_WORKER_EXECUTION_TIMEOUT`**: Optional: Sets the maximum execution duration of a Renovate CLI scan in minutes. Defaults to 60. - -## Configure Renovate Core - -The core Renovate OSS functionality can be configured using environment variables (e.g. `RENOVATE_XXXXXX`) or via a `config.js` file that you mount inside the Mend Renovate container to `/usr/src/app/config.js`. Both settings should be done in the worker. - -**npm Registry** If using your own npm registry, you may find it easiest to update your Docker Compose file to include a volume that maps an `.npmrc` file to `/home/ubuntu/.npmrc`. The RC file should contain `registry=...` with the registry URL your company uses internally. This will allow Renovate to find shared configs and other internally published packages. - -## Run Mend Renovate - -You can run Mend Renovate from a Docker command line prompt, or by using a Docker Compose file. An example is provided below. - -**Docker Compose File**: Renovate EE on GitLab - -```yaml -version: '3.6' - -x-controller-shared-variables: &variables-controller - MEND_RNV_SERVER_HOSTNAME: http://renovate-ee-server:8080 - MEND_RNV_SERVER_API_SECRET: # This secret will be used by the Worker and by Admin APIs - # Provide Mend License and accept Terms of Service - MEND_RNV_ACCEPT_TOS: # Set to 'y' to accept the Mend Renovate Terms of Service - MEND_RNV_LICENSE_KEY: # Set this to the Renovate Enterprise key obtained from Mend - -services: - renovate-ee-server: - restart: on-failure - image: ghcr.io/mend/renovate-ee-server: - ports: - - "80:8080" # Receive webhooks on port 80 - environment: - <<: *variables-controller - # Optional: Define log level. Set to Debug for more verbose output - # LOG_LEVEL: debug - # Provide connection details for the Renovate Bot/App - MEND_RNV_PLATFORM: # Set to `github` or `gitlab` - MEND_RNV_ENDPOINT: # Required for GitLab or GitHub Enterprise Server; not for GitHub.com. Include the trailing slash. - MEND_RNV_GITLAB_PAT: # Personal Access Token for the GitLab bot account. - MEND_RNV_WEBHOOK_SECRET: # Optional: defaults to 'renovate' - # Optional settings for Mend Renovate - # MEND_RNV_ADMIN_API_ENABLED: # Optional: Set to 'true' to enable Admin APIs. Defaults to 'false'. - # MEND_RNV_SQLITE_FILE_PATH: /db/renovate-ee.sqlite # Optional: Provide a path to persist the database. Needs 'db' volume defined (below). - # MEND_RNV_CRON_JOB_SCHEDULER: # Optional Job enqueue schedule: defaults to '0 * * * *' (hourly, on the hour) - # MEND_RNV_CRON_APP_SYNC: # Optional AppSync schedule: defaults to '0 0,4,8,12,16,20 * * *' (every 4 hours, on the hour) - # Core Renovate settings - # GITHUB_COM_TOKEN: # Personal Access Token for github.com (used for retrieving changelogs) - # volumes: - # Optional: You can use a file mount to persist the database between sessions - # - "/tmp/db/:/db/" # Unix-style file mounting for the db - # - "C:\\tmp/db/:/db/" # Windows-style file mounting for the db - healthcheck: - test: curl --fail http://renovate-ee-server:8080/health || exit 1 - interval: 60s - retries: 5 - start_period: 20s - timeout: 10s - - renovate-ee-worker: - restart: on-failure - deploy: - # Post deploy: - # $ docker-compose -f docker-compose-renovate-ee.yml up --scale renovate-ee-worker=3 -d --no-recreate - replicas: 2 - image: ghcr.io/mend/renovate-ee-worker:-full - depends_on: - - renovate-ee-server - environment: - <<: *variables-controller - # Optional: Define log level. Set to Debug for more verbose output - # LOG_LEVEL: debug -``` diff --git a/docs/installation-helm.md b/docs/installation-helm.md index aa9e6dd4..ff237c0c 100644 --- a/docs/installation-helm.md +++ b/docs/installation-helm.md @@ -28,5 +28,5 @@ helm repo update helm install --generate-name --set renovate.config='\{\"token\":\"...\"\}' mend-renovate-cc-ee/mend-renovate-ce ``` -See the available [values](../helm-charts/mend-renovate-ce/values.yaml) for full configuration and review configuration guides for [GitHub](./configure-renovate-ce-github.md) and/or [GitLab](./configure-renovate-ce-gitlab.md). +See the available [values](../helm-charts/mend-renovate-ce/values.yaml) for full configuration and review configuration guides for [GitHub](setup-for-github.md), [GitLab](setup-for-gitlab.md) or [Bitbucket](setup-for-bitbucket.md). diff --git a/docs/migrating-to-renovate-ce.md b/docs/migrating-to-renovate-ce.md index 0ba378f3..44b2aaac 100644 --- a/docs/migrating-to-renovate-ce.md +++ b/docs/migrating-to-renovate-ce.md @@ -10,7 +10,7 @@ If you are using a "health check" of the Renovate container then you should poin Some existing environment variables have been renamed, and some new ones have been added. -See the specific configuration instructions ([GitHub](./configure-renovate-ce-github.md), [GitLab](./configure-renovate-ee-gitlab.md)) to learn more about the variables mentioned below. +See the specific configuration instructions ([GitHub](setup-for-github.md), [GitLab](setup-for-gitlab.md), [Bitbucket](setup-for-bitbucket.md)) to learn more about the variables mentioned below. ### Environment Variable Key Migration diff --git a/docs/overview.md b/docs/overview.md index 04623f6c..2e037366 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,8 +1,8 @@ -# Mend Renovate Community Edition and Enterprise Edition +# Mend Renovate Self-hosted Apps - Community Edition and Enterprise Edition ## Overview -Mend Renovate Community Edition (Renovate CE) and Enterprise Edition (Renovate EE) are commercial offerings of Renovate for self-hosted users, such as those running on GitHub or GitLab. +Mend Renovate Self-hosted Apps (Community Edition and Enterprise Edition) are commercial offerings of Renovate for self-hosted users, such as those running on GitHub, GitLab or Bitbucket Data Center. Essentially, it is an alternative to running the `renovate` CLI tool, with the following additions: @@ -11,18 +11,18 @@ Essentially, it is an alternative to running the `renovate` CLI tool, with the f - Webhook listener to enable dynamic reactions to repository events - Administration APIs for probing the system state or triggering jobs -## Mend Renovate features +## Features of Mend Renovate Self-hosted App #### Job scheduler -The Mend Renovate's Docker container contains a built-in job scheduler that defaults to enqueing all repositories once per hour. +The Docker containers for Mend Renovate Self-hosted App contain a built-in job scheduler that defaults to enqueing all repositories once per hour. This saves the need for configuring and monitoring any external `cron` process. #### Webhook handler -Mend Renovate also supports a webserver to listen for system webhooks received from GitLab. +Mend Renovate Self-hosted App also supports a webserver to listen for system webhooks received from the SCM (GitHub, GitLab, Bitbucket). -In particular, Renovate checks webhooks for: +In particular, it checks webhooks for: - Projects it has just been added to - Commits to `main` branch for "important" files such as `package.json` and `renovate.json` @@ -54,23 +54,31 @@ Logically, Mend Renovate consists of four components: - Listens for webhook events from GitHub/GitLab, on path `/webhook` - Adds high priority jobs to the job queue if event conditions are met (e.g. a merged or closed Renovate PR, an update to an existing Renovate PR, a commit to `renovate.json` in `main` branch, etc) 4. Worker - - A wrapper on Renovate OSS, it runs non-stop, retrieving the highest priority job (repository) from the queue one at a time + - A wrapper on Renovate CLI, it runs non-stop, retrieving the highest priority job (repository) from the queue one at a time All four components run within a shared container. -As with Renovate OSS, it can also be configured to interact with an external Redis server as an alternative to the default disk-based cache. +As with Renovate CLI, it can also be configured to interact with an external Redis server as an alternative to the default disk-based cache. ## Downloading -The Mend Renovate CE image is available via GitHub Container Registry (ghcr.io) using the namespace [mend/renovate-ce](https://ghcr.io/mend/renovate-ce). -Use of the image is in accordance with the [Mend Terms of Service](https://www.mend.io/terms-of-service/). +The Docker images for Mend Renovate Self-hosted App are available via GitHub Container Registry (ghcr.io) + +Use of the images are in accordance with the [Mend Terms of Service](https://www.mend.io/terms-of-service/). + +- Community Edition: [mend/renovate-ce](https://ghcr.io/mend/renovate-ce). + +- Enterprise Edition: +Enterprise Edition uses two separate Docker images: The Server image, and the Worker image. + - Server image: [mend/renovate-ee-server](https://ghcr.io/mend/renovate-ee-server) + - Worker image: [mend/renovate-ee-worker](https://ghcr.io/mend/renovate-ee-worker) ## Versioning -Mend Renovate products have their own versioning and release schedule, independent of Renovate OSS versioning. +Mend Renovate Self-hosted Apps have their own versioning and release schedule, independent of Renovate CLI versioning. -Additionally, it is intended that Mend Renovate will have a slower release cadence than Renovate OSS in order to provide greater stability for Enterprise use. +Additionally, it is intended that Mend Renovate Self-hosted Apps will have a slower release cadence than Renovate CLI in order to provide greater stability for Enterprise use. -Specifically for Mend Renovate's use of SemVer: +Specifically, use of SemVer for Mend Renovate Self-hosted Apps: **Major**: Used only for breaking changes @@ -80,23 +88,35 @@ Specifically for Mend Renovate's use of SemVer: i.e. we do not want to ever "break" anyone with a patch release, or have behavior change. -Renovate OSS feature releases (i.e. minor version bumps in Renovate OSS) will therefore only be incorporated into minor releases of Mend Renovate. +Renovate CLI feature releases (i.e. minor version bumps in Renovate CLI) will therefore only be incorporated into minor releases of Mend Renovate. -Typically, multiple Renovate OSS feature releases will be rolled up into a single Mend Renovate release, and release notes will be embedded so that you do not need to look them up separately. +Typically, multiple Renovate CLI feature releases will be rolled up into a single Mend Renovate release, and release notes will be embedded so that you do not need to look them up separately. ## Releasing and Upgrading -The release cadence of Mend Renovate is not fixed, as it will be determined largely by the importance and stability of new Renovate OSS features, which will typically be tested using the hosted Renovate GitHub App first. +The release cadence of Mend Renovate is not fixed, as it will be determined largely by the importance and stability of new Renovate CLI features, which will typically be tested using the hosted Renovate GitHub App first. When a new version of Mend Renovate is pushed to GHCR, Release Notes will be added to this [github.com/mend/renovate-ce-ee](https://github.com/mend/renovate-ce-ee) repository. Naturally, it is recommended that you use Renovate itself for detecting and updating Mend Renovate versions if you are using a Docker Compose file internally for running Mend Renovate. -## Running Mend Renovate +## Running Mend Renovate Self-hosted App + +See the Setup Guides to get started with Mend Renovate Self-hosted App +- [Setup guide for GitHub](setup-for-github.md) +- [Setup guide for GitLab](setup-for-gitlab.md) +- [Setup guide for Bitbucket Data Center](setup-for-bitbucket-data-center.md) + +Examples using Docker Compose can be found at in the [examples directory](../examples). + +## Testing Mend Renovate Self-hosted App + +Request `/health` on your IP address hosting the deployment to check if it is running correctly. -Examples using Docker Compose can be found at the bottom of the configuration documentation for each product. -- Configuration - Renovate Community Edition - ([GitHub](./configure-renovate-ce-github.md), [GitLab](./configure-renovate-ce-gitlab.md)) -- Configuration - Renovate Enterprise Edition - ([GitHub](./configure-renovate-ee-github.md), [GitLab](./configure-renovate-ee-gitlab.md)) +For further testing, use the [Admin APIs](./api.md) to: +- check the status of the server +- see the contents of the Job and Task queues +- perform an App sync +- run a job -Request `/status` on your IP address hosting the deployment to check if it is running correctly. -It is recommended not to expose that endpoint to the internet as it could leak information about private repository names. +It is recommended not to expose the API endpoint to the internet as it could leak information about private repository names. diff --git a/docs/configure-renovate-bitbucket-server.md b/docs/setup-for-bitbucket-data-center.md similarity index 51% rename from docs/configure-renovate-bitbucket-server.md rename to docs/setup-for-bitbucket-data-center.md index 2591bff4..812d343c 100644 --- a/docs/configure-renovate-bitbucket-server.md +++ b/docs/setup-for-bitbucket-data-center.md @@ -1,134 +1,19 @@ -# Configuration - Mend Renovate CE/EE for Bitbucket Server +# Set up Mend Renovate Self-hosted App for Bitbucket Data Center +## Configure Renovate Bot Account on Bitbucket Data Center -# Table of Content -* [Available Renovate CE/EE Configurations](#available_config) -* [Installation Stages](#stages) - * [Stage 1: Configure Renovate Bot account on Bitbucket Server](#stg_1) - * [1a: Create a Renovate Bot user account (“Bitbucket User” access only)](#stg_1a) - * [1b: Fetch an HTTP Access Token for the Renovate Bot user (Project Read, Repo Write)](#stg_1b) - * [Stage 2: Install Renovate CE/EE application server (Docker-compose or Kubernetes)](#stg_2) - * [Stage 3: Install Renovate Bot and Webhooks on BitBucket project or repository](#stg_3) - * [3a: Install the Renovate Bot on Repositories](#stg_3a) - * [3b: Add Webhooks to Repositories(/Projects)](#stg_3b) - - -# Available Configurations for CE/EE - -`MEND_RNV_ACCEPT_TOS`: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). - -`MEND_RNV_LICENSE_KEY`: Provide a valid license key for Renovate Community Edition or Enterprise Edition - -> [!Note] -> -> To run Renovate Community Edition with **up to 10 repositories**, you can use this unregistered license key: -> -> `eyJsaW1pdCI6IjEwIn0=.30440220457941b71ea8eb345c729031718b692169f0ce2cf020095fd328812f4d7d5bc1022022648d1a29e71d486f89f27bdc8754dfd6df0ddda64a23155000a61a105da2a1` -> -> For a free license key for an **unrestricted number of repositories** on Renovate Community Edition, register with the form on the [Renovate Community Edition web page](https://www.mend.io/mend-renovate-community/). -> -> For an Enterprise license key, contact Mend at http://mend.io. - -`MEND_RNV_PLATFORM`: Set this to `bitbucket-server`. - -`MEND_RNV_ENDPOINT`: This is the API endpoint for your BitBucket Server installation. - -`MEND_RNV_BITBUCKET_USER`: Renovate Bot user account (“Bitbucket User” access only) - -`MEND_RNV_BITBUCKET_PAT`: BitBucket access token for the bot user `MEND_RNV_BITBUCKET_USER` - -`MEND_RNV_WEBHOOK_SECRET`: Optional: Defaults to `renovate` - -`MEND_RNV_WEBHOOK_URL`: Optional: The URL of the Renovate Server plus `/webhook`. Must be accessible to receive incoming calls from the BitBucket server. - -`MEND_RNV_ADMIN_TOKEN`: Optional: A token used for searching/add/removing repository webhooks. required if `MEND_RNV_WEBHOOK_URL` is set. - -`MEND_RNV_ADMIN_API_ENABLED`: Optional: Set to `true` to enable Admin APIs. Defaults to `false`. - -`MEND_RNV_SERVER_API_SECRET`: Required if Admin APIs are enabled. - -`MEND_RNV_SERVER_PORT`: The port on which the server listens for webhooks and api requests. Defaults to 8080. - -`MEND_RNV_CRON_JOB_SCHEDULER`: Optional: Accepts a 5-part cron schedule. Defaults to `0 * * * *` (i.e. once per hour exactly on the hour). This cron job triggers the Renovate bot against the projects in the SQLite database. If decreasing the interval then be careful that you do not exhaust the available hourly rate limit of the app on GitHub server or cause too much load. - -`MEND_RNV_CRON_APP_SYNC`: Optional: Accepts a 5-part cron schedule. Defaults to `0 0,4,8,12,16,20 * * *` (every 4 hours, on the hour). This cron job performs autodiscovery against the platform and fills the SQLite database with projects. - -`MEND_RNV_WORKER_EXECUTION_TIMEOUT`: Optional: Sets the maximum execution duration of a Renovate CLI scan in minutes. Defaults to 60. - -`MEND_RNV_AUTODISCOVER_FILTER`: a string of a comma separated values. (e.g. `org1/*, org2/test*, org2/test*`). Same behavior as Renovate [autodiscoverFilter](https://docs.renovatebot.com/self-hosted-configuration/#autodiscoverfilter) - -> [!WARNING] -> The Renovate CLI [autodiscover](https://docs.renovatebot.com/self-hosted-configuration/#autodiscover) configuration option is disabled at the client level. Repository filtering should solely rely on server-side filtering using `MEND_RNV_AUTODISCOVER_FILTER`. - -`MEND_RNV_ENQUEUE_JOBS_ON_STARTUP`: The job enqueue behavior on start (or restart). Defaults to `discovered`. (Note that the behavior can be different if the database is persisted or not) -- `enabled`: enqueue a job for all available repositories -- `discovered`: enqueue a job only for newly discovered repositories -- `disabled`: No jobs are enqueued - -`MEND_RNV_SQLITE_FILE_PATH`: Optional: Provide a path to persist the database. (eg. '/db/renovate-ce.sqlite', where 'db' is defined as a volume) - -> [!IMPORTANT] -> The container running the Renovate CE service requires read, write, and execute (rwx) permissions for the parent folder of the SQLite file. Additionally, the process inside the container executes with uid=1000 (ubuntu) and gid=0 (root). - -The [sqlite3](https://sqlite.org/cli.html) CLI tool is preinstalled in the Renovate CE/EE(server) images, allowing direct interaction with the underlying SQLite database. - -For example, Let `MEND_RNV_SQLITE_FILE_PATH=/db/renovate-ce.sqlite`: -```shell -ubuntu@23cf5aaa72ed:/usr/src/app$ sqlite3 -SQLite version 3.31.1 2020-01-27 19:55:54 -Enter ".help" for usage hints. -Connected to a transient in-memory database. -Use ".open FILENAME" to reopen on a persistent database. -sqlite> .open -readonly /db/renovate-ce.sqlite -sqlite> .tables -job_queue migrations org repo task_queue -sqlite> -``` - -`MEND_RNV_LOG_HISTORY_DIR`: Optional: Specify a directory path to save Renovate job log files, recommended to be an external volume to preserve history. Log files will be saved in a `./ORG_NAME/REPO_NAME/` hierarchy under the specified folder. Log file name structure is as follows: `(_.log)`. - -Where: -- ``: timestamp in the format `YYYYMMDD_HHmmss` local time -- ``: random 10 character alphanumeric string used as - [Renovate log context](https://docs.renovatebot.com/self-hosted-configuration/#logcontext) for cross referencing logs. - -For Example: -Let `MEND_RNV_LOG_HISTORY_DIR=/home/renovate/logs`, repository=`org/repo` - -The corresponding Renovate job log file will be saved as: - -``` -/home/renovate/logs/org/repo/20231025_104229_6e4ecdc343.log -``` - -> [!IMPORTANT] -> Note for EE: Logs are saved by the workers but clean is done by the server, so the corresponding folder must be shared between the Worker and Server containers. - -`MEND_RNV_LOG_HISTORY_TTL_DAYS`: Optional: The number of days to save log files. Defaults to 30. - -`MEND_RNV_LOG_HISTORY_CLEANUP_CRON`: Optional: Specifies a 5-part cron schedule. Defaults to `0 0 * * *` (every midnight). This cron job cleans up log history in the directory defined by `MEND_RNV_LOG_HISTORY_DIR`. It deletes any log file that exceeds the `MEND_RNV_LOG_HISTORY_TTL_DAYS` value. - -`MEND_RNV_MC_TOKEN` _(EE only)_: The merge confidence token used for Smart-Merge-Control authentication - - -# Installation Stages - - -## Stage 1 - - ### 1.a. Configure Renovate Bot User Account -The following configuration instructions are to be performed on Bitbucket Server by a user account with “Admin” or “System admin” global permissions on the Bitbucket Server. +The following configuration instructions are to be performed on Bitbucket Data Center by a user account with “Admin” or “System admin” global permissions on Bitbucket Data Center. -- Log in to Bitbucket Server with admin user (eg. http://localhost:7990)
+- Log in to Bitbucket Data Center with admin user (eg. http://localhost:7990)
Note: Bitbucket Admin user permissions - Must be at least “Admin” to create a new user account.
Also, only repo admins can add the Renovate Bot user and webhooks. - Navigate to the User settings page in Administration (Settings → Accounts/Users)
eg. http://localhost:7990/admin/users -![bb-admin-users.png](images%2Fbb-admin-users.png) +![bb-admin-users.png](images/bb-admin-users.png) - Click “Create user” to create an account for the Renovate Bot user. (eg. http://localhost:7990/admin/users?create) @@ -136,28 +21,27 @@ We recommend calling the account “Renovate Bot”. - Username: “renovate-bot” - Full name: “Renovate Bot” -![bb-create-user.png](images%2Fbb-create-user.png) +![bb-create-user.png](images/bb-create-user.png) - Note: The Renovate Bot user will be the author of Renovate pull requests. -![bb-renovate-bot.png](images%2Fbb-renovate-bot.png) +![bb-renovate-bot.png](images/bb-renovate-bot.png) - Give the Renovate Bot user basic Bitbucket user access (only required so a HTTP Token can be created through the UI) - Under Global permissions, in the User Access section, click into the table header bar (where it says “Add Users”) and search for the Renovate Bot user. - Leave the access level at “Bitbucket User”. - Press “Add” -![bb-user-access-1.png](images%2Fbb-user-access-1.png) +![bb-user-access-1.png](images/bb-user-access-1.png) - The end results should be a Renovate Bot user with “Bitbucket User” access only. -![bb-user-access-2.png](images%2Fbb-user-access-2.png) +![bb-user-access-2.png](images/bb-user-access-2.png)
Note: It is essential that the Renovate Bot user does NOT have Admin or System admin access. Because Bitbucket Admin and System admin users have full access to all projects and repos, there will be no way to control which repos Renovate will run against, and so Renovate will run against all repos. When the Renovate Bot user has only basic user access, administrators can control which repos run with Renovate by adding the Renovate Bot user to specific repos.
- # Stage 1b: Fetch HTTP Access Token for the Renovate Bot user Once the Renovate Bot user account is created, log in to Bitbucket with the Renovate User account to fetch an HTTP access token for it. This will be used as the `MEND_RNV_BITBUCKET_PAT` in the Renovate CE/EE configuration. @@ -170,19 +54,19 @@ http://localhost:7990/login - If logged in as an Admin user account, log out of Bitbucket first. - Alternatively, open a new web browser in incognito mode. _(Ctrl+Shift+N from a web browser)_ -![bb-log-in.png](images%2Fbb-log-in.png) +![bb-log-in.png](images/bb-log-in.png) - Go to the Account management page (eg. http://localhost:7990/account) You can expand the menu on the user profile icon (top right of page) and click “Manage account”. -![bb-manage-account.png](images%2Fbb-manage-account.png) +![bb-manage-account.png](images/bb-manage-account.png) - Navigate to the HTTP access tokens page - Press “Create token” to create a new HTTP access token -![bb-access-token.png](images%2Fbb-access-token.png) +![bb-access-token.png](images/bb-access-token.png) - Create an HTTP access token (with `Repository Write` permission) - Token name: Can be anything (eg. “Renovate User PAT”) @@ -190,14 +74,13 @@ You can expand the menu on the user profile icon (top right of page) and click - Project permissions: `Project read` - Repository permissions: `Repository write` -![bb-new-token.png](images%2Fbb-new-token.png) +![bb-new-token.png](images/bb-new-token.png) - Copy the token and store it for later use.
This will be used as the `MEND_RNV_BITBUCKET_PAT` in the Renovate CE/EE configuration.
- # Stage 2: Install Renovate CE/EE Application Server ## Configure the Docker files / Helm charts @@ -207,63 +90,14 @@ Example files available here: - Helm charts (Renovate CE / Renovate EE) Edit the docker files / helm chart values to provide the required environment variables. -Refer to [Available Configurations section](#available_config) for a full list of Renovate CE/EE server variables. - -You will need the following information to proceed. - -#### Mend Licence Keys -Renovate CE or Renovate EE licence key -Accept Terms of Service (‘Y’) -Merge Confidence API token - only required if using Smart Merge Control with Renovate EE (ie. `matchConfidence` in package rules) +Refer to [Configurations Options](configuration-options.md) for a full list of Renovate CE/EE server variables. -#### Bitbucket Server Connection details -Bitbucket server URL (eg, http://localhost:7990/) -Bitbucket Renovate Bot User PAT - See instructions above for getting HTTP access token for Renovate Bot user on Bitbucket +#### Bitbucket Data Center Connection details -#### Other strongly recommended Renovate Server environment settings -`MEND_RNV_ADMIN_API_ENABLED` - APIs are off by default. Set this to true to enable admin APIs. -Needs `MEND_RNV_SERVER_API_SECRET` to be set. -`MEND_RNV_SQLITE_FILE_PATH` - Mount the DB file to disc. Ensure volume mount is configured below. -`MEND_RNV_LOG_HISTORY_DIR` - Mount the Renovate job logs (Note: This is the Job logs; Not the server/worker machine logs.) -`RENOVATE_REPOSITORY_CACHE` - Faster performance running Renovate on repos on subsequent scans. - -## Run the Server -If using Docker, run the Docker Compose file after all values have been correctly inserted. - -> docker-compose -f docker-compose-bitbucket.yaml up - -If using Kubernetes, install the Helm charts after all values have been correctly inserted in the values.yaml. - -> helm install renovate-ce - -## Test and Troubleshoot - -#### First, look for Licence Key check -When running the Renovate Application Server, the first thing you should notice is the check for Licence and Terms of Service acceptance. -If you see an error for Licence or Terms of Service, it is a good sign - it means the server is running. Go back and check that the licence key is correctly referenced in the yaml files. - -#### Next, check connection with the Bitbucket Server -The Renovate Server will attempt to validate the Bitbucket Server endpoint and the Renovate User PAT. Errors will be thrown if the endpoint or PAT are incorrect. -Check that the Bitbucket Server is up and running and available on the given endpoint. -The endpoint needs “/api/1.0” on the end [Check this] - -#### Renovate will App Sync and run Renovate on new Repos -If connecting to the Bitbucket Server, an App Sync will occur (by default). Watch this in the logs. No repos will be synced at this stage if the Renovate Bot user has not been added to any repos. However, if the Renovate Bot user has Admin global permission, Renovate will run on ALL repositories on the Bitbucket server. -If there are repos with Renovate Bot installed, watch the logs to see it run. Open the installed repos to see Pull Requests created by “Renovate Bot”. - -#### Check the APIs -- Call the health check - GET /health -- Call the status check - GET /api/status -- Call the task queue - GET /api/task/queue -- Call the job queue - GET /api/job/queue -- Force an app sync - POST /api/sync -- Force a Renovate job on a repo - POST /api/job/add { "repository": ”PROJECT/repo” } - - # Install Renovate Bot and Webhooks on BitBucket project or repository - ## Stage 3a: Install Renovate Bot on Repositories(/Projects) + ### Overview Add the Renovate Bot user to any repo (or project) you want Renovate to run on. Needs “Repository Write” permission so that it can create pull requests on the repo. @@ -278,7 +112,7 @@ Note: Any Bitbucket user with global permissions of Admin or System admin has fu ### Note: - Adding the Renovate Bot user to a **project** will install Renovate on **all repositories** in the project (current and future). -- Giving the Renovate Bot user `global Admin` user access will install Renovate on **all repositories** on the Bitbucket server. +- Giving the Renovate Bot user `global Admin` user access will install Renovate on **all repositories** on Bitbucket Data Center. ### How to add Renovate Bot to a Repository @@ -286,14 +120,14 @@ Note: Any Bitbucket user with global permissions of Admin or System admin has fu Repo → Repository Settings → Repository permissions Repo settings page: http://localhost:7990/projects/PROJ1/repos/repo-1/permissions -![bb-repo-permissions.png](images%2Fbb-repo-permissions.png) +![bb-repo-permissions.png](images/bb-repo-permissions.png) - Click the “Add user or group” button (Top right corner) - Add the Renovate Bot user with permission: Repository Write
Note: The Renovate Bot user needs write permission so it can create pull requests on the repository. -![bb-add-user.png](images%2Fbb-add-user.png) +![bb-add-user.png](images/bb-add-user.png) Now the Renovate Bot is installed on the repo. @@ -319,11 +153,10 @@ Note: To run APIs, ensure Renovate Server has EnvVar `MEND_RNV_ADMIN_API_ENABLED Authorization: ``` -![bb-postman-sync.png](images%2Fbb-postman-sync.png) +![bb-postman-sync.png](images/bb-postman-sync.png)
- ## Stage 3b: Add Webhooks to Repositories(/Projects) Webhooks enable a message to be sent from the Bitbucket repository to the Renovate server to trigger a Renovate job on a repository when important files have changed (ie. package files, Renovate config files). @@ -341,11 +174,11 @@ Create webhooks via the Bitbucket UI [Repo → Repository Settings → Webhooks]
http://localhost:7990/projects/PROJ1/repos/repo-1/settings -![bb-repo-webhooks.png](images%2Fbb-repo-webhooks.png) +![bb-repo-webhooks.png](images/bb-repo-webhooks.png) - Click “Create webhook” to open the Create webhook page -![bb-create-webhook-1.png](images%2Fbb-create-webhook-1.png) +![bb-create-webhook-1.png](images/bb-create-webhook-1.png) **Provide the following values for the webhook:** - Name: Can be anything. Duplicates are allowed. @@ -359,7 +192,7 @@ Create webhooks via the Bitbucket UI - Repository: Push, Modified - Pull request: Modified -![bb-create-webhook-2.png](images%2Fbb-create-webhook-2.png) +![bb-create-webhook-2.png](images/bb-create-webhook-2.png) - Click “Save” to finish creating the webhook @@ -381,15 +214,15 @@ To create a webhook using the Bitbucket APIs, the APIs must pass an HTTP access - Navigate to the HTTP access tokens page
http://localhost:7990/plugins/servlet/access-tokens/users/admin/manage -![bb-admin-token.png](images%2Fbb-admin-token.png) +![bb-admin-token.png](images/bb-admin-token.png) -- Press “Create token” to create the Bearer token required for calling the Bitbucket Server webhook APIs. +- Press “Create token” to create the Bearer token required for calling Bitbucket Data Center webhook APIs. Note: - To create **project** webhooks, the HTTP access token must have `Project Admin` permissions.
- To create **repository** webhooks, the HTTP access token must have `Repository Admin` permissions. (Project Admin not required.) -![bb-create-admin-token.png](images%2Fbb-create-admin-token.png) +![bb-create-admin-token.png](images/bb-create-admin-token.png) - Click “Create” to finish creating the access token - Copy the access token when it is presented. Store it for use when calling Bitbucket Admin APIs. @@ -450,7 +283,7 @@ Body: (raw - JSON) **Provide the following values:** - name: Can be anything. Duplicate names are allowed. - url: The URL and port of the Renovate Server. - - Note: Ensure ports are open to receiving incoming calls from the Bitbucket server. + - Note: Ensure ports are open to receiving incoming calls from Bitbucket Data Center. - secret: The Webhook secret defined in the MEND_RNV_WEBHOOK_SECRET environment variable on the Renovate Server. ### Allow Renovate CE/EE to create Repository webhooks via Bitbucket API @@ -462,3 +295,70 @@ the server will manage the repositories webhooks automatically Notes: `MEND_RNV_ADMIN_TOKEN` 1. Recommended to use a different token than the token for Renovate bot user 2. This admin token is only used for searching/adding and removing of webhooks on repository level + +## Run Mend Renovate Self-hosted App + +You can run Mend Renovate Self-hosted App from a Docker command line prompt, or by using a Docker Compose file. Examples are provided in the links below. + +**Example Docker Compose files:** + +- [Mend Renovate Community Edition](../examples/docker-compose/renovate-ce-github.yml) +- [Mend Renovate Enterprise Edition](../examples/docker-compose/renovate-ee-simple.yml) + +> [!NOTE] +> +> Some configuration of environment variables will be required inside the Docker Compose files. +> +> Essential configuration options are shown below. For a full list of configurable variables, see [Configuration Options](configuration-options.md). + +## Configure Environment Variables + +### Essential Configuration for Mend Renovate Sever + +**`MEND_RNV_ACCEPT_TOS`**: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). + +**`MEND_RNV_LICENSE_KEY`**: Provide a valid license key for Renovate Community Edition or Enterprise Edition + +> [!Note] +> +> To run Renovate Community Edition with **up to 10 repositories**, you can use this unregistered license key: +> +> `eyJsaW1pdCI6IjEwIn0=.30440220457941b71ea8eb345c729031718b692169f0ce2cf020095fd328812f4d7d5bc1022022648d1a29e71d486f89f27bdc8754dfd6df0ddda64a23155000a61a105da2a1` +> +> For a free license key for an **unrestricted number of repositories** on Renovate Community Edition, register with the form on the [Renovate Community Edition web page](https://www.mend.io/mend-renovate-community/). +> +> For an Enterprise license key, contact Mend at http://mend.io. + +**`MEND_RNV_PLATFORM`**: Set this to `bitbucket-server`. + +**`MEND_RNV_ENDPOINT`**: This is the API endpoint for your BitBucket Data Center installation. Include the trailing slash. + +**`MEND_RNV_SERVER_PORT`**: The port on which the server listens for webhooks and api requests. Defaults to 8080. + +**`MEND_RNV_BITBUCKET_USER`**: Renovate Bot user account (“Bitbucket User” access only) + +**`MEND_RNV_BITBUCKET_PAT`**: BitBucket access token for the bot user `MEND_RNV_BITBUCKET_USER` + +**`MEND_RNV_WEBHOOK_URL`**: Optional: The URL of the Renovate Server plus '/webhook'. Must be accessible to receive incoming calls from the BitBucket Data Center. + +**`MEND_RNV_ADMIN_TOKEN`**: Optional: A token used for searching/add/removing repository webhooks. Required if `MEND_RNV_WEBHOOK_URL` is set. + +**`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 Bitbucket webhooks. Defaults to 'renovate'. + +**`GITHUB_COM_TOKEN`**: A Personal Access Token for a user account on github.com + +**Additional Configuration options** + +For further details and a list of all available options, see the [Configuration Options](configuration-options.md) page. + +### Renovate CLI Configuration + +Renovate CLI functionality can be configured using environment variables (e.g. `RENOVATE_XXXXXX`) or via a `config.js` file mounted to `/usr/src/app/config.js` inside the Mend Renovate container. + +**npm Registry** + +If using your own npm registry, you may find it easiest to update your Docker Compose file to include a volume that maps an `.npmrc` file to `/home/ubuntu/.npmrc`. The RC file should contain `registry=...` with the registry URL your company uses internally. This will allow Renovate to find shared configs and other internally published packages. diff --git a/docs/setup-for-github.md b/docs/setup-for-github.md new file mode 100644 index 00000000..74fcd01a --- /dev/null +++ b/docs/setup-for-github.md @@ -0,0 +1,111 @@ +# Set up Mend Renovate Self-hosted App for GitHub + +## Create and Configure the GitHub App (bot) + +Before running Mend Renovate, you need to provision it as an App on GitHub, and retrieve the ID + private key provided. + +If you're running a self-hosted instance of GitHub Enterprise, it is suggested to name the app "Renovate" so that it shows up as easily recognizable as "renovate[bot]" in Pull Requests. +If you're running against `github.com` then the name Renovate is already taken by the hosted Mend Renovate app, so you will need something else like "YourCompany Renovate". + +The App requires the following permissions: + +- Repository permissions + - Administration: Read-only + - Checks: Read & write + - Commit statuses: Read & write + - Contents: Read & write + - Dependabot alerts: Read-only (optional) + - Issues: Read & write + - Metadata: Read-only + - Pull Requests: Read & write + - Workflows: Read & write +- Organization permissions + - Members: Read-only + +The App should also subscribe to the following webhook events: + +- Security Advisory +- Check run +- Check suite +- Issues +- Pull request +- Push +- Repository +- Status + +Description, Homepage, User authorization callback URL, and Setup URL are all unimportant so you may set them to whatever you like. + +The Mend Renovate webhook listener binds to port 8080 by default, however it will bind to `process.env.PORT` instead if that is defined. +Note: The Mend Renovate image takes care of exposing port 8080 of the container, so if you change this port then you will need to take care of any exposing/mapping of ports yourself. +In the [Docker Compose example config](https://github.com/mend/renovate-cc-ee/tree/main/examples/), the default port 8080 is used and then mapped to port 80 on the host. + +For the Webhook URL field, point it to `/webhook` on port 80 (or whatever port you mapped to) of the server that you will run Mend Renovate on, e.g. http://1.2.3.4/webhook +Be sure to enter a webhook secret too. +If you don't care about the value, then enter 'renovate' as that is the default secret that the webhook handler process uses. + +You can use the [Renovate icon](https://docs.renovatebot.com/assets/images/logo.png) for the app/bot if you desire. + +## Run Mend Renovate Self-hosted App + +You can run Mend Renovate Self-hosted App from a Docker command line prompt, or by using a Docker Compose file. Examples are provided in the links below. + +**Example Docker Compose files:** + +- [Mend Renovate Community Edition](../examples/docker-compose/renovate-ce-github.yml) +- [Mend Renovate Enterprise Edition](../examples/docker-compose/renovate-ee-simple.yml) + +> [!NOTE] +> +> Some configuration of environment variables will be required inside the Docker Compose files. +> +> Essential configuration options are shown below. For a full list of configurable variables, see [Configuration Options](configuration-options.md). + +## Configure Environment Variables + +### Essential Configuration for Mend Renovate Server + +**`MEND_RNV_ACCEPT_TOS`**: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). + +**`MEND_RNV_LICENSE_KEY`**: Provide a valid license key for Renovate Community Edition or Enterprise Edition + +> [!Note] +> +> To run Renovate Community Edition with **up to 10 repositories**, you can use this unregistered license key: +> +> `eyJsaW1pdCI6IjEwIn0=.30440220457941b71ea8eb345c729031718b692169f0ce2cf020095fd328812f4d7d5bc1022022648d1a29e71d486f89f27bdc8754dfd6df0ddda64a23155000a61a105da2a1` +> +> For a free license key for an **unrestricted number of repositories** on Renovate Community Edition, register with the form on the [Renovate Community Edition web page](https://www.mend.io/mend-renovate-community/). +> +> For an Enterprise license key, contact Mend at http://mend.io. + +**`MEND_RNV_PLATFORM`**: Set this to `github`. + +**`MEND_RNV_ENDPOINT`**: [GitHub Enterprise Server only] This is the API endpoint for your GitHub Enterprise installation. Include the trailing slash. + +**`MEND_RNV_SERVER_PORT`**: The port on which the server listens for webhooks and api requests. Defaults to 8080. + +**`MEND_RNV_GITHUB_APP_ID`**: The GitHub App ID of the provisioned Renovate app on GitHub. + +**`MEND_RNV_GITHUB_APP_KEY`**: The private key of the Renovate app on GitHub. Alternatively, use `MEND_RNV_GITHUB_PEM_FILE_PATH`. + +**`MEND_RNV_GITHUB_PEM_FILE_PATH`**: The file path for a GitHub app key PEM file. Defaults to `/usr/src/app/renovate.private-key.pem`. Alternatively, use `MEND_RNV_GITHUB_APP_KEY`. + +**`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 GitHub webhooks. Defaults to 'renovate'. + +**`GITHUB_COM_TOKEN`**: [GitHub Enterprise Server only] A Personal Access Token for a user account on github.com (note: _not_ an account on your GitHub Enterprise instance). + +**Additional Configuration options** + +For further details and a list of all available options, see the [Configuration Options](configuration-options.md) page. + +### Renovate CLI Configuration + +Renovate CLI functionality can be configured using environment variables (e.g. `RENOVATE_XXXXXX`) or via a `config.js` file mounted to `/usr/src/app/config.js` inside the Mend Renovate container. + +**npm Registry** + +If using your own npm registry, you may find it easiest to update your Docker Compose file to include a volume that maps an `.npmrc` file to `/home/ubuntu/.npmrc`. The RC file should contain `registry=...` with the registry URL your company uses internally. This will allow Renovate to find shared configs and other internally published packages. diff --git a/docs/setup-for-gitlab.md b/docs/setup-for-gitlab.md new file mode 100644 index 00000000..e9d4e1e6 --- /dev/null +++ b/docs/setup-for-gitlab.md @@ -0,0 +1,113 @@ +# Set up Mend Renovate Self-hosted App for GitLab + +## Configure Renovate Bot Account on GitLab + +### Renovate Bot Account + +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? + +### Personal Access Token + +Once the account is created, create a Personal Access Token for it with the following permissions: + * `api` + * `read_user` + * `write_repository` + +### System Hook + +To activate Mend Renovate's webhook ability, create a System Hook that points to the Renovate installation. + +Create a System Hook (in Admin area) + +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` + +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. + +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. + +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. + +### Repo Webhooks + +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. + +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` + +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. + +## Run Mend Renovate Self-hosted App + +You can run Mend Renovate Self-hosted App from a Docker command line prompt, or by using a Docker Compose file. Examples are provided in the links below. + +**Example Docker Compose files:** + +- [Mend Renovate Community Edition](../examples/docker-compose/renovate-ce-github.yml) +- [Mend Renovate Enterprise Edition](../examples/docker-compose/renovate-ee-simple.yml) + +> [!NOTE] +> +> Some configuration of environment variables will be required inside the Docker Compose files. +> +> Essential configuration options are shown below. For a full list of configurable variables, see [Configuration Options](configuration-options.md). + +## Configure Environment Variables + +### Essential Configuration for Mend Renovate Sever + +**`MEND_RNV_ACCEPT_TOS`**: Set this environment variable to `y` to consent to [Mend's Terms of Service](https://www.mend.io/terms-of-service/). + +**`MEND_RNV_LICENSE_KEY`**: Provide a valid license key for Renovate Community Edition or Enterprise Edition + +> [!Note] +> +> To run Renovate Community Edition with **up to 10 repositories**, you can use this unregistered license key: +> +> `eyJsaW1pdCI6IjEwIn0=.30440220457941b71ea8eb345c729031718b692169f0ce2cf020095fd328812f4d7d5bc1022022648d1a29e71d486f89f27bdc8754dfd6df0ddda64a23155000a61a105da2a1` +> +> For a free license key for an **unrestricted number of repositories** on Renovate Community Edition, register with the form on the [Renovate Community Edition web page](https://www.mend.io/mend-renovate-community/). +> +> For an Enterprise license key, contact Mend at http://mend.io. + +**`MEND_RNV_PLATFORM`**: Set this to `gitlab`. + +**`MEND_RNV_ENDPOINT`**: This is the API endpoint for your GitLab host. e.g. like `https://gitlab.company.com/api/v4/`. Include the trailing slash. + +**`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_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'. + +**`GITHUB_COM_TOKEN`**: A Personal Access Token for a user account on github.com + +**Additional Configuration options** + +For further details and a list of all available options, see the [Configuration Options](configuration-options.md) page. + +### Renovate CLI Configuration + +Renovate CLI functionality can be configured using environment variables (e.g. `RENOVATE_XXXXXX`) or via a `config.js` file mounted to `/usr/src/app/config.js` inside the Mend Renovate container. + +**npm Registry** + +If using your own npm registry, you may find it easiest to update your Docker Compose file to include a volume that maps an `.npmrc` file to `/home/ubuntu/.npmrc`. The RC file should contain `registry=...` with the registry URL your company uses internally. This will allow Renovate to find shared configs and other internally published packages. diff --git a/examples/docker-compose/renovate-ce-github.yml b/examples/docker-compose/renovate-ce-github.yml index 35c060ce..fa76090c 100644 --- a/examples/docker-compose/renovate-ce-github.yml +++ b/examples/docker-compose/renovate-ce-github.yml @@ -17,8 +17,7 @@ services: # LOG_FORMAT: json # Defaults to 'pretty'. Useful when importing logs to reporting tool (eg. Splunk). # Provide a license key and accept the Terms of Service - MEND_RNV_LICENSE_KEY: # For a free unrestricted repo Community Edition license key register at https://www.mend.io/renovate-community/ - # Use this key for 10 repos: eyJsaW1pdCI6IjEwIn0=.30440220457941b71ea8eb345c729031718b692169f0ce2cf020095fd328812f4d7d5bc1022022648d1a29e71d486f89f27bdc8754dfd6df0ddda64a23155000a61a105da2a1 + MEND_RNV_LICENSE_KEY: # Get Community Edition license key from https://www.mend.io/renovate-community/ MEND_RNV_ACCEPT_TOS: # Set to 'Y' to accept Terms of Service # Provide connection details for the GitHub App # Available at: https://github.com/settings/apps/ diff --git a/examples/docker-compose/renovate-ce-postgres.yml b/examples/docker-compose/renovate-ce-postgres.yml index 1861d3f0..fe453125 100644 --- a/examples/docker-compose/renovate-ce-postgres.yml +++ b/examples/docker-compose/renovate-ce-postgres.yml @@ -19,8 +19,7 @@ services: # LOG_FORMAT: json # Defaults to 'pretty'. Useful when importing logs to reporting tool (eg. Splunk). # Provide a license key and accept the Terms of Service - MEND_RNV_LICENSE_KEY: # For a free unrestricted repo Community Edition license key register at https://www.mend.io/renovate-community/ - # Use this key for 10 repos: eyJsaW1pdCI6IjEwIn0=.30440220457941b71ea8eb345c729031718b692169f0ce2cf020095fd328812f4d7d5bc1022022648d1a29e71d486f89f27bdc8754dfd6df0ddda64a23155000a61a105da2a1 + MEND_RNV_LICENSE_KEY: # Get Community Edition license key from https://www.mend.io/renovate-community/ MEND_RNV_ACCEPT_TOS: # Set to 'Y' to accept Terms of Service # Provide connection details for the GitHub App # Available at: https://github.com/settings/apps/ diff --git a/helm-charts/mend-renovate-ce/values.yaml b/helm-charts/mend-renovate-ce/values.yaml index d6628134..6c9190b1 100644 --- a/helm-charts/mend-renovate-ce/values.yaml +++ b/helm-charts/mend-renovate-ce/values.yaml @@ -47,7 +47,7 @@ renovate: mendRnvBitbucketPat: # Optional: The URL of the Renovate Server plus '/webhook' suffix. - # Must be accessible to receive incoming calls from the BitBucket server. + # Must be accessible to receive incoming calls from BitBucket Data Center. mendRnvWebhookURL: # Optional: A token used for searching/adding/removing repository webhooks. diff --git a/helm-charts/mend-renovate-ee/values.yaml b/helm-charts/mend-renovate-ee/values.yaml index 706f6cf4..5834a997 100644 --- a/helm-charts/mend-renovate-ee/values.yaml +++ b/helm-charts/mend-renovate-ee/values.yaml @@ -64,7 +64,7 @@ renovateServer: mendRnvBitbucketPat: # Optional: The URL of the Renovate Server plus '/webhook' suffix. - # Must be accessible to receive incoming calls from the BitBucket server. + # Must be accessible to receive incoming calls from BitBucket Data Center. mendRnvWebhookURL: # Optional: A token used for searching/adding/removing repository webhooks.