Labels, badges, and roles

Configuring labels, badges, and group roles

Name-keyed collections available on group and project entries: labels and badges at both scopes, plus group member roles and SSH certificates. Instance-level topics are documented in Instance Administration.

Example definition

gitlab_settings_groups:
  - path: platform
    labels:
      - name: security
        color: "#d9534f"
        description: Security relevant
    badges:
      - name: pipeline
        link_url: "https://gitlab.example.com/%{project_path}/-/pipelines"
        image_url: "https://gitlab.example.com/%{project_path}/badges/%{default_branch}/pipeline.svg"
    member_roles:
      - name: deployer
        base_access_level: 30
        admin_merge_request: true
    ssh_certificates:
      - title: engineering-ca
        key: "ssh-rsa AAAA... ca@example.com"

gitlab_settings_projects:
  - path: platform/service
    labels:
      - name: bug
        color: "#ff0000"
      - name: unused-label
        state: absent

Labels, Badges, And Roles Spec

GitLab API reference

GitLab's API documentation defines the fields:

1. Labels API / Group labels API
2. Project badges / Group badges
3. Member roles API
4. Group SSH certificates API

labels array of objects  Group or project labels matched by name. Properties of labels  name stringRequired Current label name and identity.  color stringRequired on create Label color; reconciles with drift detection.  description string Label description; reconciles with drift detection.  priority integer Label priority; reconciles with drift detection.  new_name string Rename target. The entry's name remains the current name until the rename applies.  state string Can be one of: present, absent. Default: present	Example: labels: - name: bug color: "#ff0000" - name: old-name new_name: better-name ...
badges array of objects  Group or project badges, matched by a unique human-readable value or an explicit server id. URL placeholders such as %{project_path} pass through. Properties of badges  name string Preferred natural identity when unique.  link_url stringRequired on create Badge target URL, used as a fallback identity and reconciled by fingerprint.  image_url stringRequired on create Badge image URL; reconciles by fingerprint.  id integer Server-assigned identity for one existing badge when duplicates exist. Lookup-only.  state string Can be one of: present, absent. Default: present	Example: badges: - name: pipeline link_url: "https://gitlab.example.com/%{project_path}/-/pipelines" image_url: "https://.../pipeline.svg" ...
groups[].member_roles array of objects  Group custom member roles (Ultimate), matched by name. No update verb exists: remove and re-add a role to change it. Properties of groups[].member_roles  name stringRequired Custom-role name and identity.  description string Description shown for the custom role.  base_access_level integerRequired Base GitLab access level. Can be one of: 10, 15, 20, 25, 30, 40, 50.  apply_security_scan_profiles boolean Apply security scan profiles.  admin_merge_request boolean Allows approval of merge requests.  archive_project boolean Allows archiving of projects.  admin_ai_catalog_item_consumer boolean Enable, disable, and configure custom agents and flows from the AI catalog for a project.  destroy_package boolean Delete packages and package files in the package registry.  remove_project boolean Allows deletion of projects.  remove_group boolean Ability to delete or restore a subgroup. This ability does not allow deleting top-level groups. Review the retention period settings to prevent accidental deletion.  manage_security_policy_link boolean Allows linking security policy projects.  admin_ai_catalog_item boolean Create, edit, and delete custom agents and flows in the AI catalog.  admin_compliance_framework boolean Create, read, update, and delete compliance frameworks. Users with this permission can also assign a compliance framework label to a project, and set the default framework of a group.  admin_cicd_variables boolean Create, read, update, and delete CI/CD variables.  manage_deploy_tokens boolean Manage deploy tokens at the group or project level.  manage_group_access_tokens boolean Create, read, update, and delete group access tokens. When creating a token, users with this custom permission must select a role for that token that has the same or fewer permissions as the default role used as the base for the custom role.  admin_group_member boolean Add or remove users in a group, and assign roles to users. When assigning a role, users with this custom permission must select a role that has the same or fewer permissions as the default role used as the base for their custom role.  admin_integrations boolean Create, read, update, and delete integrations with external applications.  manage_merge_request_settings boolean Configure merge request settings at the group or project level. Group actions include managing merge checks and approval settings. Project actions include managing MR configurations, approval rules and settings, and branch targets. In order to enable Suggested reviewers, the "Manage project access tokens" custom permission needs to be enabled.  manage_project_access_tokens boolean Create, read, update, and delete project access tokens. When creating a token, users with this custom permission must select a role for that token that has the same or fewer permissions as the default role used as the base for the custom role.  admin_protected_branch boolean Create, read, update, and delete protected branches for a project.  admin_protected_environments boolean Create, read, update, and delete protected environments  admin_push_rules boolean Configure push rules for repositories at the group or project level.  admin_runners boolean Create, view, edit, and delete group or project Runners. Includes configuring Runner settings.  admin_security_attributes boolean Manage the security categories and attributes belonging to a top-level group. Also requires the read_security_attribute permission.  admin_terraform_state boolean Execute terraform commands, lock/unlock terraform state files, and remove file versions.  admin_vulnerability boolean Edit the status, linked issue, and severity of a vulnerability object. Also requires the read_vulnerability permission.  admin_web_hook boolean Manage webhooks  read_agent_artifacts boolean Read GitLab Duo Agent Platform artifacts, including audit events and session metadata, that are exposed through the agent artifacts dashboard.  read_compliance_dashboard boolean Read compliance capabilities including adherence, violations, and frameworks for groups and projects.  read_security_scan_profiles boolean Read security scan profiles.  read_virtual_registry boolean Allows read access to virtual registries at the group level. Enables users to resolve packages through the virtual registry without requiring broader group membership permissions. Only works on top level groups.  update_sec_ai_workflow_settings boolean Update security AI workflow settings such as SAST Vulnerability Resolution. Also requires the read_vulnerability permission.  read_admin_cicd boolean Read CI/CD details for runners and jobs in the Admin Area.  read_crm_contact boolean Read CRM contact.  read_dependency boolean Allows read-only access to the dependencies and licenses.  read_admin_groups boolean Read group details in the Admin Area.  read_admin_projects boolean Read project details in the Admin Area.  read_code boolean Allows read-only access to the source code in the user interface. Does not allow users to edit or download repository archives, clone or pull repositories, view source code in an IDE, or view merge requests for private projects. You can download individual files because read-only access inherently grants the ability to make a local copy of the file.  read_runners boolean Allows read-only access to group or project runners, including the runner fleet dashboard.  read_security_attribute boolean Allows read-only access to the security categories and attributes that belong to a top-level group.  read_admin_subscription boolean Read subscription details in the Admin area.  read_admin_monitoring boolean Read system information such as background migrations, health checks, and Gitaly in the Admin Area.  read_admin_users boolean Read the user list and user details in the Admin area.  read_vulnerability boolean Read vulnerability reports and security dashboards.  state string Can be one of: present, absent. Default: present. Drift on a present role fails in strict mode and skips in compatible mode.	Example: groups: - path: platform member_roles: - name: deployer base_access_level: 30 admin_merge_request: true ...
groups[].ssh_certificates array of objects  Group CA certificates for SSH signing. No update verb exists, so key drift requires explicit remove/redeclare recreation. Properties of groups[].ssh_certificates  title stringRequired on create Natural identity when unique and required to create a certificate.  id integer Server-assigned lookup identity when duplicate titles exist. Lookup-only.  key stringRequired on create Readable but immutable public CA key material.  state string Can be one of: present, absent. Default: present	Example: groups: - path: platform ssh_certificates: - title: engineering-ca key: "ssh-rsa AAAA..." ...
groups[].audit_event_destinations array of objects  Group HTTP audit event streaming destinations. GraphQL-only (backends: [graphql]); the instance form in Instance Administration uses the same declaration shape. Properties of groups[].audit_event_destinations  name stringRequired Destination name and identity.  destination_url stringRequired on create Private URL, fingerprinted in diffs and never displayed. A change recreates the destination.  secret_token string Write-only token. GitLab generates one when omitted and never returns it.  state string Can be one of: present, absent. Default: present	Example: groups: - path: platform audit_event_destinations: - name: platform-siem destination_url: https://siem.example.com/platform secret_token: "{{ vault_token }}" ...