GitLab ChatOps (FREE)
- Introduced in GitLab Ultimate 10.6.
- Moved to GitLab Free in 11.9.
CHAT_USER_IDwas introduced in GitLab 14.4.
GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting takes place in chat services. Having a method to run CI/CD jobs with output posted back to the channel can significantly augment your team's workflow.
How GitLab ChatOps works
GitLab ChatOps is built upon GitLab CI/CD and
Slack Slash Commands.
ChatOps provides a
run action for slash commands
with the following arguments:
<job name>to execute.
ChatOps passes the following CI/CD variables to the job:
CHAT_INPUTcontains any additional arguments.
CHAT_CHANNELis set to the name of channel the action was triggered in.
CHAT_USER_IDis set to the chat service's user ID of the user who triggered the slash command.
When executed, ChatOps looks up the specified job name and attempts to match it
to a corresponding job in
.gitlab-ci.yml. If a matching job
is found on the default branch, a pipeline containing only that job is scheduled. After the
- If the job completes in less than 30 minutes, the ChatOps sends the job's output to Slack.
- If the job completes in more than 30 minutes, the job must use the Slack API to send data to the channel.
To use the
run command, you must have at least the
If a job shouldn't be able to be triggered from chat, you can set the job to
Best practices for ChatOps CI jobs
Since ChatOps is built upon GitLab CI/CD, the job has all the same features and functions available. Consider these best practices when creating ChatOps jobs:
- GitLab strongly recommends you set
rulesso the job does not run as part of the standard CI pipeline.
- If the job is set to
when: manual, ChatOps creates the pipeline, but the job waits to be started.
- ChatOps provides limited support for access control. If the user triggering the
slash command has at least the Developer role
in the project, the job runs. The job itself can use existing
CI/CD variables like
GITLAB_USER_IDto perform additional rights validation, but these variables can be overridden.
Controlling the ChatOps reply
The output for jobs with a single command is sent to the channel as a reply. For
example, the chat reply of the following job is
Hello World in the channel:
stages: - chatops hello-world: stage: chatops rules: - if: $CI_PIPELINE_SOURCE == "chat" script: - echo "Hello World"
Jobs that contain multiple commands (or
before_script) return additional
content in the chat reply. In these cases, both the commands and their output are
included, with the commands wrapped in ANSI color codes.
To selectively reply with the output of one command, its output must be bounded by
chat_reply section. For example, the following job lists the files in the
stages: - chatops ls: stage: chatops rules: - if: $CI_PIPELINE_SOURCE == "chat" script: - echo "This command will not be shown." - echo -e "section_start:$( date +%s ):chat_reply\r\033[0K\n$( ls -la )\nsection_end:$( date +%s ):chat_reply\r\033[0K"
GitLab ChatOps examples
The GitLab.com team created a repository of common ChatOps scripts they use to interact with our Production instance of GitLab. Administrators of other GitLab instances may find them useful. They can serve as inspiration for ChatOps scripts you can write to interact with your own applications.
GitLab ChatOps icon
The official GitLab ChatOps icon is available for download. You can find and download the official GitLab ChatOps icon here.