Skip to content

Commit d19ee24

Browse files
timofurrertimofurrer
authored
Merge pull request #1049 from PatrickRice-KSC/add-gitlab-runner-resource
Add gitlab_runner Resource
2 parents fd03393 + 7749ef2 commit d19ee24

File tree

6 files changed

+621
-0
lines changed

6 files changed

+621
-0
lines changed

‎docs/resources/runner.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
# generated by https://github.com/hashicorp/terraform-plugin-docs
3+
page_title: "gitlab_runner Resource - terraform-provider-gitlab"
4+
subcategory: ""
5+
description: |-
6+
The gitlab_runner resource allows to manage the lifecycle of a runner.
7+
A runner can either be registered at an instance level or group level.
8+
The runner will be registered at a group level if the token used is from a group, or at an instance level if the token used is for the instance.
9+
Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner
10+
---
11+
12+
# gitlab_runner (Resource)
13+
14+
The `gitlab_runner` resource allows to manage the lifecycle of a runner.
15+
16+
A runner can either be registered at an instance level or group level.
17+
The runner will be registered at a group level if the token used is from a group, or at an instance level if the token used is for the instance.
18+
19+
**Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner)
20+
21+
## Example Usage
22+
23+
```terraform
24+
# Basic GitLab Group Runner
25+
resource "gitlab_group" "my_group" {
26+
name = "my runner"
27+
description = "group that holds the runners"
28+
}
29+
resource "gitlab_runner" "basic_runner" {
30+
registration_token = gitlab_group.my_group.runners_token
31+
}
32+
33+
# GitLab Runner that runs only tagged jobs
34+
resource "gitlab_runner" "tagged_only" {
35+
registration_token = gitlab_group.my_group.runners_token
36+
description = "I only run tagged jobs"
37+
38+
run_untagged = "false"
39+
tag_list = ["tag_one", "tag_two"]
40+
}
41+
42+
# GitLab Runner that only runs on protected branches
43+
resource "gitlab_runner" "protected" {
44+
registration_token = gitlab_group.my_group.runners_token
45+
description = "I only run protected jobs"
46+
47+
access_level = "ref_protected"
48+
}
49+
50+
# Generate a `config.toml` file that you can use to create a runner
51+
# This is the typical workflow for this resource, using it to create an authentication_token which can then be used
52+
# to generate the `config.toml` file to prevent re-registering the runner every time new hardware is created.
53+
54+
resource "gitlab_group" "my_custom_group" {
55+
name = "my custom runner"
56+
description = "group that holds the custom runners"
57+
}
58+
59+
resource "gitlab_runner" "my_runner" {
60+
registration_token = gitlab_group.my_custom_group.runners_token
61+
}
62+
63+
# This creates a configuration for a local "shell" runner, but can be changed to generate whatever is needed.
64+
# Place this configuration file on a server at `/etc/gitlab-runner/config.toml`, then run `gitlab-runner start`.
65+
# See https://docs.gitlab.com/runner/configuration/advanced-configuration.html for more information.
66+
resource "local_file" "config" {
67+
filename = "${path.module}/config.toml"
68+
content = <<CONTENT
69+
concurrent = 1
70+
71+
[[runners]]
72+
name = "Hello Terraform"
73+
url = "https://example.gitlab.com/"
74+
token = "${gitlab_runner.my_runner.authentication_token}"
75+
executor = "shell"
76+
77+
CONTENT
78+
}
79+
```
80+
81+
<!-- schema generated by tfplugindocs -->
82+
## Schema
83+
84+
### Required
85+
86+
- `registration_token` (String, Sensitive) The registration token used to register the runner.
87+
88+
### Optional
89+
90+
- `access_level` (String) The access_level of the runner. Valid values are: `not_protected`, `ref_protected`.
91+
- `description` (String) The runner's description.
92+
- `id` (String) The ID of this resource.
93+
- `locked` (Boolean) Whether the runner should be locked for current project.
94+
- `maximum_timeout` (Number) Maximum timeout set when this runner handles the job.
95+
- `paused` (Boolean) Whether the runner should ignore new jobs.
96+
- `run_untagged` (Boolean) Whether the runner should handle untagged jobs.
97+
- `tag_list` (List of String) List of runner’s tags.
98+
99+
### Read-Only
100+
101+
- `authentication_token` (String, Sensitive) The authentication token used for building a config.toml file. This value is not present when imported.
102+
- `status` (String) The status of runners to show, one of: online and offline. active and paused are also possible values
103+
which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0.
104+
105+
## Import
106+
107+
Import is supported using the following syntax:
108+
109+
```shell
110+
# A GitLab Runner can be imported using the runner's ID, eg
111+
terraform import gitlab_runner.this 1
112+
```

‎examples/resources/gitlab_runner/import.sh

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# A GitLab Runner can be imported using the runner's ID, eg
2+
terraform import gitlab_runner.this 1

‎examples/resources/gitlab_runner/resource.tf

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Basic GitLab Group Runner
2+
resource "gitlab_group" "my_group" {
3+
name = "my runner"
4+
description = "group that holds the runners"
5+
}
6+
resource "gitlab_runner" "basic_runner" {
7+
registration_token = gitlab_group.my_group.runners_token
8+
}
9+
10+
# GitLab Runner that runs only tagged jobs
11+
resource "gitlab_runner" "tagged_only" {
12+
registration_token = gitlab_group.my_group.runners_token
13+
description = "I only run tagged jobs"
14+
15+
run_untagged = "false"
16+
tag_list = ["tag_one", "tag_two"]
17+
}
18+
19+
# GitLab Runner that only runs on protected branches
20+
resource "gitlab_runner" "protected" {
21+
registration_token = gitlab_group.my_group.runners_token
22+
description = "I only run protected jobs"
23+
24+
access_level = "ref_protected"
25+
}
26+
27+
# Generate a `config.toml` file that you can use to create a runner
28+
# This is the typical workflow for this resource, using it to create an authentication_token which can then be used
29+
# to generate the `config.toml` file to prevent re-registering the runner every time new hardware is created.
30+
31+
resource "gitlab_group" "my_custom_group" {
32+
name = "my custom runner"
33+
description = "group that holds the custom runners"
34+
}
35+
36+
resource "gitlab_runner" "my_runner" {
37+
registration_token = gitlab_group.my_custom_group.runners_token
38+
}
39+
40+
# This creates a configuration for a local "shell" runner, but can be changed to generate whatever is needed.
41+
# Place this configuration file on a server at `/etc/gitlab-runner/config.toml`, then run `gitlab-runner start`.
42+
# See https://docs.gitlab.com/runner/configuration/advanced-configuration.html for more information.
43+
resource "local_file" "config" {
44+
filename = "${path.module}/config.toml"
45+
content = <<CONTENT
46+
concurrent = 1
47+
48+
[[runners]]
49+
name = "Hello Terraform"
50+
url = "https://example.gitlab.com/"
51+
token = "${gitlab_runner.my_runner.authentication_token}"
52+
executor = "shell"
53+
54+
CONTENT
55+
}
56+

0 commit comments

Comments
 (0)