diff options
Diffstat (limited to 'doc/user/project/integrations')
17 files changed, 105 insertions, 39 deletions
diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 680fcdb78bb..d0399f9193b 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,4 +1,4 @@ -# GitHub project integration **[PREMIUM]** +# GitHub project integration **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3836) in GitLab Premium 10.6. @@ -14,7 +14,7 @@ and is automatically configured on [GitHub import](../../../integration/github.m ### Complete these steps on GitHub -This integration requires a [GitHub API token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) +This integration requires a [GitHub API token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) with `repo:status` access granted: 1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> diff --git a/doc/user/project/integrations/img/jira_api_token.png b/doc/user/project/integrations/img/jira_api_token.png Binary files differindex 4fa7a46854e..29689271bf7 100644 --- a/doc/user/project/integrations/img/jira_api_token.png +++ b/doc/user/project/integrations/img/jira_api_token.png diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png Binary files differindex 14037bd0b47..1aca1d78f36 100644 --- a/doc/user/project/integrations/img/jira_api_token_menu.png +++ b/doc/user/project/integrations/img/jira_api_token_menu.png diff --git a/doc/user/project/integrations/img/jira_issue_reference.png b/doc/user/project/integrations/img/jira_issue_reference.png Binary files differindex 72c81460df7..a3e80c1b054 100644 --- a/doc/user/project/integrations/img/jira_issue_reference.png +++ b/doc/user/project/integrations/img/jira_issue_reference.png diff --git a/doc/user/project/integrations/img/jira_merge_request_close.png b/doc/user/project/integrations/img/jira_merge_request_close.png Binary files differindex 0f82ceba557..1c089c94207 100644 --- a/doc/user/project/integrations/img/jira_merge_request_close.png +++ b/doc/user/project/integrations/img/jira_merge_request_close.png diff --git a/doc/user/project/integrations/img/jira_service_close_comment.png b/doc/user/project/integrations/img/jira_service_close_comment.png Binary files differdeleted file mode 100644 index 9af0d38f098..00000000000 --- a/doc/user/project/integrations/img/jira_service_close_comment.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_service_close_issue.png b/doc/user/project/integrations/img/jira_service_close_issue.png Binary files differindex c85b1d1dd97..73d6498192c 100644 --- a/doc/user/project/integrations/img/jira_service_close_issue.png +++ b/doc/user/project/integrations/img/jira_service_close_issue.png diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png Binary files differindex 377b69d9d06..80dd65ea24e 100644 --- a/doc/user/project/integrations/img/jira_service_page.png +++ b/doc/user/project/integrations/img/jira_service_page.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 8f2e5a55b5f..ca990ee6c32 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -39,21 +39,17 @@ a GitLab project with any single Jira project. If you have one Jira instance, you can pre-fill the settings page with a default template. See the [Services Templates][services-templates] docs. -Configuration happens via user name and password. Connecting to a Jira Server -via CAS is not possible. - -In order to enable the Jira service in GitLab, you need to first configure the -project in Jira and then enter the correct values in GitLab. +In order to enable the Jira service in GitLab, you need to first configure the project in Jira and then enter the correct values in GitLab. ### Configuring Jira -When connecting to **Jira Server**, which supports basic authentication, a **username and password** are required. Check the link below and proceed to the next step: +#### Jira Server -- [Setting up a user in Jira Server](jira_server_configuration.md) +When connecting to **Jira Server**, which supports basic authentication, a **username and password** are required. Note that connecting to a Jira server via CAS is not possible. [Set up a user in Jira Server](jira_server_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). -When connecting to **Jira Cloud**, which supports authentication via API token, an **email and API token**, are required. Check the link below and proceed to the next step: +#### Jira Cloud -- [Setting up a user in Jira Cloud](jira_cloud_configuration.md) +When connecting to **Jira Cloud**, which supports authentication via API token, an **email and API token**, are required. [Set up a user in Jira Cloud](jira_cloud_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). ### Configuring GitLab @@ -68,7 +64,7 @@ When connecting to **Jira Cloud**, which supports authentication via API token, > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. -To enable Jira integration in a project, navigate to the +To enable the Jira integration in a project, navigate to the [Integrations page](project_services.md#accessing-the-project-services), click the **Jira** service, and fill in the required details on the page as described in the table below. @@ -127,6 +123,12 @@ ENTITY_TITLE  +For example, the following commit will reference the Jira issue with `PROJECT-1` as its ID: + +```bash +git commit -m "PROJECT-1 Fix spelling and grammar" +``` + ### Closing Jira Issues Jira issues can be closed directly from GitLab by using trigger words in @@ -142,7 +144,7 @@ the same goal: - `Closes PROJECT-1` - `Fixes PROJECT-1` -where `PROJECT-1` is the issue ID of the Jira project. +where `PROJECT-1` is the ID of the Jira issue. > **Notes:** > @@ -174,8 +176,6 @@ with a link to the commit that resolved the issue.  - - ## Troubleshooting If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 614f05d5b7e..5a5ba2dd168 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -3,16 +3,18 @@ An API token is needed when integrating with Jira Cloud, follow the steps below to create one: -1. Log in to <https://id.atlassian.com> with your email. -1. **Click API tokens**, then **Create API token**. +1. Log in to <https://id.atlassian.com/manage/api-tokens> with your email address. + + NOTE: **Note** + It is important that the user associated with this email address has *write* access + to projects in Jira. + +2. Click **Create API token**.   -1. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab). - -NOTE: **Note** -It is important that the user associated with this email has 'write' access to projects in Jira. +1. Click **Copy to clipboard**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab). -The Jira configuration is complete. You are going to need this newly created token and the email you used to log in, when [configuring GitLab in the next section](jira.md#configuring-gitlab). +The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section. diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 0e4c71a9d3e..f63a2c2758b 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -20,10 +20,10 @@ Below, you will find a list of the currently supported ones accompanied with com Click on the service links to see further configuration instructions and details. -| Service | Description | +| Service | Description | | ------- | ----------- | -| Asana | Asana - Teamwork without email | -| Assembla | Project Management Software (Source Commits Endpoint) | +| Asana | Asana - Teamwork without email | +| Assembla | Project Management Software (Source Commits Endpoint) | | [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server | | Buildkite | Continuous integration and deployments | | [Bugzilla](bugzilla.md) | Bugzilla issue tracker | @@ -34,12 +34,12 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | | Flowdock | Flowdock is a collaboration web app for technical teams | -| [GitHub](github.md) **[PREMIUM]** | Sends pipeline notifications to GitHub | +| [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | | [HipChat](hipchat.md) | Private group chat and IM | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | | [Jira](jira.md) | Jira issue tracker | -| [Jenkins](../../../integration/jenkins.md) **[STARTER]** | An extendable open source continuous integration server | +| [Jenkins](../../../integration/jenkins.md) **(STARTER)** | An extendable open source continuous integration server | | JetBrains TeamCity CI | A continuous integration and build server | | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | @@ -47,7 +47,7 @@ Click on the service links to see further configuration instructions and details | Packagist | Update your project on Packagist, the main Composer repository | | Pipelines emails | Email the pipeline status to a list of recipients | | [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications | -| [Slack slash commands](slack_slash_commands.md) **[CORE ONLY]** | Use slash commands in Slack to control GitLab | +| [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | | [GitLab Slack application](gitlab_slack_application.md) **[FREE ONLY]** | Use Slack's official application | | PivotalTracker | Project Management Software (Source Commits Endpoint) | | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index aab7131e353..765aa91b00f 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -18,6 +18,7 @@ Once enabled, GitLab will automatically detect metrics from known services in th ## Enabling Prometheus Integration ### Managed Prometheus on Kubernetes + > **Note**: [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28916) in GitLab 10.5 GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. @@ -39,9 +40,9 @@ Once you have a connected Kubernetes cluster with Helm installed, deploying a ma #### About managed Prometheus deployments -Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). +Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). -The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Ckubernetes_sd_config%3E) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - `prometheus.io/scrape` to `true` to enable monitoring of the resource. - `prometheus.io/port` to define the port of the metrics endpoint. @@ -66,9 +67,9 @@ Integration with Prometheus requires the following: Installing and configuring Prometheus to monitor applications is fairly straight forward. -1. [Install Prometheus](https://prometheus.io/docs/introduction/install/) +1. [Install Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) 1. Set up one of the [supported monitoring targets](prometheus_library/index.md) -1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/operating/configuration/#scrape_config) +1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) #### Configuration in GitLab @@ -93,7 +94,7 @@ GitLab will automatically scan the Prometheus server for metrics from known serv You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments.md#monitoring-environments). -### Adding additional metrics **[PREMIUM]** +### Adding additional metrics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3799) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. @@ -120,6 +121,69 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.htm To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`. +### Defining Dashboards for Prometheus Metrics per Project + +All projects include a GitLab-defined system dashboard, which includes a few key metrics. Optionally, additional dashboards can also be defined by including configuration files in the project repository under `.gitlab/dashboards`. Configuration files nested under subdirectories will not be available in the UI. Each file should define the layout of the dashboard and the prometheus queries used to populate data. Dashboards can be selected from the dropdown in the UI. + +#### Relationship to Custom Metrics + +[Custom Metrics](#adding-additional-metrics-premium) are defined through the UI and, at this point, are unique from metrics defined in dashboard configuration files. Custom Metrics will appear on the system dashboard, as well as support alerting, whereas metrics defined in configuration files do not yet support alerts. + +#### Dashboard Configuration + +Dashboards have several components. A dashboard has many panel groups, which are comprised of panels, which support one or more metrics. The dashboard should be saved with the `.yml` extension. + +Sample YML Configuration +``` +dashboard: 'Dashboard Title' +priority: 2 +panel_groups: + - group: 'Group Title' + panels: + - type: area-chart + title: "Chart Title" + y_label: "Y-Axis" + metrics: + - id: metric_of_ages + query_range: 'http_requests_total' + label: "Metric of Ages" + unit: "count" +``` + +The above sample dashboard would display a single area chart. The following sections outline the details of expected properties. + +##### Dashboard Properties +| Property | Type | Required? | Meaning | +| ------ | ------ | ------ | ------ | +| `dashboard` | string | required | Heading for the dashboard. Only one dashboard should be defined per file. | +| `priority` | number | optional, default to definition order | Order to appear in dashboard dropdown, higher priority should be higher in the dropdown. Numbers do not need to be consecutive. | +| `panel_groups` | array | required | The panel groups which should be on the dashboard. | + +##### Panel Group Properties +| Property | Type | Required? | Meaning | +| ------ | ------ | ------ | ------ | +| `group` | string | required | Heading for the panel group. | +| `priority` | number | optional, defaults to order in file | Order to appear on the dashboard, higher priority will be higher on the page. Numbers do not need to be consecutive. | +| `panels` | array | required | The panels which should be in the panel group. | + +##### Panel Properties +| Property | Type | Required? | Meaning | +| ------ | ------ | ------ | ------- | +| `type` | enum | optional, defaults to `area-chart` | Specifies the chart type to use. Only `area-chart` is currently supported. | +| `title` | string | required | Heading for the panel. | +| `y_label` | string | optional, but highly encouraged | Y-Axis label for the panel. | +| `weight` | number | optional, defaults to order in file | Order to appear within the grouping, higher priority will be higher on the page. Numbers do not need to be consecutive. | +| `metrics` | array | required | The metrics which should be displayed in the panel. | + +##### Metric Properties +| Property | Type | Required? | Meaning | +| ------ | ------ | ------ | ------ | +| `id` | string | optional | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](#setting-up-alerts-for-prometheus-metrics-ultimate) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/60319)). | +| `unit` | string | required | Defines the unit of the query's return data. | +| `label` | string | optional, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. | +| `query` | string | required unless `query_range` is defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | +| `query_range` | string | required unless `query` is defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | + ### Setting up alerts for Prometheus metrics **[ULTIMATE]** #### Managed Prometheus instances @@ -156,7 +220,7 @@ receivers: ... ``` -### Taking action on incidents **[ULTIMATE]** +### Taking action on incidents **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 01da7e00d74..5049733abdd 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -20,7 +20,7 @@ The [Prometheus service](../prometheus.md) must be enabled. To get started with Cloudwatch monitoring, you should install and configure the [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter) which retrieves and parses the specified Cloudwatch metrics and translates them into a Prometheus monitoring endpoint. -Right now, the only AWS resource supported is the Elastic Load Balancer, whose Cloudwatch metrics can be found [here](http://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). +Right now, the only AWS resource supported is the Elastic Load Balancer, whose Cloudwatch metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB monitoring, is [available for download](../samples/cloudwatch.yml). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 8b1cf1a251a..0d300d3c418 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -36,7 +36,7 @@ In order to isolate and only display relevant CPU and Memory metrics for a given Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. -## Displaying Canary metrics **[PREMIUM]** +## Displaying Canary metrics **(PREMIUM)** > Introduced in [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15201). diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index bb8d276c2fc..508e72b5753 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -6,7 +6,7 @@ The Slack Notifications Service allows your GitLab project to send events (e.g. ## Slack Configuration -1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook/). +1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). 1. Select the Slack channel where notifications will be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration. 1. Copy the **Webhook URL**, which we'll use later in the GitLab configuration. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 371e78ca3a4..813066c51ac 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,4 +1,4 @@ -# Slack slash commands **[CORE ONLY]** +# Slack slash commands **(CORE ONLY)** > Introduced in GitLab 8.15. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 04a9d9568ca..30940b65454 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -24,7 +24,7 @@ to the webhook URL. In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver) to receive information from GitLab, and send it to another app, according to your needs. -We already have a [built-in receiver](https://docs.gitlab.com/ce/project_services/slack.html) +We already have a [built-in receiver](slack.md) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. ## Overview |
