README.md 5.56 KB
Newer Older
Mathias Brodala's avatar
Mathias Brodala committed
1
# Renovate Runner
Michael Kriese's avatar
Michael Kriese committed
2

Michael Kriese's avatar
Michael Kriese committed
3
4
5
6
The intention of this project is to provide a pipeline which is easy to set up and reflects the current app settings as close as possible.

You will need to:

Rhys Arkins's avatar
Rhys Arkins committed
7
1. Create a new project to host the runner
Michael Kriese's avatar
Michael Kriese committed
8
2. Configure credentials using CI variables
Michael Kriese's avatar
Michael Kriese committed
9
3. Create a new `main` pipeline that includes this project's template
Michael Kriese's avatar
Michael Kriese committed
10
11
4. Set up a schedule to run the pipeline regularly

Mathias Brodala's avatar
Mathias Brodala committed
12
## Create a new Runner project
Michael Kriese's avatar
Michael Kriese committed
13

Rhys Arkins's avatar
Rhys Arkins committed
14
We recommend you use a new and dedicated private project to host the Renovate runner, however a public project with private CI logs should still be safe.
Thomas Praxl's avatar
Thomas Praxl committed
15
Currently one advantage of public projects is that CI minutes are not restricted however the same restrictions as private projects will soon apply.
Michael Kriese's avatar
Michael Kriese committed
16
17
18

## Configure CI/CD variables

