community.general.gitlab_runner 模块 – 创建、修改和删除 GitLab Runner

注意

此模块是 community.general 集合 (版本 10.1.0) 的一部分。

如果您正在使用 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。

要在 playbook 中使用它，请指定：community.general.gitlab_runner。

概要

• 使用 GitLab API 在 GitLab 服务器端注册、更新和删除 Runner。

• 所有操作均使用 GitLab API v4 执行。

• 详情请参阅完整 API 文档：https://docs.gitlab.com/ee/api/runners.html 和 https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user。

• 所有操作都需要有效的私有 API 令牌。您可以使用 GitLab Web 界面在 https://$GITLAB_URL/profile/personal_access_tokens 创建任意数量的令牌。

• 注册新的 Runner 需要有效的注册令牌。要创建共享 Runner，您需要请求管理员提供此令牌。它可以在 https://$GITLAB_URL/admin/runners/ 找到。

• 此模块不处理 gitlab-runner 进程部分，而只是通过其 API 管理 GitLab 服务器端的 Runner。模块创建 Runner 后，您可以使用生成的令牌运行 gitlab-runner register 命令。

要求

执行此模块的主机需要以下要求。

• 对于旧版 Runner 注册工作流（Runner 注册令牌 - https://docs.gitlab.com/runner/register/#register-with-a-runner-registration-token-deprecated），需要 python-gitlab >= 1.5.0。

• 对于新的 Runner 注册工作流（Runner 身份验证令牌 - https://docs.gitlab.com/runner/register/#register-with-a-runner-authentication-token），需要 python-gitlab >= 4.0.0。

• requests (Python 库 https://pypi.ac.cn/project/requests/)

参数

参数	注释
access_level 字符串	确定 Runner 是否只能拾取受保护分支的作业。 如果 access_level_on_creation 未明确设置为 true，则此选项在注册时会被忽略，仅在更新时应用。 如果设置为 not_protected，Runner 可以拾取受保护和不受保护分支的作业。 如果设置为 ref_protected，Runner 只能拾取受保护分支的作业。 在 community.general 8.0.0 之前，默认值为 ref_protected。community.general 8.0.0 中将其更改为无默认值。如果未显式指定此选项，GitLab 将在创建时使用 not_protected，并且在任何更新中都不会更改设置的值。 选项 "not_protected" "ref_protected"
access_level_on_creation 布尔值 在 community.general 6.3.0 中添加	Runner 是否应该注册访问级别。 如果设置为 true，则 access_level 的值用于 Runner 注册。 如果设置为 false，GitLab 将使用默认访问级别注册 Runner。 此选项的默认值在 community.general 7.0.0 中更改为 true。之前是 false。 选项 false true ← (默认)
active 布尔值	定义 Runner 在创建后是否立即处于活动状态。 与paused互斥。 选项 false true ← (默认)
api_job_token 字符串 community.general 4.2.0版本中添加	用于登录的GitLab CI作业令牌。
api_oauth_token 字符串 community.general 4.2.0版本中添加	用于登录的GitLab OAuth令牌。
api_password 字符串	用于针对API进行身份验证的密码。
api_token 字符串	具有API权限的GitLab访问令牌。
api_url 字符串	API的可解析端点。
api_username 字符串	用于针对API进行身份验证的用户名。
ca_path 字符串 community.general 8.1.0版本中添加	用于验证GitLab服务器证书的CA证书捆绑包。
description 别名：name 字符串 / 必需	运行器的唯一名称。
group 字符串 community.general 6.5.0版本中添加	组的ID或完整路径，格式为group/subgroup。 与owned和project互斥。 如果未设置registration_token且state=present，则必须是组的数字ID。
locked 布尔值	确定运行器是否被锁定。 选项 false ← (默认) true
maximum_timeout 整数	运行器完成特定作业的最长时间。 默认： 3600
owned 布尔值 community.general 2.0.0版本中添加	在搜索现有运行器时，仅搜索用户可用的运行器，如果为false，则需要管理员令牌。 自community.general 4.5.0版本起，与project互斥。 与group互斥。 选项 false ← (默认) true
paused 布尔值 community.general 8.1.0版本中添加	定义创建后运行器是处于活动状态还是暂停状态。 与active互斥。 选项 false ← (默认) true
project 字符串 community.general 3.7.0版本中添加	项目的ID或完整路径，格式为group/name。 自community.general 4.5.0版本起，与owned互斥。 与group互斥。 如果未设置registration_token且state=present，则必须是项目的数字ID。
registration_token 字符串	注册令牌用于在GitLab 16.0之前注册新的运行器。 如果GitLab < 16.0 且state=present，则需要此参数。 如果设置，则将使用旧的运行器创建工作流创建运行器。 如果未设置，则将使用GitLab 16.0中引入的新运行器创建工作流创建运行器。 如果未设置，则需要python-gitlab >= 4.0.0。
run_untagged 布尔值	是否运行未标记的作业。 选项 false true ← (默认)
state 字符串	确保具有相同名称的运行器存在且具有相同的配置，或者删除具有相同名称的运行器。 选项 "present" ← (默认) "absent"
tag_list 列表 / 元素=字符串	应用于运行器的标签。 默认： []
validate_certs 布尔值	提供HTTPS端点时是否验证SSL证书。 选项 false true ← (默认)

属性

属性	支持	描述
check_mode	支持：完全支持	可以在check_mode下运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：不支持	处于diff模式时，将返回有关已更改内容（或可能需要在check_mode中更改的内容）的详细信息。

备注

注意

• 要创建一个新的运行器，至少需要api_token、description和api_url选项。

• 运行器需要具有唯一的描述，因为此属性用作幂等性的键。

示例

- 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:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    registration_token: 4gfdsg345
    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: "Delete runner"
  community.general.gitlab_runner:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    description: Docker Machine t1
    state: absent

- name: Delete an owned runner as a non-admin
  community.general.gitlab_runner:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    description: Docker Machine t1
    owned: true
    state: absent

- name: "Register a project-level runner with registration token (deprecated)"
  community.general.gitlab_runner:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    registration_token: 4gfdsg345
    description: MyProject runner
    state: present
    project: mygroup/mysubgroup/myproject
  register: runner # Register module output to run C(gitlab-runner register) command in another task

返回值

常见的返回值已在此处记录，以下是此模块独有的字段

键	描述
error 字符串	GitLab API返回的错误消息 返回：失败 示例： "400: path is already in use"
msg 字符串	成功或失败消息 返回：始终 示例： "Success"
result 字典	来自服务器的JSON解析响应 返回：始终
runner 字典	API对象 返回：始终

作者

• Samy Coenen (@SamyCoenen)

• Guillaume Martinez (@Lunik)

集合链接

• 问题跟踪器
• 代码库（源代码）
• 寻求帮助
• 提交错误报告
• 请求功能
• 沟通