Merge branch 'docs-repo-merge-27-project-i' into 'master'

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

See merge request gitlab-org/gitlab-ce!27980

doc/user/project/import/gemnasium.md

+# 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

@@ -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

+# 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

+# 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)