Rhys Arkins's avatar
Rhys Arkins committed
19
You need to add a GitLab [Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#creating-a-personal-access-token) (scopes: `read_user`, `api` and `write_repository`) as `RENOVATE_TOKEN` to CI/CD variables.
Michael Kriese's avatar
Michael Kriese committed
20
21
22
23
24

It is also recommended to configure a [GitHub.com Personal Access Token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) (minimum scopes) as `GITHUB_COM_TOKEN` so that your bot can make authenticated requests to github.com for Changelog retrieval as well as for any dependency that uses GitHub tags.
Without such a token, github.com's API will rate limit requests and make such lookups unreliable.

Finally, you need to decide how your bot should decide which projects to run against.
Michael Kriese's avatar
Michael Kriese committed
25
By default renovate won't find any repo, you need to choose one of the following options for `RENOVATE_EXTRA_FLAGS`.
Michael Kriese's avatar
Michael Kriese committed
26

27
28
If you wish for your bot to run against any project which the `RENOVATE_TOKEN` PAT has access to, but which already have a `renovate.json` or similar config file, then add this variable: `RENOVATE_EXTRA_FLAGS=`: `--autodiscover=true`.
This will mean no new projects will be onboarded.
Michael Kriese's avatar
Michael Kriese committed
29

Michael Kriese's avatar
Michael Kriese committed
30
However, we recommend you apply an `autodiscoverFilter` value like the following so that the bot does not run on any stranger's project it gets invited to: `RENOVATE_EXTRA_FLAGS`: `--autodiscover=true --autodiscover-filter=group1/*`.
31
Checkout renovate [docs](https://docs.renovatebot.com/gitlab-bot-security/) for more information about gitlab security.
Rhys Arkins's avatar
Rhys Arkins committed
32

33
If you wish for your bot to run against *every* project which the `RENOVATE_TOKEN` PAT has access to, and onboard any projects which don't yet have a config, then add this variable: `RENOVATE_EXTRA_FLAGS`: `--autodiscover=true --onboarding=true --autodiscover-filter=group1/*`.
Rhys Arkins's avatar
Rhys Arkins committed
34

Rhys Arkins's avatar
Rhys Arkins committed
35
If you wish to manually specify which projects that your bot runs again, then add this variable with a space-delimited set of project names: `RENOVATE_EXTRA_FLAGS`: `group1/repo5 user3/repo1`.
Michael Kriese's avatar
Michael Kriese committed
36
37
38
39
40
41
42
43

## Create a GitLab CI file

Create a `.gitlab-ci.yml` file in the repository like the following:

```yaml
include:
  - project: 'renovate-bot/renovate-runner'
44
    file: '/templates/renovate-dind.gitlab-ci.yml'
Michael Kriese's avatar
Michael Kriese committed
45
46
```

Mathias Brodala's avatar
Mathias Brodala committed
47
If you are using a custom GitLab Kubernetes runner you probably need to downgrade the Docker DinD service because of [containerd/containerd#4837](https://github.com/containerd/containerd/issues/4837)
48
49
50
51
52
53
54
55
56
57

```yaml
include:
  - project: 'renovate-bot/renovate-runner'
    file: '/templates/renovate-dind.gitlab-ci.yml'

services:
  - docker:19.03.15-dind
```

Michael Kriese's avatar
Michael Kriese committed
58
59
60
61
62
Alternatively, if you cannot use the gitlab.com hosted or self-hosted privileged runners, include the following template instead.

**Note:** This will use the full renovate image, which isn't capable of respecting any binary contraints.
It will always use the latest tools to update lock files.
So please prefer the DinD version.
63
64
65
66
67
68
69

```yaml
include:
  - project: 'renovate-bot/renovate-runner'
    file: '/templates/renovate.gitlab-ci.yml'
```

Mathias Brodala's avatar
Mathias Brodala committed
70
To prevent unexpected changes in your pipeline, you can pin the version of this template and include it in your Renovate updates:
71
72
73
74

```yaml
include:
  - project: 'renovate-bot/renovate-runner'
Michael Kriese's avatar
Michael Kriese committed
75
    file: '/templates/renovate-dind.gitlab-ci.yml'
76
77
78
79
80
81
    ref: v1.0.0
```

Please check this project's [Releases page](https://gitlab.com/renovate-bot/renovate-runner/-/releases)
to find the latest release tags to reference.

Michael Kriese's avatar
Michael Kriese committed
82
By default our pipeline only runs on schedules.
83
If you want it to run on other events, see the [GitLab docs for `rules`](https://docs.gitlab.com/ee/ci/yaml/#rules).
Mathias Brodala's avatar
Mathias Brodala committed
84
85

Example to run on schedules and pushes:
Michael Kriese's avatar
Michael Kriese committed
86
87
88
89
90
91
92

```yaml
include:
  - project: 'renovate-bot/renovate-runner'
    file: '/templates/renovate-dind.gitlab-ci.yml'

renovate:
93
94
95
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - if: '$CI_PIPELINE_SOURCE == "push"'
Michael Kriese's avatar
Michael Kriese committed
96
97
``` 

Michael Kriese's avatar
Michael Kriese committed
98
99
100
101
## Configure the Schedule

Add a schedule (`CI / CD` > `Schedules`) to run Renovate regularly.

Mathias Brodala's avatar
Mathias Brodala committed
102
A good practise is to run it hourly. The following runs Renovate on the third minute every hour: `3 * * * *`.
Michael Kriese's avatar
Michael Kriese committed
103

Michael Kriese's avatar
Michael Kriese committed
104
105
Because the default pipeline only runs on schedules, you need to use the `play` button of schedule to trigger a manual run.

Michael Kriese's avatar
Michael Kriese committed
106
107
## Other config options

Mathias Brodala's avatar
Mathias Brodala committed
108
We've changed some renovate defaults for GitLab to better reflect the app's default behavior, so please see [here](./templates/_common.gitlab-ci.yml#L1) for changed options.
Michael Kriese's avatar
Michael Kriese committed
109
For renovate configuration basics checkout the official self-hosting [docs](https://docs.renovatebot.com/self-hosting/#configuration).
Michael Kriese's avatar
Michael Kriese committed
110

Mathias Brodala's avatar
Mathias Brodala committed
111
For other self-hosted GitLab samples you can check the [Renovate Gitlab Configuration](https://github.com/renovatebot/docker-renovate/blob/HEAD/docs/gitlab.md).
112

Mathias Brodala's avatar
Mathias Brodala committed
113
If you are using a self-hosted runner, please checkout the [GitLab docs for Docker DinD configuration](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-the-docker-executor-with-the-docker-image-docker-in-docker).