GitHub Action to run Renovate self-hosted.
Badge | Description | Service |
---|---|---|
Code style | Prettier | |
Commit style | Conventional Commits | |
Dependencies | Renovate | |
Build | GitHub Actions |
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 docs.
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.
Config examples can be found in the example directory.
The configurations that can be done in this file consists of two parts, as listed below. Refer to the links to the Renovate Docs for all options.
The 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 this with just the 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.
onboarding: false,
requireConfig: false,
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.
For example you can create a simple script like this one (let's call it
renovate-entrypoint.sh
).
#!/bin/bash
apt update
apt install -y build-essential libpq-dev
runuser -u ubuntu renovate
Now use this action
....
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
docker-cmd-file: .github/renovate-entrypoint.sh
docker-user: root
token: ${{ secrets.RENOVATE_TOKEN }}
Specify a network to run container in.
You can use ${{ job.container.network }}
to run renovate container in the same network as other containers for this job,
or set it to host
to run in the same network as github runner, or specify any custom network.
Allows the overriding of the host path for the Docker socket that is mounted into the container.
Useful on systems where the host Docker socket is located somewhere other than /var/run/docker.sock
(the default).
Only applicable when mount-docker-socket
is true.
Specify a user (or user-id) to run docker command.
You can use it with docker-cmd-file
in order to start the
image as root, do some customization and switch back to a unprivileged user.
Specify volume mounts. Defaults to /tmp:/tmp
.
The volume mounts are separated through ;
.
This sample will mount /tmp:/tmp
, /home:/home
and /foo:/bar
.
....
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
token: ${{ secrets.RENOVATE_TOKEN }}
docker-volumes: |
/tmp:/tmp ;
/home:/home ;
/foo:/bar
Allows to configure the regex to define which environment variables are passed to the renovate container. See Passing other environment variables section for more details.
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.
Generate a Personal Access Token (classic), 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, 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.
Note that Renovate cannot currently use Fine-grained Personal Access Tokens since they do not support the GitHub GraphQL API, yet.
Note that the GITHUB_TOKEN
secret can't be used for authenticating Renovate because it has too restrictive permissions.
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.
If you want to use the github-actions
manager, you must setup a special token with some requirements.
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.
....
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
renovate-image: myproxyhub.domain.com/renovate/renovate
token: ${{ secrets.RENOVATE_TOKEN }}
This sample will use ghcr.io/renovatebot/renovate
image.
....
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
token: ${{ secrets.RENOVATE_TOKEN }}
The Renovate version to use.
If omitted the action will use the latest
Docker tag.
Check the available tags on Docker Hub.
This sample will use ghcr.io/renovatebot/renovate:38.110.2
image.
....
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
renovate-version: 38.110.2
token: ${{ secrets.RENOVATE_TOKEN }}
This sample will use ghcr.io/renovatebot/renovate:full
image.
....
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
renovate-version: full
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.
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 the example/renovate-config.js
file as configuration.
Live examples with more advanced configurations of this action can be found in the following repositories:
Remark Update the action version to the most current, see here for latest release.
name: Renovate
on:
schedule:
# The "*" (#42, asterisk) character has special semantics in YAML, so this
# string has to be quoted.
- cron: '0/15 * * * *'
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
configurationFile: example/renovate-config.js
token: ${{ secrets.RENOVATE_TOKEN }}
If you want to use the Renovate Action on a GitHub Enterprise instance you have to add the following environment variable:
....
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
configurationFile: example/renovate-config.js
token: ${{ secrets.RENOVATE_TOKEN }}
env:
RENOVATE_ENDPOINT: "https://git.your-company.com/api/v3"
Instead of using a Personal Access Token (PAT) that is tied to a particular user you can use a GitHub App where permissions can be even better tuned.
Create a new app and configure the app permissions and your config.js
as described in the Renovate documentation.
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
.
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 in order to exchange the GitHub App certificate for an access token that Renovate can use.
The final workflow will look like this:
name: Renovate
on:
schedule:
# The "*" (#42, asterisk) character has special semantics in YAML, so this
# string has to be quoted.
- cron: '0/15 * * * *'
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Get token
id: get_token
uses: actions/create-github-app-token@v1
with:
private-key: ${{ secrets.private_key }}
app-id: ${{ secrets.app_id }}
owner: ${{ github.repository_owner }}
repositories: 'repo1,repo2'
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
configurationFile: example/renovate-config.js
token: '${{ steps.get_token.outputs.token }}'
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.
For example:
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
token: '${{ steps.get_token.outputs.token }}'
env:
RENOVATE_PLATFORM_COMMIT: 'true'
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_
.
For example if you wish to pass through some credentials for a host rule to the config.js
then you should do so like this.
-
In your workflow pass in the environment variable
.... jobs: renovate: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4.2.1 - name: Self-hosted Renovate uses: renovatebot/github-action@v40.3.3 with: configurationFile: example/renovate-config.js token: ${{ secrets.RENOVATE_TOKEN }} env: RENOVATE_TFE_TOKEN: ${{ secrets.MY_TFE_TOKEN }}
-
In
example/renovate-config.js
include the hostRules blockmodule.exports = { hostRules: [ { hostType: 'terraform-module', matchHost: 'app.terraform.io', token: process.env.RENOVATE_TFE_TOKEN, }, ], };
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
:
....
jobs:
renovate:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4.2.1
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
configurationFile: example/renovate-config.js
token: ${{ secrets.RENOVATE_TOKEN }}
env-regex: "^(?:RENOVATE_\\w+|LOG_LEVEL|GITHUB_COM_TOKEN|NODE_OPTIONS|AWS_TOKEN)$"
env:
AWS_TOKEN: ${{ secrets.AWS_TOKEN }}
In some cases, Renovate can update PRs more frequently than you expect. The repository cache can help with this issue. You need a few things to persist this cache in GitHub actions:
- Enable the
repositoryCache
option via env vars or renovate.json. - Persist
/tmp/renovate/cache/renovate/repository
as an artifact. - Restore the artifact before renovate runs.
Below is a workflow example 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.
name: Renovate
on:
# This lets you dispatch a renovate job with different cache options if you want to reset or disable the cache manually.
workflow_dispatch:
inputs:
repoCache:
description: 'Reset or disable the cache?'
type: choice
default: enabled
options:
- enabled
- disabled
- reset
schedule:
# 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.
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.
# It is also possible to cache a higher level of the directory, but it has minimal benefit. While renovate execution
# time gets faster, it also takes longer to upload the cache as it grows bigger.
cache_dir: /tmp/renovate/cache/renovate/repository
# This can be manually changed to bust the cache if neccessary.
cache_key: renovate-cache
jobs:
renovate:
name: Renovate
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
# 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
# because it only handles artifacts uploaded in the same run, and we want to restore from the
# previous successful run.
- uses: dawidd6/action-download-artifact@v2
if: github.event.inputs.repoCache != 'disabled'
continue-on-error: true
with:
name: ${{ env.cache_key }}
path: cache-download
# Using tar to compress and extract the archive isn't strictly necessary, but it can improve
# performance significantly when uploading artifacts with lots of files.
- name: Extract renovate cache
run: |
set -x
# Skip if no cache is set, such as the first time it runs.
if [ ! -d cache-download ] ; then
echo "No cache found."
exit 0
fi
# Make sure the directory exists, and extract it there. Note that it's nested in the download directory.
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
# the entire /tmp/renovate tree, not just the section with the repo cache.
sudo chown -R runneradmin:root /tmp/renovate/
ls -R $cache_dir
- uses: renovatebot/github-action@v40.3.3
with:
configurationFile: renovate.json5
token: ${{ secrets.RENOVATE_TOKEN }}
renovate-version: 38.110.2
env:
# This enables the cache -- if this is set, it's not necessary to add it to renovate.json.
RENOVATE_REPOSITORY_CACHE: ${{ github.event.inputs.repoCache || 'enabled' }}
# Compression helps performance in the upload step!
- name: Compress renovate cache
run: |
ls $cache_dir
# The -C is important -- otherwise we end up extracting the files with
# their full path, ultimately leading to a nested directory situation.
# To solve *that*, we'd have to extract to root (/), which isn't safe.
tar -czvf $cache_archive -C $cache_dir .
- uses: actions/upload-artifact@v3
if: github.event.inputs.repoCache != 'disabled'
with:
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
# runs can happen before older cache archives are deleted.
retention-days: 1
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:
- name: Self-hosted Renovate
uses: renovatebot/github-action@v40.3.3
with:
configurationFile: example/renovate-config.js
token: ${{ secrets.RENOVATE_TOKEN }}
env:
LOG_LEVEL: 'debug'
If you want to use the github-actions
manager 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).