Skip to main content

Synchronize GitLab project labels from CI. The component creates missing labels and removes labels that are no longer listed when pruning is enabled.

Use this component from the default branch with a project access token stored in GITLAB_TOKEN or another masked CI/CD variable. The token needs permission to manage project labels. By default, the label sync job runs in the .post stage so it does not block the rest of the pipeline. Override the stage input when a project needs a different placement.

Usage

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/label@stable
    inputs:
      labels:
        - bug
        - name: documentation
          color: '#428bca'
          description: Issues related to documentation updates.
        - needs-triage

Labels can be plain strings or structured entries. Structured entries support name, color, and description; entries without a color use default-color.

Set prune: false if the job should only create the selected labels without deleting existing labels.

Using default labels​

The GitLab Agent Skill describes the use of the set of default labels of type workflow::*

Inputs​

NameDescriptionDefaultType
------------
labelsLabels to keep on the current project.[{"name":"priority::low","description":"Low priority issues that can be worked on when time allows."},{"name":"priority::medium","description":"Medium priority issues that should be worked on after high priority issues are resolved."},{"name":"priority::high","description":"High priority issues that should be worked on as soon as possible."},{"name":"priority::blocker","description":"Blocker issues that prevent progress and should be worked on immediately."},{"name":"type::hotfix","description":"Issues that require an immediate fix in production."},{"name":"type::bug","description":"Issues related to bugs in the codebase that need to be fixed."},{"name":"type::feature","description":"Issues related to new features or enhancements that need to be implemented."},{"name":"type::support","description":"Issues related to support requests from users or customers."},{"name":"size::small","description":"Issues that are small in scope and can be completed quickly."},{"name":"size::medium","description":"Issues that are medium in scope and may require some time to complete."},{"name":"size::large","description":"Issues that are large in scope and may require significant time to complete."},{"name":"size::xlarge","description":"Issues that are very large in scope and may require a lot of time to complete."},{"name":"workflow::stale","description":"Issues that have not had any activity for a while and may need attention."},{"name":"workflow::backlog","description":"Issues that are in the backlog and have not been started yet."},{"name":"workflow::in-progress","description":"Issues that are currently being worked on or have recent activity."},{"name":"workflow::review","description":"Issues that are currently under review."},{"name":"workflow::paused","description":"Issues that are currently paused and not being worked on."},{"name":"workflow::blocked","description":"Issues that are currently blocked and cannot be worked on."},{"name":"workflow::need-human","description":"Issues that require human intervention to proceed."},{"name":"workflow::done","description":"Issues that are completed and no further action is required."}]array
nameThe name of the label sync job.project-labelsstring
needsThe jobs that this job depends on.[]array
pruneRemove project labels that are not present in the labels input.trueboolean
rulesRules controlling when the label sync job runs.[{"if":"$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH","when":"on_success"},{"when":"never"}]array
stageThe stage where the label sync job runs..prestring
tagsThe runners that this job depends on.[]array
token-variableName of the CI/CD variable containing a GitLab token allowed to manage project labels.GITLAB_TOKENstring