diff options
Diffstat (limited to 'doc/user')
253 files changed, 5832 insertions, 110 deletions
diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md new file mode 100644 index 00000000000..776ab139c64 --- /dev/null +++ b/doc/user/admin_area/geo_nodes.md @@ -0,0 +1,70 @@ +# Geo nodes admin area **[PREMIUM ONLY]** + +For more information about setting up GitLab Geo, read the +[Geo documentation](https://docs.gitlab.com/ee/administration/geo/replication/index.html). + +When you're done, you can navigate to **Admin area > Geo** (`/admin/geo/nodes`). + +## Common settings + +All Geo nodes have the following settings: + +| Setting | Description | +| --------| ----------- | +| Primary | This marks a Geo Node as **primary** node. There can be only one **primary** node; make sure that you first add the **primary** node and then all the others. | +| Name | The unique identifier for the Geo node. Must match the setting `gitlab_rails[geo_node_name]` in `/etc/gitlab/gitlab.rb`. The setting defaults to `external_url` with a trailing slash. | +| URL | The instance's user-facing URL. | + +The node you're reading from is indicated with a green `Current node` label, and +the **primary** node is given a blue `Primary` label. Remember that you can only make +changes on the **primary** node! + +## **Secondary** node settings + +**Secondary** nodes have a number of additional settings available: + +| Setting | Description | +|---------------------------|-------------| +| Selective synchronization | Enable Geo [selective sync](https://docs.gitlab.com/ee/administration/geo/replication/configuration.html#selective-synchronization) for this **secondary** node. | +| Repository sync capacity | Number of concurrent requests this **secondary** node will make to the **primary** node when backfilling repositories. | +| File sync capacity | Number of concurrent requests this **secondary** node will make to the **primary** node when backfilling files. | + +## Geo backfill + +**Secondary** nodes are notified of changes to repositories and files by the **primary** node, +and will always attempt to synchronize those changes as quickly as possible. + +Backfill is the act of populating the **secondary** node with repositories and files that +existed *before* the **secondary** node was added to the database. Since there may be +extremely large numbers of repositories and files, it's infeasible to attempt to +download them all at once, so GitLab places an upper limit on the concurrency of +these operations. + +How long the backfill takes is a function of the maximum concurrency, but higher +values place more strain on the **primary** node. From [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3107), +the limits are configurable. If your **primary** node has lots of surplus capacity, +you can increase the values to complete backfill in a shorter time. If it's +under heavy load and backfill is reducing its availability for normal requests, +you can decrease them. + +## Using a different URL for synchronization + +The **primary** node's Internal URL is used by **secondary** nodes to contact it +(to sync repositories, for example). The name Internal URL distinguishes it from +[External URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab) +which is used by users. Internal URL does not need to be a private address. + +Internal URL defaults to External URL, but you can customize it under +**Admin area > Geo Nodes**. + +## Multiple secondary nodes behind a load balancer + +In GitLab 11.11, **secondary** nodes can use identical external URLs as long as +a unique `name` is set for each Geo node. The `gitlab.rb` setting +`gitlab_rails[geo_node_name]` must: + +- Be set for each GitLab instance that runs `unicorn`, `sidekiq`, or `geo_logcursor`. +- Match a Geo node name. + +The load balancer must use sticky sessions in order to avoid authentication +failures and cross site request errors. diff --git a/doc/user/admin_area/img/admin_wrench.png b/doc/user/admin_area/img/admin_wrench.png Binary files differnew file mode 100644 index 00000000000..17eee143e87 --- /dev/null +++ b/doc/user/admin_area/img/admin_wrench.png diff --git a/doc/user/admin_area/img/license_admin_area.png b/doc/user/admin_area/img/license_admin_area.png Binary files differnew file mode 100644 index 00000000000..b5662b81c5e --- /dev/null +++ b/doc/user/admin_area/img/license_admin_area.png diff --git a/doc/user/admin_area/img/license_details.png b/doc/user/admin_area/img/license_details.png Binary files differnew file mode 100644 index 00000000000..2085bb437ad --- /dev/null +++ b/doc/user/admin_area/img/license_details.png diff --git a/doc/user/admin_area/img/license_no_license_message.png b/doc/user/admin_area/img/license_no_license_message.png Binary files differnew file mode 100644 index 00000000000..87b397f7905 --- /dev/null +++ b/doc/user/admin_area/img/license_no_license_message.png diff --git a/doc/user/admin_area/img/license_upload.png b/doc/user/admin_area/img/license_upload.png Binary files differnew file mode 100644 index 00000000000..29d55175a2d --- /dev/null +++ b/doc/user/admin_area/img/license_upload.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index f924ff8dfde..dd4e96c1f4a 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -14,19 +14,22 @@ Only admin users can access the Admin Area. The Admin Area is made up of the following sections: -| Section | Description | -|:------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------| -| Overview | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administer-projects), users, groups, jobs, runners, and Gitaly servers. | -| Monitoring | View GitLab system information, and information on background jobs, logs, [health checks](monitoring/health_check.md), request profiles, and audit logs. | -| Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | -| System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | -| Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | -| Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. | -| Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | -| Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | -| Labels | Create and maintain [labels](labels.md) for your GitLab instance. | -| Appearance | Customize [GitLab's appearance](../../customization/index.md). | -| Settings | Modify the [settings](settings/index.md) for your GitLab instance. | +| Section | Description | +|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------| +| Overview | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administer-projects), users, groups, jobs, runners, and Gitaly servers. | +| Monitoring | View GitLab system information, and information on background jobs, logs, [health checks](monitoring/health_check.md), request profiles, and audit logs. | +| Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | +| System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | +| Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | +| Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. | +| License **[STARTER ONLY]** | Upload, display, and remove [licenses](license.md). | +| Push Rules **[STARTER]** | Configure pre-defined git [push rules](https://docs.gitlab.com/ee/push_rules/push_rules.html) for projects. | +| Geo **[PREMIUM ONLY]** | Configure and maintain [Geo nodes](geo_nodes.md). | +| Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | +| Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | +| Labels | Create and maintain [labels](labels.md) for your GitLab instance. | +| Appearance | Customize [GitLab's appearance](../../customization/index.md). | +| Settings | Modify the [settings](settings/index.md) for your GitLab instance. | ## Admin Dashboard @@ -70,4 +73,4 @@ them as you type. Select from the **Namespace** dropdown to filter only projects in that namespace. You can combine the filter options. For example, click the **Public** tab, and enter `score` in -the **Filter by name...** input box to list only public projects with `score` in their name.
\ No newline at end of file +the **Filter by name...** input box to list only public projects with `score` in their name. diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md new file mode 100644 index 00000000000..49959a9daef --- /dev/null +++ b/doc/user/admin_area/license.md @@ -0,0 +1,110 @@ +# Activate all GitLab Enterprise Edition functionality with a license **[STARTER ONLY]** + +To activate all GitLab Enterprise Edition (EE) functionality, you need to upload +a license. Once you've received your license from GitLab Inc., you can upload it +by **signing into your GitLab instance as an admin** or add it at +installation time. + +The license has the form of a base64 encoded ASCII text with a `.gitlab-license` +extension and can be obtained when you [purchase one][pricing] or when you sign +up for a [free trial]. + +NOTE: **Note:** +As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an +uploaded license will only have the Core features active. A trial license will +activate all Ultimate features, but after +[the trial expires](#what-happens-when-your-license-expires), some functionality +will be locked. + +## Uploading your license + +The very first time you visit your GitLab EE installation signed in as an admin, +you should see a note urging you to upload a license with a link that takes you +straight to the License admin area. + +Otherwise, you can: + +1. Navigate manually to the **Admin Area** by clicking the wrench icon in the menu bar. + +  + +1. And then going to the **License** tab and click on **Upload New License**. + +  + +1. If you've received a `.gitlab-license` file, you should have already downloaded + it in your local machine. You can then upload it directly by choosing the + license file and clicking the **Upload license** button. In the image below, + you can see that the selected license file is named `GitLab.gitlab-license`. + +  + + If you've received your license as plain text, you need to select the + "Enter license key" option, copy the license, paste it into the "License key" + field and click **Upload license**. + +## Add your license at install time + +The license may be automatically injected during installation using one of +two methods. + +The first requires a license file named `Gitlab.gitlab-release`. + +Place it in the `config/` directory if installing from source or in the +`/etc/gitlab/` directory if installing Omnibus. + +The second allows the administrator to configure the location and +filename of the license. + +Source installations should set the `GITLAB_LICENSE_FILE` environment +variable with the path to a valid GitLab Enterprise Edition license. + +```sh +export GITLAB_LICENSE_FILE="/path/to/license/file" +``` + +Omnibus installations should add this entry to `gitlab.rb`: + +```ruby +gitlab_rails['license_file'] = "/path/to/license/file" +``` + +CAUTION:: **Caution:** +These methods will only add a license at the time of installation. Use the +admin area in the web ui to renew or upgrade licenses. + +--- + +Once the license is uploaded, all GitLab Enterprise Edition functionality +will be active until the end of the license period. When that period ends, the +instance will [fall back](#what-happens-when-your-license-expires) to Core-only +functionality. + +You can review the license details at any time in the License section of the +Admin Area. + + + +## Notification before the license expires + +One month before the license expires, a message informing when the expiration +is due to, will start appearing to GitLab admins. Make sure that you update your +license, otherwise you will miss all the paid features if it expires. + +## What happens when your license expires + +In case your license expires, GitLab will lock down some features like Git pushes, +issue creation, etc., and a message to inform of the expired license will be +presented to all admins. + +In order to get back all the previous functionality, a new license must be uploaded. +To fall back to having only the Core features active, you'll need to delete the +expired license(s). + +## License history + +It's possible to upload and view more than one license, +but only the latest license will be used as the active license. + +[free trial]: https://about.gitlab.com/free-trial/ +[pricing]: https://about.gitlab.com/pricing/ diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md new file mode 100644 index 00000000000..4a5bfb6b677 --- /dev/null +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -0,0 +1,53 @@ +# Account and limit settings + +## Repository size limit **[STARTER]** + +> [Introduced][ee-740] in [GitLab Enterprise Edition 8.12][ee-8.12]. + +Repositories within your GitLab instance can grow quickly, especially if you are +using LFS. Their size can grow exponentially and eat up your storage device quite +fast. + +In order to avoid this from happening, you can set a hard limit for your +repositories' size. This limit can be set globally, per group, or per project, +with per project limits taking the highest priority. + +There are numerous cases where you'll need to set up a limit for repository size. +For instance, consider the following workflow: + +1. Your team develops apps which demand large files to be stored in + the application repository. +1. Although you have enabled [Git LFS](../../../workflow/lfs/manage_large_binaries_with_git_lfs.html#git-lfs) + to your project, your storage has grown significantly. +1. Before you blow your storage limit up, you set up a limit of 10 GB + per repository. + +### How it works + +Only a GitLab administrator can set those limits. Setting the limit to `0` means +there are no restrictions. + +These settings can be found within: + +- Each project's settings. +- A group's settings. +- The **Size limit per repository (MB)** field in the **Account and limit** section of a GitLab instance's + settings by navigating to either: + - **Admin Area > Settings > General**. + - The path `/admin/application_settings`. + +The very first push of a new project cannot be checked for size as of now, so +the first push will allow you to upload more than the limit dictates, but every +subsequent push will be denied. LFS objects, however, can be checked on first +push and **will** be rejected if the sum of their sizes exceeds the maximum +allowed repository size. + +For more manually purging the files, read the docs on +[reducing the repository size using Git][repo-size]. + +> **Note:** +> For GitLab.com, the repository size limit is 10 GB. + +[ee-740]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/740 +[repo-size]: ../../project/repository/reducing_the_repo_size_using_git.md +[ee-8.12]: https://about.gitlab.com/2016/09/22/gitlab-8-12-released/#limit-project-size-ee diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 22011cc6967..834a1e2423a 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -10,8 +10,8 @@ You can find it in the admin area, under **Settings > Continuous Integration and To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: -1. Go to **Admin area > Settings > Continuous Integration and Deployment**. -1. Check (or uncheck to disable) the box that says "Default to Auto DevOps pipeline for all projects". +1. Go to **Admin area > Settings > Continuous Integration and Deployment** +1. Check (or uncheck to disable) the box that says "Default to Auto DevOps pipeline for all projects" 1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/index.md#auto-devops-base-domain) which is going to be used for Auto Deploy and Auto Review Apps. 1. Hit **Save changes** for the changes to take effect. @@ -24,9 +24,9 @@ If you want to disable it for a specific project, you can do so in ## Maximum artifacts size **[CORE ONLY]** -The maximum size of the [job artifacts][art-yml] can be set in the Admin area -of your GitLab instance. The value is in *MB* and the default is 100MB per job; -on GitLab.com it's [set to 1G](../../gitlab_com/index.md#gitlab-cicd). +The maximum size of the [job artifacts](../../../administration/job_artifacts.md) +can be set in the Admin area of your GitLab instance. The value is in *MB* and +the default is 100MB per job; on GitLab.com it's [set to 1G](../../gitlab_com/index.md#gitlab-cicd). To change it: @@ -50,6 +50,79 @@ This setting is set per job and can be overridden in [`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifactsexpire_in). To disable the expiration, set it to `0`. The default unit is in seconds. +## Shared Runners pipeline minutes quota **[STARTER ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1078) +in GitLab Starter 8.16. + +If you have enabled shared Runners for your GitLab instance, you can limit their +usage by setting a maximum number of pipeline minutes that a group can use on +shared Runners per month. Setting this to `0` (default value) will grant +unlimited pipeline minutes. While build limits are stored as minutes, the +counting is done in seconds. Usage resets on the first day of each month. +On GitLab.com, the quota is calculated based on your +[subscription plan](https://about.gitlab.com/pricing/#gitlab-com). + +To change the pipelines minutes quota: + +1. Go to **Admin area > Settings > Continuous Integration and Deployment** +1. Set the pipeline minutes quota limit. +1. Hit **Save changes** for the changes to take effect + +--- + +While the setting in the Admin area has a global effect, as an admin you can +also change each group's pipeline minutes quota to override the global value. + +1. Navigate to the **Groups** admin area and hit the **Edit** button for the + group you wish to change the pipeline minutes quota. +1. Set the pipeline minutes quota to the desired value +1. Hit **Save changes** for the changes to take effect. + +Once saved, you can see the build quota in the group admin view. +The quota can also be viewed in the project admin view if shared Runners +are enabled. + + + +When the pipeline minutes quota for a group is set to a value different than 0, +the **Pipelines quota** page is available to the group page settings list. +You can see there an overview of the pipeline minutes quota of all projects of +the group. + + + + +## Extra Shared Runners pipeline minutes quota + +NOTE: **Note:** +Only available on GitLab.com. + +If you have a Group with a [paid plan](https://about.gitlab.com/pricing/#gitlab-com) on GitLab.com, +then you can purchase additional CI minutes so your pipelines will not be blocked after you have +used all your CI minutes from your main quota. + +In order to purchase additional minutes, you should follow these steps: + +1. Go to **Group > Settings > Pipelines quota**. Once you are on that page, click on **Buy additional minutes**. + +  + +1. Locate the subscription card that is linked to your group on GitLab.com, +click on **Buy more CI minutes**, and complete the details about the transaction. + +  + +1. Once we have processed your payment, the extra CI minutes +will be synced to your Group and you can visualize it from the +**Group > Settings > Pipelines quota** page: + +  + +NOTE: **Important note**: If you have some minutes used over your default quota, these minutes will +be deducted from your Additional Minutes quota immediately after your purchase of additional +minutes. + ## Archive jobs **[CORE ONLY]** Archiving jobs is useful for reducing the CI/CD footprint on the system by diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 50c318a4969..01a98cf15dc 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -4,6 +4,22 @@ The logo in the header of some emails can be customized, see the [logo customization section](../../../customization/branded_page_and_email_header.md). +## Custom additional text **[PREMIUM ONLY]** + +>[Introduced][ee-5031] in [GitLab Premium][eep] 10.7. + +The additional text will appear at the bottom of any email and can be used for +legal/auditing/compliance reasons. + +1. Go to **Admin area > Settings** (`/admin/application_settings`). +1. Under the **Email** section, change the **Additional text** field. +1. Hit **Save** for the changes to take effect. + + + +[ee-5031]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5031 +[eep]: https://about.gitlab.com/pricing/ + ## Custom hostname for private commit emails > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22560) in GitLab 11.5. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 72e76ac2a84..06e00e02f3d 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,4 +1,4 @@ -# External authorization control +# External authorization control **[CORE ONLY]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4216) in > [GitLab Premium](https://about.gitlab.com/pricing) 10.6. diff --git a/doc/user/admin_area/settings/img/additional_minutes.png b/doc/user/admin_area/settings/img/additional_minutes.png Binary files differnew file mode 100644 index 00000000000..d148ed79b92 --- /dev/null +++ b/doc/user/admin_area/settings/img/additional_minutes.png diff --git a/doc/user/admin_area/settings/img/admin_area_group_edit.png b/doc/user/admin_area/settings/img/admin_area_group_edit.png Binary files differnew file mode 100644 index 00000000000..c9bd2f10b36 --- /dev/null +++ b/doc/user/admin_area/settings/img/admin_area_group_edit.png diff --git a/doc/user/admin_area/settings/img/admin_area_groups.png b/doc/user/admin_area/settings/img/admin_area_groups.png Binary files differnew file mode 100644 index 00000000000..ebdee0eafdc --- /dev/null +++ b/doc/user/admin_area/settings/img/admin_area_groups.png diff --git a/doc/user/admin_area/settings/img/admin_project_quota_view.png b/doc/user/admin_area/settings/img/admin_project_quota_view.png Binary files differnew file mode 100644 index 00000000000..8320be860da --- /dev/null +++ b/doc/user/admin_area/settings/img/admin_project_quota_view.png diff --git a/doc/user/admin_area/settings/img/buy_btn.png b/doc/user/admin_area/settings/img/buy_btn.png Binary files differnew file mode 100644 index 00000000000..0cc88b8a48f --- /dev/null +++ b/doc/user/admin_area/settings/img/buy_btn.png diff --git a/doc/user/admin_area/settings/img/buy_minutes_card.png b/doc/user/admin_area/settings/img/buy_minutes_card.png Binary files differnew file mode 100644 index 00000000000..cf4ad34ead7 --- /dev/null +++ b/doc/user/admin_area/settings/img/buy_minutes_card.png diff --git a/doc/user/admin_area/settings/img/ci_shared_runners_build_minutes_quota.png b/doc/user/admin_area/settings/img/ci_shared_runners_build_minutes_quota.png Binary files differnew file mode 100644 index 00000000000..269a3cf1fbc --- /dev/null +++ b/doc/user/admin_area/settings/img/ci_shared_runners_build_minutes_quota.png diff --git a/doc/user/admin_area/settings/img/email_settings.png b/doc/user/admin_area/settings/img/email_settings.png Binary files differnew file mode 100644 index 00000000000..ed0a80d10ce --- /dev/null +++ b/doc/user/admin_area/settings/img/email_settings.png diff --git a/doc/user/admin_area/settings/img/file_template_admin_area.png b/doc/user/admin_area/settings/img/file_template_admin_area.png Binary files differnew file mode 100644 index 00000000000..269d997e1d9 --- /dev/null +++ b/doc/user/admin_area/settings/img/file_template_admin_area.png diff --git a/doc/user/admin_area/settings/img/file_template_user_dropdown.png b/doc/user/admin_area/settings/img/file_template_user_dropdown.png Binary files differnew file mode 100644 index 00000000000..8c9eb49f6c9 --- /dev/null +++ b/doc/user/admin_area/settings/img/file_template_user_dropdown.png diff --git a/doc/user/admin_area/settings/img/group_pipelines_quota.png b/doc/user/admin_area/settings/img/group_pipelines_quota.png Binary files differnew file mode 100644 index 00000000000..d94b609ad6f --- /dev/null +++ b/doc/user/admin_area/settings/img/group_pipelines_quota.png diff --git a/doc/user/admin_area/settings/img/group_quota_view.png b/doc/user/admin_area/settings/img/group_quota_view.png Binary files differnew file mode 100644 index 00000000000..791bfd868e0 --- /dev/null +++ b/doc/user/admin_area/settings/img/group_quota_view.png diff --git a/doc/user/admin_area/settings/img/group_settings.png b/doc/user/admin_area/settings/img/group_settings.png Binary files differnew file mode 100644 index 00000000000..a849d9cfdc1 --- /dev/null +++ b/doc/user/admin_area/settings/img/group_settings.png diff --git a/doc/user/admin_area/settings/img/mirror_settings.png b/doc/user/admin_area/settings/img/mirror_settings.png Binary files differnew file mode 100644 index 00000000000..090db6808a7 --- /dev/null +++ b/doc/user/admin_area/settings/img/mirror_settings.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 8358fe64f18..0e697b9e445 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -6,6 +6,7 @@ instance like sign-up restrictions, account limits and quota, metrics, etc. Navigate to it by going to **Admin area > Settings**. Some of the settings include: +- [Account and limit settings](account_and_limit_settings.md) **[STARTER]** - [Continuous Integration and Deployment](continuous_integration.md) - [Email](email.md) - [Sign up restrictions](sign_up_restrictions.md) @@ -13,6 +14,7 @@ include: - [Third party offers](third_party_offers.md) - [Usage statistics](usage_statistics.md) - [Visibility and access controls](visibility_and_access_controls.md) +- [Custom templates repository](instance_template_repository.md) **[PREMIUM]** NOTE: **Note:** You can change the [first day of the week](../../profile/preferences.md) for the entire GitLab instance diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md new file mode 100644 index 00000000000..4010008f694 --- /dev/null +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -0,0 +1,63 @@ +# Instance template repository **[PREMIUM ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5986) in +> [GitLab Premium](https://about.gitlab.com/pricing) 11.3. + +## Overview + +In hosted systems, enterprises often have a need to share their own templates +across teams. This feature allows an administrator to pick a project to be the +instance-wide collection of file templates. These templates are then exposed to +all users [via the web editor](../../project/repository/web_editor.md#template-dropdowns) +while the project remains secure. + +## Configuration + +As an administrator, navigate to **Admin area > Settings > Templates** and +select the project to serve as the custom template repository. + + + +Once a project has been selected, you can add custom templates to the repository, +and they will appear in the appropriate places in the +[frontend](../../project/repository/web_editor.md#template-dropdowns) and +[API](../../../api/settings.md). + +Templates must be added to a specific subdirectory in the repository, +corresponding to the kind of template. The following types of custom templates +are supported: + +| Type | Directory | Extension | +| :---------------: | :-----------: | :-----------: | +| `Dockerfile` | `Dockerfile` | `.dockerfile` | +| `.gitignore` | `gitignore` | `.gitignore` | +| `.gitlab-ci.yml` | `gitlab-ci` | `.yml` | +| `LICENSE` | `LICENSE` | `.txt` | + +Each template must go in its respective subdirectory, have the correct +extension and not be empty. So, the hierarchy should look like this: + +```text +|-- README.md +|-- Dockerfile + |-- custom_dockerfile.dockerfile + |-- another_dockerfile.dockerfile +|-- gitignore + |-- custom_gitignore.gitignore + |-- another_gitignore.gitignore +|-- gitlab-ci + |-- custom_gitlab-ci.yml + |-- another_gitlab-ci.yml +|-- LICENSE + |-- custom_license.txt + |-- another_license.txt +``` + +Once this is established, the list of custom templates will be included when +creating a new file and the template type is selected. These will appear at the +top of the list. + + + +If this feature is disabled or no templates are present, there will be +no "Custom" section in the selection dropdown. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index e165a120162..8b5d80efb0d 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -48,6 +48,8 @@ You can view the exact JSON payload in the administration panel. To view the pay 1. Expand **Settings** in the left sidebar and click on **Metrics and profiling**. 1. Expand **Usage statistics** and click on the **Preview payload** button. +You can see how [the usage ping data maps to different stages of the product](https://gitlab.com/gitlab-data/analytics/blob/master/transform/snowflake-dbt/data/ping_metrics_to_stage_mapping_data.csv). + ### Deactivate the usage ping The usage ping is opt-out. If you want to deactivate this feature, go to diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 6a1e8004f87..4d1b7d0f252 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -49,5 +49,15 @@ block access to the server itself. The ports used for the protocol, be it SSH or HTTP, will still be accessible. What GitLab does is restrict access on the application level. +## Allow mirrors to be set up for projects + +> [Introduced][ee-3586] in GitLab 10.3. + +This option is enabled by default. By disabling it, both pull and push mirroring will no longer +work in every repository and can only be re-enabled on a per-project basis by an admin. + + + [ce-4696]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4696 [ce-18021]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18021 +[ee-3586]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3586 diff --git a/doc/user/application_security/container_scanning/img/container_scanning.png b/doc/user/application_security/container_scanning/img/container_scanning.png Binary files differnew file mode 100644 index 00000000000..e47f62acd9d --- /dev/null +++ b/doc/user/application_security/container_scanning/img/container_scanning.png diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md new file mode 100644 index 00000000000..ce86ade3c1a --- /dev/null +++ b/doc/user/application_security/container_scanning/index.md @@ -0,0 +1,202 @@ +# Container Scanning **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can check your Docker +images (or more precisely the containers) for known vulnerabilities by using +[Clair](https://github.com/coreos/clair) and [clair-scanner](https://github.com/arminc/clair-scanner), +two open source tools for Vulnerability Static Analysis for containers. + +You can take advantage of Container Scanning by either [including the CI job](#including-the-provided-template) in +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto Container Scanning](../../../topics/autodevops/index.md#auto-container-scanning) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +GitLab checks the Container Scanning report, compares the found vulnerabilities +between the source and target branches, and shows the information right on the +merge request. + + + +## Use cases + +If you distribute your application with Docker, then there's a great chance +that your image is based on other Docker images that may in turn contain some +known vulnerabilities that could be exploited. + +Having an extra job in your pipeline that checks for those vulnerabilities, +and the fact that they are displayed inside a merge request, makes it very easy +to perform audits for your Docker-based apps. + +## Requirements + +To enable Container Scanning in your pipeline, you need: + +- A GitLab Runner with the + [`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or + [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) + executor running in privileged mode. If you're using the shared Runners on GitLab.com, + this is enabled by default. +- To [build and push](../../../ci/docker/using_docker_build.md#container-registry-examples) + your Docker image to your project's [Container Registry](../../project/container_registry.md). + The name of the Docker image should match the following scheme: + + ``` + $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA + ``` + + The variables above can be found in the + [predefined environment variables](../../../ci/variables/predefined_variables.md) + document. + +## Configuring Container Scanning + +To enable Container Scanning in your project, define a job in your +`.gitlab-ci.yml` file that generates the +[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate). + +This can be done in two ways: + +- For GitLab 11.9 and later, including the provided + `Container-Scanning.gitlab-ci.yml` template (recommended). +- Manually specifying the job definition. Not recommended unless using GitLab + 11.8 and earlier. + +### Including the provided template + +NOTE: **Note:** +The CI/CD Container Scanning template is supported on GitLab 11.9 and later versions. +For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). + +A CI/CD [Container Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) +with the default Container Scanning job definition is provided as a part of your GitLab +installation that you can [include](../../../ci/yaml/README.md#includetemplate) +in your `.gitlab-ci.yml` file. + +To enable Container Scanning using the provided template, add the following to +your `.gitlab-ci.yml` file: + +```yaml +include: + template: Container-Scanning.gitlab-ci.yml +``` + +The included template will: + +- Create a `container_scanning` job in your CI/CD pipeline. +- Pull the already built Docker image from your project's + [Container Registry](../../project/container_registry.md) (see [requirements](#requirements)) + and scan it for possible vulnerabilities. + +The report will be saved as a +[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate) +that you can later download and analyze. +Due to implementation limitations, we always take the latest Container Scanning +artifact available. Behind the scenes, the +[GitLab Container Scanning analyzer](https://gitlab.com/gitlab-org/security-products/container-scanning) +is used and runs the scans. + +If you want to whitelist some specific vulnerabilities, you can do so by defining +them in a YAML file named `clair-whitelist.yml`. Read more in the +[Clair documentation](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file). + +### Manual job definition for GitLab 11.5 and later + +CAUTION: **Caution:** +The job definition shown below is supported on GitLab 11.5 and later versions. +However, if you're using GitLab 11.9+, it's recommended to use +[the provided Container Scanning template](#including-the-provided-template). + +For GitLab 11.5 and GitLab Runner 11.5 and later, the following `container_scanning` +job can be added: + +```yaml +container_scanning: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + ## Define two new variables based on GitLab's CI/CD predefined variables + ## https://docs.gitlab.com/ee/ci/variables/#predefined-environment-variables + CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG + CI_APPLICATION_TAG: $CI_COMMIT_SHA + allow_failure: true + services: + - docker:stable-dind + script: + - docker run -d --name db arminc/clair-db:latest + - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:v2.0.6 + - apk add -U wget ca-certificates + - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} + - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 + - mv clair-scanner_linux_amd64 clair-scanner + - chmod +x clair-scanner + - touch clair-whitelist.yml + - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done + - retries=0 + - echo "Waiting for clair daemon to start" + - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done + - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true + artifacts: + reports: + container_scanning: gl-container-scanning-report.json +``` + +### Manual job definition for GitLab 11.4 and earlier (deprecated) + +CAUTION: **Deprecated:** +Before GitLab 11.5, the Container Scanning job and artifact had to be named specifically +to automatically extract report data and show it in the merge request widget. +While these old job definitions are still maintained, they have been deprecated +and may be removed in the next major release, GitLab 12.0. You are strongly +advised to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the Container Scanning job should look like: + +```yaml +container_scanning: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + ## Define two new variables based on GitLab's CI/CD predefined variables + ## https://docs.gitlab.com/ee/ci/variables/#predefined-environment-variables + CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG + CI_APPLICATION_TAG: $CI_COMMIT_SHA + allow_failure: true + services: + - docker:stable-dind + script: + - docker run -d --name db arminc/clair-db:latest + - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:v2.0.6 + - apk add -U wget ca-certificates + - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} + - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 + - mv clair-scanner_linux_amd64 clair-scanner + - chmod +x clair-scanner + - touch clair-whitelist.yml + - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done + - retries=0 + - echo "Waiting for clair daemon to start" + - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done + - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true + artifacts: + paths: [gl-container-scanning-report.json] +``` + +Alternatively, the job name could be `sast:container` +and the artifact name could be `gl-sast-container-report.json`. +These names have been deprecated with GitLab 11.0 +and may be removed in the next major release, GitLab 12.0. + +## Security Dashboard + +The Security Dashboard is a good place to get an overview of all the security +vulnerabilities in your groups and projects. Read more about the +[Security Dashboard](../security_dashboard/index.md). + +## Interacting with the vulnerabilities + +Once a vulnerability is found, you can interact with it. Read more on how to +[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). diff --git a/doc/user/application_security/dast/img/dast_all.png b/doc/user/application_security/dast/img/dast_all.png Binary files differnew file mode 100644 index 00000000000..b6edc928dc3 --- /dev/null +++ b/doc/user/application_security/dast/img/dast_all.png diff --git a/doc/user/application_security/dast/img/dast_single.png b/doc/user/application_security/dast/img/dast_single.png Binary files differnew file mode 100644 index 00000000000..26ca4bde786 --- /dev/null +++ b/doc/user/application_security/dast/img/dast_single.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md new file mode 100644 index 00000000000..904c9e8fefe --- /dev/null +++ b/doc/user/application_security/dast/index.md @@ -0,0 +1,262 @@ +# Dynamic Application Security Testing (DAST) **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4348) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. + +Running [static checks](../sast/index.md) on your code is the first step to detect +vulnerabilities that can put the security of your code at risk. Yet, once +deployed, your application is exposed to a new category of possible attacks, +such as cross-site scripting or broken authentication flaws. This is where +Dynamic Application Security Testing (DAST) comes into place. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s) +for known vulnerabilities using Dynamic Application Security Testing (DAST). + +You can take advantage of DAST by either [including the CI job](#configuring-dast) in +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto DAST](../../../topics/autodevops/index.md#auto-dast-ultimate) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +GitLab checks the DAST report, compares the found vulnerabilities between the source and target +branches, and shows the information right on the merge request. + + + +By clicking on one of the detected linked vulnerabilities, you will be able to +see the details and the URL(s) affected. + + + +[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing) +is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy) +to perform an analysis on your running web application. + +By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) and will perform passive scanning only. It will not actively attack your application. + +However, DAST can be [configured](#full-scan) +to also perform a so-called "active scan". That is, attack your application and produce a more extensive security report. +It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md). + +## Use cases + +It helps you automatically find security vulnerabilities in your running web +applications while you are developing and testing your applications. + +## Requirements + +To run a DAST job, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or +[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) +executor running in privileged mode. If you're using the shared Runners on GitLab.com, +this is enabled by default. + +## Configuring DAST + +To enable DAST in your project, define a job in your `.gitlab-ci.yml` file that generates the +[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate). + +This can be done in two ways: + +- For GitLab 11.9 and later, including the provided DAST `.gitlab-ci.yml` template (recommended). +- Manually specifying the job definition. Not recommended unless using GitLab + 11.8 and earlier. + +### Including the provided template + +NOTE: **Note:** +The CI/CD DAST template is supported on GitLab 11.9 and later versions. +For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). + +A CI/CD [DAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml) +with the default DAST job definition is provided as a part of your GitLab +installation which you can [include](../../../ci/yaml/README.md#includetemplate) +in your `.gitlab-ci.yml` file. + +To enable DAST using the provided template, add the following to your `.gitlab-ci.yml` +file: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_WEBSITE: https://example.com +``` + +The included template will create a `dast` job in your CI/CD pipeline and scan +your project's source code for possible vulnerabilities. + +The report will be saved as a +[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate) +that you can later download and analyze. Due to implementation limitations we +always take the latest DAST artifact available. Behind the scenes, the +[GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) +is used to run the tests on the specified URL and scan it for possible vulnerabilities. + +There are two ways to define the URL to be scanned by DAST: + +- Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). +- Add it in an `environment_url.txt` file at the root of your project. + +#### Authenticated scan + +It's also possible to authenticate the user before performing the DAST checks: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_WEBSITE: https://example.com + DAST_AUTH_URL: https://example.com/sign-in + DAST_USERNAME: john.doe@example.com + DAST_PASSWORD: john-doe-password + DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form + DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form + DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between +``` + +The report will be saved as a +[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate) +that you can later download and analyze. +Due to implementation limitations, we always take the latest DAST artifact available. + +#### Full scan + +DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which +includes both passive and active scanning against the same target website: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_FULL_SCAN_ENABLED: "true" +``` + +#### Customizing the DAST settings + +The SAST settings can be changed through environment variables by using the +[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. +These variables are documented in the [DAST README](https://gitlab.com/gitlab-org/security-products/dast#settings). + +For example: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_WEBSITE: https://example.com + DAST_TARGET_AVAILABILITY_TIMEOUT: 120 +``` + +Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline +configuration, the last mention of the variable will take precedence. + +#### Overriding the DAST template + +If you want to override the job definition (for example, change properties like +`variables` or `dependencies`), you need to declare a `dast` job after the +template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: DAST.gitlab-ci.yml + +dast: + stage: dast # IMPORTANT: don't forget to add this + variables: + DAST_WEBSITE: https://example.com + CI_DEBUG_TRACE: "true" +``` + +As the DAST job belongs to a separate `dast` stage that runs after all +[default stages](../../../ci/yaml/README.md#stages), +don't forget to add `stage: dast` when you override the template job definition. + +### Manual job definition for GitLab 11.5 and later + +For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dast` +job can be added: + +```yaml +dast: + image: registry.gitlab.com/gitlab-org/security-products/zaproxy + variables: + website: "https://example.com" + allow_failure: true + script: + - mkdir /zap/wrk/ + - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true + - cp /zap/wrk/gl-dast-report.json . + artifacts: + reports: + dast: gl-dast-report.json +``` + +Where the `website` variable holds the URL to run the tests against. + +For an authenticated scan, use the following definition: + +```yaml +dast: + image: registry.gitlab.com/gitlab-org/security-products/zaproxy + variables: + website: "https://example.com" + login_url: "https://example.com/sign-in" + username: "john.doe@example.com" + password: "john-doe-password" + allow_failure: true + script: + - mkdir /zap/wrk/ + - /zap/zap-baseline.py -J gl-dast-report.json -t $website + --auth-url $login_url + --auth-username $username + --auth-password $password || true + - cp /zap/wrk/gl-dast-report.json . + artifacts: + reports: + dast: gl-dast-report.json +``` + +See the [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy) +to learn more about the authentication settings. + +### Manual job definition for GitLab 11.4 and earlier (deprecated) + +CAUTION: **Caution:** +Before GitLab 11.5, DAST job and artifact had to be named specifically +to automatically extract report data and show it in the merge request widget. +While these old job definitions are still maintained they have been deprecated +and may be removed in next major release, GitLab 12.0. You are strongly advised +to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the job should look like: + +```yaml +dast: + image: registry.gitlab.com/gitlab-org/security-products/zaproxy + variables: + website: "https://example.com" + allow_failure: true + script: + - mkdir /zap/wrk/ + - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true + - cp /zap/wrk/gl-dast-report.json . + artifacts: + paths: [gl-dast-report.json] +``` + +## Security Dashboard + +The Security Dashboard is a good place to get an overview of all the security +vulnerabilities in your groups and projects. Read more about the +[Security Dashboard](../security_dashboard/index.md). + +## Interacting with the vulnerabilities + +Once a vulnerability is found, you can interact with it. Read more on how to +[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). diff --git a/doc/user/application_security/dependency_scanning/img/dependency_scanning.png b/doc/user/application_security/dependency_scanning/img/dependency_scanning.png Binary files differnew file mode 100644 index 00000000000..18df356f846 --- /dev/null +++ b/doc/user/application_security/dependency_scanning/img/dependency_scanning.png diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md new file mode 100644 index 00000000000..2d0c2be4233 --- /dev/null +++ b/doc/user/application_security/dependency_scanning/index.md @@ -0,0 +1,225 @@ +# Dependency Scanning **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known +vulnerabilities using Dependency Scanning. + +You can take advantage of Dependency Scanning by either [including the CI job](#including-the-provided-template) +in your existing `.gitlab-ci.yml` file or by implicitly using +[Auto Dependency Scanning](../../../topics/autodevops/index.md#auto-dependency-scanning-ultimate) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +GitLab checks the Dependency Scanning report, compares the found vulnerabilities +between the source and target branches, and shows the information right on the +merge request. + + + +The results are sorted by the priority of the vulnerability: + +1. High +1. Medium +1. Low +1. Unknown +1. Everything else + +## Use cases + +It helps to automatically find security vulnerabilities in your dependencies +while you are developing and testing your applications. For example when your +application is using an external (open source) library which is known to be vulnerable. + +## Requirements + +To run a Dependency Scanning job, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or +[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) +executor running in privileged mode. If you're using the shared Runners on GitLab.com, +this is enabled by default. + +## Supported languages and package managers + +The following languages and dependency managers are supported. + +| Language (package managers) | Scan tool | +|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [Retire.js](https://retirejs.github.io/retire.js) | +| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | +| Ruby ([gem](https://rubygems.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [bundler-audit](https://github.com/rubysec/bundler-audit) | +| Java ([Maven](https://maven.apache.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | +| PHP ([Composer](https://getcomposer.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | + +Some scanners require to send a list of project dependencies to GitLab's central +servers to check for vulnerabilities. To learn more about this or to disable it, +refer to the [GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks). + +## Configuring Dependency Scanning + +To enable Dependency Scanning in your project, define a job in your `.gitlab-ci.yml` +file that generates the +[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate). + +This can be done in two ways: + +- For GitLab 11.9 and later, including the provided Dependency Scanning + `.gitlab-ci.yml` template (recommended). +- Manually specifying the job definition. Not recommended unless using GitLab + 11.8 and earlier. + +### Including the provided template + +NOTE: **Note:** +The CI/CD Dependency Scanning template is supported on GitLab 11.9 and later versions. +For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). + +A CI/CD [Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) +with the default Dependency Scanning job definition is provided as a part of your GitLab +installation which you can [include](../../../ci/yaml/README.md#includetemplate) +in your `.gitlab-ci.yml` file. + +To enable Dependency Scanning using the provided template, add the following to +your `.gitlab-ci.yml` file: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml +``` + +The included template will create a `dependency_scanning` job in your CI/CD +pipeline and scan your project's source code for possible vulnerabilities. + +The report will be saved as a +[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate) +that you can later download and analyze. Due to implementation limitations, we +always take the latest Dependency Scanning artifact available. + +Some security scanners require to send a list of project dependencies to GitLab +central servers to check for vulnerabilities. To learn more about this or to +disable it, check the +[GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks). + +#### Customizing the Dependency Scanning settings + +The Dependency Scanning settings can be changed through environment variables by using the +[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. +These variables are documented in the +[Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings). + +For example: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DEP_SCAN_DISABLE_REMOTE_CHECKS: true +``` + +Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline +configuration, the last mention of the variable will take precedence. + +#### Overriding the Dependency Scanning template + +If you want to override the job definition (for example, change properties like +`variables` or `dependencies`), you need to declare a `dependency_scanning` job +after the template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +dependency_scanning: + variables: + CI_DEBUG_TRACE: "true" +``` + +### Manual job definition for GitLab 11.5 and later + +For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dependency_scanning` +job can be added: + +```yaml +dependency_scanning: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + allow_failure: true + services: + - docker:stable-dind + script: + - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} + - | + docker run \ + --env DS_ANALYZER_IMAGES \ + --env DS_ANALYZER_IMAGE_PREFIX \ + --env DS_ANALYZER_IMAGE_TAG \ + --env DS_DEFAULT_ANALYZERS \ + --env DEP_SCAN_DISABLE_REMOTE_CHECKS \ + --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ + --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \ + --env DS_RUN_ANALYZER_TIMEOUT \ + --volume "$PWD:/code" \ + --volume /var/run/docker.sock:/var/run/docker.sock \ + "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code + dependencies: [] + artifacts: + reports: + dependency_scanning: gl-dependency-scanning-report.json +``` + +You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings) +via `docker run --env` to customize your job execution. + +### Manual job definition for GitLab 11.4 and earlier (deprecated) + +CAUTION: **Caution:** +Before GitLab 11.5, the Dependency Scanning job and artifact had to be named specifically +to automatically extract the report data and show it in the merge request widget. +While these old job definitions are still maintained, they have been deprecated +and may be removed in the next major release, GitLab 12.0. You are strongly advised +to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the job should look like: + +```yaml +dependency_scanning: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + allow_failure: true + services: + - docker:stable-dind + script: + - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} + - | + docker run \ + --env DS_ANALYZER_IMAGES \ + --env DS_ANALYZER_IMAGE_PREFIX \ + --env DS_ANALYZER_IMAGE_TAG \ + --env DS_DEFAULT_ANALYZERS \ + --env DS_EXCLUDED_PATHS \ + --env DEP_SCAN_DISABLE_REMOTE_CHECKS \ + --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ + --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \ + --env DS_RUN_ANALYZER_TIMEOUT \ + --volume "$PWD:/code" \ + --volume /var/run/docker.sock:/var/run/docker.sock \ + "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code + artifacts: + paths: [gl-dependency-scanning-report.json] +``` + +## Security Dashboard + +The Security Dashboard is a good place to get an overview of all the security +vulnerabilities in your groups and projects. Read more about the +[Security Dashboard](../security_dashboard/index.md). + +## Interacting with the vulnerabilities + +Once a vulnerability is found, you can interact with it. Read more on how to +[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). diff --git a/doc/user/application_security/img/create_issue_with_list_hover.png b/doc/user/application_security/img/create_issue_with_list_hover.png Binary files differnew file mode 100644 index 00000000000..7d70e8299f5 --- /dev/null +++ b/doc/user/application_security/img/create_issue_with_list_hover.png diff --git a/doc/user/application_security/img/interactive_reports.png b/doc/user/application_security/img/interactive_reports.png Binary files differnew file mode 100644 index 00000000000..9f9812dc69d --- /dev/null +++ b/doc/user/application_security/img/interactive_reports.png diff --git a/doc/user/application_security/img/issue.png b/doc/user/application_security/img/issue.png Binary files differnew file mode 100644 index 00000000000..6467201df3f --- /dev/null +++ b/doc/user/application_security/img/issue.png diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png Binary files differnew file mode 100644 index 00000000000..7443b9b6eea --- /dev/null +++ b/doc/user/application_security/img/vulnerability_solution.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md new file mode 100644 index 00000000000..64e72fab198 --- /dev/null +++ b/doc/user/application_security/index.md @@ -0,0 +1,104 @@ +# GitLab Secure **[ULTIMATE]** + +Check your application for security vulnerabilities that may lead to unauthorized access, +data leaks, and denial of services. GitLab will perform static and dynamic tests on the +code of your application, looking for known flaws and report them in the merge request +so you can fix them before merging. Security teams can use dashboards to get a +high-level view on projects and groups, and start remediation processes when needed. + +## Security scanning tools + +GitLab can scan and report any vulnerabilities found in your project. + +| Secure scanning tools | Description | +|:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------| +| [Container Scanning](container_scanning/index.md) **[ULTIMATE]** | Scan Docker containers for known vulnerabilities. | +| [Dependency Scanning](dependency_scanning/index.md) **[ULTIMATE]** | Analyze your dependencies for known vulnerabilities. | +| [Dynamic Application Security Testing (DAST)](dast/index.md) **[ULTIMATE]** | Analyze running web applications for known vulnerabilities. | +| [License Management](license_management/index.md) **[ULTIMATE]** | Search your project's dependencies for their licenses. | +| [Security Dashboard](security_dashboard/index.md) **[ULTIMATE]** | View vulnerabilities in all your projects and groups. | +| [Static Application Security Testing (SAST)](sast/index.md) **[ULTIMATE]** | Analyze source code for known vulnerabilities. | + +## Interacting with the vulnerabilities + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.8. + +CAUTION: **Warning:** +This feature is currently [Alpha](https://about.gitlab.com/handbook/product/#alpha-beta-ga) and while you can start using it, it may receive important changes in the future. + +Each security vulnerability in the merge request report or the +[Security Dashboard](security_dashboard/index.md) is actionable. Clicking on an +entry, a detailed information will pop up with different possible options: + +- [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability + will place a <s>strikethrough</s> styling on it. +- [Create issue](#creating-an-issue-for-a-vulnerability): The new issue will + have the title and description pre-populated with the information from the + vulnerability report and will be created as [confidential](../project/issues/confidential_issues.md) by default. +- [Solution](#solutions-for-vulnerabilities): For some vulnerabilities + ([Dependency Scanning](dependency_scanning/index.md) and [Container Scanning](container_scanning/index.md)) + a solution is provided for how to fix the vulnerability. + + + +### Dismissing a vulnerability + +You can dismiss vulnerabilities by clicking the **Dismiss vulnerability** button. +This will dismiss the vulnerability and re-render it to reflect its dismissed state. +If you wish to undo this dismissal, you can click the **Undo dismiss** button. + +### Creating an issue for a vulnerability + +You can create an issue for a vulnerability by selecting the **Create issue** +button from within the vulnerability modal or using the action buttons to the right of +a vulnerability row when in the group security dashboard. + +This will create a [confidential issue](../project/issues/confidential_issues.md) +on the project this vulnerability came from and pre-fill it with some useful +information taken from the vulnerability report. Once the issue is created, you +will be redirected to it so you can edit, assign, or comment on it. + +Upon returning to the group security dashboard, you'll see that +the vulnerability will now have an associated issue next to the name. + + + +### Solutions for vulnerabilities + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.7. + +CAUTION: **Warning:** +Automatic Patch creation is only available for a subset of +[Dependency Scanning](dependency_scanning/index.md). At the moment only Node.JS +projects managed with yarn are supported. + +Some vulnerabilities can be fixed by applying the solution that GitLab +automatically generates. + +#### Manually applying the suggested patch + +Some vulnerabilities can be fixed by applying a patch that is automatically +generated by GitLab. To apply the fix: + +1. Click on the vulnerability. +1. Download and review the patch file `remediation.patch`. +2. Ensure your local project has the same commit checked out that was used to generate the patch. +3. Run `git apply remediation.patch`. +4. Verify and commit the changes to your branch. + + + +#### Creating a merge request from a vulnerability + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9224) in + [GitLab Ultimate](https://about.gitlab.com/pricing) 11.9. + +In certain cases, GitLab will allow you to create a merge request that will +automatically remediate the vulnerability. Any vulnerability that has a +[solution](#solutions-for-vulnerabilities) can have a merge request created to +automatically solve the issue. + +If this action is available there will be a **Create merge request** button in the vulnerability modal. +Clicking on this button will create a merge request to apply the solution onto the source branch. + + diff --git a/doc/user/application_security/license_management/img/license_management.png b/doc/user/application_security/license_management/img/license_management.png Binary files differnew file mode 100644 index 00000000000..cdce6b5fe38 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management.png diff --git a/doc/user/application_security/license_management/img/license_management_decision.png b/doc/user/application_security/license_management/img/license_management_decision.png Binary files differnew file mode 100644 index 00000000000..0763130c375 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_decision.png diff --git a/doc/user/application_security/license_management/img/license_management_pipeline_tab.png b/doc/user/application_security/license_management/img/license_management_pipeline_tab.png Binary files differnew file mode 100644 index 00000000000..80ffca815b9 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_pipeline_tab.png diff --git a/doc/user/application_security/license_management/img/license_management_settings.png b/doc/user/application_security/license_management/img/license_management_settings.png Binary files differnew file mode 100644 index 00000000000..b5490e59074 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_settings.png diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md new file mode 100644 index 00000000000..8b75995c377 --- /dev/null +++ b/doc/user/application_security/license_management/index.md @@ -0,0 +1,264 @@ +# License Management **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses +using License Management. + +You can take advantage of License Management by either [including the job](#configuring-license-management) +in your existing `.gitlab-ci.yml` file or by implicitly using +[Auto License Management](../../../topics/autodevops/index.md#auto-license-management-ultimate) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +GitLab checks the License Management report, compares the licenses between the +source and target branches, and shows the information right on the merge request. +Blacklisted licenses will be clearly visible with an `x` red icon next to them +as well as new licenses which need a decision from you. In addition, you can +[manually approve or blacklist](#project-policies-for-license-management) +licenses in your project's settings. + +NOTE: **Note:** +If the license management report doesn't have anything to compare to, no information +will be displayed in the merge request area. That is the case when you add the +`license_management` job in your `.gitlab-ci.yml` for the first time. +Consecutive merge requests will have something to compare to and the license +management report will be shown properly. + + + +If you are a project or group Maintainer, you can click on a license to be given +the choice to approve it or blacklist it. + + + +## Use cases + +It helps you find what licenses your project uses in its dependencies, and decide for each of then +whether to allow it or forbid it. For example, your application is using an external (open source) +library whose license is incompatible with yours. + +## Supported languages and package managers + +The following languages and package managers are supported. + +| Language | Package managers | +|------------|-------------------------------------------------------------------| +| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | +| Go | [Godep](https://github.com/tools/godep), go get | +| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | +| .NET | [Nuget](https://www.nuget.org/) | +| Python | [pip](https://pip.pypa.io/en/stable/) | +| Ruby | [gem](https://rubygems.org/) | + +## Requirements + +To run a License Management scanning job, you need GitLab Runner with the +[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). + +## Configuring License Management + +To enable License Management in your project, define a job in your `.gitlab-ci.yml` +file that generates the [License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate). + +This can be done in two ways: + +- For GitLab 11.9 and later, including the provided License Management `.gitlab-ci.yml` template (recommended). +- Manually specifying the job definition. Not recommended unless using GitLab + 11.8 and earlier. + +### Including the provided template + +NOTE: **Note:** +The CI/CD License Management template is supported on GitLab 11.9 and later versions. +For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). + +A CI/CD [License Management template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml) +with the default License Management job definition is provided as a part of your GitLab +installation which you can [include](../../../ci/yaml/README.md#includetemplate) +in your `.gitlab-ci.yml` file. + +To enable License Management using the provided template, add the following to +your `.gitlab-ci.yml` file: + +```yaml +include: + template: License-Management.gitlab-ci.yml +``` + +The included template will create a `license_management` job in your CI/CD pipeline +and scan your dependencies to find their licenses. + +The report will be saved as a +[License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate) +that you can later download and analyze. Due to implementation limitations, we +always take the latest License Management artifact available. Behind the scenes, the +[GitLab License Management Docker image](https://gitlab.com/gitlab-org/security-products/license-management) +is used to detect the languages/frameworks and in turn analyzes the licenses. + +#### Installing custom dependencies + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. + +The `license_management` image already embeds many auto-detection scripts, languages, +and packages. Nevertheless, it's almost impossible to cover all cases for all projects. +That's why sometimes it's necessary to install extra packages, or to have extra steps +in the project automated setup, like the download and installation of a certificate. +For that, a `LICENSE_MANAGEMENT_SETUP_CMD` environment variable can be passed to the container, +with the required commands to run before the license detection. + +If present, this variable will override the setup step necessary to install all the packages +of your application (e.g.: for a project with a `Gemfile`, the setup step could be +`bundle install`). + +For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +variables: + LICENSE_MANAGEMENT_SETUP_CMD: sh my-custom-install-script.sh +``` + +In this example, `my-custom-install-script.sh` is a shell script at the root +directory of your project. + +#### Overriding the template + +If you want to override the job definition (for example, change properties like +`variables` or `dependencies`), you need to declare a `license_management` job +after the template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +license_management: + variables: + CI_DEBUG_TRACE: "true" +``` + +#### Configuring Maven projects + +The License Management tool provides a `MAVEN_CLI_OPTS` environment variable which can hold +the command line arguments to pass to the `mvn install` command which is executed under the hood. +Feel free to use it for the customization of Maven execution. For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +license_management: + variables: + MAVEN_CLI_OPTS: --debug +``` + +`mvn install` runs through all of the [build life cycle](http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) +stages prior to `install`, including `test`. Running unit tests is not directly +necessary for the license scanning purposes and consumes time, so it's skipped +by having the default value of `MAVEN_CLI_OPTS` as `-DskipTests`. If you want +to supply custom `MAVEN_CLI_OPTS` and skip tests at the same time, don't forget +to explicitly add `-DskipTests` to your options. +If you still need to run tests during `mvn install`, add `-DskipTests=false` to +`MAVEN_CLI_OPTS`. + +### Manual job definition for GitLab 11.5 and later + +For GitLab 11.5 and GitLab Runner 11.5 and later, the following `license_management` +job can be added: + +```yaml +license_management: + image: + name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" + entrypoint: [""] + stage: test + allow_failure: true + script: + - /run.sh analyze . + artifacts: + reports: + license_management: gl-license-management-report.json +``` + +If you want to install custom project dependencies via the `SETUP_CMD` variable: + +```yaml +license_management: + image: + name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" + entrypoint: [""] + stage: test + variables: + SETUP_CMD: ./my-custom-install-script.sh + allow_failure: true + script: + - /run.sh analyze . + artifacts: + reports: + license_management: gl-license-management-report.json +``` + +### Manual job definition for GitLab 11.4 and earlier (deprecated) + +CAUTION: **Caution:** +Before GitLab 11.5, the License Management job and artifact had to be named specifically +to automatically extract the report data and show it in the merge request widget. +While these old job definitions are still maintained, they have been deprecated +and may be removed in the next major release, GitLab 12.0. You are strongly advised +to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the job should look like: + +```yaml +license_management: + image: + name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" + entrypoint: [""] + stage: test + allow_failure: true + script: + - /run.sh analyze . + artifacts: + paths: [gl-license-management-report.json] +``` + +## Project policies for License Management + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5940) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. + +From the project's settings: + +- The list of licenses and their status can be managed. +- Licenses can be manually approved or blacklisted. + +To approve or blacklist a license: + +1. Either use the **Manage licenses** button in the merge request widget, or + navigate to the project's **Settings > CI/CD** and expand the + **License Management** section. +1. Click the **Add a license** button. +1. In the **License name** dropdown, either: + - Select one of the available licenses. You can search for licenses in the field + at the top of the list. + - Enter arbitrary text in the field at the top of the list. This will cause the text to be + added as a license name to the list. +1. Select the **Approve** or **Blacklist** radio button to approve or blacklist respectively + the selected license. + +  + +## License Management report under pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. + +From your project's left sidebar, navigate to **CI/CD > Pipelines** and click on the +pipeline ID that has a `license_management` job to see the Licenses tab with the listed +licenses (if any). + + diff --git a/doc/user/application_security/sast/img/sast.png b/doc/user/application_security/sast/img/sast.png Binary files differnew file mode 100644 index 00000000000..2c75592c32a --- /dev/null +++ b/doc/user/application_security/sast/img/sast.png diff --git a/doc/user/application_security/sast/img/security_report.png b/doc/user/application_security/sast/img/security_report.png Binary files differnew file mode 100644 index 00000000000..ba41b707238 --- /dev/null +++ b/doc/user/application_security/sast/img/security_report.png diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md new file mode 100644 index 00000000000..02c115b7f22 --- /dev/null +++ b/doc/user/application_security/sast/index.md @@ -0,0 +1,254 @@ +# Static Application Security Testing (SAST) **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3775) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. + +NOTE: **4 of the top 6 attacks were application based.** +Download our whitepaper, +["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) +to learn how to protect your organization. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known +vulnerabilities using Static Application Security Testing (SAST). + +You can take advantage of SAST by either [including the CI job](#configuring-sast) in +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto SAST](../../../topics/autodevops/index.md#auto-sast-ultimate) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +GitLab checks the SAST report, compares the found vulnerabilities between the +source and target branches, and shows the information right on the merge request. + + + +The results are sorted by the priority of the vulnerability: + +1. Critical +1. High +1. Medium +1. Low +1. Unknown +1. Everything else + +## Use cases + +- Your code has a potentially dangerous attribute in a class, or unsafe code + that can lead to unintended code execution. +- Your application is vulnerable to cross-site scripting (XSS) attacks that can + be leveraged to unauthorized access to session data. + +## Requirements + +To run a SAST job, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or +[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) +executor running in privileged mode. If you're using the shared Runners on GitLab.com, +this is enabled by default. + +## Supported languages and frameworks + +The following table shows which languages, package managers and frameworks are supported and which tools are used. + +| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | +|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------| +| .NET | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | +| Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11.9 | +| C/C++ | [Flawfinder](https://www.dwheeler.com/flawfinder/) | 10.7 | +| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10 | +| Go | [Gosec](https://github.com/securego/gosec) | 10.7 | +| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | +| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | +| Javascript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | +| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | +| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | +| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/openstack/bandit) | 10.3 | +| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | +| Typescript | [TSLint config security](https://github.com/webschik/tslint-config-security/) | 11.9 | + +NOTE: **Note:** +The Java analyzers can also be used for variants like the +[Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), +[Grails](https://grails.org/) and the [Maven wrapper](https://github.com/takari/maven-wrapper). + +## Configuring SAST + +To enable SAST in your project, define a job in your `.gitlab-ci.yml` file that generates the +[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate). + +This can be done in two ways: + +- For GitLab 11.9 and later, including the provided SAST `.gitlab-ci.yml` template (recommended). +- Manually specifying the job definition. Not recommended unless using GitLab + 11.8 and earlier. + +### Including the provided template + +NOTE: **Note:** +The CI/CD SAST template is supported on GitLab 11.9 and later versions. +For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). + +A CI/CD [SAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) +with the default SAST job definition is provided as a part of your GitLab +installation which you can [include](../../../ci/yaml/README.md#includetemplate) +in your `.gitlab-ci.yml` file. + +To enable SAST using the provided template, add the following to your `.gitlab-ci.yml` +file: + +```yaml +include: + template: SAST.gitlab-ci.yml +``` + +The included template will create a `sast` job in your CI/CD pipeline and scan +your project's source code for possible vulnerabilities. + +The report will be saved as a +[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate) +that you can later download and analyze. Due to implementation limitations, we +always take the latest SAST artifact available. Behind the scenes, the +[GitLab SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) +is used to detect the languages/frameworks and in turn runs the matching scan tools. + +#### Customizing the SAST settings + +The SAST settings can be changed through environment variables by using the +[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. +These variables are documented in the +[SAST tool documentation](https://gitlab.com/gitlab-org/security-products/sast#settings). + +In the following example, we include the SAST template and at the same time we +set the `SAST_GOSEC_LEVEL` variable to `2`: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_GOSEC_LEVEL: 2 +``` + +Because the template is [evaluated before](../../../ci/yaml/README.md#include) +the pipeline configuration, the last mention of the variable will take precedence. + +#### Overriding the SAST template + +If you want to override the job definition (for example, change properties like +`variables` or `dependencies`), you need to declare a `sast` job after the +template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: SAST.gitlab-ci.yml + +sast: + variables: + CI_DEBUG_TRACE: "true" +``` + +### Manual job definition for GitLab 11.5 and later + +For GitLab 11.5 and GitLab Runner 11.5 and later, the following `sast` +job can be added: + +```yaml +sast: + stage: test + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + allow_failure: true + services: + - docker:stable-dind + script: + - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} + - | + docker run \ + --env SAST_ANALYZER_IMAGES \ + --env SAST_ANALYZER_IMAGE_PREFIX \ + --env SAST_ANALYZER_IMAGE_TAG \ + --env SAST_DEFAULT_ANALYZERS \ + --env SAST_EXCLUDED_PATHS \ + --env SAST_BANDIT_EXCLUDED_PATHS \ + --env SAST_BRAKEMAN_LEVEL \ + --env SAST_GOSEC_LEVEL \ + --env SAST_FLAWFINDER_LEVEL \ + --env SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ + --env SAST_PULL_ANALYZER_IMAGE_TIMEOUT \ + --env SAST_RUN_ANALYZER_TIMEOUT \ + --volume "$PWD:/code" \ + --volume /var/run/docker.sock:/var/run/docker.sock \ + "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code + dependencies: [] + artifacts: + reports: + sast: gl-sast-report.json +``` + +You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/sast#settings) +via `docker run --env` to customize your job execution. + +## Manual job definition for GitLab 11.4 and earlier (deprecated) + +CAUTION: **Deprecated:** +Before GitLab 11.5, the SAST job and artifact had to be named specifically +to automatically extract report data and show it in the merge request widget. +While these old job definitions are still maintained, they have been deprecated +and may be removed in the next major release, GitLab 12.0. You are strongly +advised to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the SAST job should look like: + +```yaml +sast: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + allow_failure: true + services: + - docker:stable-dind + script: + - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} + - docker run + --env SAST_CONFIDENCE_LEVEL="${SAST_CONFIDENCE_LEVEL:-3}" + --volume "$PWD:/code" + --volume /var/run/docker.sock:/var/run/docker.sock + "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code + artifacts: + paths: [gl-sast-report.json] +``` + +## Secret detection + +GitLab is also able to detect secrets and credentials that have been unintentionally pushed to the repository. +For example, an API key that allows write access to third-party deployment environments. + +This check is performed by a specific analyzer during the `sast` job. It runs regardless of the programming +language of your app, and you don't need to change anything to your +CI/CD configuration file to turn it on. Results are available in the SAST report. + +GitLab currently includes [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) checks. + +## Security report under pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3776) +in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.6. + +Visit any pipeline page which has a `sast` job and you will be able to see +the security report tab with the listed vulnerabilities (if any). + + + +## Security Dashboard + +The Security Dashboard is a good place to get an overview of all the security +vulnerabilities in your groups and projects. Read more about the +[Security Dashboard](../security_dashboard/index.md). + +## Interacting with the vulnerabilities + +Once a vulnerability is found, you can interact with it. Read more on how to +[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). diff --git a/doc/user/application_security/security_dashboard/img/dashboard.png b/doc/user/application_security/security_dashboard/img/dashboard.png Binary files differnew file mode 100644 index 00000000000..d52a6dacdbf --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/dashboard.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png Binary files differnew file mode 100644 index 00000000000..3294e59e943 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md new file mode 100644 index 00000000000..ca31e15c65f --- /dev/null +++ b/doc/user/application_security/security_dashboard/index.md @@ -0,0 +1,103 @@ +# GitLab Security Dashboard **[ULTIMATE]** + +The Security Dashboard is a good place to get an overview of all the security +vulnerabilities in your groups and projects. + +You can also drill down into a vulnerability and get extra information, see which +project it comes from, the file it's in, and various metadata to help you analyze +the risk. You can also action these vulnerabilities by creating an issue for them, +or by dismissing them. + +To benefit from the Security Dashboard you must first configure one of the +[security reports](../index.md). + +## Supported reports + +The Security Dashboard supports the following reports: + +- [Container Scanning](../container_scanning/index.md) +- [DAST](../dast/index.md) +- [Dependency Scanning](../dependency_scanning/index.md) +- [SAST](../sast/index.md) + +## Requirements + +To use the project or group security dashboard: + +1. At least one project inside a group must be configured with at least one of + the [supported reports](#supported-reports). +2. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports). +3. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. + If you're using the shared Runners on GitLab.com, this is already the case. + +## Project Security Dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.1. + +At the project level, the Security Dashboard displays the latest security reports +for your project. Use it to find and fix vulnerabilities affecting the +[default branch](../../project/repository/branches/index.md#default-branch). + + + +## Group Security Dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6709) in + [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5. + +The group Security Dashboard gives an overview of the vulnerabilities of all the +projects in a group and its subgroups. + +First, navigate to the Security Dashboard found under your group's +**Overview > Security Dashboard**. + +Once you're on the dashboard, at the top you should see a series of filters for: + +- Severity +- Report type +- Project + + + +Selecting one or more filters will filter the results in this page. +The first section is an overview of all the vulnerabilities, grouped by severity. +Underneath this overview is a timeline chart that shows how many open +vulnerabilities your projects had at various points in time. You can filter among 30, 60, and +90 days, with the default being 90. Hover over the chart to get more details about +the open vulnerabilities at a specific time. + +Finally, there is a list of all the vulnerabilities in the group, sorted by severity. +In that list, you can see the severity of the vulnerability, its name, its +confidence (likelihood of the vulnerability to be a positive one), and the project +it's from. + +If you hover over a row, there will appear some actions you can take: + +- "More info" +- "Create issue" +- "Dismiss vulnerability" + +Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). + +## Keeping the dashboards up to date + +The Security Dashboard displays information from the results of the most recent +security scan on the [default branch](../../project/repository/branches/index.md#default-branch), +which means that security scans are performed every time the branch is updated. + +If the default branch is updated infrequently, scans are run infrequently and the +information on the Security Dashboard can become outdated as new vulnerabilities +are discovered. + +To ensure the information on the Security Dashboard is regularly updated, +[configure a scheduled pipeline](../../project/pipelines/schedules.md) to run a +daily security scan. This will update the information displayed on the Security +Dashboard regardless of how often the default branch is updated. + +That way, reports are created even if no code change happens. + +## Security scans using Auto DevOps + +When using [Auto DevOps](../../../topics/autodevops/index.md), use +[special environment variables](../../../topics/autodevops/index.md#environment-variables) +to configure daily security scans. diff --git a/doc/user/discussions/img/mr_review_resolve.png b/doc/user/discussions/img/mr_review_resolve.png Binary files differnew file mode 100644 index 00000000000..34176f3fa8e --- /dev/null +++ b/doc/user/discussions/img/mr_review_resolve.png diff --git a/doc/user/discussions/img/mr_review_resolve2.png b/doc/user/discussions/img/mr_review_resolve2.png Binary files differnew file mode 100644 index 00000000000..e4adb5f2c2d --- /dev/null +++ b/doc/user/discussions/img/mr_review_resolve2.png diff --git a/doc/user/discussions/img/mr_review_second_comment.png b/doc/user/discussions/img/mr_review_second_comment.png Binary files differnew file mode 100644 index 00000000000..920ea05ad66 --- /dev/null +++ b/doc/user/discussions/img/mr_review_second_comment.png diff --git a/doc/user/discussions/img/mr_review_second_comment_added.png b/doc/user/discussions/img/mr_review_second_comment_added.png Binary files differnew file mode 100644 index 00000000000..1fb54348547 --- /dev/null +++ b/doc/user/discussions/img/mr_review_second_comment_added.png diff --git a/doc/user/discussions/img/mr_review_start.png b/doc/user/discussions/img/mr_review_start.png Binary files differnew file mode 100644 index 00000000000..38b44bda0d2 --- /dev/null +++ b/doc/user/discussions/img/mr_review_start.png diff --git a/doc/user/discussions/img/mr_review_unresolve.png b/doc/user/discussions/img/mr_review_unresolve.png Binary files differnew file mode 100644 index 00000000000..da895ceb89f --- /dev/null +++ b/doc/user/discussions/img/mr_review_unresolve.png diff --git a/doc/user/discussions/img/mr_review_unresolve2.png b/doc/user/discussions/img/mr_review_unresolve2.png Binary files differnew file mode 100644 index 00000000000..a824b806e4a --- /dev/null +++ b/doc/user/discussions/img/mr_review_unresolve2.png diff --git a/doc/user/discussions/img/pending_review_comment.png b/doc/user/discussions/img/pending_review_comment.png Binary files differnew file mode 100644 index 00000000000..916ef5b7452 --- /dev/null +++ b/doc/user/discussions/img/pending_review_comment.png diff --git a/doc/user/discussions/img/review_comment_quickactions.png b/doc/user/discussions/img/review_comment_quickactions.png Binary files differnew file mode 100644 index 00000000000..bd9880c329a --- /dev/null +++ b/doc/user/discussions/img/review_comment_quickactions.png diff --git a/doc/user/discussions/img/review_preview.png b/doc/user/discussions/img/review_preview.png Binary files differnew file mode 100644 index 00000000000..4bf53a81b9c --- /dev/null +++ b/doc/user/discussions/img/review_preview.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index c7e8bb5b33b..5d69efc3600 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -5,6 +5,7 @@ The ability to contribute conversationally is offered throughout GitLab. You can leave a comment in the following places: - issues +- epics **[ULTIMATE]** - merge requests - snippets - commits @@ -279,6 +280,75 @@ edit existing comments. Non-team members are restricted from adding or editing c Additionally, locked issues and merge requests can not be reopened. +## Merge Request Reviews **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4213) in GitLab 11.4. + +When looking at a Merge Request diff, you are able to start a review. +This allows you to create comments inside a Merge Request that are **only visible to you** until published, +in order to allow you to submit them all as a single action. + +### Starting a review + +In order to start a review, simply write a comment on a diff as normal under the **Changes** tab +in an MR and click on the **Start a review** button. + + + +Once a review is started, you will see any comments that are part of this review marked `Pending`. +All comments that are part of a review show two buttons: + +- **Submit review**: Submits all comments that are part of the review, making them visible to other users. +- **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. + + + +You can use [quick actions] inside review comments. The comment will show the actions that will be performed once published. + + + +To add more comments to a review, start writing a comment as normal and click the **Add to review** button. + + + +This will add the comment to the review. + + + +### Resolving/Unresolving discussions + +Review comments can also resolve/unresolve [resolvable discussions](#resolvable-comments-and-discussions). +When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve +the discussion once published. + + + + +If a particular pending comment will resolve or unresolve the discussion, this will be shown on the pending +comment itself. + + + + +### Submitting a review + +If you have any comments that have not been submitted, you will see a bar at the +bottom of the screen with two buttons: + +- **Discard**: Discards all comments that have not been submitted. +- **Finish review**: Opens a list of comments ready to be submitted for review. + Clicking **Submit review** will publish all comments. Any quick actions + submitted are performed at this time. + +Alternatively, every pending comment has a button to finish the entire review. + + + +Submitting the review will send a single email to every notifiable user of the +merge request with all the comments associated to it. + +Replying to this email will, consequentially, create a new comment on the associated merge request. + ## Filtering notes > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26723) in GitLab 11.5. @@ -315,11 +385,6 @@ the Merge Request authored by the user that applied them.  - > **Note:** - The suggestion will only affect the commented line. Multi-line - suggestions are currently not supported. Will be introduced by - [#53310](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310). - 1. In the comment, add your suggestion to the pre-populated code block:  @@ -331,13 +396,10 @@ the Merge Request authored by the user that applied them.  - > **Note:** - Discussions are _not_ automatically resolved. Will be introduced by - [#54405](https://gitlab.com/gitlab-org/gitlab-ce/issues/54405). - Once the author applies a suggestion, it will be marked with the **Applied** label, -and GitLab will create a new commit with the message `Apply suggestion to <file-name>` -and push the suggested change directly into the codebase in the merge request's branch. +the discussion will be automatically resolved, and GitLab will create a new commit +with the message `Apply suggestion to <file-name>` and push the suggested change +directly into the codebase in the merge request's branch. [Developer permission](../permissions.md) is required to do so. > **Note:** diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 984881ef26c..53c82169e15 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -28,6 +28,7 @@ deployments. | [Helm Tiller](https://docs.helm.sh) | 11.6+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | n/a | | [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress) | 11.6+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps](../../../topics/autodevops/index.md) or deploy your own web apps. | [stable/nginx-ingress](https://github.com/helm/charts/tree/master/stable/nginx-ingress) | | [Cert-Manager](https://docs.cert-manager.io/en/latest/) | 11.6+ | Cert-Manager is a native Kubernetes certificate management controller that helps with issuing certificates. Installing Cert-Manager on your cluster will issue a certificate by [Let's Encrypt](https://letsencrypt.org/) and ensure that certificates are valid and up-to-date. | [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager) | +| [Prometheus](https://prometheus.io/docs/introduction/overview/) | 11.11+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. | [stable/prometheus](https://github.com/helm/charts/tree/master/stable/prometheus) | | [GitLab Runner](https://docs.gitlab.com/runner/) | 11.10+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](../../../ci/README.md), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](../../project/clusters/index.md#security-implications) before doing so. | [runner/gitlab-runner](https://gitlab.com/charts/gitlab-runner) | NOTE: **Note:** @@ -38,8 +39,6 @@ applications in a group-level cluster is planned for future releases. For update - Support installing [JupyterHub in group-level clusters](https://gitlab.com/gitlab-org/gitlab-ce/issues/51989) -- Support installing [Prometheus in group-level - clusters](https://gitlab.com/gitlab-org/gitlab-ce/issues/51963) ## RBAC compatibility @@ -72,6 +71,29 @@ Add another cluster similar to the first one and make sure to [set an environment scope](#environment-scopes-premium) that will differentiate the new cluster from the rest. +## Gitlab-managed clusters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22011) in GitLab 11.5. +> Became [optional](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26565) in GitLab 11.11. + +NOTE: **Note:** +Only available when creating clusters. Existing clusters not managed by GitLab +cannot become GitLab-managed later. + +You can choose to allow GitLab to manage your cluster for you. If your cluster is +managed by GitLab, resources for your projects will be automatically created. See the +[Access controls](../../project/clusters/index.md#access-controls) section for details on which resources will +be created. + +If you choose to manage your own cluster, project-specific resources will not be created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will +need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](../../project/clusters/index.md#deployment-variables) +that will be used by your deployment jobs. + +NOTE: **Note:** +If you [install applications](#installing-applications) on your cluster, GitLab will create +the resources required to run these even if you have chosen to manage your own cluster. + ## Base domain > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8. @@ -88,7 +110,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the -[environment-specific variables](https://docs.gitlab.com/ee/ci/variables/README.html#limiting-environment-scopes-of-variables-premium) +[environment-specific variables](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-environment-variables-premium) work. While evaluating which environment matches the environment scope of a diff --git a/doc/user/group/contribution_analytics/img/group_stats_cal.png b/doc/user/group/contribution_analytics/img/group_stats_cal.png Binary files differnew file mode 100644 index 00000000000..0238c7bf088 --- /dev/null +++ b/doc/user/group/contribution_analytics/img/group_stats_cal.png diff --git a/doc/user/group/contribution_analytics/img/group_stats_graph.png b/doc/user/group/contribution_analytics/img/group_stats_graph.png Binary files differnew file mode 100644 index 00000000000..ccfd3782c6f --- /dev/null +++ b/doc/user/group/contribution_analytics/img/group_stats_graph.png diff --git a/doc/user/group/contribution_analytics/img/group_stats_table.png b/doc/user/group/contribution_analytics/img/group_stats_table.png Binary files differnew file mode 100644 index 00000000000..f1d1031fa18 --- /dev/null +++ b/doc/user/group/contribution_analytics/img/group_stats_table.png diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md new file mode 100644 index 00000000000..bc88eff9ed2 --- /dev/null +++ b/doc/user/group/contribution_analytics/index.md @@ -0,0 +1,55 @@ +# Contribution Analytics **[STARTER]** + +>**Note:** +Introduced in [GitLab Starter][ee] 8.3. + +Track your team members' activity across your organization. + +## Overview + +With Contribution Analytics you can get an overview of the activity of +issues, merge requests, and push events of your organization and its members. + +The analytics page is located at **Group > Contribution Analytics** +under the URL `/groups/<groupname>/analytics`. + +## Use cases + +- Analyze your team's contributions over a period of time and offer a bonus for the top contributors +- Identify opportunities for improvement with group members who may benefit from additional support + +## Using Contribution Analytics + +There are three main bar graphs that are deducted from the number of +contributions per group member. These contributions include push events, merge +requests and closed issues. Hovering on each bar you can see the number of +events for a specific member. + + + +## Changing the period time + +There are three periods you can choose from, 'Last week', 'Last month' and +'Last three months'. The default is 'Last week'. + +You can choose which period to display by using the dropdown calendar menu in +the upper right corner. + + + +## Sorting by different factors + +Apart from the bar graphs you can also see the contributions per group member +which are depicted in a table that can be sorted by: + +* Member name +* Number of pushed events +* Number of opened issues +* Number of closed issues +* Number of opened MRs +* Number of accepted MRs +* Number of total contributions + + + +[ee]: https://about.gitlab.com/pricing/ diff --git a/doc/user/group/epics/img/button_close_epic.png b/doc/user/group/epics/img/button_close_epic.png Binary files differnew file mode 100644 index 00000000000..aa1a889ea23 --- /dev/null +++ b/doc/user/group/epics/img/button_close_epic.png diff --git a/doc/user/group/epics/img/button_reopen_epic.png b/doc/user/group/epics/img/button_reopen_epic.png Binary files differnew file mode 100644 index 00000000000..7a953189270 --- /dev/null +++ b/doc/user/group/epics/img/button_reopen_epic.png diff --git a/doc/user/group/epics/img/child_epics_roadmap.png b/doc/user/group/epics/img/child_epics_roadmap.png Binary files differnew file mode 100644 index 00000000000..819fed58989 --- /dev/null +++ b/doc/user/group/epics/img/child_epics_roadmap.png diff --git a/doc/user/group/epics/img/containing_epic.png b/doc/user/group/epics/img/containing_epic.png Binary files differnew file mode 100644 index 00000000000..5ed693e6d6a --- /dev/null +++ b/doc/user/group/epics/img/containing_epic.png diff --git a/doc/user/group/epics/img/epic_view.png b/doc/user/group/epics/img/epic_view.png Binary files differnew file mode 100644 index 00000000000..dbda98e4351 --- /dev/null +++ b/doc/user/group/epics/img/epic_view.png diff --git a/doc/user/group/epics/img/epics_list_view.png b/doc/user/group/epics/img/epics_list_view.png Binary files differnew file mode 100644 index 00000000000..b30608d9d31 --- /dev/null +++ b/doc/user/group/epics/img/epics_list_view.png diff --git a/doc/user/group/epics/img/epics_search.png b/doc/user/group/epics/img/epics_search.png Binary files differnew file mode 100644 index 00000000000..96335527468 --- /dev/null +++ b/doc/user/group/epics/img/epics_search.png diff --git a/doc/user/group/epics/img/epics_sort.png b/doc/user/group/epics/img/epics_sort.png Binary files differnew file mode 100644 index 00000000000..b23c65fd0ef --- /dev/null +++ b/doc/user/group/epics/img/epics_sort.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md new file mode 100644 index 00000000000..6035f0c7326 --- /dev/null +++ b/doc/user/group/epics/index.md @@ -0,0 +1,217 @@ +# Epics **[ULTIMATE]** + +> Introduced in [GitLab Ultimate][ee] 10.2. + +Epics let you manage your portfolio of projects more efficiently and with less +effort by tracking groups of issues that share a theme, across projects and +milestones. + + + +## Use cases + +- Suppose your team is working on a large feature that involves multiple discussions throughout different issues created in distinct projects within a [Group](../index.md). With Epics, you can track all the related activities that together contribute to that single feature. +- Track when the work for the group of issues is targeted to begin, and when it is targeted to end. +- Discuss and collaborate on feature ideas and scope at a high-level. + +## Creating an epic + +A paginated list of epics is available in each group from where you can create +a new epic. The list of epics includes also epics from all subgroups of the +selected group. From your group page: + +1. Go to **Epics** +1. Click the **New epic** button at the top right +1. Enter a descriptive title and hit **Create epic** + +Once created, you will be taken to the view for that newly-created epic where +you can change its title, description, start date, and due date. + + + +## Adding an issue to an epic + +An epic contains a list of issues and an issue can be associated with at most +one epic. When on an epic, you can add its associated issues: + +1. Click the plus icon (<kbd>+</kbd>) under the epic description. +1. Paste the link of the issue (you can hit <kbd>Spacebar</kbd> to add more than + one issues at a time). +1. Click **Add**. + +Any issue belonging to a project in the epic's group or any of the epic's +subgroups are eligible to be added. To remove an issue from an epic, click +on the <kbd>x</kbd> button in the epic's issue list. + +NOTE: **Note:** +When you add an issue or an epic to an epic that's already associated with another epic, +the issue or the epic is automatically removed from the previous epic. + +## Multi-level child epics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8333) in GitLab Ultimate 11.7. + +Much like adding issues to an epic, an epic can have multiple child epics with +the maximum depth being 5. To add a child epic: + +1. Click the plus icon (<kbd>+</kbd>) under the epic description. +1. Paste the link of the epic. +1. Click **Add**. + +Any epic that belongs to a group or subgroup of the parent epic's group is +eligible to be added. To remove a child epic from a parent epic, +click on the <kbd>x</kbd> button in the parent epic's epic list. + +## Start date and due date + +For each of the dates in the sidebar of an epic, you can choose to either: + +- Enter a fixed value. +- Inherit a dynamic value called "From milestones". + +If you select "From milestones" for the start date, GitLab will automatically set the +date to be earliest start date across all milestones that are currently assigned +to the issues that are attached to the epic. Similarly, if you select "From milestones" +for the due date, GitLab will set it to be the latest due date across all +milestones that are currently assigned to those issues. + +These are dynamic dates in that if milestones are re-assigned to the issues, if the +milestone dates change, or if issues are added or removed from the epic, then +the re-calculation will happen immediately to set a new dynamic date. + +## Roadmap in epics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.10. + +If your epic contains one or more [child epics](#multi-level-child-epics) which +have a [start or due date](#start-date-and-due-date), then you can see a +[roadmap](../roadmap/index.md) view of the child epics under the parent epic itself. + + + +## Reordering issues and child epics + +Drag and drop to reorder issues and child epics. New issues and child epics added to an epic appear at the top of the list. + +## Deleting an epic + +NOTE: **Note:** +To delete an epic, you need to be an [Owner][permissions] of a group/subgroup. + +When inside a single epic view, click the **Delete** button to delete the epic. +A modal will pop-up to confirm your action. + +Deleting an epic releases all existing issues from their associated epic in the +system. + +## Closing and reopening epics + +### Using buttons + +Whenever you decide that there is no longer need for that epic, +close the epic using the close button: + + + +You can always reopen it using the reopen button. + + + +### Using quick actions + +You can close or reopen an epic using [Quick actions](../../project/quick_actions.md) + +## Navigating to an epic from an issue + +If an issue belongs to an epic, you can navigate to the containing epic with the +link in the issue sidebar. + + + +## Promoting an issue to an epic + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. + +If you have [permissions](../../permissions.md) to close an issue and create an +epic in the parent group, you can promote an issue to an epic with the `/promote` +[quick action](../../project/quick_actions.md#quick-actions-for-epics-ultimate). +Only issues from projects that are in groups can be promoted. + +When the quick action is executed: + +- An epic is created in the same group as the project of the issue. +- Subscribers of the issue are notified that the epic was created. + +The following issue metadata will be copied to the epic: + +- Title, description, activity/comment thread. +- Upvotes/downvotes. +- Participants. +- Group labels that the issue already has. + +## Searching for an epic from epics list page + +> Introduced in [GitLab Ultimate][ee] 10.5. + +You can search for an epic from the list of epics using filtered search bar (similar to +that of Issues and Merge requests) based on following parameters: + +- Title or description +- Author name / username +- Labels + + + +To search, go to the list of epics and click on the field **Search or filter results...**. +It will display a dropdown menu, from which you can add an author. You can also enter plain +text to search by epic title or description. When done, press <kbd>Enter</kbd> on your +keyboard to filter the list. + +You can also sort epics list by: + +- **Created date** +- **Last updated** +- **Start date** +- **Due date** + +Each option contains a button that can toggle the order between **ascending** and **descending**. The sort option and order will be persisted to be used wherever epics are browsed including the [roadmap](../roadmap/index.md). + + + +## Permissions + +If you have access to view an epic and have access to view an issue already +added to that epic, then you can view the issue in the epic issue list. + +If you have access to edit an epic and have access to edit an issue, then you +can add the issue to or remove it from the epic. + +Note that for a given group, the visibility of all projects must be the same as +the group, or less restrictive. That means if you have access to a group's epic, +then you already have access to its projects' issues. + +You may also consult the [group permissions table][permissions]. + +[ee]: https://about.gitlab.com/pricing/ +[permissions]: ../../permissions.md#group-members-permissions + +## Thread + +- Comments: collaborate on that epic by posting comments in its thread. +These text fields also fully support +[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + +## Comment, or start a discussion + +Once you wrote your comment, you can either: + +- Click "Comment" and your comment will be published. +- Click "Start discussion": start a thread within that epic's thread to discuss specific points. + +## Award emoji + +- You can [award an emoji](../../award_emojis.md) to that epic or its comments. + +## Notifications + +- [Receive notifications](../../../workflow/notifications.md) for epic events. diff --git a/doc/user/group/img/group_file_template_dropdown.png b/doc/user/group/img/group_file_template_dropdown.png Binary files differnew file mode 100644 index 00000000000..d9caae1a223 --- /dev/null +++ b/doc/user/group/img/group_file_template_dropdown.png diff --git a/doc/user/group/img/group_file_template_settings.png b/doc/user/group/img/group_file_template_settings.png Binary files differnew file mode 100644 index 00000000000..ca42f7726db --- /dev/null +++ b/doc/user/group/img/group_file_template_settings.png diff --git a/doc/user/group/img/group_issue_board.png b/doc/user/group/img/group_issue_board.png Binary files differnew file mode 100644 index 00000000000..a0da74a320f --- /dev/null +++ b/doc/user/group/img/group_issue_board.png diff --git a/doc/user/group/img/member_lock.png b/doc/user/group/img/member_lock.png Binary files differnew file mode 100644 index 00000000000..3f1382e76c6 --- /dev/null +++ b/doc/user/group/img/member_lock.png diff --git a/doc/user/group/img/membership_lock.png b/doc/user/group/img/membership_lock.png Binary files differdeleted file mode 100644 index c9ad82c90f2..00000000000 --- a/doc/user/group/img/membership_lock.png +++ /dev/null diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 2d887673fd6..06564fd6cd1 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -5,10 +5,12 @@ and grant members access to several projects at once. Groups can also be nested in [subgroups](subgroups/index.md). -Find your groups by expanding the left menu and clicking **Groups**: +Find your groups by clicking **Groups** in the top navigation.  +> The groups dropdown in the top navigation was [introduced][ce-36234] in [GitLab 11.1](https://about.gitlab.com/2018/07/22/gitlab-11-1-released/#groups-dropdown-in-navigation). + The Groups page displays all groups you are a member of, how many projects it holds, how many members it has, the group visibility, and, if you have enough permissions, a link to the group settings. By clicking the last button you can leave that group. @@ -44,7 +46,7 @@ For example, consider a user named Alex: 1. Alex creates an account on GitLab.com with the username `alex`; their profile will be accessed under `https://gitlab.example.com/alex` -1. Alex creates a group for their team with the groupname `alex-team`; +1. Alex creates a group for their team with the group name `alex-team`; the group and its projects will be accessed under `https://gitlab.example.com/alex-team` 1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`; this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing` @@ -160,6 +162,10 @@ There are two different ways to add a new project to a group: ### Default project creation level +> [Introduced][ee-2534] in [GitLab Premium][ee] 10.5. +> Brought to [GitLab Starter][ee] in 10.7. +> [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25975) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. + Group owners or administrators can allow users with the Developer role to create projects under groups. @@ -185,6 +191,32 @@ Alternatively, you can [lock the sharing with group feature](#share-with-group-l In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups. See [the GitLab Enterprise Edition documentation](../../integration/ldap.md) for more information. +## Epics **[ULTIMATE]** + +> Introduced in [GitLab Ultimate][ee] 10.2. + +Epics let you manage your portfolio of projects more efficiently and with less +effort by tracking groups of issues that share a theme, across projects and +milestones. + +[Learn more about Epics.](epics/index.md) + +## Group Security Dashboard **[ULTIMATE]** + +Get an overview of the vulnerabilities of all the projects in a group and its subgroups. + +[Learn more about the Group Security Dashboard.](security_dashboard/index.md) + +## Insights **[ULTIMATE]** + +> Introduced in [GitLab Ultimate][ee] 11.9 behind the `insights` feature flag. + +Configure the Insights that matter for your groups or 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. + +[Learn more about Insights](insights/index.md). + ## Transferring groups From GitLab 10.5, groups can be transferred in the following ways: @@ -257,7 +289,7 @@ working together in a project. To inherit the group membership, you share the project between the two groups A and B. **Share with group lock** prevents any project within the group from being shared with another group. By doing so, you -guarantee only the right group members have access to that projects. +guarantee only the right group members have access to those projects. To enable this feature, navigate to the group settings page. Select **Share with group lock** and **Save the group**. @@ -266,17 +298,50 @@ To enable this feature, navigate to the group settings page. Select #### Member Lock **[STARTER]** -With **Member Lock** it is possible to lock membership in project to the -level of members in group. +With Member lock, it is possible to lock membership in a project to the +level of members in the group. + +Member lock lets a group owner lock down any new project membership to all the +projects within the group, allowing tighter control over project membership. -Learn more about [Member Lock](https://docs.gitlab.com/ee/user/group/index.html#member-lock). +For instance, if you want to lock the group for an [Audit Event](https://docs.gitlab.com/ee/administration/audit_events.html), +you enable Member lock to guarantee that membership of a project cannot be modified during that audit. -#### Group-level file templates **[PREMIUM]** +To enable this feature: -Group-level file templates allow you to share a set of templates for common file -types with every project in a group. +1. Navigate to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section and select **Member lock**. +1. Click the **Save changes** button. -Learn more about [Group-level file templates](https://docs.gitlab.com/ee/user/group/index.html#group-level-file-templates-premium). + + +This will disable the option for all users who previously had permissions to +operate project memberships so no new users can be added. Furthermore, any +request to add a new user to a project through API will not be possible. + +#### Group file templates **[PREMIUM]** + +Group file templates allow you to share a set of templates for common file +types with every project in a group. It is analogous to the +[instance template repository](https://docs.gitlab.com/ee/user/admin_area/settings/instance_template_repository.html) +feature, and the selected project should follow the same naming conventions as +are documented on that page. + +Only projects that are in the group may be chosen as the source of templates. +This includes projects shared with the group, but **excludes** projects in +subgroups or parent groups of the group being configured. + +This feature may be configured for subgroups as well as parent groups. A project +in a subgroup will have access to the templates for that subgroup, as well as +any parent groups. + + + +To enable this feature, navigate to the group settings page, expand the +**Templates** section, choose a project to act as the template repository, and +**Save group**. + + #### Group-level project templates **[PREMIUM]** @@ -289,6 +354,19 @@ Define project templates at a group-level by setting a group as a template sourc access each project's settings, and remove any project from the same screen. - **Webhooks**: configure [webhooks](../project/integrations/webhooks.md) to your group. - **Kubernetes cluster integration**: connect your GitLab group with [Kubernetes clusters](clusters/index.md). -- **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html#audit-events) +- **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html) for the group. **[STARTER ONLY]** - **Pipelines quota**: keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. + +## User contribution analysis **[STARTER]** + +With [GitLab Contribution Analytics](contribution_analytics/index.md) +you have an overview of the contributions (pushes, merge requests, +and issues) performed by your group members. + +## Issues analytics **[PREMIUM]** + +With [GitLab Issues Analytics](issues_analytics/index.md), in groups, you can see a bar chart of the number of issues created each month. + +[ee]: https://about.gitlab.com/pricing/ +[ee-2534]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2534 diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png Binary files differnew file mode 100644 index 00000000000..791d0e4bcdf --- /dev/null +++ b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png diff --git a/doc/user/group/insights/img/insights_group_configuration.png b/doc/user/group/insights/img/insights_group_configuration.png Binary files differnew file mode 100644 index 00000000000..0af0073e448 --- /dev/null +++ b/doc/user/group/insights/img/insights_group_configuration.png diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md new file mode 100644 index 00000000000..5283d8da77d --- /dev/null +++ b/doc/user/group/insights/index.md @@ -0,0 +1,39 @@ +# 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 groups 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. + + + +## Configure your Insights + +Navigate to your group's **Settings > General**, expand **Insights**, and choose +the project that holds your `.gitlab/insights.yml` configuration file: + + + +If no configuration was set, a [default configuration file]( +https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/fixtures/insights/ee/fixtures/insights/default.yml) +will be used. + +See the [Project's Insights documentation](https://docs.gitlab.com/ee/user/project/insights/index.html) for +more details about the `.gitlab/insights.yml` configuration file. + +## Permissions + +If you have access to view a group, 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). diff --git a/doc/user/group/issues_analytics/img/issues_created_per_month.png b/doc/user/group/issues_analytics/img/issues_created_per_month.png Binary files differnew file mode 100644 index 00000000000..96f0d36c917 --- /dev/null +++ b/doc/user/group/issues_analytics/img/issues_created_per_month.png diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md new file mode 100644 index 00000000000..cf53d7423a6 --- /dev/null +++ b/doc/user/group/issues_analytics/index.md @@ -0,0 +1,16 @@ +# Issues Analytics **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. + +GitLab by default displays a bar chart of the number of issues created each month, for the +current month, and 12 months prior, for a total of 13 months. + +You can change the total number of months displayed by setting a URL parameter. +For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` +would show a total of 15 months for the chart in the GitLab.org group. + +The **Search or filter results...** field can be used for filtering the issues by any attribute. For example, labels, assignee, milestone, and author. + +To access the chart, navigate to a group's sidebar and select **Issues > Analytics**. + + diff --git a/doc/user/group/roadmap/img/epics_state_dropdown.png b/doc/user/group/roadmap/img/epics_state_dropdown.png Binary files differnew file mode 100644 index 00000000000..cbcc3658a54 --- /dev/null +++ b/doc/user/group/roadmap/img/epics_state_dropdown.png diff --git a/doc/user/group/roadmap/img/roadmap_timeline_months.png b/doc/user/group/roadmap/img/roadmap_timeline_months.png Binary files differnew file mode 100644 index 00000000000..5a046b21507 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_timeline_months.png diff --git a/doc/user/group/roadmap/img/roadmap_timeline_quarters.png b/doc/user/group/roadmap/img/roadmap_timeline_quarters.png Binary files differnew file mode 100644 index 00000000000..56f428cb471 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_timeline_quarters.png diff --git a/doc/user/group/roadmap/img/roadmap_timeline_weeks.png b/doc/user/group/roadmap/img/roadmap_timeline_weeks.png Binary files differnew file mode 100644 index 00000000000..bf4c1dc0284 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_timeline_weeks.png diff --git a/doc/user/group/roadmap/img/roadmap_view.png b/doc/user/group/roadmap/img/roadmap_view.png Binary files differnew file mode 100644 index 00000000000..ff41a2e0441 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_view.png diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md new file mode 100644 index 00000000000..310c4bb88d0 --- /dev/null +++ b/doc/user/group/roadmap/index.md @@ -0,0 +1,64 @@ +# Roadmap **[ULTIMATE]** + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.5. + +An Epic within a group containing **Start date** and/or **Due date** +can be visualized in a form of a timeline (e.g. a Gantt chart). The Epics Roadmap page +shows such a visualization for all the epics which are under a group and/or its subgroups. + + + +A dropdown allows you to show only open or closed epics. By default, all epics are shown. + + + +Epics in the view can be sorted by: + +- **Created date** +- **Last updated** +- **Start date** +- **Due date** + +Each option contains a button that can toggle the order between **ascending** and **descending**. The sort option and order will be persisted to be used wherever epics are browsed including the [epics list view](../epics/index.md). + +Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). + +## Timeline duration + +Starting with [GitLab Ultimate][ee] 11.0, Roadmap supports three different date ranges; Quarters, Months (Default) and Weeks. + +### Quarters + + + +In _Quarters_ preset, roadmap shows epics which have start or due dates _falling within_ or +_going through_ **past quarter**, **current quarter** and **next 4 quarters**, where _today_ +is shown by the vertical red line in the timeline. The sub-headers underneath the quarter name on +the timeline header represent the month of the quarter. + +### Months + + + +In _Months_ preset, roadmap shows epics which have start or due dates _falling within_ or +_going through_ **past month**, **current month** and **next 5 months**, where _today_ +is shown by the vertical red line in the timeline. The sub-headers underneath the month name on +the timeline header represent the date on starting day (Sunday) of the week. This preset is +selected by default. + +### Weeks + + + +In _Weeks_ preset, roadmap shows epics which have start or due dates _falling within_ or +_going through_ **past week**, **current week** and **next 4 weeks**, where _today_ +is shown by the vertical red line in the timeline. The sub-headers underneath the week name on +the timeline header represent the days of the week. + +## Timeline bar for an epic + +The timeline bar indicates the approximate position of an epic based on its start +and due date. If an epic doesn't have a due date, the timeline bar fades +away towards the future. Similarly, if an epic doesn't have a start date, the +timeline bar becomes more visible as it approaches the epic's due date on the +timeline. diff --git a/doc/user/group/saml_sso/img/group_saml_configuration_information.png b/doc/user/group/saml_sso/img/group_saml_configuration_information.png Binary files differnew file mode 100644 index 00000000000..98b83d0cb0f --- /dev/null +++ b/doc/user/group/saml_sso/img/group_saml_configuration_information.png diff --git a/doc/user/group/saml_sso/img/group_saml_settings.png b/doc/user/group/saml_sso/img/group_saml_settings.png Binary files differnew file mode 100644 index 00000000000..d95acb5075f --- /dev/null +++ b/doc/user/group/saml_sso/img/group_saml_settings.png diff --git a/doc/user/group/saml_sso/img/scim_advanced.png b/doc/user/group/saml_sso/img/scim_advanced.png Binary files differnew file mode 100644 index 00000000000..3b70e3fbe83 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_advanced.png diff --git a/doc/user/group/saml_sso/img/scim_attribute_mapping.png b/doc/user/group/saml_sso/img/scim_attribute_mapping.png Binary files differnew file mode 100644 index 00000000000..c9f6b71f5b0 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_attribute_mapping.png diff --git a/doc/user/group/saml_sso/img/scim_token.png b/doc/user/group/saml_sso/img/scim_token.png Binary files differnew file mode 100644 index 00000000000..7eb52bf6ea2 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_token.png diff --git a/doc/user/group/saml_sso/img/unlink_group_saml.png b/doc/user/group/saml_sso/img/unlink_group_saml.png Binary files differnew file mode 100644 index 00000000000..0561443b5f4 --- /dev/null +++ b/doc/user/group/saml_sso/img/unlink_group_saml.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md new file mode 100644 index 00000000000..ee3137d032e --- /dev/null +++ b/doc/user/group/saml_sso/index.md @@ -0,0 +1,91 @@ +# SAML SSO for GitLab.com Groups **[SILVER ONLY]** + +> Introduced in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.0. + +NOTE: **Note:** +This topic is for SAML on GitLab.com Silver tier and above. For SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md). + +Currently SAML on GitLab.com can be used to automatically add users to a group, and does not yet sign users into GitLab.com. Users should already have an account on the GitLab instance, or can create one when logging in for the first time. + +User synchronization for GitLab.com is partially supported using [SCIM](scim_setup.md). + +NOTE: **Note:** +SAML SSO for groups is used only as a convenient way to add users and does not sync users between providers without using SCIM. If a group is not using SCIM, group Owners will still need to manage user accounts, such as removing users when necessary. + +## Configuring your Identity Provider + +1. Navigate to the group and click **Settings > SAML SSO**. +1. Configure your SAML server using the **Assertion consumer service URL** and **Issuer**. See [your identity provider's documentation](#providers) for more details. +1. Configure the SAML response to include a NameID that uniquely identifies each user. +1. Configure required assertions using the [table below](#assertions). +1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab). + + + +NOTE: **Note:** +Partial SSO enforcement was introduced in [11.8](https://gitlab.com/gitlab-org/gitlab-ee/issues/5291). With this option enabled, users must use your group's GitLab single sign on URL to be added to the group or be added via SCIM. Users can no longer be added manually. After a user has been added to the group, GitLab does not continue to enforce the use of SSO, but we'll [add a persistent check](https://gitlab.com/gitlab-org/gitlab-ee/issues/9255) in a later version. + +### NameID + +GitLab.com uses the SAML NameID to identify users. The NameID element: + +- Is a required field in the SAML response. +- Must be unique to each user. +- Must be a persistent value that will never change, such as a unique ID or username. Email could also be used as the NameID, but only if it can be guaranteed to never change. + +### Assertions + +| Field | Supported keys | Notes | +|-|----------------|-------------| +| Email | `email`, `mail` | (required) | +| Full Name | `name` | | +| First Name | `first_name`, `firstname`, `firstName` | | +| Last Name | `last_name`, `lastname`, `lastName` | | + +## Configuring GitLab + +Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication: + +1. Navigate to the group's **Settings > SAML SSO**. +1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign on URL** field. +1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. +1. Check the **Enable SAML authentication for this group** checkbox. +1. Click the **Save changes** button. + + + +## Providers + +| Provider | Documentation | +|----------|---------------| +| ADFS (Active Directory Federation Services) | [Create a Relying Party Trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) | +| Azure | [Configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/active-directory-saas-custom-apps) | +| Auth0 | [Auth0 as Identity Provider](https://auth0.com/docs/protocols/saml/saml-idp-generic) | +| G Suite | [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en) | +| JumpCloud | [Single Sign On (SSO) with GitLab](https://support.jumpcloud.com/customer/en/portal/articles/2810701-single-sign-on-sso-with-gitlab) | +| Okta | [Setting up a SAML application in Okta](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) | +| OneLogin | [Use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) | +| Ping Identity | [Add and configure a new SAML application](https://docs.pingidentity.com/bundle/p1_enterpriseConfigSsoSaml_cas/page/enableAppWithoutURL.html) | + +## Unlinking accounts + +Users can unlink SAML for a group from their profile page. This can be helpful if: + +- You no longer want a group to be able to sign you in to GitLab.com. +- Your SAML NameID has changed and so GitLab can no longer find your user. + +For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**: + + + +## Glossary + +| Term | Description | +|------|-------------| +| Identity Provider | The service which manages your user identities such as ADFS, Okta, Onelogin or Ping Identity. | +| Service Provider | SAML considers GitLab to be a service provider. | +| Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | +| SSO | Single Sign On. | +| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | +| Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md new file mode 100644 index 00000000000..ec27ec3e336 --- /dev/null +++ b/doc/user/group/saml_sso/scim_setup.md @@ -0,0 +1,102 @@ +# SCIM provisioning using SAML SSO for Groups **[SILVER ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. + +GitLab's [SCIM API](https://docs.gitlab.com/ee/api/scim.html) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). + +Currently, the following actions are available: + +- CREATE +- UPDATE +- DELETE (deprovisioning) + +The following identity providers are supported: + +- Azure + +## Requirements + +- [Group SSO](index.md) needs to be configured. +- The `scim_group` feature flag must be enabled: + + Run the following commands in a Rails console: + + ```sh + # Omnibus GitLab + gitlab-rails console + + # Installation from source + cd /home/git/gitlab + sudo -u git -H bin/rails console RAILS_ENV=production + ``` + + To enable SCIM for a group named `group_name`: + + ```ruby + group = Group.find_by_full_path('group_name') + Feature.enable(:group_scim, group) + ``` + +### GitLab configuration + +Once [Single sign-on](index.md) has been configured, we can: + +1. Navigate to the group and click **Settings > SAML SSO**. +1. Click on the **Generate a SCIM token** button. +1. Save the token and URL so they can be used in the next step. + + + +## SCIM IdP configuration + +### Configuration on Azure + +In the [Single sign-on](index.md) configuration for the group, make sure +that the **Name identifier value** (NameID) points to a unique identifier, such +as the `user.objectid`. This will match the `extern_uid` used on GitLab. + +The GitLab app in Azure needs to be configured following +[Azure's SCIM setup](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#getting-started). + +Note the following: + +- The `Tenant URL` and `secret token` are the ones retrieved in the +[previous step](#gitlab-configuration). +- Should there be any problems with the availability of GitLab or similar +errors, the notification email set will get those. +- For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled. + +You can then test the connection clicking on `Test Connection`. + +### Synchronize Azure Active Directory users + +1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure +the attribute mapping. +1. Select the unique identifier (in the example `objectId`) as the `id` and `externalId`, +and enable the `Create`, `Update`, and `Delete` actions. +1. Map the `userPricipalName` to `emails[type eq "work"].value` and `mailNickname` to +`userName`. + + Example configuration: + +  + +1. Click on **Show advanced options > Edit attribute list for AppName**. +1. Leave the `id` as the primary and only required field. + + NOTE: **Note:** + `username` should neither be primary nor required as we don't support + that field on GitLab SCIM yet. + +  + +1. Save all the screens and, in the **Provisioning** step, set +the `Provisioning Status` to `ON`. + + NOTE: **Note:** + You can control what is actually synced by selecting the `Scope`. For example, + `Sync only assigned users and groups` will only sync the users assigned to + the application (`Users and groups`), otherwise it will sync the whole Active Directory. + +Once enabled, the synchronization details and any errors will appear on the +bottom of the **Provisioning** screen, together with a link to the audit logs. diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md new file mode 100644 index 00000000000..43e910b29fe --- /dev/null +++ b/doc/user/group/security_dashboard/index.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html). diff --git a/doc/user/index.md b/doc/user/index.md index 8164b31c37e..67d5cbf06ec 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -51,19 +51,20 @@ With GitLab Enterprise Edition, you can also: - Provide support with [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html). - Improve collaboration with - [Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/index.html#merge-request-approvals), + [Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/index.html#merge-request-approvals-starter), [Multiple Assignees for Issues](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html), and [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards-starter). - Create formal relationships between issues with [Related Issues](https://docs.gitlab.com/ee/user/project/issues/related_issues.html). - Use [Burndown Charts](https://docs.gitlab.com/ee/user/project/milestones/burndown_charts.html) to track progress during a sprint or while working on a new version of their software. -- Leverage [Elasticsearch](https://docs.gitlab.com/ee/integration/elasticsearch.html) with [Advanced Global Search](https://docs.gitlab.com/ee/user/search/advanced_global_search.html) and [Advanced Syntax Search](https://docs.gitlab.com/ee/user/search/advanced_search_syntax.html) for faster, more advanced code search across your entire GitLab instance. +- Leverage [Elasticsearch](https://docs.gitlab.com/ee/integration/elasticsearch.html) with [Advanced Global Search](search/advanced_global_search.md) and [Advanced Syntax Search](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance. - [Authenticate users with Kerberos](https://docs.gitlab.com/ee/integration/kerberos.html). -- [Mirror a repository](https://docs.gitlab.com/ee/workflow/repository_mirroring.html) from elsewhere on your local server. +- [Mirror a repository](../workflow/repository_mirroring.md) from elsewhere on your local server. - [Export issues as CSV](https://docs.gitlab.com/ee/user/project/issues/csv_export.html). - View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html). - [Lock files](https://docs.gitlab.com/ee/user/project/file_lock.html) to prevent conflicts. - View the current health and status of each CI environment running on Kubernetes with [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html). - Leverage continuous delivery method with [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html). +- Scan your code for vulnerabilities and [display them in merge requests](https://docs.gitlab.com/ee/user/application_security/sast/index.html). You can also [integrate](project/integrations/project_services.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, JIRA, and a lot more. @@ -106,8 +107,8 @@ to enjoy the best of GitLab. - [Permissions](permissions.md): Learn the different set of permissions levels for each user type (guest, reporter, developer, maintainer, owner). - [Feature highlight](feature_highlight.md): Learn more about the little blue dots - around the app that explain certain features -- [Abuse reports](abuse_reports.md): Report abuse from users to GitLab administrators + around the app that explain certain features. +- [Abuse reports](abuse_reports.md): Report abuse from users to GitLab administrators. ## Groups @@ -171,3 +172,8 @@ Learn what is [Git](../topics/git/index.md) and its best practices. ## Instance statistics See [various statistics](instance_statistics/index.md) of your GitLab instance. + +## Operations Dashboard **[PREMIUM]** + +See [Operations Dashboard](operations_dashboard/index.md) for a summary of each +project's operational health. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 9891a43aa61..c1c2c036bae 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -20,6 +20,7 @@ You can use GFM in the following areas: - Snippets (the snippet must be named with a `.md` extension) - Wiki pages - Markdown documents inside repositories +- Epics **[ULTIMATE]** You can also use other rich text files in GitLab. You might have to install a dependency to do so. Please see the [`github-markup` gem readme](https://github.com/gitlabhq/markup#markups) for more information. @@ -320,6 +321,7 @@ GFM will recognize the following: | `#12345` | issue | | `!123` | merge request | | `$123` | snippet | +| `&123` | epic **[ULTIMATE]** | | `~123` | label by ID | | `~bug` | one-word label by name | | `~"feature request"` | multi-word label by name | @@ -340,6 +342,7 @@ GFM also recognizes certain cross-project references: | `namespace/project%123` | project milestone | | `namespace/project$123` | snippet | | `namespace/project@9ba12248` | specific commit | +| `group1/subgroup&123` | epic **[ULTIMATE]** | | `namespace/project@9ba12248...b19a04f5` | commit range comparison | | `namespace/project~"Some label"` | issues with given label | diff --git a/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png b/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png Binary files differnew file mode 100644 index 00000000000..9d6a509ea72 --- /dev/null +++ b/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png diff --git a/doc/user/operations_dashboard/img/index_operations_dashboard_with_projects.png b/doc/user/operations_dashboard/img/index_operations_dashboard_with_projects.png Binary files differnew file mode 100644 index 00000000000..ee33eee8134 --- /dev/null +++ b/doc/user/operations_dashboard/img/index_operations_dashboard_with_projects.png diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md new file mode 100644 index 00000000000..66362f27299 --- /dev/null +++ b/doc/user/operations_dashboard/index.md @@ -0,0 +1,37 @@ +# Operations Dashboard **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5781) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. +[Moved](https://gitlab.com/gitlab-org/gitlab-ee/issues/9218) to +[GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. + +The Operations Dashboard provides a summary of each project's operational health, +including pipeline and alert status. + +The dashboard can be accessed via the top bar, by clicking on the new +dashboard icon: + + + +## Adding a project to the dashboard + +NOTE: **Note:** +For GitLab.com, the Operations Dashboard is available for free for public projects. +If your project is private, the group it belongs to must have a +[Gold](https://about.gitlab.com/pricing/) plan. + +To add a project to the dashboard: + +1. Click the **Add projects** button in the homescreen of the dashboard. +1. Search and add one or more projects using the **Search your projects** field. +1. Click the **Add projects** button. + +Once added, the dashboard will display the project's number of active alerts, +last commit, pipeline status, and when it was last deployed. + + + +## Making it the default dashboard when you sign in + +The Operations Dashboard can also be made the default GitLab dashboard shown when +you sign in. To make it the default, visit your [profile preferences](../profile/preferences.md). diff --git a/doc/user/permissions.md b/doc/user/permissions.md index a340dd063e4..9b298e4eb30 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -42,8 +42,7 @@ The following table depicts the various user permission levels in a project. | Create confidential issue | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | | View confidential issues | (✓) [^2] | ✓ | ✓ | ✓ | ✓ | | Leave comments | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | -| Lock issue discussions | | ✓ | ✓ | ✓ | ✓ | -| Lock merge request discussions | | | ✓ | ✓ | ✓ | +| See related issues | ✓ | ✓ | ✓ | ✓ | ✓ | | See a list of jobs | ✓ [^3] | ✓ | ✓ | ✓ | ✓ | | See a job log | ✓ [^3] | ✓ | ✓ | ✓ | ✓ | | Download and browse job artifacts | ✓ [^3] | ✓ | ✓ | ✓ | ✓ | @@ -87,11 +86,12 @@ The following table depicts the various user permission levels in a project. | Update a container registry | | | ✓ | ✓ | ✓ | | Remove a container registry image | | | ✓ | ✓ | ✓ | | Create/edit/delete project milestones | | | ✓ | ✓ | ✓ | -| View approved/blacklisted licenses **[ULTIMATE]** | | | ✓ | ✓ | ✓ | +| View approved/blacklisted licenses **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | | Use security dashboard **[ULTIMATE]** | | | ✓ | ✓ | ✓ | | Dismiss vulnerability **[ULTIMATE]** | | | ✓ | ✓ | ✓ | | Apply code change suggestions | | | ✓ | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | +| Run Web IDE's Interactive Web Terminals **[ULTIMATE ONLY]** | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | | Enable/disable branch protection | | | | ✓ | ✓ | @@ -120,6 +120,7 @@ The following table depicts the various user permission levels in a project. | Remove protected branches [^4] | | | | | | | View project Audit Events | | | | ✓ | ✓ | | View project statistics | | ✓ | ✓ | ✓ | ✓ | +| View Insights charts **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | ## Project features permissions @@ -172,8 +173,12 @@ read through the documentation on [permissions and access to confidential issues ### Releases permissions -[Project Releases](project/releases/index.md) can be read by all project -members (Reporters, Developers, Maintainers, Owners) **except Guests**. +[Project Releases](project/releases/index.md) can be read by project +members with Reporter, Developer, Maintainer, and Owner permissions. +Guest users can access Release pages for downloading assets but +are not allowed to download the source code nor see repository +information such as tags and commits. + Releases can be created, updated, or deleted via [Releases APIs](../api/releases/index.md) by project Developers, Maintainers, and Owners. @@ -200,6 +205,7 @@ group. | Create/edit group epic **[ULTIMATE]** | | ✓ | ✓ | ✓ | ✓ | | Delete group epic **[ULTIMATE]** | | | | | ✓ | | View group Audit Events | | | | | ✓ | +| View Insights charts **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | ### Subgroup permissions @@ -344,7 +350,7 @@ for details about the pipelines security model. ## LDAP users permissions Since GitLab 8.15, LDAP user permissions can now be manually overridden by an admin user. -Read through the documentation on [LDAP users permissions](https://docs.gitlab.com/ee/articles/how_to_configure_ldap_gitlab_ee/index.html#updating-user-permissions-new-feature) to learn more. +Read through the documentation on [LDAP users permissions](https://docs.gitlab.com/ee/administration/auth/how_to_configure_ldap_gitlab_ee/index.html) to learn more. [^1]: On public and internal projects, all users are able to perform this action [^2]: Guest users can only view the confidential issues they created themselves diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index f399dc40164..b61216b7b67 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -79,6 +79,7 @@ You have 8 options here that you can use for your default dashboard view: - Your [Todos](../../workflow/todos.md) - Assigned Issues - Assigned Merge Requests +- Operations Dashboard **[PREMIUM]** ### Project overview content diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md new file mode 100644 index 00000000000..cce862b0911 --- /dev/null +++ b/doc/user/project/canary_deployments.md @@ -0,0 +1,71 @@ +# Canary Deployments **[PREMIUM]** + +> [Introduced][ee-1659] in [GitLab Premium][eep] 9.1. + +A popular [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) +strategy, where a small portion of the fleet is updated to the new version of +your application. + +## Overview + +When embracing [Continuous Delivery][cd-blog], a company needs to decide what +type of deployment strategy to use. One of the most popular strategies is canary +deployments, where a small portion of the fleet is updated to the new version +first. This subset, the canaries, then serve as the proverbial +[canary in the coal mine](https://en.wiktionary.org/wiki/canary_in_a_coal_mine). + +If there is a problem with the new version of the application, only a small +percentage of users are affected and the change can either be fixed or quickly +reverted. + +Leveraging [Kubernetes' Canary deployments][kube-canary], visualize your canary +deployments right inside the [Deploy Board], without the need to leave GitLab. + +## Use cases + +Canary deployments can be used when you want to ship features to only a portion of +your pods fleet and watch their behavior as a percentage of your user base +visits the temporarily deployed feature. If all works well, you can deploy the +feature to production knowing that it won't cause any problems. + +Canary deployments are also especially useful for backend refactors, performance +improvements, or other changes where the user interface doesn't change, but you +want to make sure the performance stays the same, or improves. Developers need +to be careful when using canaries with user-facing changes, because by default, +requests from the same user will be randomly distributed between canary and +non-canary pods, which could result in confusion or even errors. If needed, you +may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in +your Kubernetes service definitions][kube-net], but that is beyond the scope of +this document. + +## Enabling Canary Deployments + +Canary deployments require that you properly configure Deploy Boards: + +1. Follow the steps to [enable Deploy Boards](deploy_boards.md#enabling-deploy-boards). +1. To track canary deployments you need to label your Kubernetes deployments and + pods with `track: canary`. To get started quickly, you can use the [Auto Deploy] + template for canary deployments that GitLab provides. + +Depending on the deploy, the label should be either `stable` or `canary`. +Usually, `stable` and blank or missing label means the same thing, and `canary` +or any other track means canary/temporary. +This allows GitLab to discover whether deployment is stable or canary (temporary). + +Once all of the above are set up and the pipeline has run at least once, +navigate to the environments page under **Pipelines > Environments**. +As the pipeline executes Deploy Boards will clearly mark canary pods, enabling +quick and easy insight into the status of each environment and deployment. + +Canary deployments are marked with a yellow dot in the Deploy Board so that you +can easily notice them. + + + +[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy" +[eep]: https://about.gitlab.com/pricing/ +[ee-1659]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1659 +[kube-canary]: https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments +[deploy board]: deploy_boards.md +[cd-blog]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/ +[kube-net]: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md new file mode 100644 index 00000000000..51b86a68c7b --- /dev/null +++ b/doc/user/project/ci_cd_for_external_repo.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html). diff --git a/doc/user/project/clusters/img/k8s_cluster_monitoring.png b/doc/user/project/clusters/img/k8s_cluster_monitoring.png Binary files differnew file mode 100644 index 00000000000..e449893a606 --- /dev/null +++ b/doc/user/project/clusters/img/k8s_cluster_monitoring.png diff --git a/doc/user/project/clusters/img/kubernetes_pod_logs.png b/doc/user/project/clusters/img/kubernetes_pod_logs.png Binary files differnew file mode 100644 index 00000000000..e664a47386a --- /dev/null +++ b/doc/user/project/clusters/img/kubernetes_pod_logs.png diff --git a/doc/user/project/clusters/img/pod_logs_deploy_board.png b/doc/user/project/clusters/img/pod_logs_deploy_board.png Binary files differnew file mode 100644 index 00000000000..7f83382968b --- /dev/null +++ b/doc/user/project/clusters/img/pod_logs_deploy_board.png diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 0677fe622f2..157afb3a78c 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -70,6 +70,7 @@ new Kubernetes cluster to your project: - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) of the Virtual Machine instance that the cluster will be based on. - **RBAC-enabled cluster** - Leave this checked if using default GKE creation options, see the [RBAC section](#role-based-access-control-rbac) for more information. + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. After a couple of minutes, your cluster will be ready to go. You can now proceed @@ -188,6 +189,9 @@ To add an existing Kubernetes cluster to your project: role binding. You can follow the [Google Cloud documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) to grant access. + + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. + - **Project namespace** (optional) - You don't have to fill it in; by leaving it blank, GitLab will create one for you. Also: - Each project should have a unique namespace. @@ -214,6 +218,29 @@ functionalities needed to successfully build and deploy a containerized application. Bear in mind that the same credentials are used for all the applications running on the cluster. +## Gitlab-managed clusters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22011) in GitLab 11.5. +> Became [optional](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26565) in GitLab 11.11. + +NOTE: **Note:** +Only available when creating clusters. Existing clusters not managed by GitLab +cannot become GitLab-managed later. + +You can choose to allow GitLab to manage your cluster for you. If your cluster is +managed by GitLab, resources for your projects will be automatically created. See the +[Access controls](#access-controls) section for details on which resources will +be created. + +If you choose to manage your own cluster, project-specific resources will not be created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will +need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) +that will be used by your deployment jobs, otherwise a namespace will be created for you. + +NOTE: **Note:** +If you [install applications](#installing-applications) on your cluster, GitLab will create +the resources required to run these even if you have chosen to manage your own cluster. + ## Base domain > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8. @@ -278,8 +305,8 @@ The following sections summarize which resources will be created on ABAC/RBAC cl | `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | | `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | | `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | -| Project namespace | `ServiceAccount` | Uses namespace of Project | Creating/Adding a new GKE Cluster | -| Project namespace | `Secret` | Token for project ServiceAccount | Creating/Adding a new GKE Cluster | +| Project namespace | `ServiceAccount` | Uses namespace of Project | Deploying to a cluster | +| Project namespace | `Secret` | Token for project ServiceAccount | Deploying to a cluster | ### Role-based access control (RBAC) @@ -290,9 +317,12 @@ The following sections summarize which resources will be created on ABAC/RBAC cl | `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | | `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | | `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | -| Project namespace | `ServiceAccount` | Uses namespace of Project | Creating/Adding a new GKE Cluster | -| Project namespace | `Secret` | Token for project ServiceAccount | Creating/Adding a new GKE Cluster | -| Project namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating/Adding a new GKE Cluster | +| Project namespace | `ServiceAccount` | Uses namespace of Project | Deploying to a cluster | +| Project namespace | `Secret` | Token for project ServiceAccount | Deploying to a cluster | +| Project namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | + +NOTE: **Note:** +Project-specific resources are only created if your cluster is [managed by GitLab](#gitlab-managed-clusters). ### Security of GitLab Runners @@ -376,6 +406,27 @@ Upgrades will reset values back to the values built into the `runner` chart plus the values set by [`values.yaml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/vendor/runner/values.yaml) +### Uninstalling applications + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/60665) in +> GitLab 11.11. + +The applications below can be uninstalled. + +| Application | GitLab version | Notes | +| ----------- | -------------- | ----- | +| Prometheus | 11.11+ | All data will be deleted and cannot be restored. | + +To uninstall an application: + +1. Navigate to your project's **Operations > Kubernetes**. +1. Select your cluster. +1. Click the **Uninstall** button for the application. + +Support for uninstalling all applications will be progressively +introduced (see [related +epic](https://gitlab.com/groups/gitlab-org/-/epics/1201)). + ### Troubleshooting applications Applications can fail with the following error: @@ -497,7 +548,7 @@ differentiate the new cluster with the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the -[environment-specific variables](https://docs.gitlab.com/ee/ci/variables/README.html#limiting-environment-scopes-of-variables-premium) work. +[environment-specific variables](https://docs.gitlab.com/ee/ci/variables/index.html#limiting-environment-scopes-of-environment-variables-premium) work. The default environment scope is `*`, which means all jobs, regardless of their environment, will use that cluster. Each scope can only be used by a single @@ -595,7 +646,7 @@ Common reasons for failure include: When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. - + ## Enabling or disabling the Kubernetes cluster integration @@ -626,7 +677,7 @@ and add a Kubernetes cluster again. ## View Kubernetes pod logs from GitLab **[ULTIMATE]** Learn how to easily -[view the logs of running pods in connected Kubernetes clusters](https://docs.gitlab.com/ee/user/project/clusters/kubernetes_pod_logs.html). +[view the logs of running pods in connected Kubernetes clusters](kubernetes_pod_logs.md). ## What you can get with the Kubernetes integration diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md new file mode 100644 index 00000000000..d5b60250860 --- /dev/null +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -0,0 +1,21 @@ +# Kubernetes Pod Logs **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. + +GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). +By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. + +## Overview + +[Kubernetes](https://kubernetes.io) pod logs can be viewed directly within GitLab. Logs can be displayed by clicking on a specific pod from [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html): + +1. Go to **Operations > Environments** and find the environment which contains the desired pod, like `production`. +1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html). +1. When mousing over the list of pods, a tooltip will appear with the exact pod name and status. + +1. Click on the desired pod to bring up the logs view, which will contain the last 500 lines for that pod. Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab-ee/issues/6502). + + +## Requirements + +[Enabling Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html#enabling-deploy-boards) is required in order to be able to use Pod Logs. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md new file mode 100644 index 00000000000..a4937e6cf6b --- /dev/null +++ b/doc/user/project/code_owners.md @@ -0,0 +1,85 @@ +# Code Owners **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6916) +in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. + +You can use a `CODEOWNERS` file to specify users that are responsible +for certain files in a repository. + +You can choose and add the `CODEOWNERS` file in three places: + +- to the root directory of the repository +- inside the `.gitlab/` directory +- inside the `docs/` directory + +The `CODEOWNERS` file is scoped to a branch, which means that with the +introduction of new files, the person adding the new content can +specify themselves as a code owner, all before the new changes +get merged to the default branch. + +When a file matches multiple entries in the `CODEOWNERS` file, +the users from all entries are displayed on the blob page of +the given file. + +## The syntax of Code Owners files + +Files can be specified using the same kind of patterns you would use +in the `.gitignore` file followed by the `@username` or email of one +or more users that should be owners of the file. + +The order in which the paths are defined is significant: the last +pattern that matches a given path will be used to find the code +owners. + +Starting a line with a `#` indicates a comment. This needs to be +escaped using `\#` to address files for which the name starts with a +`#`. + +Example `CODEOWNERS` file: + +``` +# This is an example code owners file, lines starting with a `#` will +# be ignored. + +# app/ @commented-rule + +# We can specifiy a default match using wildcards: +* @default-codeowner + +# Rules defined later in the file take precedence over the rules +# defined before. +# This will match all files for which the file name ends in `.rb` +*.rb @ruby-owner + +# Files with a `#` can still be accesssed by escaping the pound sign +\#file_with_pound.rb @owner-file-with-pound + +# Multiple codeowners can be specified, separated by whitespace +CODEOWNERS @multiple @owners @tab-separated + +# Both usernames or email addresses can be used to match +# users. Everything else will be ignored. For example this will +# specify `@legal` and a user with email `janedoe@gitlab.com` as the +# owner for the LICENSE file +LICENSE @legal this_does_not_match janedoe@gitlab.com + +# Ending a path in a `/` will specify the code owners for every file +# nested in that directory, on any level +/docs/ @all-docs + +# Ending a path in `/*` will specify code owners for every file in +# that directory, but not nested deeper. This will match +# `docs/index.md` but not `docs/projects/index.md` +/docs/* @root-docs + +# This will make a `lib` directory nested anywhere in the repository +# match +lib/ @lib-owner + +# This will only match a `config` directory in the root of the +# repository +/config/ @config-owner + +# If the path contains spaces, these need to be escaped like this: +path\ with\ spaces/ @space-owner +``` diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md new file mode 100644 index 00000000000..2f2a9c5eec3 --- /dev/null +++ b/doc/user/project/deploy_boards.md @@ -0,0 +1,132 @@ +# Deploy Boards **[PREMIUM]** + +> [Introduced][ee-1589] in [GitLab Premium][ee] 9.0. + +GitLab's Deploy Boards offer a consolidated view of the current health and +status of each CI [environment] running on [Kubernetes], displaying the status +of the pods in the deployment. Developers and other teammates can view the +progress and status of a rollout, pod by pod, in the workflow they already use +without any need to access Kubernetes. + +## Overview + +With Deploy Boards you can gain more insight into deploys with benefits such as: + +- Following a deploy from the start, not just when it's done +- Watching the rollout of a build across multiple servers +- Finer state detail (Waiting, Deploying, Finished, Unknown) +- See [Canary Deployments](canary_deployments.md) + +Here's an example of a Deploy Board of the production environment. + + + +The squares represent pods in your Kubernetes cluster that are associated with +the given environment. Hovering above each square you can see the state of a +deploy rolling out. The percentage is the percent of the pods that are updated +to the latest release. + +Since Deploy Boards are tightly coupled with Kubernetes, there is some required +knowledge. In particular you should be familiar with: + +- [Kubernetes pods](https://kubernetes.io/docs/user-guide/pods) +- [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) +- [Kubernetes namespaces](https://kubernetes.io/docs/user-guide/namespaces/) +- [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) + +## Use cases + +Since the Deploy Board is a visual representation of the Kubernetes pods for a +specific environment, there are lot of uses cases. To name a few: + +- You want to promote what's running in staging, to production. You go to the + environments list, verify that what's running in staging is what you think is + running, then click on the [manual action](../../ci/yaml/README.md#whenmanual) to deploy to production. +- You trigger a deploy, and you've got lots of containers to upgrade so you know + it'll take a while (you've also throttled your deploy to only take down X + containers at a time). But you need to tell someone when it's deployed, so you + go to the environments list, look at the production environment to see what + the progress is in real-time as each pod is rolled. +- You get a report that something is weird in production, so you look at the + production environment to see what is running, and if a deploy is ongoing or + stuck or failed. +- You've got an MR that looks good, but you want to run it on staging because + staging is set up in some way closer to production. You go to the environment + list, find the [Review App][review apps] you're interested in, and click the + manual action to deploy it to staging. + +## Enabling Deploy Boards + +To display the Deploy Boards for a specific [environment] you should: + +1. Have a Kubernetes cluster up and running. + + NOTE: **Running on OpenShift:** + If you are using OpenShift, ensure that you're using the `Deployment` resource + instead of `DeploymentConfiguration`, otherwise the Deploy Boards won't render + correctly. For more information, read the + [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) + and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab-ee/issues/4584). + +1. [Configure GitLab Runner][runners] with the [Docker][docker-exec] or + [Kubernetes][kube-exec] executor. +1. Configure the [Kubernetes service][kube-service] in your project for the + cluster. The Kubernetes namespace is of particular note as you will need it + for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable). +1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` + and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the + deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and + `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can + lookup the proper environment in a cluster/namespace which may have more + than one. These resources should be contained in the namespace defined in + the Kubernetes service setting. You can use an [Autodeploy] `.gitlab-ci.yml` + template which has predefined stages and commands to use, and automatically + applies the annotations. Each project will need to have a unique namespace in + Kubernetes as well. The image below demonstrates how this is shown inside + Kubernetes. + + NOTE: **Note:** + The Kubernetes label of `app` is deprecated and may be removed in next major + release, GitLab 12.0. + +  + +Once all of the above are set up and the pipeline has run at least once, +navigate to the environments page under **Operations > Environments**. + +Deploy Boards are visible by default. You can explicitly click +the triangle next to their respective environment name in order to hide them. +GitLab will then query Kubernetes for the state of each pod (e.g., waiting, +deploying, finished, unknown), and the Deploy Board status will finally appear. + +GitLab will only display a Deploy Board for top-level environments. Foldered +environments like `review/*` (usually used for [Review Apps]) won't have a +Deploy Board attached to them. + +## Canary Deployments + +A popular CI strategy, where a small portion of the fleet is updated to the new +version of your application. + +[Read more about Canary Deployments.](canary_deployments.md) + +## Further reading + +- [GitLab Autodeploy][autodeploy] +- [GitLab CI environment variables][variables] +- [Environments and deployments][environment] +- [Kubernetes deploy example][kube-deploy] + +[ee-1589]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1589 "Deploy Boards initial issue" +[ee]: https://about.gitlab.com/pricing/ "GitLab Enterprise Edition landing page" +[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project" +[kubernetes]: https://kubernetes.io "Kubernetes website" +[environment]: ../../ci/environments.md "Environments and deployments documentation" +[docker-exec]: https://docs.gitlab.com/runner/executors/docker.html "GitLab Runner Docker executor" +[kube-exec]: https://docs.gitlab.com/runner/executors/kubernetes.html "GitLab Runner Kubernetes executor" +[kube-service]: integrations/kubernetes.md "Kubernetes project service" +[review apps]: ../../ci/review_apps/index.md "Review Apps documentation" +[variables]: ../../ci/variables/README.md "GitLab CI variables" +[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy" +[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry" +[runners]: ../../ci/runners/README.md diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 08647caaf07..e230444fa67 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -2,8 +2,12 @@ >[Introduced][ce-4981] in GitLab 8.11. +We all know that a properly submitted issue is more likely to be addressed in +a timely manner by the developers of a project. + Description templates allow you to define context-specific templates for issue -and merge request description fields for your project. +and merge request description fields for your project, as well as help filter +out a lot of unnecessary noise from issues. ## Overview @@ -18,6 +22,18 @@ Description templates must be written in [Markdown](../markdown.md) and stored in your project's repository under a directory named `.gitlab`. Only the templates of the default branch will be taken into account. +## Use-cases + +- Add a template to be used in every issue for a specific project, +giving instructions and guidelines, requiring for information specific to that subject. +For example, if you have a project for tracking new blog posts, you can require the +title, outlines, author name, author social media information, etc. +- Following the previous example, you can make a template for every MR submitted +with a new blog post, requiring information about the post date, frontmatter data, +images guidelines, link to the related issue, reviewer name, etc. +- You can also create issues and merge request templates for different +stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc. + ## Creating issue templates Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/` @@ -39,6 +55,32 @@ changes you made after picking the template and return it to its initial status.  +## Setting a default template for issues and merge requests **[STARTER]** + +> **Notes:** +> - This feature was introduced before [description templates](#overview) and is +> available in [GitLab Starter][products]. It can be enabled +> in the project's settings. +> - Templates for issues were [introduced][ee-28] in GitLab EE 8.1. +> - Templates for merge requests were [introduced][ee-7478ece] in GitLab EE 6.9. + +The visibility of issues and/or merge requests should be set to either "Everyone +with access" or "Only team members" in your project's **Settings** otherwise the +template text areas won't show. This is the default behavior so in most cases +you should be fine. + +Go to your project's **Settings** and fill in the "Default description template +for issues" and "Default description template for merge requests" text areas +for issues and merge requests respectively. Since GitLab issues and merge +request support [Markdown](../markdown.md), you can use special markup like +headings, lists, etc. + + + +After you add the description, hit **Save changes** for the settings to take +effect. Now, every time a new issue or merge request is created, it will be +pre-filled with the text you entered in the template(s). + ## Description template example We make use of Description Templates for Issues and Merge Requests within the GitLab Community Edition project. Please refer to the [`.gitlab` folder][gitlab-ce-templates] for some examples. @@ -93,3 +135,6 @@ Possible fixes [ce-4981]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4981 [gitlab-ce-templates]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/.gitlab +[ee-28]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/28 "Merge Request for adding issues template" +[ee-7478ece]: https://gitlab.com/gitlab-org/gitlab-ee/commit/7478ece8b48e80782b5465b96c79f85cc91d391b "Commit that introduced merge requests templates" +[products]: https://about.gitlab.com/pricing/ diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md new file mode 100644 index 00000000000..541023692ea --- /dev/null +++ b/doc/user/project/file_lock.md @@ -0,0 +1,107 @@ +# File Locking **[PREMIUM]** + +> **Notes:** +> - [Introduced][ee-440] in [GitLab Premium][ee] 8.9. +> - This feature needs to have a license with the "File Lock" option enabled. If +> you are using Premium but you don't see the "Lock" button, +> ask your GitLab administrator. + +File Locking helps you avoid merge conflicts and better manage your binary files. +Lock any file or directory, make your changes, and then unlock it so another +member of the team can edit it. + +## Overview + +Working with multiple people on the same file can be a risk. Conflicts +when merging a non-text file are hard to overcome and will require a lot +of manual work to resolve. With GitLab Premium, File +Locking helps you avoid merge conflicts and better manage your binary +files by preventing everyone, except you, from modifying a specific file +or entire directory. + +## Use-cases + +The file locking feature is useful in situations when: + +- Multiple people are working on the same file and you want to avoid merge + conflicts. +- Your repository contains binary files in which situation there is no easy + way to tell the diff between yours and your colleagues' changes. +- Prevent design assets from being overwritten. + +Locked directories are locked recursively, which means that everything that +lies under them is also locked. + +## Permissions on file locking + +The user that locks a file or directory **is the only one** that can edit and +push their changes back to the repository where the locked objects are located. + +Locks can be created by any person who has [push access] to the repository; i.e., +Developer and higher level, and can be removed solely by their author and any +user with Maintainer permissions and above. + +If a file is locked and you are not the author of its locked state, a +pre-receive hook will reject your changes when you try to push. In the +following example, a user who has no permissions on the locked `.gitignore` +file will see the message below: + +```bash +Counting objects: 3, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (3/3), done. +Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done. +Total 3 (delta 1), reused 0 (delta 0) +remote: GitLab: The path '.gitignore' is locked by Administrator +To https://example.com/gitlab-org/gitlab-ce.git + ! [remote rejected] master -> master (pre-receive hook declined) + error: failed to push some refs to 'https://example.com/gitlab-org/gitlab-ce.git' +``` + +Similarly, when a user that is not the author of the locked state of a file +accepts a merge request, an error message will appear stating that the file +is locked. + + + +## Locking a file or a directory + +>**Note:** +Locking only works for the default branch you have set in the project's settings +(usually `master`). + +To lock a file, navigate to the repository tree under the **Repository > Files** tab, +pick the file you want to lock and hit the "Lock" button. + + + +--- + +To lock an entire directory, look for the "Lock" link next to "History". + + + +--- + +After you lock a file or directory, it will appear as locked in the repository +view. + + + +## Unlocking a file or a directory + +To unlock a file or a directory, follow the same procedure as when you locked +them. For a detailed view of every existing lock, see the next section on +"Viewing and managing existing locks". + +## Viewing and managing existing locks + +To view or manage every existing lock, navigate to the +**Project > Repository > Locked Files** area. There, you can view all existing +locks and [remove the ones you have permission for](#permissions-on-file-locking). + + + +[ee-440]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/440 "File Lock" +[ee]: https://about.gitlab.com/pricing/ +[push access]: ../../user/permissions.md diff --git a/doc/user/project/img/assignee_lists.png b/doc/user/project/img/assignee_lists.png Binary files differnew file mode 100644 index 00000000000..f2660cd8f80 --- /dev/null +++ b/doc/user/project/img/assignee_lists.png diff --git a/doc/user/project/img/deploy_boards_canary_deployments.png b/doc/user/project/img/deploy_boards_canary_deployments.png Binary files differnew file mode 100644 index 00000000000..037b4a908ab --- /dev/null +++ b/doc/user/project/img/deploy_boards_canary_deployments.png diff --git a/doc/user/project/img/deploy_boards_kubernetes_label.png b/doc/user/project/img/deploy_boards_kubernetes_label.png Binary files differnew file mode 100644 index 00000000000..19785c74d07 --- /dev/null +++ b/doc/user/project/img/deploy_boards_kubernetes_label.png diff --git a/doc/user/project/img/deploy_boards_landing_page.png b/doc/user/project/img/deploy_boards_landing_page.png Binary files differnew file mode 100644 index 00000000000..c9621a06860 --- /dev/null +++ b/doc/user/project/img/deploy_boards_landing_page.png diff --git a/doc/user/project/img/description_templates_default_settings.png b/doc/user/project/img/description_templates_default_settings.png Binary files differnew file mode 100644 index 00000000000..ab314e83d06 --- /dev/null +++ b/doc/user/project/img/description_templates_default_settings.png diff --git a/doc/user/project/img/file_lock.png b/doc/user/project/img/file_lock.png Binary files differnew file mode 100644 index 00000000000..33f96f20e91 --- /dev/null +++ b/doc/user/project/img/file_lock.png diff --git a/doc/user/project/img/file_lock_folders.png b/doc/user/project/img/file_lock_folders.png Binary files differnew file mode 100644 index 00000000000..5ff3d4d9dbd --- /dev/null +++ b/doc/user/project/img/file_lock_folders.png diff --git a/doc/user/project/img/file_lock_list.png b/doc/user/project/img/file_lock_list.png Binary files differnew file mode 100644 index 00000000000..2c276335c83 --- /dev/null +++ b/doc/user/project/img/file_lock_list.png diff --git a/doc/user/project/img/file_lock_merge_request_error_message.png b/doc/user/project/img/file_lock_merge_request_error_message.png Binary files differnew file mode 100644 index 00000000000..65bc3692da0 --- /dev/null +++ b/doc/user/project/img/file_lock_merge_request_error_message.png diff --git a/doc/user/project/img/file_lock_repository_view.png b/doc/user/project/img/file_lock_repository_view.png Binary files differnew file mode 100644 index 00000000000..8f4ef52aacd --- /dev/null +++ b/doc/user/project/img/file_lock_repository_view.png diff --git a/doc/user/project/img/key_value_labels.png b/doc/user/project/img/key_value_labels.png Binary files differnew file mode 100644 index 00000000000..bec901f127f --- /dev/null +++ b/doc/user/project/img/key_value_labels.png diff --git a/doc/user/project/img/labels_epic_sidebar.png b/doc/user/project/img/labels_epic_sidebar.png Binary files differnew file mode 100644 index 00000000000..f8162d89e9d --- /dev/null +++ b/doc/user/project/img/labels_epic_sidebar.png diff --git a/doc/user/project/img/project_security_dashboard.png b/doc/user/project/img/project_security_dashboard.png Binary files differnew file mode 100644 index 00000000000..3294e59e943 --- /dev/null +++ b/doc/user/project/img/project_security_dashboard.png diff --git a/doc/user/project/img/protected_branches_select_roles_and_users.png b/doc/user/project/img/protected_branches_select_roles_and_users.png Binary files differnew file mode 100644 index 00000000000..4f62b057cc7 --- /dev/null +++ b/doc/user/project/img/protected_branches_select_roles_and_users.png diff --git a/doc/user/project/img/protected_branches_select_roles_and_users_list.png b/doc/user/project/img/protected_branches_select_roles_and_users_list.png Binary files differnew file mode 100644 index 00000000000..519f2267496 --- /dev/null +++ b/doc/user/project/img/protected_branches_select_roles_and_users_list.png diff --git a/doc/user/project/img/service_desk_confirmation_email.png b/doc/user/project/img/service_desk_confirmation_email.png Binary files differnew file mode 100644 index 00000000000..e08dced1e38 --- /dev/null +++ b/doc/user/project/img/service_desk_confirmation_email.png diff --git a/doc/user/project/img/service_desk_disabled.png b/doc/user/project/img/service_desk_disabled.png Binary files differnew file mode 100644 index 00000000000..3ae64dcbe96 --- /dev/null +++ b/doc/user/project/img/service_desk_disabled.png diff --git a/doc/user/project/img/service_desk_enabled.png b/doc/user/project/img/service_desk_enabled.png Binary files differnew file mode 100644 index 00000000000..329348e4b52 --- /dev/null +++ b/doc/user/project/img/service_desk_enabled.png diff --git a/doc/user/project/img/service_desk_issue_tracker.png b/doc/user/project/img/service_desk_issue_tracker.png Binary files differnew file mode 100644 index 00000000000..485751fab0a --- /dev/null +++ b/doc/user/project/img/service_desk_issue_tracker.png diff --git a/doc/user/project/img/service_desk_nav_item.png b/doc/user/project/img/service_desk_nav_item.png Binary files differnew file mode 100644 index 00000000000..3420e355f67 --- /dev/null +++ b/doc/user/project/img/service_desk_nav_item.png diff --git a/doc/user/project/img/service_desk_reply.png b/doc/user/project/img/service_desk_reply.png Binary files differnew file mode 100644 index 00000000000..ae6ce31713b --- /dev/null +++ b/doc/user/project/img/service_desk_reply.png diff --git a/doc/user/project/img/service_desk_thread.png b/doc/user/project/img/service_desk_thread.png Binary files differnew file mode 100644 index 00000000000..8d8ac39cc5b --- /dev/null +++ b/doc/user/project/img/service_desk_thread.png diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md new file mode 100644 index 00000000000..dc5b3fcd0bb --- /dev/null +++ b/doc/user/project/import/gemnasium.md @@ -0,0 +1,102 @@ +# 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: + +  + +1. Use the "GitHub" button to connect your repositories. + +  + +1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect". + +  + + Once the configuration is done, you may click on your new + project on GitLab. + +  + + 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: + +  + +1. Once your file has been committed, a new pipeline will be automatically + triggered if your file is valid: + +  + +1. The result of the job will be visible directly from the pipeline view: + +  + +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. diff --git a/doc/user/project/import/img/gemnasium/connect_github.png b/doc/user/project/import/img/gemnasium/connect_github.png Binary files differnew file mode 100644 index 00000000000..5933f4d5d0a --- /dev/null +++ b/doc/user/project/import/img/gemnasium/connect_github.png diff --git a/doc/user/project/import/img/gemnasium/create_project.png b/doc/user/project/import/img/gemnasium/create_project.png Binary files differnew file mode 100644 index 00000000000..6e00bf63405 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/create_project.png diff --git a/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png b/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png Binary files differnew file mode 100644 index 00000000000..8336c803b83 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png diff --git a/doc/user/project/import/img/gemnasium/pipeline.png b/doc/user/project/import/img/gemnasium/pipeline.png Binary files differnew file mode 100644 index 00000000000..ae4d5295ffa --- /dev/null +++ b/doc/user/project/import/img/gemnasium/pipeline.png diff --git a/doc/user/project/import/img/gemnasium/project_connected.png b/doc/user/project/import/img/gemnasium/project_connected.png Binary files differnew file mode 100644 index 00000000000..8e7216c015b --- /dev/null +++ b/doc/user/project/import/img/gemnasium/project_connected.png diff --git a/doc/user/project/import/img/gemnasium/report.png b/doc/user/project/import/img/gemnasium/report.png Binary files differnew file mode 100644 index 00000000000..5c4d58662c0 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/report.png diff --git a/doc/user/project/import/img/gemnasium/select_project.png b/doc/user/project/import/img/gemnasium/select_project.png Binary files differnew file mode 100644 index 00000000000..588c5ca7ce1 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/select_project.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index cc73ea95f51..ebbc5ca133b 100644 --- a/doc/user/project/import/index.md +++ b/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. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 64139f9dbe9..6b3b40bf9f8 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -13,7 +13,7 @@ the number of private projects you create. When you create a project in GitLab, you'll have access to a large number of [features](https://about.gitlab.com/features/): -**Issues and merge requests:** +**Repositories:** - [Issue tracker](issues/index.md): Discuss implementations with your team within issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow @@ -28,6 +28,13 @@ When you create a project in GitLab, you'll have access to a large number of permission to create tags, and prevent accidental update or deletion - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. +- [Web IDE](web_ide/index.md) + +**Issues and merge requests:** + +- [Issue tracker](issues/index.md): Discuss implementations with your team within issues + - [Issue Boards](issue_board.md): Organize and prioritize your workflow + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards-starter): Allow your teams to create their own workflows (Issue Boards) for the same project **[STARTER]** - [Merge Requests](merge_requests/index.md): Apply your branching strategy and get reviewed by your team - [Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html): Ask for approval before @@ -67,6 +74,8 @@ When you create a project in GitLab, you'll have access to a large number of timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project with a Kubernetes cluster + - [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html): Feature flags allow you to ship a project in + different flavors by dynamically toggling certain functionality **[PREMIUM]** - [GitLab Pages](pages/index.md): Build, test, and deploy your static website with GitLab Pages @@ -75,12 +84,17 @@ When you create a project in GitLab, you'll have access to a large number of - [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki. - [Snippets](../snippets.md): store, share and collaborate on code snippets. - [Cycle Analytics](cycle_analytics.md): review your development lifecycle. +- [Security Dashboard](security_dashboard.md): Security Dashboard. **[ULTIMATE]** - [Syntax highlighting](highlighting.md): an alternative to customize your code blocks, overriding GitLab's default choice of language. - [Badges](badges.md): badges for the project overview. - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of the source, build output, and other metadata or artifacts associated with a released version of your code. +- [Maven packages](https://docs.gitlab.com/ee/user/project/packages/maven_repository.html): your private Maven repository in GitLab. **[PREMIUM]** +- [NPM packages](https://docs.gitlab.com/ee/user/project/packages/npm_registry.html): your private NPM package registry in GitLab. **[PREMIUM]** +- [Code owners](code_owners.md): specify code owners for certain files **[STARTER]** +- [License Management](https://docs.gitlab.com/ee/user/application_security/license_management/index.html): approve and blacklist licenses for projects. **[ULTIMATE]** ### Project integrations @@ -116,6 +130,13 @@ Read through the documentation on [project settings](settings/index.md). - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) +## CI/CD for external repositories **[PREMIUM]** + +Instead of importing a repository directly to GitLab, you can connect your repository +as a CI/CD project. + +Read through the documentation on [CI/CD for external repositories](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html). + ## Project members Learn how to [add members to your projects](members/index.md). diff --git a/doc/user/project/insights/img/insights_example_bar_chart.png b/doc/user/project/insights/img/insights_example_bar_chart.png Binary files differnew file mode 100644 index 00000000000..eb96eb4a90f --- /dev/null +++ b/doc/user/project/insights/img/insights_example_bar_chart.png diff --git a/doc/user/project/insights/img/insights_example_bar_time_series_chart.png b/doc/user/project/insights/img/insights_example_bar_time_series_chart.png Binary files differnew file mode 100644 index 00000000000..28aa81939d8 --- /dev/null +++ b/doc/user/project/insights/img/insights_example_bar_time_series_chart.png diff --git a/doc/user/project/insights/img/insights_example_line_chart.png b/doc/user/project/insights/img/insights_example_line_chart.png Binary files differnew file mode 100644 index 00000000000..131dbedd35e --- /dev/null +++ b/doc/user/project/insights/img/insights_example_line_chart.png diff --git a/doc/user/project/insights/img/insights_example_pie_chart.png b/doc/user/project/insights/img/insights_example_pie_chart.png Binary files differnew file mode 100644 index 00000000000..518ed7338f9 --- /dev/null +++ b/doc/user/project/insights/img/insights_example_pie_chart.png diff --git a/doc/user/project/insights/img/insights_example_stacked_bar_chart.png b/doc/user/project/insights/img/insights_example_stacked_bar_chart.png Binary files differnew file mode 100644 index 00000000000..aafec4b394e --- /dev/null +++ b/doc/user/project/insights/img/insights_example_stacked_bar_chart.png diff --git a/doc/user/project/insights/img/project_insights.png b/doc/user/project/insights/img/project_insights.png Binary files differnew file mode 100644 index 00000000000..2d0292dda54 --- /dev/null +++ b/doc/user/project/insights/img/project_insights.png diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md new file mode 100644 index 00000000000..720f4c6604e --- /dev/null +++ b/doc/user/project/insights/index.md @@ -0,0 +1,300 @@ +# 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. + + + +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` |  | +| `bar` (time series, i.e. when `group_by` is used) |  | +| `pie` |  | +| `line` |  | +| `stacked-bar` |  | + +### `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 +``` diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md new file mode 100644 index 00000000000..cdb0e34fdf6 --- /dev/null +++ b/doc/user/project/integrations/github.md @@ -0,0 +1,48 @@ +# 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). + + + +## 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. + + diff --git a/doc/user/project/integrations/img/github_configuration.png b/doc/user/project/integrations/img/github_configuration.png Binary files differnew file mode 100644 index 00000000000..9f2d47921c7 --- /dev/null +++ b/doc/user/project/integrations/img/github_configuration.png diff --git a/doc/user/project/integrations/img/github_status_check_pipeline_update.png b/doc/user/project/integrations/img/github_status_check_pipeline_update.png Binary files differnew file mode 100644 index 00000000000..9d02ca18497 --- /dev/null +++ b/doc/user/project/integrations/img/github_status_check_pipeline_update.png diff --git a/doc/user/project/integrations/img/prometheus_add_metric.png b/doc/user/project/integrations/img/prometheus_add_metric.png Binary files differnew file mode 100644 index 00000000000..e85670e1a13 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_add_metric.png diff --git a/doc/user/project/integrations/img/prometheus_alert.png b/doc/user/project/integrations/img/prometheus_alert.png Binary files differnew file mode 100644 index 00000000000..a37f0477fd9 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_alert.png diff --git a/doc/user/project/integrations/img/prometheus_service_alerts.png b/doc/user/project/integrations/img/prometheus_service_alerts.png Binary files differnew file mode 100644 index 00000000000..a81dfe7da14 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_service_alerts.png diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 339e6873c41..f560de427c5 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -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 | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 43a9e24526d..40113624430 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -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. + + + +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. + + + +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. + + + +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. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 7a45c87ada0..436129f1dbc 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,6 +1,6 @@ # 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)) + ``` diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 9a147deecd4..5e05846b77f 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -65,6 +65,26 @@ In GitLab 11.7, we updated the format of the generated email address. However the older format is still supported, allowing existing aliases or contacts to continue working._ +## New issue via Service Desk **[PREMIUM]** + +Enable [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) to your project and offer email support. +By doing so, when your customer sends a new email, a new issue can be created in +the appropriate project and followed up from there. + +## New issue from the group-level Issue Tracker + +Head to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker +for all projects in your Group. Select the project you'd like to add an issue for +using the dropdown button at the top-right of the page. + + + +We'll keep track of the project you selected most recently, and use it as the default +for your next visit. This should save you a lot of time and clicks, if you mostly +create issues for the same project. + + + ## New issue via URL with prefilled fields You can link directly to the new issue page for a given project, with prefilled diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md new file mode 100644 index 00000000000..56b94585672 --- /dev/null +++ b/doc/user/project/issues/csv_export.md @@ -0,0 +1,77 @@ +# Export Issues to CSV **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1126) in [GitLab Starter 9.0](https://about.gitlab.com/2017/03/22/gitlab-9-0-released/#export-issues-ees-eep). + +Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. + +## Overview + +**Export Issues to CSV** enables you and your team to export all the data collected from issues into +a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) file, +which stores tabular data in plain text. + +> _CSVs are a handy way of getting data from one program to another where one program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) + +CSV files can be used with any plotter or spreadsheet-based program, such as Microsoft Excel, +Open Office Calc, or Google Spreadsheets. + +## Use cases + +Among numerous use cases for exporting issues for CSV, we can name a few: + +- Make a snapshot of issues for offline analysis or to communicate with other teams who may not be in GitLab +- Create diagrams, graphs, and charts from the CSV data +- Present the data in any other format for auditing or sharing reasons +- Import the issues elsewhere to a system outside of GitLab +- Long-term issues' data analysis with multiple snapshots created along the time +- Use the long-term data to gather relevant feedback given in the issues, and improve your product based on real metrics + +## Choosing which issues to include + +From the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned will be exported, including those not shown on the first page. + + + +You will be asked to confirm the number of issues and email address for the export, after which the email will begin being prepared. + + + +## Sorting + +Exported issues are always sorted by `Issue ID`. + +## Format + +> **Time Estimate** and **Time Spent** columns were [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2627) in GitLab Starter 10.0. +> +> **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5300) in GitLab Starter 10.8. + +Data will be encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row will be the headers, which are listed in the following table along with a description of the values: + + +| Column | Description | +|---------|-------------| +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| Title | Issue `title` | +| State | `Open` or `Closed` | +| Description | Issue `description` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | +| Assignee Username | Username of the author, with the `@` symbol omitted | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formated as `YYYY-MM-DD` | +| Created At (UTC) | Formated as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formated as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Title of any labels joined with a `,` | +| Time Estimate | [Time estimate](../../../workflow/time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../../../workflow/time_tracking.md#time-spent) in seconds | + + +## Limitations + +As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 20MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. diff --git a/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png b/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png Binary files differnew file mode 100644 index 00000000000..8996490ae63 --- /dev/null +++ b/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png diff --git a/doc/user/project/issues/img/csv_export_button.png b/doc/user/project/issues/img/csv_export_button.png Binary files differnew file mode 100644 index 00000000000..f9fcfd71c2f --- /dev/null +++ b/doc/user/project/issues/img/csv_export_button.png diff --git a/doc/user/project/issues/img/csv_export_modal.png b/doc/user/project/issues/img/csv_export_modal.png Binary files differnew file mode 100644 index 00000000000..f988deec966 --- /dev/null +++ b/doc/user/project/issues/img/csv_export_modal.png diff --git a/doc/user/project/issues/img/multiple_assignees.gif b/doc/user/project/issues/img/multiple_assignees.gif Binary files differnew file mode 100644 index 00000000000..055a0efd9ae --- /dev/null +++ b/doc/user/project/issues/img/multiple_assignees.gif diff --git a/doc/user/project/issues/img/multiple_assignees_for_issues.png b/doc/user/project/issues/img/multiple_assignees_for_issues.png Binary files differnew file mode 100644 index 00000000000..e8ae37d427d --- /dev/null +++ b/doc/user/project/issues/img/multiple_assignees_for_issues.png diff --git a/doc/user/project/issues/img/related_issues_add.png b/doc/user/project/issues/img/related_issues_add.png Binary files differnew file mode 100644 index 00000000000..f59d2335386 --- /dev/null +++ b/doc/user/project/issues/img/related_issues_add.png diff --git a/doc/user/project/issues/img/related_issues_remove.png b/doc/user/project/issues/img/related_issues_remove.png Binary files differnew file mode 100644 index 00000000000..be2ec59e61b --- /dev/null +++ b/doc/user/project/issues/img/related_issues_remove.png diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png Binary files differnew file mode 100644 index 00000000000..97d93620b2a --- /dev/null +++ b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 653bd94e513..ef9fcaec3e6 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -50,7 +50,7 @@ where there is shared ownership of an issue. In [GitLab Starter](https://about.gitlab.com/pricing/), you can assign multiple people to an issue. -Learn more in the [Multiple Assignees documentation](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html). +Learn more in the [Multiple Assignees documentation](multiple_assignees_for_issues.md). #### 4. Milestone @@ -103,7 +103,7 @@ Learn more in the [Issue Weight documentation](https://docs.gitlab.com/ee/workfl - Unsubscribe: if you are receiving notifications on that issue but no longer want to receive them, unsubscribe from it. -Read more in the [notifications documentation](../../../workflow/notifications.md#issue--merge-request-events). +Read more in the [notifications documentation](https://docs.gitlab.com/ee/workflow/notifications.html#issue--epics--merge-request-events). #### 11. Reference diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md new file mode 100644 index 00000000000..8781ebdd5b0 --- /dev/null +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -0,0 +1,41 @@ +# Multiple Assignees for Issues **[STARTER]** + +> **Note:** +[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1904) +in [GitLab Starter 9.2](https://about.gitlab.com/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). + +## Overview + +In large teams, where there is shared ownership of an issue, it can be difficult +to track who is working on it, who already completed their contributions, who +didn't even start yet. + +In [GitLab Enterprise Edition](https://about.gitlab.com/pricing/), +you can also select multiple assignees to an issue, making it easier to +track, and making clearer who is accountable for it. + + + +## Use cases + +Consider a team formed by frontend developers, backend developers, +UX designers, QA testers, and a product manager working together to bring an idea to +market. + +Multiple Assignees for Issues makes collaboration smother, +and allows shared responsibilities to be clearly displayed. +All assignees are shown across your team's workflows and receive notifications (as they +would as single assignees), simplifying communication and ownership. + +Once an assignee had their work completed, they would remove themselves as assignees, making +it clear that their role is complete. + +## How it works + +From an opened issue, expand the right sidebar, locate the assignees entry, +and click on **Edit**. From the dropdown menu, select as many users as you want +to assign the issue to. + + + +An assignee can be easily removed by deselecting them from the same dropdown menu. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md new file mode 100644 index 00000000000..db0ab65b442 --- /dev/null +++ b/doc/user/project/issues/related_issues.md @@ -0,0 +1,45 @@ +# Related issues **[STARTER]** + +> [Introduced][ee-1797] in [GitLab Starter][ee] 9.4. + +Related issues are a bi-directional relationship between any two issues +and appear in a block below the issue description. Issues can be across groups +and projects. + +The relationship only shows up in the UI if the user can see both issues. + +## Adding a related issue + +You can relate one issue to another by clicking the related issues "+" button +in the header of the related issue block. Then, input the issue reference number +or paste in the full URL of the issue. + +Issues of the same project can be specified just by the reference number. +Issues from a different project require additional information like the +group and the project name. For example: + +- same project: `#44` +- same group: `project#44 ` +- different group: `group/project#44` + +Valid references will be added to a temporary list that you can review. +When ready, click the green "Add related issues" button to submit. + + + +## Removing a related issue + +In the related issues block, click the "x" icon on the right-side of each issue +token that you wish to remove. Due to the bi-directional relationship, it +will no longer appear in either issue. + + + +Please access our [permissions] page for more information. + +Additionally, you are also able to manage related issues through [our API]. + +[ee]: https://about.gitlab.com/pricing/ +[ee-1797]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1797 +[permissions]: ../../permissions.md +[Our API]: https://docs.gitlab.com/ee/api/issue_links.html diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 9c045dfcce4..ac91cd4ea98 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -8,13 +8,52 @@ Labels allow you to categorize issues or merge requests using descriptive titles In GitLab, you can create project and group labels: -- **Project labels** can be assigned to issues or merge requests in that project only. +- **Project labels** can be assigned to issues or merge requests in that project only. - **Group labels** can be assigned to any issue or merge request of any project in that group or any subgroups of the group. +## Scoped labels **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. + +Scoped labels allow teams to use the simple and familiar feature of labels to +annotate their issues, merge requests, and epics to achieve custom fields and +custom workflow states by leveraging a special label title syntax. + +A scoped label is a kind of label defined only by a special double-colon syntax +in the label’s title, using the format `key::value`. For example: + + + +Two scoped labels with the same key but a different value cannot simultaneously +apply to an issue, epic, or merge request. For example, if an issue already has `priority::3` +and you apply `priority::2` to it, `priority::3` is automatically removed from the issue. + +An issue, epic, or merge request cannot have two scoped labels with the same key. +For example, if an issue is already labeled `priority::3` and you apply the label `priority::2` to it, +`priority::3` is automatically removed. + +### Workflows with scoped labels **[PREMIUM]** + +Suppose you wanted a custom field in issues to track the platform operating system +that your features target, where each issue should only target one platform. You +would then create labels `platform::iOS`, `platform::Android`, `platform::Linux`, +etc., as necessary. Applying any one of these labels on a given issue would +automatically remove any other existing label that starts with `platform::`. + +The same pattern could be applied to represent the workflow states of your teams. +Suppose you have the labels `workflow::development`, `workflow::review`, and +`workflow::deployed`. If an issue already has the label `workflow::development` +applied, and a developer wanted to advance the issue to `workflow::review`, they +would simply apply that label, and the `workflow::development` label would +automatically be removed. This behavior already exists when you move issues +across label lists in an [issue board](issue_board.md#creating-workflows), but +now, team members who may not be working in an issue board directly would still +be able to advance workflow states consistently in issues themselves. + ## Creating labels >**Note:** -A permission level of `Developer` or higher is required to create labels. +A permission level of Reporter or higher is required to create labels. ### New project label @@ -35,6 +74,9 @@ GitLab will add the following default labels to the project: To create a **group label**, follow similar steps from above to project labels. Navigate to **Issues > Labels** in the group and create it from there. This page only shows group labels in this group. +Alternatively, you can create group labels also from Epic sidebar. Please note that the created label will belong to the immediate group to which epic belongs. + + Group labels appear in every label list page of the group's child projects. @@ -42,14 +84,14 @@ Group labels appear in every label list page of the group's child projects. ### New project label from sidebar -From the sidebar of an issue or a merge request, you can create a create a new **project label** inline immediately, instead of navigating to the project label list page. +From the sidebar of an issue or a merge request, you can create a new **project label** inline immediately, instead of navigating to the project label list page.  ## Editing labels NOTE: **Note:** -A permission level of `Developer` or higher is required to edit labels. +A permission level of Reporter or higher is required to edit labels. You can update a label by navigating to **Issues > Labels** in the project or group and clicking the pencil icon. @@ -81,7 +123,7 @@ top-right: GitLab will consider the label title and description for the search. -## Filtering issues and merge requests by label +## Filtering issues, merge requests and epics by label ### Filtering in list pages @@ -89,11 +131,16 @@ From the project issue list page and the project merge request list page, you ca From the group issue list page and the group merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels (including subgroup ancestors and subgroup descendants) and project labels. +From the group epic list page, you can [filter](../search/index.md#issues-and-merge-requests) by both current group labels as well as decendent group labels. +  ### Filtering in issue boards - From [project boards](issue_board.md), you can filter by both group labels and project labels in the [search and filter bar](../search/index.md#issue-boards). +- From [group issue boards](issue_board.md#group-issue-boards-premium), you can filter by only group labels in the [search and filter bar](../search/index.md#issue-boards). **[PREMIUM]** +- From [project boards](issue_board.md), you can filter by both group labels and project labels in the [issue board configuration](issue_board.md#configurable-issue-boards-starter). **[STARTER]** +- From [group issue boards](issue_board.md#group-issue-boards-premium), you can filter by only group labels in the [issue board configuration](issue_board.md#configurable-issue-boards-starter). **[STARTER]** ## Subscribing to labels diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md new file mode 100644 index 00000000000..d32d6084b38 --- /dev/null +++ b/doc/user/project/maven_packages.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/project/packages/maven_repository.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/project/packages/maven_repository.html). diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md new file mode 100644 index 00000000000..65ee2e128ae --- /dev/null +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -0,0 +1,54 @@ +# Browser Performance Testing **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3507) +in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. + +## Overview + +If your application offers a web interface and you are using +[GitLab CI/CD](../../../ci/README.md), you can quickly determine the performance +impact of pending code changes. + +GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source +tool for measuring the performance of web sites, and has built a simple +[Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance) +which outputs the results in a file called `performance.json`. This plugin +outputs the performance score for each page that is analyzed. + +The [Sitespeed.io performance score](http://examples.sitespeed.io/6.0/2017-11-23-23-43-35/help.html) +is a composite value based on best practices, and we will be expanding support +for [additional metrics](https://gitlab.com/gitlab-org/gitlab-ee/issues/4370) +in a future release. + +Going a step further, GitLab can show the Performance report right +in the merge request widget area: + +## Use cases + +For instance, consider the following workflow: + +1. A member of the marketing team is attempting to track engagement by adding a new tool +1. With browser performance metrics, they see how their changes are impacting the usability of the page for end users +1. The metrics show that after their changes the performance score of the page has gone down +1. When looking at the detailed report, they see that the new Javascript library was included in `<head>` which affects loading page speed +1. They ask a front end developer to help them, who sets the library to load asynchronously +1. The frontend developer approves the merge request and authorizes its deployment to production + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance-premium). +For more information on how the Performance job should look like, check the +example on [Testing Browser Performance](../../../ci/examples/browser_performance.md). + +GitLab then checks this report, compares key performance metrics for each page +between the source and target branches, and shows the information right on the merge request. + +>**Note:** +If the Performance report doesn't have anything to compare to, no information +will be displayed in the merge request area. That is the case when you add the +Performance job in your `.gitlab-ci.yml` for the very first time. +Consecutive merge requests will have something to compare to and the Performance +report will be shown properly. + + diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md new file mode 100644 index 00000000000..e6811b5df5e --- /dev/null +++ b/doc/user/project/merge_requests/code_quality.md @@ -0,0 +1,82 @@ +# Code Quality **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1984) +in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your +source code quality using GitLab Code Quality. +Code Quality uses [Code Climate Engines](https://codeclimate.com), which are +free and open source. Code Quality doesn’t require a Code Climate subscription. + +Going a step further, GitLab can show the Code Quality report right +in the merge request widget area: + + + +## Use cases + +For instance, consider the following workflow: + +1. Your backend team member starts a new implementation for making certain feature in your app faster +1. With Code Quality reports, they analyze how their implementation is impacting the code quality +1. The metrics show that their code degrade the quality in 10 points +1. You ask a co-worker to help them with this modification +1. They both work on the changes until Code Quality report displays no degradations, only improvements +1. You approve the merge request and authorize its deployment to staging +1. Once verified, their changes are deployed to production + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter). + +The Code Quality report artifact is a subset of the +[Code Climate spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types). +It must be a JSON file containing an array of objects with the following properties: + +| Name | Description | +| ---------------------- | -------------------------------------------------------------------------------------- | +| `description` | A description of the code quality violation. | +| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `location.path` | The relative path to the file containing the code quality violation. | +| `location.lines.begin` | The line on which the code quality violation occurred. | + +Example: + +```json +[ + { + "description": "'unused' is assigned a value but never used.", + "fingerprint": "7815696ecbf1c96e6894b779456d330e", + "location": { + "path": "lib/index.js", + "lines": { + "begin": 42 + } + } + } +] +``` + +NOTE: **Note:** +Although the Code Climate spec supports more properties, those are ignored by GitLab. + +For more information on how the Code Quality job should look like, check the +example on [analyzing a project's code quality](../../../ci/examples/code_quality.md). + +GitLab then checks this report, compares the metrics between the source and target +branches, and shows the information right on the merge request. + +CAUTION: **Caution:** +If multiple jobs in a pipeline generate a code quality artifact, only the artifact from +the last created job (the job with the largest job ID) is used. To avoid confusion, +configure only one job to generate a code quality artifact. + +NOTE: **Note:** +If the Code Quality report doesn't have anything to compare to, no information +will be displayed in the merge request area. That is the case when you add the +Code Quality job in your `.gitlab-ci.yml` for the very first time. +Consecutive merge requests will have something to compare to and the Code Quality +report will be shown properly. diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md new file mode 100644 index 00000000000..890058eec6f --- /dev/null +++ b/doc/user/project/merge_requests/code_quality_diff.md @@ -0,0 +1,6 @@ +--- +redirect_from: 'https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html' +redirect_to: 'code_quality.md' +--- + +This document was moved to [another location](code_quality.md). diff --git a/doc/user/project/merge_requests/container_scanning.md b/doc/user/project/merge_requests/container_scanning.md new file mode 100644 index 00000000000..4d41e424f4a --- /dev/null +++ b/doc/user/project/merge_requests/container_scanning.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html). diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md new file mode 100644 index 00000000000..b676c661267 --- /dev/null +++ b/doc/user/project/merge_requests/dast.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/dast/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/dast/index.html). diff --git a/doc/user/project/merge_requests/dependency_scanning.md b/doc/user/project/merge_requests/dependency_scanning.md new file mode 100644 index 00000000000..3a8b53b425c --- /dev/null +++ b/doc/user/project/merge_requests/dependency_scanning.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html). diff --git a/doc/user/project/merge_requests/img/approvals_can_override.png b/doc/user/project/merge_requests/img/approvals_can_override.png Binary files differnew file mode 100644 index 00000000000..8d207d018e0 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_can_override.png diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png Binary files differnew file mode 100644 index 00000000000..b6dc86f312e --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png Binary files differnew file mode 100644 index 00000000000..b6f6188b9cd --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png diff --git a/doc/user/project/merge_requests/img/approvals_remove_on_push.png b/doc/user/project/merge_requests/img/approvals_remove_on_push.png Binary files differnew file mode 100644 index 00000000000..73964827587 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_remove_on_push.png diff --git a/doc/user/project/merge_requests/img/approvals_starter_project_edit.png b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png Binary files differnew file mode 100644 index 00000000000..868b9d58740 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png diff --git a/doc/user/project/merge_requests/img/approvals_starter_project_empty.png b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png Binary files differnew file mode 100644 index 00000000000..7375820224c --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png diff --git a/doc/user/project/merge_requests/img/approve.png b/doc/user/project/merge_requests/img/approve.png Binary files differnew file mode 100644 index 00000000000..e68259ac5c2 --- /dev/null +++ b/doc/user/project/merge_requests/img/approve.png diff --git a/doc/user/project/merge_requests/img/approve_additionally.png b/doc/user/project/merge_requests/img/approve_additionally.png Binary files differnew file mode 100644 index 00000000000..3db5a9159e5 --- /dev/null +++ b/doc/user/project/merge_requests/img/approve_additionally.png diff --git a/doc/user/project/merge_requests/img/browser_performance_testing.png b/doc/user/project/merge_requests/img/browser_performance_testing.png Binary files differnew file mode 100644 index 00000000000..eea77fb8b93 --- /dev/null +++ b/doc/user/project/merge_requests/img/browser_performance_testing.png diff --git a/doc/user/project/merge_requests/img/code_quality.gif b/doc/user/project/merge_requests/img/code_quality.gif Binary files differnew file mode 100644 index 00000000000..bab921cf38b --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality.gif diff --git a/doc/user/project/merge_requests/img/container_scanning.png b/doc/user/project/merge_requests/img/container_scanning.png Binary files differnew file mode 100644 index 00000000000..e47f62acd9d --- /dev/null +++ b/doc/user/project/merge_requests/img/container_scanning.png diff --git a/doc/user/project/merge_requests/img/create-issue-with-list-hover.png b/doc/user/project/merge_requests/img/create-issue-with-list-hover.png Binary files differnew file mode 100644 index 00000000000..7d70e8299f5 --- /dev/null +++ b/doc/user/project/merge_requests/img/create-issue-with-list-hover.png diff --git a/doc/user/project/merge_requests/img/dast_all.png b/doc/user/project/merge_requests/img/dast_all.png Binary files differnew file mode 100644 index 00000000000..b6edc928dc3 --- /dev/null +++ b/doc/user/project/merge_requests/img/dast_all.png diff --git a/doc/user/project/merge_requests/img/dast_single.png b/doc/user/project/merge_requests/img/dast_single.png Binary files differnew file mode 100644 index 00000000000..26ca4bde786 --- /dev/null +++ b/doc/user/project/merge_requests/img/dast_single.png diff --git a/doc/user/project/merge_requests/img/dependency_scanning.png b/doc/user/project/merge_requests/img/dependency_scanning.png Binary files differnew file mode 100644 index 00000000000..18df356f846 --- /dev/null +++ b/doc/user/project/merge_requests/img/dependency_scanning.png diff --git a/doc/user/project/merge_requests/img/filter_approver_merge_requests.png b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png Binary files differnew file mode 100644 index 00000000000..9c386391a4f --- /dev/null +++ b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png diff --git a/doc/user/project/merge_requests/img/interactive_reports.png b/doc/user/project/merge_requests/img/interactive_reports.png Binary files differnew file mode 100644 index 00000000000..9f9812dc69d --- /dev/null +++ b/doc/user/project/merge_requests/img/interactive_reports.png diff --git a/doc/user/project/merge_requests/img/license_management.png b/doc/user/project/merge_requests/img/license_management.png Binary files differnew file mode 100644 index 00000000000..cdce6b5fe38 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_management.png diff --git a/doc/user/project/merge_requests/img/license_management_decision.png b/doc/user/project/merge_requests/img/license_management_decision.png Binary files differnew file mode 100644 index 00000000000..0763130c375 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_management_decision.png diff --git a/doc/user/project/merge_requests/img/license_management_pipeline_tab.png b/doc/user/project/merge_requests/img/license_management_pipeline_tab.png Binary files differnew file mode 100644 index 00000000000..80ffca815b9 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_management_pipeline_tab.png diff --git a/doc/user/project/merge_requests/img/license_management_settings.png b/doc/user/project/merge_requests/img/license_management_settings.png Binary files differnew file mode 100644 index 00000000000..b5490e59074 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_management_settings.png diff --git a/doc/user/project/merge_requests/img/remove_approval.png b/doc/user/project/merge_requests/img/remove_approval.png Binary files differnew file mode 100644 index 00000000000..6083e1745ef --- /dev/null +++ b/doc/user/project/merge_requests/img/remove_approval.png diff --git a/doc/user/project/merge_requests/img/sast.png b/doc/user/project/merge_requests/img/sast.png Binary files differnew file mode 100644 index 00000000000..2c75592c32a --- /dev/null +++ b/doc/user/project/merge_requests/img/sast.png diff --git a/doc/user/project/merge_requests/img/security_report.png b/doc/user/project/merge_requests/img/security_report.png Binary files differnew file mode 100644 index 00000000000..ba41b707238 --- /dev/null +++ b/doc/user/project/merge_requests/img/security_report.png diff --git a/doc/user/project/merge_requests/img/vulnerability_solution.png b/doc/user/project/merge_requests/img/vulnerability_solution.png Binary files differnew file mode 100644 index 00000000000..7443b9b6eea --- /dev/null +++ b/doc/user/project/merge_requests/img/vulnerability_solution.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 2765a32c845..2bb2d906453 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -23,7 +23,7 @@ With GitLab merge requests, you can: - Assign it to any registered user, and change the assignee how many times you need - Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation - Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md) -- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.html#time-tracking) +- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.md#time-tracking) - [Resolve merge conflicts from the UI](#resolve-conflicts) - Enable [fast-forward merge requests](#fast-forward-merge-requests) - Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch @@ -33,9 +33,16 @@ With GitLab merge requests, you can: With **[GitLab Enterprise Edition][ee]**, you can also: -- View the deployment process across projects with [Multi-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html#multi-project-pipeline-graphs) **[PREMIUM]** -- Request [approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers **[STARTER]** -- Analyze the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html) **[STARTER]** +- Prepare a full review and submit it once it's ready with [Merge Request Reviews](https://docs.gitlab.com/ee/user/discussions/index.md#merge-request-reviews-premium) **[PREMIUM]** +- View the deployment process across projects with [Multi-Project Pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipelines.md) **[PREMIUM]** +- Request [approvals](merge_request_approvals.md) from your managers **[STARTER]** +- Analyze the impact of your changes with [Code Quality reports](code_quality.md) **[STARTER]** +- Manage the licenses of your dependencies with [License Management](https://docs.gitlab.com/ee/user/application_security/license_management/index.md) **[ULTIMATE]** +- Analyze your source code for vulnerabilities with [Static Application Security Testing](https://docs.gitlab.com/ee/user/application_security/sast/index.md) **[ULTIMATE]** +- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](https://docs.gitlab.com/ee/user/application_security/dast/index.md) **[ULTIMATE]** +- Analyze your dependencies for vulnerabilities with [Dependency Scanning](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.md) **[ULTIMATE]** +- Analyze your Docker images for vulnerabilities with [Container Scanning](https://docs.gitlab.com/ee/user/application_security/container_scanning/index.md) **[ULTIMATE]** +- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **[PREMIUM]** ## Use cases @@ -43,19 +50,21 @@ A. Consider you are a software developer working in a team: 1. You checkout a new branch, and submit your changes through a merge request 1. You gather feedback from your team +1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) **[STARTER]** 1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD -1. You request the approval from your manager -1. Your manager pushes a commit with his final review, [approves the merge request](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter) +1. You avoid using dependencies whose license is not compatible with your project with [License Management reports](license_management.md) **[ULTIMATE]** +1. You request the [approval](#merge-request-approvals-starter) from your manager +1. Your manager pushes a commit with their final review, [approves the merge request](merge_request_approvals.md), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter) 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD 1. Your implementations were successfully shipped to your customer -B. Consider you're a web developer writing a webpage for your company's: +B. Consider you're a web developer writing a webpage for your company's website: 1. You checkout a new branch, and submit a new page through a merge request 1. You gather feedback from your reviewers 1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md) 1. You request your web designers for their implementation -1. You request the [approval](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your manager **[STARTER]** +1. You request the [approval](merge_request_approvals.md) from your manager **[STARTER]** 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) 1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production @@ -159,6 +168,21 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg  +## Perform a Review **[PREMIUM]** + +Start a review in order to create multiple comments on a diff and publish them once you're ready. +Starting a review allows you to get all your thoughts in order and ensure you haven't missed anything +before submitting all your comments. + +[Learn more about Merge Request Reviews](https://docs.gitlab.com/ee/user/discussions/index.html#merge-request-reviews-premium) + +## Squash and merge + +GitLab allows you to squash all changes present in a merge request into a single +commit when merging, to allow for a neater commit history. + +[Learn more about squash and merge.](squash_and_merge.md) + ## Suggest changes > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. @@ -182,7 +206,7 @@ To assign multiple assignees to a merge request: 1. From a merge request, expand the right sidebar and locate the **Assignees** section. 1. Click on **Edit** and from the dropdown menu, select as many users as you want -to assign the merge request to. + to assign the merge request to. Similarly, assignees are removed by deselecting them from the same dropdown menu. @@ -336,6 +360,52 @@ have been marked as a **Work In Progress**. [Learn more about setting a merge request as "Work In Progress".](work_in_progress_merge_requests.md) +## Merge request approvals **[STARTER]** + +> Included in [GitLab Starter][products]. + +If you want to make sure every merge request is approved by one or more people, +you can enforce this workflow by using merge request approvals. Merge request +approvals allow you to set the number of necessary approvals and predefine a +list of approvers that will need to approve every merge request in a project. + +[Read more about merge request approvals.](merge_request_approvals.md) + +## Code Quality **[STARTER]** + +> Introduced in [GitLab Starter][products] 9.3. + +If you are using [GitLab CI][ci], you can analyze your source code quality using +the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab +can show the Code Climate report right in the merge request widget area. + +[Read more about Code Quality reports.](code_quality.md) + +## Browser Performance Testing **[PREMIUM]** + +> Introduced in [GitLab Premium][products] 10.3. + +If your application offers a web interface and you are using [GitLab CI/CD][ci], you can quickly determine the performance impact of pending code changes. GitLab uses [Sitespeed.io][sitespeed], a free and open source tool for measuring the performance of web sites, to analyze the performance of specific pages. + +GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the difference in overall performance scores between the source and target branches. + +[Read more about Browser Performance Testing.](browser_performance_testing.md) + +## Security reports **[ULTIMATE]** + +GitLab can scan and report any vulnerabilities found in your project. + +[Read more about security reports.](https://docs.gitlab.com/ee/user/application_security/index.html) + +## Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project, +you can preview the changes submitted to a feature-branch through a merge request +in a per-branch basis. No need to checkout the branch, install and preview locally; +all your changes will be available to preview by anyone with the Review Apps link. + +[Read more about Review Apps.](../../../ci/review_apps/index.md) + ## Merge request diff file navigation When reviewing changes in the **Changes** tab the diff can be navigated using @@ -528,5 +598,11 @@ And to check out a particular merge request: git checkout origin/merge-requests/1 ``` +[products]: https://about.gitlab.com/products/ "GitLab products page" [protected branches]: ../protected_branches.md +[ci]: ../../../ci/README.md +[cc]: https://codeclimate.com/ +[cd]: https://hub.docker.com/r/codeclimate/codeclimate/ +[sitespeed]: https://www.sitespeed.io +[sitespeed-container]: https://hub.docker.com/r/sitespeedio/sitespeed.io/ [ee]: https://about.gitlab.com/pricing/ "GitLab Enterprise Edition" diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md new file mode 100644 index 00000000000..08704425a75 --- /dev/null +++ b/doc/user/project/merge_requests/license_management.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/license_management/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/license_management/index.html). diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md new file mode 100644 index 00000000000..265871a7b4b --- /dev/null +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -0,0 +1,319 @@ +# Merge request approvals **[STARTER]** + +> Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only). + +NOTE: **Note:** +If you are running a self-managed instance, the new interface shown on +this page will not be available unless the feature flag +`approval_rules` is enabled, which can be done from the Rails console by +instance administrators. + +Use these commands to start the Rails console: + +```sh +# Omnibus GitLab +gitlab-rails console + +# Installation from source +cd /home/git/gitlab +sudo -u git -H bin/rails console RAILS_ENV=production +``` + +Then run `Feature.enable(:approval_rules)` to enable the feature flag. + +The documentation for the older interface can be accessed +[here](/11.7/ee/user/project/merge_requests/merge_request_approvals.html). + +## Overview + +Merge request approvals enable enforced code review by requiring specified people to approve a merge request before it can be unblocked for merging. + +## Use cases + +1. Enforcing review of all code that gets merged into a repository. +2. Specifying code maintainers for an entire repository. +3. Specifying reviewers for a given proposed code change. +4. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes. + +## Editing approvals + +To edit the merge request approvals: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals**. + +  + +1. Click **Edit**. +1. Search for users or groups that will be [eligible to approve](#eligible-approvers) + merge requests and click the **Add** button to add them as approvers. Note: selecting + approvers is optional. +1. Set the minimum number of required approvals under the **No. approvals required** + box. Note: the minimum can be 0. +1. Click **Update approvers**. + +  + +The steps above are the minimum required to get approvals working in your +merge requests, but there are a couple more options available that might be +suitable to your workflow: + +- Choose whether the default settings can be + [overridden per merge request](#overriding-the-merge-request-approvals-default-settings) +- Choose whether [approvals will be reset with new pushed commits](#resetting-approvals-on-push) + +## Editing approvals **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. + +CAUTION: **Caution:** +There was a [regression affecting this feature in 11.8](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9648). We recommend upgrading _at least_ to version 11.8.2. to avoid any issues. + +NOTE: **Note:** +In 11.8 this feature does not work in [private groups](https://gitlab.com/gitlab-org/gitlab-ee/issues/10356). + +For GitLab Premium, [multiple approver rules](#multiple-approval-rules-premium) can be configured. To configure the merge +request approval rules: + +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Click **Add approvers** to create a new approval rule. +1. Just like in [GitLab Starter](#editing-approvals), select the approval members and aprovals required. +1. Give the approval rule a name that describes the set of approvers selected. +1. Click **Add approvers** to submit the new rule. + +  + +## Multiple approval rules **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. + +For GitLab Premium, a merge request's overall approval status is determined by a set of rules. Each rule contains: + +- A set of [eligible approvers](#eligible-approvers). +- A minimum number of approvals required. + +When an [eligible approver](#eligible-approvers) approves a merge request, it will reduce the number of approvals left for +all rules that the approver belongs to. + + + +If no approval rules are set, then the overall minimum number of approvals required can be configured. With no approval rules, +any [eligible approver](#eligible-approvers) may approve. + +## Eligible approvers + +The following can approve merge requests: + +- Users being added as approvers at project or merge request level. +- [Code owners](https://docs.gitlab.com/ee/user/project/code_owners.html) related to the merge request ([introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5). + +An individual user can be added as an approver for a project if they are a member of: + +- The project. +- The project's immediate parent group. +- A group that has access to the project via a [share](../members/share_project_with_groups.md). + +A group can also be added as an approver. [In the future](https://gitlab.com/gitlab-org/gitlab-ee/issues/2048), +group approvers will be restricted. + +If a user is added as an individual approver and is also part of a group approver, +then that user is just counted once. The merge request author, as well as users who have committed +to the merge request, do not count as eligible approvers, +if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) +and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) +are enabled on the project settings. + +### Implicit approvers + +If the number of required approvals is greater than the number of approvers, +other users will become implicit approvers to fill the gap. +Those implicit approvers include members of the given project with Developer role or higher. + +## Adding or removing an approval + +If approvals are activated for the given project, when a user visits an open +merge request, depending on their [eligibility](#eligible-approvers), one of +the following is possible: + +- **They are not an eligible approver**: They cannot do anything with respect + to approving this merge request. + +- **They have not approved this merge request**: + + - If the required number of approvals has _not_ been yet met, they can approve + it by clicking the displayed **Approve** button. +  + - If the required number of approvals has already been met, they can still + approve it by clicking the displayed **Approve additionally** button. +  + +- **They have already approved this merge request**: They can remove their approval. + +  + +NOTE: **Note:** +The merge request author is only allowed to approve their own merge request +if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is disabled on the project settings. + +For a given merge request, if the approval restrictions have been satisfied, +the merge request is unblocked and can be merged. +Note, that meeting the required number of approvals is a necessary, but not +sufficient condition for unblocking a merge request from being merged. There +are other conditions that may block it, such as merge conflicts, +[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved) +or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). + +## Code Owners approvals **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. + +It is possible to require at least one approval for each entry in the +[`CODEOWNERS` file](https://docs.gitlab.com/ee/user/project/code_owners.html) that matches a file changed in +the merge request. To enable this feature: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals**. +1. Tick the **Require approval from code owners** checkbox + checkbox. +1. Click **Save changes**. + +When this feature is enabled, all merge requests will need approval +from one code owner per matched rule before it can be merged. + +## Overriding the merge request approvals default settings + +> Introduced in GitLab Enterprise Edition 9.4. + +NOTE: **Note:** +If you are using GitLab Premium, things are a little different with [multiple approval rules](#multiple-approval-rules-premium). +Read the differences [in GitLab Premium when overriding merge request approvals](#overriding-merge-request-approvals-default-settings-premium). + +If approvals are [set at the project level](#editing-approvals), the +default configuration (number of required approvals and approvers) can be +overridden for each merge request in that project. + +One possible scenario would be to to assign a group of approvers at the project +level and change them later when creating or editing the merge request. + +First, you have to enable this option in the project's settings: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals** +1. Tick the "Can override approvers and approvals required per merge request" + checkbox + +  + +1. Click **Save changes** + +NOTE: **Note:** +If approver overriding is enabled +and the project level approvers are changed after a merge request is created, +the merge request retains the previous approvers. +However, the approvers can be changed by [editing the merge request](#overriding-the-merge-request-approvals-default-settings). + +--- + +The default approval settings can now be overridden when creating a +[merge request](index.md) or by editing it after it's been created: + +1. Click **Edit** under the **Approvers** section. +1. Search for users or groups that will be [eligible to approve](#eligible-approvers) + merge requests and click the **Add** button to add them as approvers or + remove existing approvers that were set in the project's settings. +1. If you want to change the number of required approvals, set a new number + in the **No. approvals required** box. +1. Click **Update approvers**. + +There are however some restrictions: + +- The amount of required approvals, if changed, must be greater than the default + set at the project level. This ensures that you're not forced to adjust settings + when someone is unavailable for approval, yet the process is still enforced. + +NOTE: **Note:** +If you are contributing to a forked project, things are a little different. +Read what happens when the +[source and target branches are not the same](#merge-requests-with-different-source-branch-and-target-branch-projects). + +## Overriding merge request approvals default settings **[PREMIUM]** + +In GitLab Premium, when the approval rules are [set at the project level](#editing-approvals-premium), and +**Can override approvers and approvals required per merge request** is checked, there are a few more +restrictions (compared to [GitLab Starter](#overriding-the-merge-request-approvals-default-settings)): + +- Approval rules can be added to an MR with no restriction. +- For project sourced approval rules, editing and removing approvers is not allowed. +- The approvals required of all approval rules is configurable, but if a rule is backed by a project rule, then it is restricted +to the minimum approvals required set in the project's corresponding rule. + +## Resetting approvals on push + +If approvals are [set at the project level](#editing-approvals), +you can choose whether all approvals on a merge request are removed when +new commits are pushed to the source branch of the merge request: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals** +1. Tick the "Remove all approvals in a merge request when new commits are pushed to its source branch" + checkbox + +  + +1. Click **Save changes** + +NOTE: **Note:** +Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) +from the UI. +However, approvals will be reset if the target branch is changed. + +If you want approvals to persist, independent of changes to the merge request, +turn this setting to off by unchecking the box and saving the changes. + +## Allowing merge request authors to approve their own merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. + +You can allow merge request authors to self-approve merge requests by +enabling it [at the project level](#editing-approvals). Authors +also need to be included in the approvers list in order to be able to +approve their merge request. + +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox, which is enabled by default. +1. Click **Save changes**. + +## Prevent approval of merge requests by their committers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. + +You can prevent users that have committed to a merge request from approving it by +enabling [**Prevent approval of merge requests by their committers**](#prevent-approval-of-merge-requests-by-their-committers). + +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Tick the checkbox **Prevent approval of merge requests by their committers**. +1. Click **Save changes**. + +## Merge requests with different source branch and target branch projects + +If the merge request source branch and target branch belong to different +projects (which happens in merge requests in forked projects), everything is +with respect to the target branch's project (typically the original project). +In particular, since the merge request in this case is part of the target +branch's project, the relevant settings are the target project's. The source +branch's project settings are not applicable. Even if you start the merge +request from the source branch's project UI, pay attention to the created merge +request itself. It belongs to the target branch's project. + +## Approver suggestions + +Approvers are suggested for merge requests based on the previous authors of the files affected by the merge request. + +## Filtering merge requests by approvers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9468) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.9. + +To filter merge requests by an individual approver, you can type (or select from +the dropdown) `approver` and select the user. + + diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md new file mode 100644 index 00000000000..688cc79d0f6 --- /dev/null +++ b/doc/user/project/merge_requests/sast.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/sast/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/sast/index.html). diff --git a/doc/user/project/merge_requests/sast_docker.md b/doc/user/project/merge_requests/sast_docker.md new file mode 100644 index 00000000000..4d41e424f4a --- /dev/null +++ b/doc/user/project/merge_requests/sast_docker.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html). diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md new file mode 100644 index 00000000000..0ad08da8ff5 --- /dev/null +++ b/doc/user/project/milestones/burndown_charts.md @@ -0,0 +1,70 @@ +# Burndown Charts **[STARTER]** + +> **Notes:** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. +> - [Added](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. +> - Closed or reopened issues prior to GitLab 9.1 won't have a `closed_at` +> value, so the burndown chart considers them as closed on the milestone +> `start_date`. In that case, a warning will be displayed. + +## Overview + +Burndown Charts are visual representations of the progress of completing a milestone. + + + +At a glance, you see the current state for the completion a given milestone. +Without them, you would have to organize the data from the milestone and plot it +yourself to have the same sense of progress. + +GitLab Starter plots it for you and presents it in a clear and beautiful chart. + +For an overview, check the video demonstration on [Mapping Work Versus Time, With Burndown Charts](https://about.gitlab.com/2017/04/25/mapping-work-to-do-versus-time-with-burndown-charts/). + +## Use cases + +Burndown Charts, in general, are used for tracking and analyzing the completion of +a milestone. Therefore, their use cases are tied to the +[use you are assigning your milestone to](index.md). + +To exemplify, suppose you lead a team of developers in a large company, +and you follow this workflow: + +- Your company set the goal for the quarter to deliver 10 new features for your app + in the upcoming major release. +- You create a milestone, and remind your team to assign that milestone to every new issue + and merge request that's part of the launch of your app. +- Every week, you open the milestone, visualize the progress, identify the gaps, + and help your team to get their work done. +- Every month, you check in with your supervisor, and show the progress of that milestone + from the Burndown Chart. +- By the end of the quarter, your team successfully delivered 100% of that milestone, as + it was taken care of closely throughout the whole quarter. + +## How it works + +A Burndown Chart is available for every project or group milestone that has been attributed a **start +date** and a **due date**. + +Find your project's **Burndown Chart** under **Project > Issues > Milestones**, +and select a milestone from your current ones, while for group's, access the **Groups** dashboard, +select a group, and go through **Issues > Milestones** on the sidebar. + +NOTE: **Note:** +You're able to [promote project](https://docs.gitlab.com/ee/user/project/milestones/#promoting-project-milestones-to-group-milestones) to group milestones and still see the **Burndown Chart** for them, respecting license limitations. + +The chart indicates the project's progress throughout that milestone (for issues assigned to it). + +In particular, it shows how many issues were or are still open for a given day in the +milestone's corresponding period. + +The Burndown Chart tracks when issues were created and when they were last closed—not their full history. For each day, it takes the number of issues still open and issues created that day and subtracts the number of issues closed that day. +**Issues that were created and assigned a milestone before its start date—and remain open as of the start date—are considered as having been opened on the start date**. Therefore, when the milestone start date is changed the number of opened issues on each day may change. +Reopened issues are +considered as having been opened on the day after they were last closed. + +The Burndown Chart can also be toggled to display the cumulative open issue +weight for a given day. When using this feature, make sure issue weights have +been properly assigned, since an open issue with no weight adds zero to the +cumulative value. diff --git a/doc/user/project/milestones/img/burndown_chart.png b/doc/user/project/milestones/img/burndown_chart.png Binary files differnew file mode 100644 index 00000000000..e06b24f9907 --- /dev/null +++ b/doc/user/project/milestones/img/burndown_chart.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index a7d6144e3ec..0d8ee0a6cd2 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -83,7 +83,10 @@ From the project issue/merge request list pages and the group issue/merge reques ### Filtering in issue boards -From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). +- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). +- From [group issue boards](../issue_board.md#group-issue-boards-premium), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **[PREMIUM]** +- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **[STARTER]** +- From [group issue boards](../issue_board.md#group-issue-boards-premium) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **[STARTER]** ### Special milestone filters @@ -98,16 +101,17 @@ When filtering by milestone, in addition to choosing a specific project mileston Not all features in the project milestone view are available in the group milestone view. This table summarizes the differences: -| Feature | Project milestone view | Group milestone view | -|---|:---:|:---:| -| Title an description | ✓ | ✓ | -| Issues assigned to milestone | ✓ | | -| Merge requests assigned to milestone | ✓ | | -| Participants and labels used | ✓ | | -| Percentage complete | ✓ | ✓ | -| Start date and due date | ✓ | ✓ | -| Total issue time spent | ✓ | ✓ | -| Total issue weight | ✓ | | +| Feature | Project milestone view | Group milestone view | +|--------------------------------------|:----------------------:|:--------------------:| +| Title an description | ✓ | ✓ | +| Issues assigned to milestone | ✓ | | +| Merge requests assigned to milestone | ✓ | | +| Participants and labels used | ✓ | | +| Percentage complete | ✓ | ✓ | +| Start date and due date | ✓ | ✓ | +| Total issue time spent | ✓ | ✓ | +| Total issue weight | ✓ | | +| Burndown chart **[STARTER}** | ✓ | ✓ | The milestone view shows the title and description. @@ -118,6 +122,17 @@ These features are only available for project milestones and not group milestone - Issues assigned to the milestone are displayed in three columns: Unstarted issues, ongoing issues, and completed issues. - Merge requests assigned to the milestone are displayed in four columns: Work in progress merge requests, waiting for merge, rejected, and closed. - Participants and labels that are used in issues and merge requests that have the milestone assigned are displayed. +- [Burndown chart](#project-burndown-charts-starter). + +### Project Burndown Charts **[STARTER]** + +For project milestones in [GitLab Starter](https://about.gitlab.com/pricing), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. + + + +### Group Burndown Charts **[PREMIUM]** + +For group milestones in [GitLab Premium](https://about.gitlab.com/pricing), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md new file mode 100644 index 00000000000..a5db3d70bb9 --- /dev/null +++ b/doc/user/project/operations/feature_flags.md @@ -0,0 +1,177 @@ +# Feature Flags **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 11.4. + +CAUTION: **Warning:** +This an _alpha_ feature and is subject to change at any time without +prior notice. + +Feature flags allow you to ship a project in different flavors by +dynamically toggling certain functionality. + +## Overview + +Feature Flags offer a feature toggle system for your application. They enable teams +to achieve Continuous Delivery by deploying new features to production at smaller +batches for controlled testing, separating feature delivery from customer launch. +This helps reducing risk and allows you to easily manage which features to enable. + +GitLab offers a Feature Flags interface that allows you to create, toggle and +remove feature flags. + +## How it works + +Underneath, GitLab uses [unleash](https://github.com/Unleash/unleash), a feature +toggle service. GitLab provides an API where your application can talk to and get the +list of feature flags you set in GitLab. + +The application must be configured to talk to GitLab, so that's up to the +developers to use a compatible [client library](#client-libraries) and +integrate it in their app. + +By setting a flag active or inactive via GitLab, your application will automatically +know which features to enable or disable respectively. + +## Adding a new feature flag + +To add a new feature flag: + +1. Navigate to your project's **Operations > Feature Flags**. +1. Click on the **New Feature Flag** button. +1. Give it a name. + + NOTE: **Note:** + A name can contain only lowercase letters, digits, underscores (`_`) + and dashes (`-`), must start with a letter, and cannot end with a dash (`-`) + or an underscore (`_`). + +1. Give it a description (optional, 255 characters max). +1. Define environment [specs](#define-environment-specs). If you want the flag on by default, enable the catch-all [wildcard spec (`*`)](#define-environment-specs) +1. Click **Create feature flag**. + +Once a feature flag is created, the list of existing feature flags will be presented +with ability to edit or remove them. + +To make a feature flag active or inactive, click the pencil icon to edit it, +and toggle the status for each [spec](#define-environment-specs). + + + +## Define environment specs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8621) in GitLab 11.8. + +In general, an application is deployed to multiple environments, such as +production, staging and [review apps](../../../ci/review_apps/index.md). +For example, you may not want to enable a feature flag on production until your QA team has +first confirmed that the feature is working correctly on testing environments. + +To handle these situations, you can enable a feature flag on a particular environment +with [Environment specs](../../../ci/environments.md#scoping-environments-with-specs-premium). +You can define multiple specs per flag so that you can control your feature flag more granularly. + +To define specs for each environment: + +1. Navigate to your project's **Operations > Feature Flags**. +1. Click on the **New Feature Flag** button or edit an existing flag. +1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) (`*`). This status will be used for _all_ environments. +1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) and type the environment name. +1. Set the status of the additional spec. This status takes precedence over the default spec's status since we always use the most specific match available. +1. Click **Create feature flag** or **Update feature flag**. + + + +NOTE: **NOTE** +We'd highly recommend you to use the [Environment](../../../ci/environments.md) +feature in order to quickly assess which flag is enabled per environment. + +## Integrating with your application + +In order to use Feature Flags, you need to first +[get the access credentials](#configuring-feature-flags) from GitLab and then +prepare your application and hook it with a [client library](#client-libraries). + +### Configuring Feature Flags + +To get the access credentials that your application will need to talk to GitLab: + +1. Navigate to your project's **Operations > Feature Flags**. +1. Click on the **Configure** button to see the values: + - **API URL**: URL where the client (application) connects to get a list of feature flags. + - **Instance ID**: Unique token that authorizes the retrieval of the feature flags. + - **Application name**: The name of the running environment. For instance, + if the application runs for production server, application name would be + `production` or similar. This value is used for + [the environment spec evaluation](#define-environment-specs). + +NOTE: **Note:** +The meaning of these fields might change over time. For example, we are not sure +if **Instance ID** will be single token or multiple tokens, assigned to the +**Environment**. Also, **Application name** could describe the version of +application instead of the running environment. + +### Client libraries + +GitLab currently implements a single backend that is compatible with +[Unleash](https://github.com/Unleash/unleash#client-implementations) clients. + +Unleash clients allow the developers to define in the app's code the default +values for flags. Each feature flag evaluation can express the desired +outcome in case the flag isn't present on the provided configuration file. + +Unleash currently offers a number of official SDKs for various frameworks and +a number of community contributed libraries. + +Official clients: + +- [unleash/unleash-client-java](https://github.com/unleash/unleash-client-java) +- [unleash/unleash-client-node](https://github.com/unleash/unleash-client-node) +- [unleash/unleash-client-go](https://github.com/unleash/unleash-client-go) +- [unleash/unleash-client-ruby](https://github.com/unleash/unleash-client-ruby) + +Community contributed clients: + +- [stiano/unleash-client-dotnet](https://github.com/stiano/unleash-client-dotnet) (.Net Core) +- [onybo/unleash-client-core](https://github.com/onybo/unleash-client-core) (.Net Core) +- [aes/unleash-client-python](https://github.com/aes/unleash-client-python) (Python 3) + +### Golang application example + +Here's an example of how to integrate the feature flags in a Golang application: + +```golang +package main + +import ( + "io" + "log" + "net/http" + + "github.com/Unleash/unleash-client-go" +) + +type metricsInterface struct { +} + +func init() { + unleash.Initialize( + unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"), + unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"), + unleash.WithAppName("production"), + unleash.WithListener(&metricsInterface{}), + ) +} + +func helloServer(w http.ResponseWriter, req *http.Request) { + if unleash.IsEnabled("my_feature_name") { + io.WriteString(w, "Feature enabled\n") + } else { + io.WriteString(w, "hello, world!\n") + } +} + +func main() { + http.HandleFunc("/", helloServer) + log.Fatal(http.ListenAndServe(":8080", nil)) +} +``` diff --git a/doc/user/project/operations/img/feature_flags_list.png b/doc/user/project/operations/img/feature_flags_list.png Binary files differnew file mode 100644 index 00000000000..5313a163fec --- /dev/null +++ b/doc/user/project/operations/img/feature_flags_list.png diff --git a/doc/user/project/operations/img/specs_list.png b/doc/user/project/operations/img/specs_list.png Binary files differnew file mode 100644 index 00000000000..9630c907cfc --- /dev/null +++ b/doc/user/project/operations/img/specs_list.png diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index b0f9936be5c..0086c15c98a 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -7,5 +7,5 @@ your applications: - Deploy to different [environments](../../../ci/environments.md). - Connect your project to a [Kubernetes cluster](../clusters/index.md). - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). -- Create, toggle, and remove [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html). **[PREMIUM]** -- [Trace](https://docs.gitlab.com/ee/user/project/operations/tracing.html) the performance and health of a deployed application. **[ULTIMATE]** +- Create, toggle, and remove [Feature Flags](feature_flags.md). **[PREMIUM]** +- [Trace](tracing.md) the performance and health of a deployed application. **[ULTIMATE]** diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md new file mode 100644 index 00000000000..0416e096cf2 --- /dev/null +++ b/doc/user/project/operations/tracing.md @@ -0,0 +1,34 @@ +# Tracing **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7903) in GitLab Ultimate 11.5. + +Tracing provides insight into the performance and health of a deployed application, +tracking each function or microservice which handles a given request. + +This makes it easy to +understand the end-to-end flow of a request, regardless of whether you are using a monolithic or distributed system. + +## Jaeger tracing + +[Jaeger](https://www.jaegertracing.io/) is an open source, end-to-end distributed +tracing system used for monitoring and troubleshooting microservices-based distributed +systems. + +### Deploying Jaeger + +To learn more about deploying Jaeger, read the official +[Getting Started documentation](https://www.jaegertracing.io/docs/latest/getting-started/). +There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/latest/getting-started/#AllinoneDockerimage), +as well as deployment options for [Kubernetes](https://github.com/jaegertracing/jaeger-kubernetes) +and [OpenShift](https://github.com/jaegertracing/jaeger-openshift). + +### Enabling Jaeger + +GitLab provides an easy way to open the Jaeger UI from within your project: + +1. [Set up Jaeger](#deploying-jaeger) and configure your application using one of the + [client libraries](https://www.jaegertracing.io/docs/latest/client-libraries/). +1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL. +1. Click **Save changes** for the changes to take effect. +1. You can now visit **Operations > Tracing** in your project's sidebar and + GitLab will redirect you to the configured Jaeger URL.
\ No newline at end of file diff --git a/doc/user/project/packages/img/maven_package_view.png b/doc/user/project/packages/img/maven_package_view.png Binary files differnew file mode 100644 index 00000000000..2eb4b6f76b4 --- /dev/null +++ b/doc/user/project/packages/img/maven_package_view.png diff --git a/doc/user/project/packages/img/npm_package_view.png b/doc/user/project/packages/img/npm_package_view.png Binary files differnew file mode 100644 index 00000000000..8baf7d0ef9f --- /dev/null +++ b/doc/user/project/packages/img/npm_package_view.png diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md new file mode 100644 index 00000000000..266225fdb8d --- /dev/null +++ b/doc/user/project/packages/maven.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'maven_repository.md' +--- + +This document was moved to [another location](maven_repository.md). diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md new file mode 100644 index 00000000000..266225fdb8d --- /dev/null +++ b/doc/user/project/packages/maven_packages.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'maven_repository.md' +--- + +This document was moved to [another location](maven_repository.md). diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md new file mode 100644 index 00000000000..94785eb6aec --- /dev/null +++ b/doc/user/project/packages/maven_repository.md @@ -0,0 +1,341 @@ +# GitLab Maven Repository **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in + [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. + +With the GitLab [Maven](https://maven.apache.org) Repository, every +project can have its own space to store its Maven artifacts. + + + +## Enabling the Maven Repository + +NOTE: **Note:** +This option is available only if your GitLab administrator has +[enabled support for the Maven repository](https://docs.gitlab.com/ee/administration/packages.html).**[PREMIUM ONLY]** + +After the Packages feature is enabled, the Maven Repository will be available for +all new projects by default. To enable it for existing projects, or if you want +to disable it: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages** section on the left sidebar. +Next, you must configure your project to authorize with the GitLab Maven +repository. + +## Authenticating to the GitLab Maven Repository + +If a project is private or you want to upload Maven artifacts to GitLab, +credentials will need to be provided for authorization. Support is available for +[personal access tokens](#authenticating-with-a-personal-access-token) and +[CI job tokens](#authenticating-with-a-ci-job-token) only. +[Deploy tokens](../deploy_tokens/index.md) and regular username/password +credentials do not work. + +### Authenticating with a personal access token + +To authenticate with a [personal access token](../../profile/personal_access_tokens.md), +add a corresponding section to your +[`settings.xml`](https://maven.apache.org/settings.html) file: + +```xml +<settings> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Private-Token</name> + <value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> +``` + +You should now be able to upload Maven artifacts to your project. + +### Authenticating with a CI job token + +If you're using Maven with GitLab CI/CD, a CI job token can be used instead +of a personal access token. + +To authenticate with a CI job token, add a corresponding section to your +[`settings.xml`](https://maven.apache.org/settings.html) file: + +```xml +<settings> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Job-Token</name> + <value>${env.CI_JOB_TOKEN}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> +``` + +You can read more on +[how to create Maven packages using GitLab CI/CD](#creating-maven-packages-with-gitlab-cicd). + +## Configuring your project to use the GitLab Maven repository URL + +To download and upload packages from GitLab, you need a `repository` and +`distributionManagement` section in your `pom.xml` file. + +Depending on your workflow and the amount of Maven packages you have, there are +3 ways you can configure your project to use the GitLab endpoint for Maven packages: + +- **Project level**: Useful when you have few Maven packages which are not under + the same GitLab group. +- **Group level**: Useful when you have many Maven packages under the same GitLab + group. +- **Instance level**: Useful when you have many Maven packages under different + GitLab groups or on their own namespace. + +NOTE: **Note:** +In all cases, you need a project specific URL for uploading a package in +the `distributionManagement` section. + +### Project level Maven endpoint + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `PROJECT_ID` with your project ID which can be found on the home page +of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project +(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the +project's ID can be used for uploading. + +### Group level Maven endpoint + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8798) in GitLab Premium 11.7. + +If you rely on many packages, it might be inefficient to include the `repository` section +with a unique URL for each package. Instead, you can use the group level endpoint for +all your Maven packages stored within one GitLab group. Only packages you have access to +will be available for download. + +The group level endpoint works with any package names, which means the you +have the flexibility of naming compared to [instance level endpoint](#instance-level-maven-endpoint). +However, GitLab will not guarantee the uniqueness of the package names within +the group. You can have two projects with the same package name and package +version. As a result, GitLab will serve whichever one is more recent. + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like. You still need a project specific URL for uploading a package in +the `distributionManagement` section: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/groups/my-group/-/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `my-group` with your group name and `PROJECT_ID` with your project ID +which can be found on the home page of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the group +(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`). + +### Instance level Maven endpoint + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8274) in GitLab Premium 11.7. + +If you rely on many packages, it might be inefficient to include the `repository` section +with a unique URL for each package. Instead, you can use the instance level endpoint for +all maven packages stored in GitLab and the packages you have access to will be available +for download. + +Note that **only packages that have the same path as the project** are exposed via +the instance level endpoint. + +| Project | Package | Instance level endpoint available | +| ------- | ------- | --------------------------------- | +| `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | +| `gitlab-org/gitlab-ce` | `foo/bar/1.0-SNAPSHOT` | No | +| `gitlab-org/gitlab-ce` | `gitlab-org/gitlab-ce/1.0-SNAPSHOT` | Yes | + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like. You still need a project specific URL for uploading a package in +the `distributionManagement` section: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `PROJECT_ID` with your project ID which can be found on the home page +of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project +(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the +project's ID can be used for uploading. + +## Uploading packages + +Once you have set up the [authentication](#authenticating-to-the-gitlab-maven-repository) +and [configuration](#configuring-your-project-to-use-the-gitlab-maven-repository-url), +test to upload a Maven artifact from a project of yours: + +```sh +mvn deploy +``` + +You can then navigate to your project's **Packages** page and see the uploaded +artifacts or even delete them. + +## Creating Maven packages with GitLab CI/CD + +Once you have your repository configured to use the GitLab Maven Repository, +you can configure GitLab CI/CD to build new packages automatically. The example below +shows how to create a new package each time the `master` branch is updated: + +1. Create a `ci_settings.xml` file that will serve as Maven's `settings.xml` file. + Add the server section with the same id you defined in your `pom.xml` file. + For example, in our case it's `gitlab-maven`: + + ```xml + <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Job-Token</name> + <value>${env.CI_JOB_TOKEN}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> + </settings> + ``` + +1. Make sure your `pom.xml` file includes the following: + + ```xml + <repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </repository> + </repositories> + <distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </snapshotRepository> + </distributionManagement> + ``` + + TIP: **Tip:** + You can either let Maven utilize the CI environment variables or hardcode your project's ID. + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + deploy: + image: maven:3.3.9-jdk-8 + script: + - 'mvn deploy -s ci_settings.xml' + only: + - master + ``` + +1. Push those files to your repository. + +The next time the `deploy` job runs, it will copy `ci_settings.xml` to the +user's home location (in this case the user is `root` since it runs in a +Docker container), and Maven will utilize the configured CI +[environment variables](../../../ci/variables/README.md#predefined-environment-variables). diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md new file mode 100644 index 00000000000..9f4c01c9a0a --- /dev/null +++ b/doc/user/project/packages/npm_registry.md @@ -0,0 +1,120 @@ +# GitLab NPM Registry **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934) + in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. + +With the GitLab NPM Registry, every +project can have its own space to store NPM packages. + + + +NOTE: **Note:** +Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. + + +NOTE: **Note:** +As `@group/subgroup/project` is not a valid NPM package name, publishing a package +within a subgroup is not supported yet. + +## Enabling the NPM Registry + +NOTE: **Note:** +This option is available only if your GitLab administrator has +[enabled support for the NPM registry](https://docs.gitlab.com/ee/administration/packages.html).**[PREMIUM ONLY]** + +After the NPM registry is enabled, it will be available for all new projects +by default. To enable it for existing projects, or if you want to disable it: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages** section on the left sidebar. + +Before proceeding to authenticating with the GitLab NPM Registry, you should +get familiar with the package naming convention. + +## Package naming convention + +**Only packages that have the same path as the project** are supported. For + example: + +| Project | Package | Supported | +| ---------------------- | ----------------------- | --------- | +| `foo/bar` | `@foo/bar` | Yes | +| `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes | +| `gitlab-org/gitlab-ce` | `@foo/bar` | No | + +Now, you can configure your project to authenticate with the GitLab NPM +Registry. + +## Authenticating to the GitLab NPM Registry + +If a project is private or you want to upload an NPM package to GitLab, +credentials will need to be provided for authentication. Support is available +only for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). + +CAUTION: **2FA not supported:** +Authentication for personal access tokens is not yet supported +([#9140](https://gitlab.com/gitlab-org/gitlab-ee/issues/9140)). If you have 2FA +enabled, you won't be able to authenticate to the GitLab NPM Registry. + +### Authenticating with an OAuth token + +To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow), +add a corresponding section to your `.npmrc` file: + +```ini +; Set URL for your scoped packages. +; For example package with name `@foo/bar` will use this URL for download +@foo:registry=https://gitlab.com/api/v4/packages/npm/ + +; Add the OAuth token for the scoped packages URL. This will allow you to download +; `@foo/` packages from private projects. +//gitlab.com/api/v4/packages/npm/:_authToken=<your_oauth_token> + +; Add OAuth token for uploading to the registry. Replace <your_project_id> +; with the project you want your package to be uploaded to. +//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_oauth_token> +``` + +Replace `<your_project_id>` with your project ID which can be found on the home page +of your project and `<your_oauth_token>` with your OAuth token. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +You should now be able to download and upload NPM packages to your project. + +## Uploading packages + +Before you will be able to upload a package, you need to specify the registry +for NPM. To do this, add the following section to the bottom of `package.json`: + +```json + "publishConfig": { + "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" + } +``` + +Replace `<your_project_id>` with your project ID, which can be found on the home +page of your project, and replace `@foo` with your own scope. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry), +you can upload an NPM package to your project: + +```sh +npm publish +``` + +You can then navigate to your project's **Packages** page and see the uploaded +packages or even delete them. + +## Uploading a package with the same version twice + +If you upload a package with a same name and version twice, GitLab will show +both packages in the UI, but the GitLab NPM Registry will expose the most recent +one as it supports only one package per version for `npm install`. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index f552f60a07e..87cd4941ae6 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -54,7 +54,7 @@ Of course, before building it, you had to install Jekyll in your computer. For that, you had to open your terminal and run `gem install jekyll`. Right? GitLab CI + GitLab Runner do the same thing. But you need to write in the `.gitlab-ci.yml` the script you want to run so -GitLab Runner will do it for you. It looks more complicated then it +GitLab Runner will do it for you. It looks more complicated than it is. What you need to tell the Runner: ``` diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 1034ba1733d..faf51154e3b 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -94,8 +94,9 @@ You can also take some **optional** further steps: - _Make it a user or group website._ To turn a **project website** forked from the Pages group into a **user/group** website, you'll need to: - - Rename it to `namespace.gitlab.io`: navigate to project's **Settings** > - expand **Advanced settings** > and scroll down to **Rename repository**. + - Rename it to `namespace.gitlab.io`: go to your project's + **Settings > General** and expand **Advanced**. Scroll down to + **Rename repository** and change the path to `namespace.gitlab.io`. - Adjust your SSG's [base URL](#urls-and-baseurls) from `"project-name"` to `""`. This setting will be at a different place for each SSG, as each of them have their own structure and file tree. Most likely, it will be in the SSG's diff --git a/doc/user/project/pipelines/img/pipeline_schedule_variables.png b/doc/user/project/pipelines/img/pipeline_schedule_variables.png Binary files differindex 74692add93a..29846206491 100644 --- a/doc/user/project/pipelines/img/pipeline_schedule_variables.png +++ b/doc/user/project/pipelines/img/pipeline_schedule_variables.png diff --git a/doc/user/project/pipelines/img/pipeline_schedules_new_form.png b/doc/user/project/pipelines/img/pipeline_schedules_new_form.png Binary files differindex 95203ec861b..e135dd51070 100644 --- a/doc/user/project/pipelines/img/pipeline_schedules_new_form.png +++ b/doc/user/project/pipelines/img/pipeline_schedules_new_form.png diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index 89f1beb6d1f..dd5427ab35a 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -79,7 +79,7 @@ For example, only two pipelines will be created per day if: To change the Sidekiq worker's frequency: -1. Edit the `pipeline_schedule_worker_cron` value in your instance's `gitlab.rb` file. +1. Edit the `gitlab_rails['pipeline_schedule_worker_cron']` value in your instance's `gitlab.rb` file. 1. [Restart GitLab](../../../administration/restart_gitlab.md). For GitLab.com, refer to the [dedicated settings page](../../gitlab_com/index.md#cron-jobs). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 2060b5dd4a2..56e8f1731ae 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -15,12 +15,10 @@ By default, a protected branch does four simple things: - it prevents **anyone** from force pushing to the branch - it prevents **anyone** from deleting the branch -See the [Changelog](#changelog) section for changes over time. +>**Note**: +A GitLab admin is allowed to push to the protected branches. -> ->Additional functionality for GitLab Enterprise Edition: -> ->- Restrict push and merge access to [certain users][ee-restrict] +See the [Changelog](#changelog) section for changes over time. ## Configuring protected branches @@ -68,6 +66,21 @@ dropdown list in the "Already protected" area. If you don't choose any of those options while creating a protected branch, they are set to "Maintainers" by default. +## Restricting push and merge access to certain users **[STARTER]** + +> This feature was [introduced][ce-5081] in [GitLab Starter][ee] 8.11. + +With GitLab Enterprise Edition you can restrict access to protected branches +by choosing a role (Maintainers, Developers) as well as certain users. From the +dropdown menu select the role and/or the users you want to have merge or push +access. + + + +Click **Protect** and the branch will appear in the "Protected branch" list. + + + ## Wildcard protected branches > [Introduced][ce-4665] in GitLab 8.10. @@ -169,3 +182,4 @@ for details about the pipelines security model. [ce-21393]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21393 [ee-restrict]: http://docs.gitlab.com/ee/user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users [perm]: ../permissions.md +[ee]: https://about.gitlab.com/pricing/ diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 2040e2ee004..15eb862b431 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -46,13 +46,15 @@ discussions, and descriptions: | `/remove_due_date` | Remove due date | ✓ | | | `/weight 0,1,2, ...` | Set weight **[STARTER]** | ✓ | | | `/clear_weight` | Clears weight **[STARTER]** | ✓ | | -| `/epic <group&epic | Epic URL>` | Add to epic **[ULTIMATE]** | ✓ | | +| `/epic <&epic | group&epic | Epic URL>` | Add to epic **[ULTIMATE]** | ✓ | | | `/remove_epic` | Removes from epic **[ULTIMATE]** | ✓ | | +| `/promote` | Promote issue to epic **[ULTIMATE]** | ✓ | | | `/confidential` | Make confidential | ✓ | | | `/duplicate #issue` | Mark this issue as a duplicate of another issue | ✓ | | `/move path/to/project` | Move this issue to another project | ✓ | | | `/target_branch <Local branch Name>` | Set target branch | | ✓ | | `/wip` | Toggle the Work In Progress status | | ✓ | +| `/approve` | Approve the merge request | | ✓ | | `/merge` | Merge (when pipeline succeeds) | | ✓ | | `/create_merge_request <branch name>` | Create a new merge request starting from the current issue | ✓ | | diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 6495ede42e0..3260a355fdc 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -264,7 +264,7 @@ To remove a GPG key from your account: ## Rejecting commits that are not signed **[PREMIUM]** You can configure your project to reject commits that aren't GPG-signed -via [push rules](https://docs.gitlab.com/ee/push_rules/push_rules.html). +via [push rules](../../../../push_rules/push_rules.md). ## GPG signing API diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 672567a8d7d..2339759ecc8 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -98,6 +98,12 @@ up its own internal state, maximizing the space saved. `git gc` against the repository. You will receive an email once it has completed. +This process will remove some copies of the rewritten commits from GitLab's +cache and database, but there are still numerous gaps in coverage - at present, +some of the copies may persist indefinitely. [Clearing the instance cache] +(../../../administration/raketasks/maintenance.md#clear-redis-cache) may help to +remove some of them, but it should not be depended on for security purposes! + ## Using `git filter-branch` 1. Navigate to your repository: diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md new file mode 100644 index 00000000000..43e910b29fe --- /dev/null +++ b/doc/user/project/security_dashboard.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html). diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md new file mode 100644 index 00000000000..1a582164d03 --- /dev/null +++ b/doc/user/project/service_desk.md @@ -0,0 +1,124 @@ +# Service Desk **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/149) in [GitLab Premium 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#service-desk-eep). + +## Overview + +Service Desk is a module that allows your team to connect directly +with any external party through email right inside of GitLab; no external tools required. +An ongoing conversation right where your software is built ensures that user feedback ends +up directly where it's needed, helping you build the right features to solve your users' +real problems. + +With Service Desk, you can provide efficient email support to your customers, who can now +email you bug reports, feature requests, or general feedback that will all end up in your +GitLab project as new issues. In turn, your team can respond straight from the project. + +As Service Desk is built right into GitLab itself, the complexity and inefficiencies +of multiple tools and external integrations are eliminated, significantly shortening +the cycle time from feedback to software update. + +For an overview, check the video demonstration on [GitLab Service Desk](https://about.gitlab.com/2017/05/09/demo-service-desk/). + +## Use cases + +For instance, let's assume you develop a game for iOS or Android. +The codebase is hosted in your GitLab instance, built and deployed +with GitLab CI. + +Here's how Service Desk will work for you: + +1. You'll provide a project-specific email address to your paying customers, who can email you directly from within the app +1. Each email they send creates an issue in the appropriate project +1. Your team members navigate to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues +1. Your team communicates back and forth with the customer to understand the request +1. Your team starts working on implementing code to solve your customer's problem +1. When your team finishes the implementation, whereupon the merge request is merged and the issue is closed automatically +1. The customer will have been attended successfully via email, without having real access to your GitLab instance +1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with your customer + +## How it works + +GitLab Service Desk is a simple way to allow people to create issues in your +GitLab instance without needing their own user account. + +It provides a unique email address for end users to create issues in a project, +and replies can be sent either through the GitLab interface or by email. End +users will only see the thread through email. + +## Configuring Service Desk + +> **Note:** +Service Desk is enabled on GitLab.com. If you're a +[Silver subscriber](https://about.gitlab.com/gitlab-com/), +you can skip the step 1 below; you only need to enable it per project. + +1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. This must + support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing). +2. Navigate to your project's **Settings** and scroll down to the **Service Desk** + section. +3. If you have the correct access and an Premium license, + you will see an option to set up Service Desk: + +  + +4. Checking that box will enable Service Desk for the project, and show a + unique email address to email issues to the project. These issues will be + [confidential](issues/confidential_issues.md), so they will only be visible to project members. + + **Warning**: this email address can be used by anyone to create an issue on + this project, whether or not they have access to your GitLab instance. + We recommend **putting this behind an alias** so that it can be changed if + needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab instance to add spam + checking to this service. Unblocked email spam would result in many spam + issues being created, and may disrupt your GitLab service. + +  + + _In GitLab 11.7, we updated the format of the generated email address. + However the older format is still supported, allowing existing aliases + or contacts to continue working._ + + +5. Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**: + +  + +## Using Service Desk + +### As an end user (issue creator) + +To create a Service Desk issue, an end user doesn't need to know anything about +the GitLab instance. They just send an email to the address they are given, and +receive an email back confirming receipt: + + + +This also gives the end user an option to unsubscribe. + +If they don't choose to unsubscribe, then any new comments added to the issue +will be sent as emails: + + + +And any responses they send will be displayed in the issue itself. + +### As a responder to the issue + +For responders to the issue, everything works as usual. They'll see a familiar looking +issue tracker, where they can see issues created via customer support requests and +filter and interact with them just like other GitLab issues. + + + +Messages from the end user will show as coming from the special Support Bot user, but apart from that, +you can read and write comments as you normally do: + + + +> Note that the project's visibility (private, internal, public) does not affect Service Desk. + +### Support Bot user + +Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user +does not count toward the license limit count. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index d5f4a7fd4ac..99dd018a3ba 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -42,9 +42,9 @@ Set up your project's merge request settings:  -### Service Desk +### Service Desk **[PREMIUM]** -Enable [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) for your project to offer customer support. Service Desk is available in [GitLab Premium](https://about.gitlab.com/pricing/). +Enable [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) for your project to offer customer support. ### Export project @@ -128,3 +128,7 @@ namespace if needed. ### Error Tracking Configure Error Tracking to discover and view [Sentry errors within GitLab](../operations/error_tracking.md). + +### Jaeger tracing **[ULTIMATE]** + +Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../operations/tracing.md). diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 46a1b2bc3aa..2a2507d98a3 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -128,5 +128,123 @@ IDE. An example `package.json` is below. } ``` +## Interactive Web Terminals for the Web IDE **[ULTIMATE ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. + +CAUTION: **Warning:** +Interactive Web Terminals for the Web IDE is currently in **Beta**. + +[Interactive web terminals](../../../ci/interactive_web_terminal/index.md) +give the user access to a terminal to interact with the Runner directly from +GitLab, including through the Web IDE. + +Only project [**maintainers**](../../permissions.md#project-members-permissions) +can run Interactive Web Terminals through the Web IDE. + +CAUTION: **Warning:** +GitLab.com [does not support Interactive Web Terminals yet](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611). +Shared Runners in private instances are not supported either. + +### Runner configuration + +Some things need to be configured in the runner for the interactive web terminal +to work: + +- The Runner needs to have + [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). +- If you are using a reverse proxy with your GitLab instance, web terminals need to be + [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **[ULTIMATE ONLY]** + +If you have the terminal open and the job has finished with its tasks, the +terminal will block the job from finishing for the duration configured in +[`[session_server].terminal_max_retention_time`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) +until you close the terminal window. + +NOTE: **Note:** Not all executors are +[supported](https://docs.gitlab.com/runner/executors/#compatibility-chart) + +### Web IDE configuration file + +In order to enable the Web IDE terminals you need to create the file +`.gitlab/.gitlab-webide.yml` inside the repository's root. This +file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md) +syntax but with some restrictions: + +- No global blocks can be defined (ie: `before_script` or `after_script`) +- Only one job named `terminal` can be added to this file. +- Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and +`variables` are allowed to be used to configure the job. +- To connect to the interactive terminal, the `terminal` job must be still alive +and running, otherwise the terminal won't be able to connect to the job's session. +By default the `script` keyword has the value `sleep 60` to prevent +the job from ending and giving the Web IDE enough time to connect. This means +that, if you override the default `script` value, you'll have to add a command +which would keep the job running, like `sleep`. + +In the code below there is an example of this configuration file: + +```yaml +terminal: + before_script: + - apt-get update + script: sleep 60 + variables: + RAILS_ENV: "test" + NODE_ENV: "test" +``` + +Once the terminal has started, the console will be displayed and we could access +the project repository files. + +**Important**. The terminal job is branch dependant. This means that the +configuration file used to trigger and configure the terminal will be the one in +the selected branch of the Web IDE. + +If there is no configuration file in a branch, an error message will be shown. + +### Running Interactive Terminals in the Web IDE + +If Interactive Terminals are available for the current user, the **Terminal** button +will be visible in the right sidebar of the Web IDE. Click this button to open +or close the terminal tab. + +Once open, the tab will show the **Start Web Terminal** button. This button may +be disabled if the environment is not configured correctly. If so, a status +message will describe the issue. Here are some reasons why **Start Web Terminal** +may be disabled: + +- `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly. +- No active private runners are available for the project. + +If active, clicking the **Start Web Terminal** button will load the terminal view +and start connecting to the runner's terminal. At any time, the **Terminal** tab +can be closed and reopened and the state of the terminal will not be affected. + +When the terminal is started and is successfully connected to the runner, then the +runner's shell prompt will appear in the terminal. From here, you can enter +commands that will be executed within the runner's environment. This is similar +to running commands in a local terminal or through SSH. + +While the terminal is running, it can be stopped by clicking **Stop Terminal**. +This will disconnect the terminal and stop the runner's terminal job. From here, +click **Restart Terminal** to start a new terminal session. + +### Limitations + +Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming +releases. In the meantime, please note that the user is limited to having only one +active terminal at a time. + +### Troubleshooting + +- If the terminal's text is gray and unresponsive, then the terminal has stopped + and it can no longer be used. A stopped terminal can be restarted by clicking + **Restart Terminal**. +- If the terminal displays **Connection Failure**, then the terminal could not + connect to the runner. Please try to stop and restart the terminal. If the + problem persists, double check your runner configuration. + + [ce]: https://about.gitlab.com/pricing/ [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md new file mode 100644 index 00000000000..38b26f31417 --- /dev/null +++ b/doc/user/search/advanced_global_search.md @@ -0,0 +1,75 @@ +# Advanced Global Search **[STARTER ONLY]** + +> - [Introduced][ee-109] in GitLab [Starter][ee] 8.4. +> - This is the user documentation. To install and configure Elasticsearch, +> visit the [administrator documentation](https://docs.gitlab.com/ee/integration/elasticsearch.html). + +NOTE: **Note** +Advanced Global Search (powered by Elasticsearch) is not yet available on GitLab.com. We are working on adding it. [Follow this epic for the latest updates](https://gitlab.com/groups/gitlab-org/-/epics/153). + +Leverage Elasticsearch for faster, more advanced code search across your entire +GitLab instance. + +## Overview + +The Advanced Global Search in GitLab is a powerful search service that saves +you time. Instead of creating duplicate code and wasting time, you can +now search for code within other teams that can help your own project. + +GitLab leverages the search capabilities of [Elasticsearch] and enables it when +searching in: + +- GitLab application +- Projects +- Repositories +- Commits +- Issues +- Merge requests +- Milestones +- Notes (comments) +- Snippets +- Wiki + +## Use cases + +The Advanced Global Search can be useful in various scenarios. + +### Faster searches + +If you are dealing with huge amount of data and want to keep GitLab's search +fast, the Advanced Global Search will help you achieve that. + +### Promote innersourcing + +Your company may consist of many different developer teams each of which has +their own group where the various projects are hosted. Some of your applications +may be connected to each other, so your developers need to instantly search +throughout the GitLab instance and find the code they search for. + +## Searching globally + +Just use the search as before and GitLab will show you matching code from each +project you have access to. + + + +You can also use the [Advanced Syntax Search](advanced_search_syntax.md) which +provides some useful queries. + +>**Note:** +Elasticsearch has only data for the default branch. That means that if you go +to the repository tree and switch the branch from the default to something else, +then the "Code" tab in the search result page will be served by the regular +search even if Elasticsearch is enabled. + +[ee-1305]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1305 +[aws-elastic]: http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html +[aws-iam]: http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html +[aws-instance-profile]: http://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli +[ee-109]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/109 "Elasticsearch Merge Request" +[elasticsearch]: https://www.elastic.co/products/elasticsearch "Elasticsearch website" +[install]: https://www.elastic.co/guide/en/elasticsearch/reference/current/_installation.html "Elasticsearch installation documentation" +[pkg]: https://about.gitlab.com/downloads/ "Download Omnibus GitLab" +[elastic-settings]: https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-configuration.html#settings "Elasticsearch configuration settings" +[ee]: https://about.gitlab.com/pricing/ +[es]: https://www.elastic.co/products/elasticsearch diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md new file mode 100644 index 00000000000..8d4aac5f502 --- /dev/null +++ b/doc/user/search/advanced_search_syntax.md @@ -0,0 +1,69 @@ +# Advanced Syntax Search **[STARTER ONLY]** + +> **Notes:** +> - Introduced in [GitLab Enterprise Starter][ee] 9.2 +> - This is the user documentation. To install and configure Elasticsearch, +> visit the [administrator documentation](https://docs.gitlab.com/ee/integration/elasticsearch.html). + +NOTE: **Note** +Advanced Global Search (powered by Elasticsearch) is not yet available on GitLab.com. We are working on adding it. [Follow this epic for the latest updates](https://gitlab.com/groups/gitlab-org/-/epics/153). + +Use advanced queries for more targeted search results. + +## Overview + +The Advanced Syntax Search is a subset of the +[Advanced Global Search](advanced_global_search.md), which you can use if you +want to have more specific search results. + +## Use cases + +Let's say for example that the product you develop relies on the code of another +product that's hosted under some other group. + +Since under your GitLab instance there are hosted hundreds of different projects, +you need the search results to be as efficient as possible. You have a feeling +of what you want to find (e.g., a function name), but at the same you're also +not so sure. + +In that case, using the advanced search syntax in your query will yield much +better results. + +## Using the Advanced Syntax Search + +The Advanced Syntax Search supports fuzzy or exact search queries with prefixes, +boolean operators, and much more. + +Full details can be found in the [Elasticsearch documentation][elastic], but +here's a quick guide: + +- Searches look for all the words in a query, in any order - e.g.: searching + issues for `display bug` will return all issues matching both those words, in any order. +- To find the exact phrase (stemming still applies), use double quotes: `"display bug"` +- To find bugs not mentioning display, use `-`: `bug -display` +- To find a bug in display or sound, use `|`: `bug display | sound` +- To group terms together, use parentheses: `bug | (display +sound)` +- To match a partial word, use `*`: `bug find_by_*` +- To find a term containing one of these symbols, use `\`: `argument \-last` + +### Syntax search filters + +The Advanced Syntax Search also supports the use of filters. The available filters are: + + - filename: Filters by filename. You can use the glob (`*`) operator for fuzzy matching. + - path: Filters by path. You can use the glob (`*`) operator for fuzzy matching. + - extension: Filters by extension in the filename. Please write the extension without a leading dot. Exact match only. + +To use them, simply add them to your query in the format `<filter_name>:<value>` without + any spaces between the colon (`:`) and the value. + +Examples: + +- Finding a file with any content named `hello_world.rb`: `* filename:hello_world.rb` +- Finding a file named `hello_world` with the text `whatever` inside of it: `whatever filename:hello_world` +- Finding the text 'def create' inside files with the `.rb` extension: `def create extension:rb` +- Finding the text `sha` inside files in a folder called `encryption`: `sha path:encryption` +- Finding any file starting with `hello` containing `world` and with the `.js` extension: `world filename:hello* extension:js` + +[ee]: https://about.gitlab.com/pricing/ +[elastic]: https://www.elastic.co/guide/en/elasticsearch/reference/5.3/query-dsl-simple-query-string-query.html#_simple_query_string_syntax diff --git a/doc/user/search/img/advanced_global_search.png b/doc/user/search/img/advanced_global_search.png Binary files differnew file mode 100644 index 00000000000..4903bbb07e1 --- /dev/null +++ b/doc/user/search/img/advanced_global_search.png diff --git a/doc/user/search/img/multiple_assignees.png b/doc/user/search/img/multiple_assignees.png Binary files differnew file mode 100644 index 00000000000..5c46f3dda46 --- /dev/null +++ b/doc/user/search/img/multiple_assignees.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 705983cce2a..bb6c48471c7 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -84,6 +84,12 @@ You can view recent searches by clicking on the little arrow-clock icon, which i Individual filters can be removed by clicking on the filter's (x) button or backspacing. The entire search filter can be cleared by clicking on the search box's (x) button. +## Filtering with multiple filters of the same type + +Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results will only include entries whereby the assignees are assigned to both Sam and Sarah are returned. + + + ### Shortcut You'll also find a shortcut on the search field on the top-right of the project's dashboard to @@ -136,3 +142,18 @@ you'll be able to, besides filtering them by **Name**, **Author**, **Assignee**, and **Labels**, select multiple issues to add to a list of your choice:  + +## Advanced Global Search **[STARTER]** + +Leverage Elasticsearch for faster, more advanced code search across your entire +GitLab instance. + +[Learn how to use the Advanced Global Search.](advanced_global_search.md) + +## Advanced Syntax Search **[STARTER]** + +Use advanced queries for more targeted search results. + +[Learn how to use the Advanced Syntax Search.](advanced_search_syntax.md) + +[ee]: https://about.gitlab.com/pricing/ |
