diff options
Diffstat (limited to 'doc/ci/chatops/index.md')
| -rw-r--r-- | doc/ci/chatops/index.md | 129 |
1 files changed, 58 insertions, 71 deletions
diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index f0efb5fc884..6dff87ed1c5 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Manage +group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: index, concepts, howto --- @@ -9,62 +9,70 @@ type: index, concepts, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in GitLab Ultimate 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free in 11.9. -> - `CHAT_USER_ID` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341798) in GitLab 14.4. +> - `CHAT_USER_ID` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341798) 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. +Use GitLab ChatOps to interact with CI/CD jobs through chat services +like Slack. -## How GitLab ChatOps works +Many organizations use chat services to collaborate, troubleshoot, and plan work. With ChatOps, +you can discuss work with your team, run CI/CD jobs, and view job output, all from the same +application. -GitLab ChatOps is built upon [GitLab CI/CD](../index.md) and -[Slack Slash Commands](../../user/project/integrations/slack_slash_commands.md). -ChatOps provides a `run` action for [slash commands](../../integration/slash_commands.md) -with the following arguments: +## ChatOps workflow and CI/CD configuration -- A `<job name>` to execute. -- The `<job arguments>`. +ChatOps looks for the specified job in the +[`.gitlab-ci.yml`](../yaml/index.md) on the project's default +branch. If the job is found, ChatOps creates a pipeline that contains +only the specified job. If you set `when: manual`, ChatOps creates the +pipeline, but the job doesn't start automatically. + +A job run with ChatOps has the same functionality as a job run from +GitLab. The job can use existing [CI/CD variables](../variables/index.md#predefined-cicd-variables) like +`GITLAB_USER_ID` to perform additional rights validation, but these +variables can be [overridden](../variables/index.md#cicd-variable-precedence). + +You should set [`rules`](../yaml/index.md#rules) so the job does not +run as part of the standard CI/CD pipeline. ChatOps passes the following [CI/CD variables](../variables/index.md#predefined-cicd-variables) to the job: -- `CHAT_INPUT` contains any additional arguments. -- `CHAT_CHANNEL` is set to the name of channel the action was triggered in. -- `CHAT_USER_ID` is set to the chat service's user ID of the user who triggered the slash command. +- `CHAT_INPUT` - The arguments passed to `/project-name run`. +- `CHAT_CHANNEL` - The name of the chat channel the job is run from. +- `CHAT_USER_ID` - The chat service ID of the user who runs the job. -When executed, ChatOps looks up the specified job name and attempts to match it -to a corresponding job in [`.gitlab-ci.yml`](../yaml/index.md). If a matching job -is found on the default branch, a pipeline containing only that job is scheduled. After the -job completes: +When the job runs: -- 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 +- If the job completes in less than 30 minutes, ChatOps sends the job output to the chat channel. +- If the job completes in more than 30 minutes, you must use a method like the [Slack API](https://api.slack.com/) to send data to the channel. -To use the `run` command, you must have at least the -Developer role. -If a job shouldn't be able to be triggered from chat, you can set the job to `except: [chat]`. +## Run a CI/CD job + +You can run a CI/CD job from chat with the `/project-name run` +[slash command](../../integration/slash_commands.md). + +Prerequisites: + +- You must have at least the Developer role for the project. + +To run a CI/CD job: + +- In the chat client, enter `/project-name run <job name> <arguments>`. -## Best practices for ChatOps CI jobs +ChatOps schedules a pipeline that contains only the specified job. -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: +### Exclude a job from ChatOps -- GitLab strongly recommends you set [`rules`](../yaml/index.md#rules) so 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](../variables/index.md#predefined-cicd-variables) like - `GITLAB_USER_ID` to perform additional rights validation, but - these variables can be [overridden](../variables/index.md#cicd-variable-precedence). +To prevent a job from being run from chat: -### Controlling the ChatOps reply +- In `.gitlab-ci.yml`, set the job to `except: [chat]`. -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: +## Customize the ChatOps reply + +ChatOps sends the output for a job with a single command to the +channel as a reply. For example, when the following job runs, +the chat reply is `Hello world`: ```yaml stages: @@ -78,13 +86,12 @@ hello-world: - 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. +If the job contains multiple commands, or if `before_script` is set, ChatOps sends the commands +and their output to the channel. The commands are wrapped in ANSI color codes. -To selectively reply with the output of one command, its output must be bounded by -the `chat_reply` section. For example, the following job lists the files in the -current directory: +To selectively reply with the output of one command, place the output +in a `chat_reply` section. For example, the following job lists the +files in the current directory: ```yaml stages: @@ -99,28 +106,8 @@ ls: - 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](https://gitlab.com/gitlab-com/chatops) -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](img/gitlab-chatops-icon.png) is available for download. -You can find and download the official GitLab ChatOps icon here. - - - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +## Related topics -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +- [The official GitLab ChatOps icon](img/gitlab-chatops-icon.png) +- [A repository of common ChatOps scripts](https://gitlab.com/gitlab-com/chatops) + that GitLab uses to interact with GitLab.com |