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 证书包。
描述 别名: name 字符串 / 必填	运行器的唯一名称。
组 字符串 新增于 community.general 6.5.0	组的ID或完整路径，格式为 group/subgroup。 与 owned 和 project 互斥。 如果未设置 registration_token 且 state=present，则必须为组的数字 ID。
锁定 布尔值	确定运行器是否被锁定。 选项 false ← (默认) true
最大超时时间 整数	运行器完成特定作业的最长时间。 默认值: 3600
owned 布尔值 新增于 community.general 2.0.0	搜索现有运行器时，仅搜索用户可用的运行器；如果为false，则需要管理员令牌。 自 community.general 4.5.0 起，与 project 互斥。 与 group 互斥。 选项 false ← (默认) true
暂停 布尔值 在 community.general 8.1.0 中添加	定义创建后运行器是处于活动状态还是暂停状态。 与 active 互斥。 选项 false ← (默认) true
项目 字符串 新增于 community.general 3.7.0	项目的ID或完整路径，格式为 group/name。 自 community.general 4.5.0 起，与 owned 互斥。 与 group 互斥。 如果未设置 registration_token 且 state=present，则必须为项目的数字 ID。
注册令牌 字符串	注册令牌用于在 GitLab 16.0 之前注册新的运行器。 对于 GitLab < 16.0，如果 state=present，则此项必填。 如果设置，则将使用旧的运行器创建工作流程创建运行器。 如果未设置，则将使用在 GitLab 16.0 中引入的新运行器创建工作流程创建运行器。 如果未设置，则需要 python-gitlab >= 4.0.0。
运行未标记的任务 布尔值	是否运行未标记的作业。 选项 false true ← (默认)
状态 字符串	确保具有相同名称的运行器存在且具有相同的配置，或者删除具有相同名称的运行器。 选项 "present" ← (默认) "absent"
标签列表 列表 / 元素=字符串	应用于运行器的标签。 默认值: []
验证证书 布尔值	提供 HTTPS 端点时是否验证 SSL 证书。 选项 false true ← (默认)

属性

属性	支持	描述
检查模式	支持: 完全支持	可以在 check_mode 中运行，并在不修改目标的情况下返回更改状态预测。
差异模式	支持: 不支持	在差异模式下，将返回有关已更改内容（或可能需要在 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

返回值

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

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

作者

• Samy Coenen (@SamyCoenen)

• Guillaume Martinez (@Lunik)

集合链接

• 问题追踪器
• 代码仓库
• 寻求帮助
• 提交错误报告
• 请求功能
• 沟通