Gitlab hero border pattern left svg Gitlab hero border pattern right svg

105 - Label Hygiene - Keeping your issues squeaky clean


When you use labels to manage day to day work and define a specific process, often there are situations and times where it's hard to keep labels in the right status. For example:

Solution - Label Hygiene / Triage Bot

Define a set of rules that will automatically

The Triage Bot is an Open GitLab project that makes it possible to automate many issue and merge request hygiene tasks to ensure that your projects are more consistently following a given process.

Example Triage Policies/rules

Here are two examples of how Triage Polices/Rules can automate updates and issue hygiene:

  1. This example finds issues that are more than 5 days old, but have no label associated with them, then it adds a comment to ask the Author to do something. The policy also notifies a team member to make them aware of the issue.
        - name: My policy
             attribute: updated_at
             condition: older_than
             interval_type: days
             interval: 5
           state: opened
             - No Label
           most_recent: 50
             - needs attention
             - markglenfletcher
           comment: |
             {{author}} This issue is unlabelled after 5 days. It needs attention. Please take care of this before the end of #{2.days.from_now.strftime('%Y-%m-%d')}
  2. In Strategic marketing, here is a rule that finds any Strategic marketing Requests that are missing a Scoped Workflow label.
      - name: sm_request (MISSING a scoped label and assign it as a New Reqeust)
            - sm_request
          state: opened
            - sm_req::triage
            - sm_req::transfered
            - sm_req::new_request
            - sm_req::declined
            - sm_req::completed
            - sm_req::backlog
            - sm_req::assigned
            - sm_req::new_request
          comment: |
           SM TriageBot helping out here: This SM Request issue was not in the workflow, automatically adding it as a new request.

Setting Up the Triage Bot:

There are only two simple steps to set up the TriageBot.

  1. Configuring your CI/CD pipeline
  2. Drafting your first Triage Policy
  3. Setting up a CI/CD Schedule to run your Triage Policies periodically.

Step 1: Configuring your CI/CD Pipeline for the first time.

  1. The triage bot runs as a scheduled CI pipeline job, so your project will need to define a gitlab-ci.yml file. The gitlab-ci.yml file is stored in the root directory of your project.

Here is an example of the Strategic Marketing pipeline, where there are three Jobs defined. There are two Manual jobs, and one Scheduled Job. The two Manual jobs either test(dry-run) the rules/policies, or actually apply the rules/policies (policy:run). The one Scheduled job (schedule:policyrun), when runs will actually apply the rules/policies.

 >image: ruby:2.4
  - triage
  - run

  stage: triage
    - gem install gitlab-triage
    - gitlab-triage --help
    - gitlab-triage --dry-run --token $API_TOKEN --source projects --source-id $CI_PROJECT_PATH
  when: manual
    - schedules

  stage: run
    - gem install gitlab-triage
    - gitlab-triage --token $API_TOKEN --source projects --source-id $CI_PROJECT_PATH
  when: manual
    - schedules

  stage: run
    - gem install gitlab-triage
    - gitlab-triage --token $API_TOKEN --source projects --source-id $CI_PROJECT_PATH
    - schedules
  1. The TriageBot needs to have access and permission to your GitLab project to read and update issues. This is called a "token", and is stored in GitLab using a "CI/CD Variable" - in this case it is the $API_TOKEN that you see in the above example pipeline.

You will need to configure a GitLab CI/CD Environment Variable$API_TOKEN for these jobs to run.

Here's how:

2. Setting Up CI-CD API Token Variable Image
1. In your project select the left menu option Settings-->CI/CD Settings-CI-CD
2. Then expand the Variables section Settings-CI-CD-Variables
3. Add a new line where
- Type= "Variable"
- Key = "API_TOKEN"
- Value = Your API Key. - You have an API Key don't you? (See short instructions below)
- Set Masked to True.
4. Save Variables  
3. Getting your API Key Image
1. The API Key is linked to your account and basically gives the Bot permission to act on your behalf. First click on the dropdown on your personal settings in Gitlab. User Settings
2. Select Access Tokens and
- Give the access token a Name
- Leave the Expiration Date blank (unless you want it to expire)
- Select "API" for the Scopes
- Click Create personal access token
Access Tokens
3. The Personal Access Token will appear at the top of the page. Personal Access Token
4. Copy the Token and then Add it to the API_TOKEN Value in the CI/CD Variables settings.  

Step 2: Setting up your FIRST Triage policy

The Triage Policies/Rules are defined in a YML file called .triage-policies.yml which is stored in the root directory of your project. For DETAILED instructions about rules and policy options read the Defining a Policy section in the file in the Triage Bot project.

  1. Create a new file in the root directory called .triage-policies.yml
  2. Paste in the following first simple rule:
        - name: find all open issues - any label (simple - should be lots)
           state: opened
  1. Commit and merge your changes.

This will trigger a pipeline, where the Jobs should all be skipped. You should see this at the bottom of your screen. Pipeline

4. Dry-Run TriageBot Image
1. Click on the Pipeline link and go to the pipeline screen Pipeline View
2. Run the "Dry Run" pipeline job. Pipeline Dry Run
3. Click on the job and watch it run. Pipeline Dry Run
4. Fist it starts by creating a container and getting a runner growing (That means your CI job is defined OK so far) Pipeline Dry Run starting
5. Then it prompts the Triage bot to show it's help output (that means it's working, and your API key is good) Pipeline Dry Run Help Details
6. Then the job runs the "Dry-Run" and you see the output from the bot as it runs. Just one job - find all the open issues, so it runs fast, finds over 1,000 issues. Since the policy/rule had no filters or actions, the job finishes. Pipeline Dry Run Complete

Now, you need to define any specific policies/rules that you need for your project.

Step 3: Scheduling Jobs

Scheduling Jobs Image
1. Go to CI/CD–>Pipelines on the left menu CI-CD-Pipelines
2. Click on Create New Schedule CI-CD-Pipelines
3. Create the schedule
- Write a Name/description
- Select an Interval pattern (how frequently do you want it to run. Probably daily.)
- Leave the Target Branch, and Variables options with the default
- Click on Save Pipeline Schedule.
CI-CD-Pipelines-schedule new

Success and Next Steps.

From here, you can build/draft your specific policies/rules for your project.