diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-03-14 12:08:45 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-03-14 12:08:45 +0300 |
commit | 6f9218ac84f0de0ebfddf2d4fbd79db881b2d46a (patch) | |
tree | 77315600c53ab077c7effd3ddf3f630dff6ea081 /doc/ci/chatops | |
parent | 3612694ce3931fe7fd225d9c2df42dbd513121df (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/ci/chatops')
-rw-r--r-- | doc/ci/chatops/img/gitlab-chatops-icon-small.png | bin | 2922 -> 0 bytes | |||
-rw-r--r-- | doc/ci/chatops/index.md | 124 |
2 files changed, 57 insertions, 67 deletions
diff --git a/doc/ci/chatops/img/gitlab-chatops-icon-small.png b/doc/ci/chatops/img/gitlab-chatops-icon-small.png Binary files differdeleted file mode 100644 index 71cc5dba5cf..00000000000 --- a/doc/ci/chatops/img/gitlab-chatops-icon-small.png +++ /dev/null diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index f0efb5fc884..d827fda67a1 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -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: -## Best practices for ChatOps CI jobs +- In the chat client, enter `/project-name run <job name> <arguments>`. -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: +ChatOps schedules a pipeline that contains only the specified job. -- 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). +### Exclude a job from ChatOps -### Controlling the ChatOps reply +To prevent a job from being run from 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: +- In `.gitlab-ci.yml`, set the job to `except: [chat]`. + +## 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,11 @@ 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. - -![GitLab ChatOps bot icon](img/gitlab-chatops-icon-small.png) +## Example scripts -<!-- ## Troubleshooting +The GitLab team maintains a repository of [common ChatOps scripts](https://gitlab.com/gitlab-com/chatops) +they use to interact with GitLab.com. -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. --> +- Download the [official GitLab ChatOps icon](img/gitlab-chatops-icon.png). |