diff options
| -rw-r--r-- | doc/README.md | 1 | ||||
| -rw-r--r-- | doc/ci/README.md | 1 | ||||
| -rw-r--r-- | doc/ci/chatops/README.md | 61 | ||||
| -rw-r--r-- | doc/ci/chatops/img/gitlab-chatops-icon-small.png | bin | 0 -> 2922 bytes | |||
| -rw-r--r-- | doc/ci/chatops/img/gitlab-chatops-icon.png | bin | 0 -> 12308 bytes | |||
| -rw-r--r-- | doc/ci/variables/README.md | 2 | ||||
| -rw-r--r-- | doc/integration/slash_commands.md | 3 | ||||
| -rwxr-xr-x | scripts/lint-doc.sh | 2 |
8 files changed, 69 insertions, 1 deletions
diff --git a/doc/README.md b/doc/README.md index f87ff925e94..14e8d2edb90 100644 --- a/doc/README.md +++ b/doc/README.md @@ -284,6 +284,7 @@ The following documentation relates to the DevOps **Configure** stage: | [Auto DevOps](topics/autodevops/index.md) | Automatically employ a complete DevOps lifecycle. | | [Easy creation of Kubernetes<br/>clusters on GKE](user/project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) | Use Google Kubernetes Engine and GitLab. | | [Executable Runbooks](user/project/clusters/runbooks/index.md) | Documented procedures that explain how to carry out particular processes. | +| [GitLab ChatOps](ci/chatops/README.md) | Interact with CI/CD jobs through chat services. | | [Installing Applications](user/project/clusters/index.md#installing-applications) | Deploy Helm, Ingress, and Prometheus on Kubernetes. | | [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) | Enable and use slash commands from within Mattermost. | | [Protected variables](ci/variables/README.md#protected-variables) | Restrict variables to protected branches and tags. | diff --git a/doc/ci/README.md b/doc/ci/README.md index e44db230a7f..4c3c9920b93 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -93,6 +93,7 @@ use of advanced features: | [Triggering pipelines through the API](triggers/README.md) | Use the GitLab API to trigger a pipeline. | | [Pipeline schedules](../user/project/pipelines/schedules.md) | Trigger pipelines on a schedule. | | [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md) | Integrate one or more Kubernetes clusters to your project. | +| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. | | [Interactive web terminals](interactive_web_terminal/index.md) | Open an interactive web terminal to debug the running jobs. | ### GitLab Pages diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md new file mode 100644 index 00000000000..6ad1df7bb2a --- /dev/null +++ b/doc/ci/chatops/README.md @@ -0,0 +1,61 @@ +# GitLab ChatOps + +> **Notes:** +> +> * [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. +> +> * ChatOps is currently in alpha, with some important features missing like access control. + +GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting is taking place in chat services these days, and having a method to run CI/CD jobs with output posted back to the channel can significantly augment a team's workflow. + +## How it works + +GitLab ChatOps is built upon two existing features, [GitLab CI/CD](../README.md) and [Slack Slash Commmands](../../user/project/integrations/slack_slash_commands.md). + +A new `run` action has been added to the [slash commands](../../integration/slash_commands.md), which takes two arguments: a `<job name>` to execute and the `<job arguments>`. When executed, ChatOps will look up the specified job name and attempt to match it to a corresponding job in [.gitlab-ci.yml](../yaml/README.md). If a matching job is found on `master`, a pipeline containing just that job is scheduled. Two additional [CI/CD variables](../variables/README.html#predefined-variables-environment-variables) are passed to the job: `CHAT_INPUT` contains any additional arguments, and `CHAT_CHANNEL` is set to the name of channel the action was triggered in. + +After the job has finished, its output is sent back to Slack provided it has completed within 30 minutes. If a job takes more than 30 minutes to run it must use the Slack API to manually send data back to a channel. + +[Developer access and above](../../user/permissions.html#project-members-permissions) is required to use the `run` command. If a job should not be able to be triggered from chat, it can be set to `except: [chat]`. + +## Creating a ChatOps CI job + +Since ChatOps is built upon GitLab CI/CD, the job has all the same features and functions available. There a few best practices to consider however when creating ChatOps jobs: + +* It is strongly recommended to set `only: [chat]` so the job does not run as part of the standard CI pipeline. +* If the job is set to `when: manual`, the pipeline will be created however the job will wait to be started. +* It is important to keep in mind that there is very limited support for access control. If the user who triggered the slash command is a developer in the project, the job will run. The job itself can utilize existing [CI/CD variables](../variables/README.html#predefined-environment-variables) like `GITLAB_USER_ID` to perform additional rights validation, however these variables can be [overridden](https://docs.gitlab.com/ce/ci/variables/README.html#priority-of-variables). + +### Controlling the ChatOps reply + +For jobs with a single command, its output is automatically sent back to the channel as a reply. For example the chat reply of the following job is simply `Hello World.` + +```yaml +hello-world: + stage: chatops + only: [chat] + script: + - echo "Hello World." +``` + +Jobs that contain multiple commands, or have a `before_script`, include additional content in the chat reply. In these cases both the commands and their output are included, with the commands wrapped in ANSI colors 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 will list the files in the current directory. + +```yaml +ls: + stage: chatops + only: [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 icon + +Say Hi to our ChatOps bot. +You can find and download the official GitLab ChatOps icon here. + + + +[Download bigger image](img/gitlab-chatops-icon.png) diff --git a/doc/ci/chatops/img/gitlab-chatops-icon-small.png b/doc/ci/chatops/img/gitlab-chatops-icon-small.png Binary files differnew file mode 100644 index 00000000000..71cc5dba5cf --- /dev/null +++ b/doc/ci/chatops/img/gitlab-chatops-icon-small.png diff --git a/doc/ci/chatops/img/gitlab-chatops-icon.png b/doc/ci/chatops/img/gitlab-chatops-icon.png Binary files differnew file mode 100644 index 00000000000..3ba8bd308e3 --- /dev/null +++ b/doc/ci/chatops/img/gitlab-chatops-icon.png diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 7498617ed2c..ca668ac526f 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -53,6 +53,8 @@ future GitLab releases.** | Variable | GitLab | Runner | Description | |-------------------------------------------|--------|--------|-------------| | **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to download artifacts running a job | +| **CHAT_INPUT** | 10.6 | all | Additional arguments passed in the [ChatOps](../chatops/README.md) command | +| **CHAT_CHANNEL** | 10.6 | all | Source chat channel which triggered the [ChatOps](../chatops/README.md) command | | **CI** | all | 0.4 | Mark that job is executed in CI environment | | **CI_COMMIT_BEFORE_SHA** | 11.2 | all | The previous latest commit present on a branch before a push request. | | **CI_COMMIT_DESCRIPTION** | 10.8 | all | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. | diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 82ba1d7d984..cd755089be8 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -1,5 +1,7 @@ # Slash Commands +> The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. + Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires a [project service configuration](../user/project/integrations/slack_slash_commands.md). Simply type the command as a message in your chat client to activate it. Commands are scoped to a project, with a trigger term that is specified during configuration. @@ -16,6 +18,7 @@ Taking the trigger term as `project-name`, the commands are: | `/project-name issue search <query>` | Shows up to 5 issues matching `<query>` | | `/project-name issue move <id> to <project>` | Moves issue ID `<id>` to `<project>` | | `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment | +| `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/README.md) job `<job name>` on `master` | Note that if you are using the [GitLab Slack application](https://docs.gitlab.com/ee/user/project/integrations/gitlab_slack_application.html) for your GitLab.com projects, you need to [add the `gitlab` keyword at the beginning of the command](https://docs.gitlab.com/ee/user/project/integrations/gitlab_slack_application.html#usage). diff --git a/scripts/lint-doc.sh b/scripts/lint-doc.sh index 848364b4a9b..bc73225c1bf 100755 --- a/scripts/lint-doc.sh +++ b/scripts/lint-doc.sh @@ -35,7 +35,7 @@ fi # Do not use 'README.md', instead use 'index.md' # Number of 'README.md's as of 2018-03-26 -NUMBER_READMES_CE=42 +NUMBER_READMES_CE=43 NUMBER_READMES_EE=46 FIND_READMES=$(find doc/ -name "README.md" | wc -l) echo '=> Checking for new README.md files...' |
