1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00

docs(gitlab_runner): improve docs and add examples (#8310)

This commit is contained in:
Léo GATELLIER 2024-05-10 15:15:18 +02:00 committed by GitHub
parent feb443d260
commit cb985b31f9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -15,17 +15,20 @@ DOCUMENTATION = '''
module: gitlab_runner module: gitlab_runner
short_description: Create, modify and delete GitLab Runners short_description: Create, modify and delete GitLab Runners
description: description:
- Register, update and delete runners with the GitLab API. - Register, update and delete runners on GitLab Server side with the GitLab API.
- All operations are performed using the GitLab API v4. - All operations are performed using the GitLab API v4.
- For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html). - For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html)
and U(https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user).
- A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web interface at - A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web interface at
U(https://$GITLAB_URL/profile/personal_access_tokens). U(https://$GITLAB_URL/profile/personal_access_tokens).
- A valid registration token is required for registering a new runner. - A valid registration token is required for registering a new runner.
To create shared runners, you need to ask your administrator to give you this token. To create shared runners, you need to ask your administrator to give you this token.
It can be found at U(https://$GITLAB_URL/admin/runners/). It can be found at U(https://$GITLAB_URL/admin/runners/).
- This module does not handle the C(gitlab-runner) process part, but only manages the runner on GitLab Server side through its API.
Once the module has created the runner, you may use the generated token to run C(gitlab-runner register) command
notes: notes:
- To create a new runner at least the O(api_token), O(description) and O(api_url) options are required. - To create a new runner at least the O(api_token), O(description) and O(api_url) options are required.
- Runners need to have unique descriptions. - Runners need to have unique descriptions, since this attribute is used as key for idempotency
author: author:
- Samy Coenen (@SamyCoenen) - Samy Coenen (@SamyCoenen)
- Guillaume Martinez (@Lunik) - Guillaume Martinez (@Lunik)
@ -153,7 +156,45 @@ options:
''' '''
EXAMPLES = ''' EXAMPLES = '''
- name: "Register runner" - name: Create an instance-level runner
community.general.gitlab_runner:
api_url: https://gitlab.example.com/
api_token: "{{ access_token }}"
description: Docker Machine t1
state: present
active: true
tag_list: ['docker']
run_untagged: false
locked: false
register: runner # Register module output to run C(gitlab-runner register) command in another task
- name: Create a group-level runner
community.general.gitlab_runner:
api_url: https://gitlab.example.com/
api_token: "{{ access_token }}"
description: Docker Machine t1
state: present
active: true
tag_list: ['docker']
run_untagged: false
locked: false
group: top-level-group/subgroup
register: runner # Register module output to run C(gitlab-runner register) command in another task
- name: Create a project-level runner
community.general.gitlab_runner:
api_url: https://gitlab.example.com/
api_token: "{{ access_token }}"
description: Docker Machine t1
state: present
active: true
tag_list: ['docker']
run_untagged: false
locked: false
project: top-level-group/subgroup/project
register: runner # Register module output to run C(gitlab-runner register) command in another task
- name: "Register instance-level runner with registration token (deprecated)"
community.general.gitlab_runner: community.general.gitlab_runner:
api_url: https://gitlab.example.com/ api_url: https://gitlab.example.com/
api_token: "{{ access_token }}" api_token: "{{ access_token }}"
@ -164,6 +205,7 @@ EXAMPLES = '''
tag_list: ['docker'] tag_list: ['docker']
run_untagged: false run_untagged: false
locked: false locked: false
register: runner # Register module output to run C(gitlab-runner register) command in another task
- name: "Delete runner" - name: "Delete runner"
community.general.gitlab_runner: community.general.gitlab_runner:
@ -180,7 +222,7 @@ EXAMPLES = '''
owned: true owned: true
state: absent state: absent
- name: Register runner for a specific project - name: "Register a project-level runner with registration token (deprecated)"
community.general.gitlab_runner: community.general.gitlab_runner:
api_url: https://gitlab.example.com/ api_url: https://gitlab.example.com/
api_token: "{{ access_token }}" api_token: "{{ access_token }}"
@ -188,6 +230,7 @@ EXAMPLES = '''
description: MyProject runner description: MyProject runner
state: present state: present
project: mygroup/mysubgroup/myproject project: mygroup/mysubgroup/myproject
register: runner # Register module output to run C(gitlab-runner register) command in another task
''' '''
RETURN = ''' RETURN = '''