The main repository for Quetzal is GitLab. Please create issues and questions there. Github is a mirror of that repo

Quetzal

Quetzal is a GitLab bot written in Go. It takes inspiration from the GitLab Triage Bot.

Installation

The easiest way is using Docker.

docker run --name my-quetzal -v '/path/to/.policies.yaml:/.policies.yaml:ro' -e user="GitLab.User" -e token="your-token" -e bot="https://bot-server.com" -e host="https://custom-gitlab-instance.com" -e policies="./.policies.yaml" -d -p 7838:7838 jonny7/quetzal 

However, you can build the source yourself

go build -o quetzal ./cmd/quetzal

Releases

Releases are available on GitLab detailing what the changes were. The containers are on dockerhub also. You'll also see -dev tags for any containers that need patches.

Environment Vars

  -user string
        the bot user (default "")
  -token string
        The personal access token for the bot (default "")
  -bot string
        The url the bot lives on eg https://your-domain.com (default "")
  -webhook string
        The endpoint to accept webhooks from (default "/webhook-endpoint")
  -secret string
        The webhook secret (default "")
  -host string
        The Gitlab instance (default "https://gitlab.com")
  -port string
        specified port (default "7838")
  -dry bool
        Whether to run quetzal as a dry-run that doesn't perform actions against GitLab (default false)
  -policies string
        The path to the policies file (default "./examples/.policies.yaml")
  -version bool
        Return the version of Quetzal (default false)

Versioning

Quetzal uses the SemVer specification. To query the binary, use the -version flag

./quetzal -version
# Quetzal version 1.1.1

How Quetzal works

At its heart, Quetzal is a yaml driven policy based bot. It needs some config parameters (listed above) and a policy file. The policy file is yaml based and has a default location provided. Please note this is relative to the Quetzal binary.

File type	Default location
.policies.yaml	./.policies.yaml

You can see an example .policies.yaml in the examples directory.

Policies

Policies are what drives Quetzal. There are 5 main properties to a policy

A single Policy is declared as part of an array of the Policies property.

Policy Properties

• Name
• Resource
• Conditions

• Actions

Policy Name

Is simply the name for this chosen policy

policies:
  - name: Awesome Policy
    #...
  - name: Round robin assignee
    #...

Policy Resource

The resource is the type of webhook this policy is for. The available options are listed below and are the values of the X-Gitlab-Event header:

• Build Hook
• Deployment Hook
• Issue Hook
• Confidential Issue Hook
• Job Hook
• Merge Request Hook (In progress)
• Note Hook
• Confidential Note Hook
• Pipeline Hook
• Push Hook
• Release Hook
• System Hook
• Tag Push Hook
• Wiki Page Hook

policies:
  - name: Assign MR
    resource: Merge Request Hook

Policy Conditions

Policy Conditions allow a user to specify a series of conditions that confirm that this webhook event be processed. All available options are type-safe and validated, once the policies file has been successfully parsed.

• State
• Milestone
• Labels
• Forbidden Labels
• Note

State Condition

State must have the available options for hooks that have this property. You can apply a policy to multiple states

policies:
  - name: Assign MR
    resource: Merge Request Hook
    conditions:
      state: 
        - open
        - updated     

Merge

• open
• close
• reopen
• update
• approved
• unapproved
• merge

Issue

• open
• close
• reopen
• update

Release

• create
• update

Milestone Condition

Milestone is the integer representation of the GitLab milestone

policies:
  - name: Assign MR
    resource: Merge Request Hook
    conditions:
      milestone: 5

Labels Condition

The Labels condition accepts an array of labels by name to filter webhooks on. The webhook must match all the provided labels on the policy to be valid. Additionally, labels are case-insensitive

policies:
  - name: Assign MR
    resource: Merge Request Hook
    conditions:
      labels:
        - done
        - pre-release       

Forbidden Labels Condition

The forbidden labels condition takes an array of labels by name and confirms that they are all absent from an applicable webhook.

policies:
  - name: Assign MR
    resource: Merge Request Hook
    conditions:
      forbiddenLabels:
        - v1
        - v2
    actions:
      comment: |
      This MR needs to be tagged with either `v1` or `v2`

The above would rule would be triggered if a merge request was missing both labels. So this is a way to identify issues or applicable types that are not labelled correctly.

Policy Actions

Policy actions are what your bot performs when a webhook matching the policy pre-conditions is met.

• Labels
• RemoveLabels
• Status
• Mention
• Comment

Action Labels

The Labels action of a policy will update the issue's Labels if it has the ability to have Labels.

Action RemoveLabels

The RemoveLabels field will remove any labels on an issue.

...
actions:
  labels:
    - approved
  removeLabels:
    - pre-approved

Action Status

The Status field allows you to set the state of an issue, if that issue has a state.

Action Mention

The Mention field accepts an array of username in the format without the @ symbol. This field is often used in conjunction with Comment.

Action Comment

The Comment field is the text you wish to use to reply to an issue. If possible.

...
actions:
  mention:
    - jonny7
  comment: |
    Please look at this important issue.
// would leave a reply of "@jonny7 Please look at this important issue."

Contributions

All contributions are welcome, please open an issue/feature req at GitLab

The Quetzal icon is attributed to FreePick