Skip to content

G
gitlab-ce
Commit 363c1514 authored by Marcel Amirault's avatar Marcel Amirault Committed by Achilleas Pipinellis
Browse files
Options

Docs: Merge misc EE doc/user/project/i* dirs to CE

parent 762715ec
Show whitespace changes
Inline Side-by-side
Showing with 558 additions and 2 deletions
doc/user/project/import/gemnasium.md 0 → 100644
View file @ 363c1514
# Gemnasium **[ULTIMATE]**
This guide describes how to migrate from Gemnasium.com to your own GitLab
instance or GitLab.com.
## Why is Gemnasium.com closed?
Gemnasium has been [acquired by GitLab](https://about.gitlab.com/press/releases/2018-01-30-gemnasium-acquisition.html)
in January 2018. Since May 15, 2018, the services provided by Gemnasium are no longer available.
The team behind Gemnasium has joined GitLab as the new Security Products team
and is working on a wider range of tools than just Dependency Scanning:
[SAST](https://docs.gitlab.com/ee/user/application_security/sast/index.html),
[DAST](https://docs.gitlab.com/ee/user/application_security/dast/index.html),
[Container Scanning](https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html) and more.
If you want to continue monitoring your dependencies, see the
[Migrating to GitLab](#migrating-to-gitlab) section below.
## What happened to my account?
Your account has been automatically closed on May 15th, 2018. If you had a paid
subscription at that time, your card will be refunded on a pro rata temporis basis.
You may contact `gemnasium@gitlab.com` regarding your closed account.
## Will my account/data be transferred to GitLab Inc.?
All accounts and data have been deleted on May 15th, 2018. GitLab Inc.
doesn't know anything about your private data, nor your projects, and therefore
if they were vulnerable or not. GitLab Inc. takes personal information very seriously.
## What happened to my badge?
To avoid broken 404 images, all badges pointing to Gemnasium.com will be a
placeholder, inviting you to migrate to GitLab (and pointing to this page).
## Migrating to GitLab
Gemnasium has been ported and integrated directly into GitLab CI/CD.
You can still benefit from our dependency monitoring features, and it requires
some steps to migrate your projects. There is no automatic import since GitLab
doesn't know anything about any projects which existed on Gemnasium.com.
Security features are free for public (open-source) projects hosted on GitLab.com.
### If your project is hosted on GitLab (https://gitlab.com / self-hosted)
You're almost set! If you're already using
[Auto DevOps](../../../topics/autodevops/), you are already covered.
Otherwise, you must configure your `.gitlab-ci.yml` according to the
[dependency scanning page](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html).
### If your project is hosted on GitHub (https://github.com / GitHub Enterprise)
Since [GitLab 10.6 comes with GitHub integration](https://about.gitlab.com/features/github/),
GitLab users can now create a CI/CD project in GitLab connected to an external
GitHub.com or GitHub Enterprise repository. This will automatically prompt
GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results
back to both GitLab and GitHub when completed.
1. Create a new project, and select the "CI/CD for external repo" tab:
![Create new Project](img/gemnasium/create_project.png)
1. Use the "GitHub" button to connect your repositories.
![Connect from GitHub](img/gemnasium/connect_github.png)
1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect".
![Select projects](img/gemnasium/select_project.png)
Once the configuration is done, you may click on your new
project on GitLab.
![click on connected project](img/gemnasium/project_connected.png)
Your project is now mirrored on GitLab, where the Runners will be able to access
your source code and run your tests.
Optional step: If you set this up on GitLab.com, make sure the project is
public (in the project settings) if your GitHub project is public, since
the security feature is available only for [GitLab Ultimate](https://about.gitlab.com/pricing).
1. To set up the dependency scanning job, corresponding to what Gemnasium was
doing, you must create a `.gitlab-ci.yml` file, or update it according to
the [dependency scanning docs](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html).
The mirroring is pull-only by default, so you may create or update the file on
GitHub:
![Edit gitlab-ci.yml file](img/gemnasium/edit_gitlab-ci.png)
1. Once your file has been committed, a new pipeline will be automatically
triggered if your file is valid:
![pipeline](img/gemnasium/pipeline.png)
1. The result of the job will be visible directly from the pipeline view:
![security report](img/gemnasium/report.png)
NOTE: **Note:**
If you don't commit very often to your project, you may want to use
[scheduled pipelines](../pipelines/schedules.md) to run the job on a regular
basis.
doc/user/project/import/index.md
View file @ 363c1514
......@@ -13,11 +13,14 @@
1. [From TFS](tfs.md)
1. [From repo by URL](repo_by_url.md)
1. [By uploading a manifest file (AOSP)](manifest.md)
1. [From Gemnasium](gemnasium.md)
In addition to the specific migration documentation above, you can import any
Git repository via HTTP from the New Project page. Be aware that if the
repository is too large the import can timeout.
There is also the option of [connecting your external repository to get CI/CD benefits](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html). **[PREMIUM]**
## Migrating from self-hosted GitLab to GitLab.com
If you only need to migrate git repos, you can [import each project by URL](repo_by_url.md), but issues and merge requests can't be imported.
......
doc/user/project/insights/index.md 0 → 100644
View file @ 363c1514
# Insights **[ULTIMATE]**
> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag.
CAUTION: **Beta:**
Insights is considered beta, and is not ready for production use.
Follow [gitlab-org&725](https://gitlab.com/groups/gitlab-org/-/epics/725) for
updates.
Configure the Insights that matter for your projects to explore data such as
triage hygiene, issues created/closed per a given period, average time for merge
requests to be merged and much more.
![Insights example stacked bar chart](img/project_insights.png)
NOTE: **Note:**
This feature is [also available at the group level](https://docs.gitlab.com/ee/user/group/insights/index.html).
## Configure your Insights
Insights are configured using a YAML file called `.gitlab/insights.yml` within
a project. That file will then be used in the project's Insights page.
See [Writing your `.gitlab/insights.yml`](#writing-your-gitlabinsightsyml) below
for details about the content of this file.
NOTE: **Note:**
Once the configuration file is created, you can also
[use it for your project's group](https://docs.gitlab.com/ee/user/group/insights/index.html#configure-your-insights).
NOTE: **Note:**
If the project doesn't have any configuration file, it'll try to use
the group configuration if possible. If the group doesn't have any
configuration, the default configuration will be used.
## Permissions
If you have access to view a project, then you have access to view their
Insights.
NOTE: **Note:**
Issues or merge requests that you don't have access to (because you don't have
access to the project they belong to, or because they are confidential) are
filtered out of the Insights charts.
You may also consult the [group permissions table](../../permissions.md#group-members-permissions).
## Writing your `.gitlab/insights.yml`
The `.gitlab/insights.yml` file defines the structure and order of the Insights
charts that will be displayed in each Insights page of your project or group.
Each page has a unique key and a collection of charts to fetch and display.
For example, here's a single definition for Insights that will display one page with one chart:
```yaml
bugsCharts:
title: 'Charts for Bugs'
charts:
- title: Monthly Bugs Created (bar)
type: bar
query:
issuable_type: issue
issuable_state: opened
filter_labels:
- bug
group_by: month
period_limit: 24
```
Each chart definition is made up of a hash composed of key-value pairs.
For example, here's single chart definition:
```yaml
monthlyBugsCreated:
title: Monthly Bugs Created (bar)
type: bar
query:
issuable_type: issue
issuable_state: opened
filter_labels:
- bug
group_by: month
period_limit: 24
```
## Configuration parameters
A chart is defined as a list of parameters that define the chart's behavior.
The following table lists available parameters for charts:
| Keyword | Description |
|:---------------------------------------------------|:------------|
| [`title`](#title) | The title of the chart. This will displayed on the Insights page. |
| [`type`](#type) | The type of chart: `bar`, `line`, `stacked-bar`, `pie` etc. |
| [`query`](#query) | A hash that defines the conditions for issues / merge requests to be part of the chart. |
## Parameter details
The following are detailed explanations for parameters used to configure
Insights charts.
### `title`
`title` is the title of the chart as it will be displayed on the Insights page.
For example:
```yaml
monthlyBugsCreated:
title: Monthly Bugs Created (bar)
```
### `type`
`type` is the chart type.
For example:
```yaml
monthlyBugsCreated:
title: Monthly Bugs Created (bar)
type: bar
```
Supported values are:
| Name | Example |
| ----- | ------- |
| `bar` | ![Insights example bar chart](img/insights_example_bar_chart.png) |
| `bar` (time series, i.e. when `group_by` is used) | ![Insights example bar time series chart](img/insights_example_bar_time_series_chart.png) |
| `pie` | ![Insights example pie chart](img/insights_example_pie_chart.png) |
| `line` | ![Insights example stacked bar chart](img/insights_example_line_chart.png) |
| `stacked-bar` | ![Insights example stacked bar chart](img/insights_example_stacked_bar_chart.png) |
### `query`
`query` allows to define the conditions for issues / merge requests to be part
of the chart.
Example:
```yaml
monthlyBugsCreated:
title: Monthly Bugs Created (bar)
type: bar
query:
issuable_type: issue
issuable_state: opened
filter_labels:
- bug
collection_labels:
- S1
- S2
- S3
- S4
group_by: week
period_limit: 104
```
#### `query.issuable_type`
Defines the type of "issuable" you want to create a chart for.
Supported values are:
- `issue`: The chart will display issues' data.
- `merge_request`: The chart will display merge requests' data.
#### `query.issuable_state`
Filter by the state of the queried "issuable".
If you omit it, no state filter will be applied.
Supported values are:
- `opened`: Open issues / merge requests.
- `closed`: Closed Open issues / merge requests.
- `locked`: Issues / merge requests that have their discussion locked.
- `merged`: Merged merge requests.
#### `query.filter_labels`
Filter by labels applied to the queried "issuable".
If you omit it, no labels filter will be applied. All the defined labels must be
applied to the "issuable" in order for it to be selected.
Example:
```yaml
monthlyBugsCreated:
title: Monthly regressions Created (bar)
type: bar
query:
issuable_type: issue
issuable_state: opened
filter_labels:
- bug
- regression
```
#### `query.collection_labels`
Group "issuable" by the configured labels.
If you omit it, no grouping will be done. When using this keyword, you need to
set `type` to either `line` or `stacked-bar`.
Example:
```yaml
weeklyBugsBySeverity:
title: Weekly Bugs By Severity (stacked bar)
type: stacked-bar
query:
issuable_type: issue
issuable_state: opened
filter_labels:
- bug
collection_labels:
- S1
- S2
- S3
- S4
```
#### `query.group_by`
Define the X-axis of your chart.
Supported values are:
- `day`: Group data per day.
- `week`: Group data per week.
- `month`: Group data per month.
#### `query.period_limit`
Define how far "issuables" are queried in the past.
The unit is related to the `query.group_by` you defined. For instance if you
defined `query.group_by: 'day'` then `query.period_limit: 365` would mean
"Gather and display data for the last 365 days".
If you omit it, default values will be applied depending on the `query.group_by`
you defined.
| `query.group_by` | Default value |
| ---------------- | ------------- |
| `day` | 30 |
| `week` | 4 |
| `month` | 12 |
## Complete example
```yaml
bugsCharts:
title: 'Charts for Bugs'
charts:
- title: Monthly Bugs Created (bar)
type: bar
query:
issuable_type: issue
issuable_state: opened
filter_labels:
- bug
group_by: month
period_limit: 24
- title: Weekly Bugs By Severity (stacked bar)
type: stacked-bar
query:
issuable_type: issue
issuable_state: opened
filter_labels:
- bug
collection_labels:
- S1
- S2
- S3
- S4
group_by: week
period_limit: 104
- title: Monthly Bugs By Team (line)
type: line
query:
issuable_type: merge_request
issuable_state: opened
filter_labels:
- bug
collection_labels:
- Manage
- Plan
- Create
group_by: month
period_limit: 24
```
doc/user/project/integrations/github.md 0 → 100644
View file @ 363c1514
# GitHub project integration **[PREMIUM]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3836) in GitLab Premium 10.6.
GitLab provides an integration for updating the pipeline statuses on GitHub.
This is especially useful if using GitLab for CI/CD only.
This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirroring-and-pipeline-status-sharing)
and is automatically configured on [GitHub import](../../../integration/github.md).
![Pipeline status update on GitHub](img/github_status_check_pipeline_update.png)
## Configuration
### 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/)
with `repo:status` access granted:
1. Go to your "Personal access tokens" page at https://github.com/settings/tokens
1. Click "Generate New Token"
1. Ensure that `repo:status` is checked and click "Generate token"
1. Copy the generated token to use on GitLab
### Complete these steps on GitLab
1. Navigate to the project you want to configure.
1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services)
1. Click "GitHub".
1. Select the "Active" checkbox.
1. Paste the token you've generated on GitHub
1. Enter the path to your project on GitHub, such as `https://github.com/username/repository`
1. Optionally check "Static status check names" checkbox to enable static status check names.
1. Save or optionally click "Test Settings".
#### Static / dynamic status check names
Since GitLab 11.5 it is possible to opt-in to using static status check names.
This makes it possible to mark these status checks as _Required_ on GitHub.
If you check "Static status check names" checkbox on the integration page, your
GitLab instance host name is going to be appended to a status check name,
whereas in case of dynamic status check names, a branch name is going to be
appended.
Dynamic status check name is a default behavior.
![Configure GitHub Project Integration](img/github_configuration.png)
doc/user/project/integrations/project_services.md
View file @ 363c1514
......@@ -34,10 +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 |
| [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](https://docs.gitlab.com/ee/integration/jenkins.html) **[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 |
......
doc/user/project/integrations/prometheus.md
View file @ 363c1514
......@@ -13,7 +13,7 @@ There are two ways to set up Prometheus integration, depending on where your app
- For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes).
- For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus).
Once enabled, GitLab will automatically detect metrics from known services in the [metric library](#monitoring-cicd-environments).
Once enabled, GitLab will automatically detect metrics from known services in the [metric library](#monitoring-cicd-environments). You are also able to [add your own metrics](#adding-additional-metrics-premium) as well.
## Enabling Prometheus Integration
......@@ -93,6 +93,85 @@ 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]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3799) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6.
Additional metrics can be monitored by adding them on the Prometheus integration page. Once saved, they will be displayed on the environment performance dashboard.
![Add New Metric](img/prometheus_add_metric.png)
A few fields are required:
- **Name**: Chart title
- **Type**: Type of metric. Metrics of the same type will be shown together.
- **Query**: Valid [PromQL query](https://prometheus.io/docs/prometheus/latest/querying/basics/).
- **Y-axis label**: Y axis title to display on the dashboard.
- **Unit label**: Query units, for example `req / sec`. Shown next to the value.
Multiple metrics can be displayed on the same chart if the fields **Name**, **Type**, and **Y-axis label** match between metrics. For example, a metric with **Name** `Requests Rate`, **Type** `Business`, and **Y-axis label** `rec / sec` would display on the same chart as a second metric with the same values. A **Legend label** is suggested if this feature used.
#### Query Variables
GitLab supports a limited set of [CI variables](../../../ci/variables/README.html) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `CI_ENVIRONMENT_SLUG`. The supported variables are:
- CI_ENVIRONMENT_SLUG
- KUBE_NAMESPACE
To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`.
### Setting up alerts for Prometheus metrics **[ULTIMATE]**
#### Managed Prometheus instances
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6590) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2 for [custom metrics](#adding-additional-metrics-premium), and 11.3 for [library metrics](prometheus_library/metrics.md).
For managed Prometheus instances using auto configuration, alerts for metrics [can be configured](#adding-additional-metrics-premium) directly in the performance dashboard.
To set an alert, click on the alarm icon in the top right corner of the metric you want to create the alert for. A dropdown
will appear, with options to set the threshold and operator. Click **Add** to save and activate the alert.
![Adding an alert](img/prometheus_alert.png)
To remove the alert, click back on the alert icon for the desired metric, and click **Delete**.
#### External Prometheus instances
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8.
For manually configured Prometheus servers, a notify endpoint is provided to use with Prometheus webhooks. If you have manual configuration enabled, an **Alerts** section is added to **Settings > Integrations > Prometheus**. This contains the *URL* and *Authorization Key*. The **Reset Key** button will invalidate the key and generate a new one.
![Prometheus service configuration of Alerts](img/prometheus_service_alerts.png)
To send GitLab alert notifications, copy the *URL* and *Authorization Key* into the [`webhook_configs`](https://prometheus.io/docs/alerting/configuration/#webhook_config) section of your Prometheus Alertmanager configuration:
```yaml
receivers:
name: gitlab
webhook_configs:
- http_config:
bearer_token: 9e1cbfcd546896a9ea8be557caf13a76
send_resolved: true
url: http://192.168.178.31:3001/root/manual_prometheus/prometheus/alerts/notify.json
...
```
### 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.
Alerts can be used to trigger actions, like open an issue automatically. To configure the actions:
1. Navigate to your project's **Settings > Operations > Incidents**.
1. Enable the option to create issues.
1. Choose the [issue template](../description_templates.md) to create the issue from.
1. Optionally, select whether to send an email notification to the developers of the project.
1. Click **Save changes**.
Once enabled, an issue will be opened automatically when an alert is triggered. To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template.
If the metric exceeds the threshold of the alert for over 5 minutes, an email will be sent to all [Maintainers and Owners](../../permissions.md#project-members-permissions) of the project.
## Determining the performance impact of a merge
> [Introduced][ce-10408] in GitLab 9.2.
......
doc/user/project/integrations/prometheus_library/kubernetes.md
View file @ 363c1514
# Monitoring Kubernetes
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935) in GitLab 9.0
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935) in GitLab 9.0.
GitLab has support for automatically detecting and monitoring Kubernetes metrics.
......@@ -35,3 +35,25 @@ Prometheus needs to be deployed into the cluster and configured properly in orde
In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available.
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]**
> Introduced in [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15201).
GitLab also gathers Kubernetes metrics for [canary deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html), allowing easy comparison between the current deployed version and the canary.
These metrics expect the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name to begin with `$CI_ENVIRONMENT_SLUG-canary`, to isolate the canary metrics.
### Canary metrics supported
- Average Memory Usage (MB)
```
avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024
```
- Average CPU Utilization (%)
```
avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name))
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7