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:
parent
feb443d260
commit
cb985b31f9
1 changed files with 48 additions and 5 deletions
|
@ -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 = '''
|
||||||
|
|
Loading…
Reference in a new issue