diff --git a/README.md b/README.md index f8f16778827..a9bb5231242 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,30 @@ # GitHub Action Renovate -GitHub Action to run Renovate self-hosted. - - - - - -## Table of contents - -- [Badges](#badges) -- [Options](#options) - - [`configurationFile`](#configurationfile) - - [`docker-cmd-file`](#docker-cmd-file) - - [`docker-network`](#docker-network) - - [`docker-user`](#docker-user) - - [`docker-volumes`](#docker-volumes) - - [`env-regex`](#env-regex) - - [`mount-docker-socket`](#mount-docker-socket) - - [`token`](#token) - - [`renovate-image`](#renovate-image) - - [`renovate-version`](#renovate-version) -- [Example](#example) -- [Environment Variables](#environment-variables) - - [Passing other environment variables](#passing-other-environment-variables) -- [Persisting the Repository Cache](#persisting-the-repository-cache) -- [Troubleshooting](#troubleshooting) - - [Debug Logging](#debug-logging) - - [Special token requirements when using the `github-actions` manager](#special-token-requirements-when-using-the-github-actions-manager) - -## Badges - -| Badge | Description | Service | -| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------- | -| code style | Code style | Prettier | -| Conventional Commits: 1.0.0 | Commit style | Conventional Commits | -| Renovate enabled | Dependencies | Renovate | -| GitHub workflow status | Build | GitHub Actions | +Use this GitHub Action to self-host Renovate. + +> [!IMPORTANT] +> The version number of `renovatebot/github-action` is _different_ from that of `renovatebot/renovate`! +> By default, `renovabot/github-action` uses the latest version of Renovate from the `ghcr.io/renovatebot/renovate:latest` Docker image. ## Options -Options can be passed using the inputs of this action or the corresponding environment variables. -When both are passed, the input takes precedence over the environment variable. -For the available environment variables, see the Renovate [Self-Hosted Configuration](https://docs.renovatebot.com/self-hosted-configuration/) docs. +You can pass options with either: + +- The inputs of this action. +- Or, with the corresponding Renovate self-hosted environment variables. + +> [!NOTE] +> When you provide an input _and_ a environment variable, _the input is used_ over the enviroment variable! + +See the full list of environment variables in the [Renovate docs, Self-Hosted Configuration](https://docs.renovatebot.com/self-hosted-configuration/). ### `configurationFile` Configuration file to configure Renovate ("global" config) in JavaScript or JSON format. -It is recommended to not name it one of the repository configuration filenames listed in the Renovate Docs for [Configuration Options](https://docs.renovatebot.com/configuration-options/). -Config examples can be found in the [example](./example) directory. +We recommend you avoid names that match repository configuration filenames listed in the Renovate Docs for [Configuration Options](https://docs.renovatebot.com/configuration-options/). + +You can find configuration examples in the [example directory](./example). The configurations that can be done in this file consists of two parts, as listed below. Refer to the links to the [Renovate Docs](https://docs.renovatebot.com/) for all options. @@ -56,9 +32,10 @@ Refer to the links to the [Renovate Docs](https://docs.renovatebot.com/) for all 1. [Self-Hosted Configuration Options](https://docs.renovatebot.com/self-hosted-configuration/) 2. [Configuration Options](https://docs.renovatebot.com/configuration-options/) -The [`branchPrefix`](https://docs.renovatebot.com/configuration-options/#branchprefix) option is important to configure and should be configured to a value other than the default to prevent interference with e.g. the Renovate GitHub App. +If you want to use the Mend Renovate app _and_ this `renovatebot/github-action`, then you must set the [`branchPrefix`](https://docs.renovatebot.com/configuration-options/#branchprefix) to a different value than the default! +This prevents interference with the Mend Renovate app, or other apps. -If you want to use this with just the single configuration file, make sure to include the following two configuration lines. +If you want to use a single configuration file, make sure to include the following two configuration lines. This disables the requirement of a configuration file for the repository and disables onboarding. ```js @@ -68,15 +45,15 @@ This disables the requirement of a configuration file for the repository and dis ### `docker-cmd-file` -Specify a command to run when the image start. -By default the image run -`renovate`. -This option is useful to customize the image before running `renovate`. -It must be an existing executable file on the local system. -It will be mounted to the docker container. +By default, the image runs the `renovate` command. -For example you can create a simple script like this one (let's call it -`renovate-entrypoint.sh`). +Use `docker-cmd-file` to set which command(s) run when the image starts. +With this option you can customize the image before it runs the`renovate` command. + +`docker-cmd-file` must point to an _existing executable file_ on the local system. +This file will be mounted to the Docker container. + +For example, you may create a simple script called `renovate-entrypoint.sh`: ```sh #!/bin/bash @@ -88,9 +65,9 @@ apt install -y build-essential libpq-dev runuser -u ubuntu renovate ``` -Now use this action +Now use this Action: -```yml +```yaml .... jobs: renovate: @@ -115,17 +92,22 @@ or set it to `host` to run in the same network as github runner, or specify any ### `docker-user` -Specify a user (or user-id) to run docker command. +Specify a `user` (or `user-id`) to run Docker commands as. -You can use it with [`docker-cmd-file`](#docker-cmd-file) in order to start the -image as root, do some customization and switch back to a unprivileged user. +You can use it with a [`docker-cmd-file`](#docker-cmd-file) to start the image as root, do some customization and then _switch back to a unprivileged user_. ### `docker-volumes` -Specify volume mounts. Defaults to `/tmp:/tmp`. -The volume mounts are separated through `;`. +Defaults to `/tmp:/tmp`. -This sample will mount `/tmp:/tmp`, `/home:/home` and `/foo:/bar`. +Use `docker-volumes` to set volume mounts. +Separate each volume mount with a `;` character. + +The following example mounts three volumes: + +- `/tmp:/tmp` +- `/home:/home` +- `/foo:/bar` ```yml .... @@ -147,39 +129,49 @@ jobs: ### `env-regex` -Allows to configure the regex to define which environment variables are passed to the renovate container. -See [Passing other environment variables](#passing-other-environment-variables) section for more details. +Use `env-regex` to set which environment variables are passed to the Renovate container. +Uses the JavaScript regex syntax. + +Read the [Passing other environment variables](#passing-other-environment-variables) section to learn more. ## `mount-docker-socket` -Default to `false`. If set to `true` the action will mount the Docker socket -inside the renovate container so that the commands can use Docker. Can be useful -for `postUpgradeTasks`'s commands. Also add the user inside the renovate -container to the docker group for socket permissions. +Default to `false`. + +If set to `true` the action mounts the Docker socket inside the Renovate container, so that the commands can use Docker. +Can be useful for `postUpgradeTasks`'s commands. +Also add the user inside the Renovate container to the Docker group for socket permissions. ### `token` -[Generate a Personal Access Token (classic)](https://github.com/settings/tokens), with the `repo:public_repo` scope for only public repositories or the `repo` scope for public and private repositories, and add it to _Secrets_ (repository settings) as `RENOVATE_TOKEN`. -You can also create a token without a specific scope, which gives read-only access to public repositories, for testing. -This token is only used by Renovate, see the [token configuration](https://docs.renovatebot.com/self-hosted-configuration/#token), and gives it access to the repositories. -The name of the secret can be anything as long as it matches the argument given to the `token` option. +[Generate a Personal Access Token (classic)](https://github.com/settings/tokens): + +1. Give it the `repo:public_repo` scope for public repositories. +2. _Or_ give it the `repo` scope for public and private repositories. +3. Add it to _Secrets_ (repository settings) as `RENOVATE_TOKEN`. -Note that Renovate _cannot_ currently use [Fine-grained Personal Access Tokens](https://github.com/settings/tokens?type=beta) since they do not support the GitHub GraphQL API, yet. +You can also create a token with no specific scope, which gives read-only access to public repositories, for testing. +This token is only used by Renovate, see the [token configuration](https://docs.renovatebot.com/self-hosted-configuration/#token), and gives it access to the repositories. +When naming your secret, follow the rules from the [GitHub Docs, naming your secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#naming-your-secrets). +The name of the secret must match the argument given to the `token` option. -Note that the [`GITHUB_TOKEN`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#permissions-for-the-github_token) secret can't be used for authenticating Renovate because it has too restrictive permissions. +You can not use a [`GITHUB_TOKEN`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#permissions-for-the-github_token) secret to authenticate Renovate because the `GITHUB_TOKEN` limits permissions too much. In particular, using the `GITHUB_TOKEN` to create a new `Pull Request` from more types of Github Workflows results in `Pull Requests` that [do not trigger your `Pull Request` and `Push` CI events](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow). -If you want to use the `github-actions` manager, you must setup a [special token](#special-token-requirements-when-using-the-github-actions-manager) with some requirements. +If you want to use Renovate's `github-actions` manager, you must setup a [special token](#special-token-requirements-when-using-the-github-actions-manager) with some special requirements. ### `renovate-image` The Renovate Docker image name to use. -If omitted or `renovate-image === ''` the action will use the `ghcr.io/renovatebot/renovate` Docker image name otherwise. -If a Docker image name is defined, the action will use that name to pull the image. -This sample will use `myproxyhub.domain.com/renovate/renovate` image. +By default, the action uses the `ghcr.io/renovatebot/renovate` Docker image name. +This default applies if you do not set any name, or set `renovate-image === ''`. -```yml +But if you set a Docker image name, the action will use that name to pull the image. + +This example makes the action use the `myproxyhub.domain.com/renovate/renovate` image: + +```yaml .... jobs: renovate: @@ -194,9 +186,9 @@ jobs: token: ${{ secrets.RENOVATE_TOKEN }} ``` -This sample will use `ghcr.io/renovatebot/renovate` image. +This example makes the action use the `ghcr.io/renovatebot/renovate` image: -```yml +```yaml .... jobs: renovate: @@ -212,13 +204,14 @@ jobs: ### `renovate-version` -The Renovate version to use. -If omitted the action will use the `latest` Docker tag. +By default, the action uses the _latest_ version of Renovate, because the action uses the `latest` Docker tag. + +Use `renovate-version`to control which version of Renovate the action uses. Check [the available tags on Docker Hub](https://hub.docker.com/r/renovate/renovate/tags). -This sample will use `ghcr.io/renovatebot/renovate:37.421.3` image. +This example makes the action use the `ghcr.io/renovatebot/renovate:37.421.3` image: -```yml +```yaml .... jobs: renovate: @@ -233,9 +226,9 @@ jobs: token: ${{ secrets.RENOVATE_TOKEN }} ``` -This sample will use `ghcr.io/renovatebot/renovate:full` image. +This example makes the action use the `ghcr.io/renovatebot/renovate:full` image: -```yml +```yaml .... jobs: renovate: @@ -250,20 +243,25 @@ jobs: token: ${{ secrets.RENOVATE_TOKEN }} ``` -We recommend you pin the version of Renovate to a full version or a full checksum, and use Renovate's regex manager to create PRs to update the pinned version. -See `.github/workflows/build.yml` for an example of how to do this. +We recommend you pin your version of Renovate to a full version, or a full checksum. +Use Renovate's regex manager to tell Renovate how to create PRs to update the pinned version. +See `.github/workflows/build.yml` for an example. ## Example -This example uses a Personal Access Token and will run every 15 minutes. -The Personal Access token is configured as a GitHub secret named `RENOVATE_TOKEN`. +This example uses a Personal Access Token (PAT) and will run the action every 15 minutes. +The PAT is configured as a GitHub secret called `RENOVATE_TOKEN`. This example uses the [`example/renovate-config.js`](./example/renovate-config.js) file as configuration. -Live examples with more advanced configurations of this action can be found in the following repositories: -- [vidavidorra/renovate](https://github.com/vidavidorra/renovate/blob/main/.github/renovate.json) -- [jenkinsci/helm-charts](https://github.com/jenkinsci/helm-charts/blob/main/.github/renovate-config.json5) +Here are some real-world examples with more advanced configurations: -**Remark** Update the action version to the most current, see [here](https://github.com/renovatebot/github-action/releases/latest) for latest release. +- [the `vidavidorra/renovate` repository on GitHub](https://github.com/vidavidorra/renovate/blob/main/.github/renovate.json) +- [the `jenkinsci/helm-charts`repository on GitHub](https://github.com/jenkinsci/helm-charts/blob/main/.github/renovate-config.json5) + +> [!TIP] +> These examples may show old versions of our action. +> When you copy/paste from these examples, remember to update the action to the latest version! +> Go to [`renovatebot/github-actions` release page on GitHub](https://github.com/renovatebot/github-action/releases/latest) to see the latest release. ```yml name: Renovate @@ -287,9 +285,9 @@ jobs: ### Example for GitHub Enterprise -If you want to use the Renovate Action on a GitHub Enterprise instance you have to add the following environment variable: +To use the Renovate Action on a GitHub Enterprise instance you must add the following environment variable: -```yml +```yaml .... - name: Self-hosted Renovate uses: renovatebot/github-action@v40.1.12 @@ -303,15 +301,14 @@ If you want to use the Renovate Action on a GitHub Enterprise instance you have ### Example with GitHub App Instead of using a Personal Access Token (PAT) that is tied to a particular user you can use a [GitHub App](https://docs.github.com/en/developers/apps/building-github-apps) where permissions can be even better tuned. -[Create a new app](https://docs.github.com/en/developers/apps/creating-a-github-app) and configure the app permissions and your `config.js` as described in the [Renovate documentation](https://docs.renovatebot.com/modules/platform/github/#running-as-a-github-app). +[Create a new app](https://docs.github.com/en/developers/apps/creating-a-github-app) and configure the app permissions and your `config.js` as explained in the [Renovate documentation](https://docs.renovatebot.com/modules/platform/github/#running-as-a-github-app). Generate and download a new private key for the app, adding the contents of the downloaded `.pem` file to _Secrets_ (repository settings) with the name `private_key` and app ID as a secret with name `app_id`. +Edit your Renovate configuration file so it sets the username of your bot! -Adjust your Renovate configuration file to specify the username of your bot. - -Going forward we will be using the [`actions/create-github-app-token` action](https://github.com/actions/create-github-app-token) in order to exchange the GitHub App certificate for an access token that Renovate can use. +In this example we use the [`actions/create-github-app-token` action](https://github.com/actions/create-github-app-token) to exchange the GitHub App certificate for an access token that Renovate can use. -The final workflow will look like this: +The final workflow looks like this: ```yaml name: Renovate @@ -345,9 +342,10 @@ jobs: ### Commit signing with GitHub App -Renovate can sign commits when deployed as a GitHub App by utilizing GitHub's API-based commits. -To activate this, ensure that `platformCommit` is set to `true` in global config. -If a configuration file is defined, include `platformCommit: true` to activate this feature. +Renovate can sign commits when deployed as a GitHub App. + +Renovate uses GitHub's API-based commits to sign commits. +To enable commit-signing set `platformCommit` to `true` in your global config, or in your local configuration file. For example: ```yaml @@ -361,9 +359,9 @@ For example: ## Environment Variables -If you wish to pass through environment variables through to the Docker container that powers this action you need to prefix the environment variable with `RENOVATE_`. +To pass through environment variables through to the Docker container that powers this action, you must prefix the environment variable with `RENOVATE_`. -For example if you wish to pass through some credentials for a [host rule](https://docs.renovatebot.com/configuration-options/#hostrules) to the `config.js` then you should do so like this. +For example, if you wish to pass through some credentials for a [host rule](https://docs.renovatebot.com/configuration-options/#hostrules) to the `config.js` then you should do so like this: 1. In your workflow pass in the environment variable @@ -384,7 +382,7 @@ For example if you wish to pass through some credentials for a [host rule](https RENOVATE_TFE_TOKEN: ${{ secrets.MY_TFE_TOKEN }} ``` -1. In `example/renovate-config.js` include the hostRules block +1. In `example/renovate-config.js` include the hostRules block: ```js module.exports = { @@ -402,7 +400,7 @@ For example if you wish to pass through some credentials for a [host rule](https If you want to pass other variables to the Docker container use the `env-regex` input to override the regular expression that is used to allow environment variables. -In your workflow pass the environment variable and whitelist it by specifying the `env-regex`: +In your workflow pass the environment variable and whitelist it by setting the `env-regex`: ```yml .... @@ -424,20 +422,24 @@ jobs: ## Persisting the repository cache -In some cases, Renovate can update PRs more frequently than you expect. The [repository cache](https://docs.renovatebot.com/self-hosted-configuration/#repositorycache) can help with this issue. You need a few things to persist this cache in GitHub actions: +In some cases, Renovate can update PRs more frequently than you expect. +The [repository cache](https://docs.renovatebot.com/self-hosted-configuration/#repositorycache) can help with this issue. +You need a few things to persist this cache in GitHub Actions: -1. Enable the `repositoryCache` [option](https://docs.renovatebot.com/self-hosted-configuration/#repositorycache) via env vars or renovate.json. +1. Enable the `repositoryCache` [option](https://docs.renovatebot.com/self-hosted-configuration/#repositorycache) via environment variables, or in your `renovate.json.` file. 2. Persist `/tmp/renovate/cache/renovate/repository` as an artifact. -3. Restore the artifact before renovate runs. +3. Restore the artifact _before_ Renovate runs. -Below is a workflow example with caching. +### Example workflow with caching -Note that while archiving and compressing the cache is more performant, especially if you need to handle lots of files within the cache, it's not strictly necessary. You could simplify this workflow and only upload and download a single artifact file (or directory) with a direct path (e.g. `/tmp/renovate/cache/renovate/repository/github/$org/$repo.json`). However, you'll still need to set the correct permissions with `chown` as shown in the example. +Archiving and compressing the cache is faster, especially if you handle lots of files within the cache, but it's not strictly needed. +If you want, you can simplify this workflow by only uploading and downloading a _single artifact file_ (or directory) with a direct path like: `/tmp/renovate/cache/renovate/repository/github/$org/$repo.json`. +But even in the simplified workflow, you must still set the correct permissions with `chown` as shown in the example. ```yml name: Renovate on: - # This lets you dispatch a renovate job with different cache options if you want to reset or disable the cache manually. + # This lets you dispatch a Renovate job with different cache options, which is handy if you want to reset (or disable) the cache manually. workflow_dispatch: inputs: repoCache: @@ -452,7 +454,7 @@ on: # Run every 30 minutes: - cron: '0,30 * * * *' -# Adding these as env variables makes it easy to re-use them in different steps and in bash. +# Adding these as environment variables makes it easy to re-use them in different steps and in Bash. env: cache_archive: renovate_cache.tar.gz # This is the dir renovate provides -- if we set our own directory via cacheDir, we can run into permissions issues. @@ -469,7 +471,7 @@ jobs: steps: - uses: actions/checkout@v3 - # This third party action allows you to download the cache artifact from different workflow runs + # This third-party Action allows you to download the cache artifact from different workflow runs # Note that actions/cache doesn't work well because the cache key would need to be computed from # a file within the cache, meaning there would never be any data to restore. With other keys, the # cache wouldn't necessarily upload when it changes. actions/download-artifact also doesn't work @@ -497,9 +499,9 @@ jobs: mkdir -p $cache_dir tar -xzf cache-download/$cache_archive -C $cache_dir - # Unfortunately, the permissions expected within renovate's docker container - # are different than the ones given after the cache is restored. We have to - # change ownership to solve this. We also need to have correct permissions in + # Unfortunately, the permissions expected within Renovate's Docker container + # are different than the ones given after the cache is restored. We must + # change ownership to solve this. We also must have the correct permissions in # the entire /tmp/renovate tree, not just the section with the repo cache. sudo chown -R runneradmin:root /tmp/renovate/ ls -R $cache_dir @@ -528,7 +530,7 @@ jobs: name: ${{ env.cache_key }} path: ${{ env.cache_archive }} # Since this is updated and restored on every run, we don't need to keep it - # for long. Just make sure this value is large enough that multiple renovate + # for long. Just make sure this value is large enough that multiple Renovate # runs can happen before older cache archives are deleted. retention-days: 1 ``` @@ -537,8 +539,9 @@ jobs: ### Debug logging -In case of issues, it's always a good idea to enable debug logging first. -To enable debug logging, add the environment variable `LOG_LEVEL: 'debug'` to the action: +If you have problems, a good first step is to enable debug logging. + +Enable debug logging by adding the environment variable `LOG_LEVEL: 'debug'` to the Action: ```yml - name: Self-hosted Renovate @@ -552,5 +555,5 @@ To enable debug logging, add the environment variable `LOG_LEVEL: 'debug'` to th ### Special token requirements when using the `github-actions` manager -If you want to use the `github-actions` [manager](https://docs.renovatebot.com/modules/manager/github-actions/) in Renovate, ensure that the `token` you provide contains the `workflow` scope. -Otherwise, GitHub does not allow Renovate to update workflow files and therefore it will be unable to create update PRs for affected packages (like `actions/checkout` or `renovatebot/github-action` itself). +If you want to use the `github-actions` [manager](https://docs.renovatebot.com/modules/manager/github-actions/) in Renovate, the `token` you give must have the `workflow` scope. +If you skip this step, GitHub will block Renovate from updating workflow files, this in turn means that Renovate can _not_ create update PRs for affected packages, like `actions/checkout` or `renovatebot/github-action`!