diff options
| author | Achilleas Pipinellis <axil@gitlab.com> | 2019-08-20 20:22:43 +0200 |
|---|---|---|
| committer | Achilleas Pipinellis <axil@gitlab.com> | 2019-08-20 20:22:43 +0200 |
| commit | e61308ce1d82e12e5087371469baea4a452875d1 (patch) | |
| tree | 62551a3ae4eab75e5af7e3b35358c07a51b2132f /doc/user | |
| parent | 4f323bb62fbe71a4352de25cab141f361a3fe1a6 (diff) | |
| parent | 2989ed078c1d45b0959dcecb1bc3c8f4740a3c0d (diff) | |
| download | gitlab-ce-docs-patch-71.tar.gz | |
Merge branch 'master' into docs-patch-71docs-patch-71
Diffstat (limited to 'doc/user')
415 files changed, 8134 insertions, 4727 deletions
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index 41ee7e62b2c..e6c86cc8f2e 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -1,6 +1,12 @@ # Abuse reports -Report abuse from users to GitLab administrators. +You can report abuse from other GitLab users to GitLab administrators. + +A GitLab administrator [can then choose](admin_area/abuse_reports.md) to: + +- Remove the user, which deletes them from the instance. +- Block the user, which denies them access to the instance. +- Or remove the report, which retains the users access to the instance. You can report a user through their: @@ -12,7 +18,8 @@ You can report a user through their: To report abuse from a user's profile page: -1. Click on the exclamation point report abuse button at the top right of the user's profile. +1. Click on the exclamation point report abuse button at the top right of the + user's profile. 1. Complete an abuse report. 1. Click the **Send report** button. @@ -26,15 +33,18 @@ To report abuse from a user's comment: 1. Click the **Send report** button. NOTE: **Note:** -A URL to the reported user's comment will be -pre-filled in the abuse report's **Message** field. +A URL to the reported user's comment will be pre-filled in the abuse report's +**Message** field. ## Reporting abuse through a user's issue or merge request The **Report abuse** button is displayed at the top right of the issue or merge request: -- When **Report abuse** is selected from the menu that appears when the **Close issue** or **Close merge request** button is clicked, for users that have permission to close the issue or merge request. -- When viewing the issue or merge request, for users that don't have permission to close the issue or merge request. +- When **Report abuse** is selected from the menu that appears when the + **Close issue** or **Close merge request** button is clicked, for users that + have permission to close the issue or merge request. +- When viewing the issue or merge request, for users that don't have permission + to close the issue or merge request. With the **Report abuse** button displayed, to submit an abuse report: diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 01c2d9607f5..0c5d2f81e25 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -1,31 +1,77 @@ +--- +type: reference, howto +--- + # Abuse reports View and resolve abuse reports from GitLab users. -Admins can view abuse reports in the admin area and are able to -resolve the reports by removing the reported user, blocking the reported user, or removing the report. +GitLab administrators can view and [resolve](#resolving-abuse-reports) abuse +reports in the Admin Area. ## Reporting abuse -To find out more about reporting abuse, see [abuse reports user documentation](../abuse_reports.md). +To find out more about reporting abuse, see [abuse reports user +documentation](../abuse_reports.md). ## Resolving abuse reports -To access abuse reports, go to **Admin area > Abuse Reports**. +To access abuse reports, go to **Admin Area > Abuse Reports**. There are 3 ways to resolve an abuse report, with a button for each method: -- Remove user & report: [Deletes the reported user](../profile/account/delete_account.md) from the instance and removes the abuse report from the list. -- Block user: Blocks the reported user from the instance and does not remove the abuse report from the list. -- Remove report: Removes the abuse report from the list and does not restrict the access for the reported user. +- Remove user & report. This will: + - [Delete the reported user](../profile/account/delete_account.md) from the + instance. + - Remove the abuse report from the list. +- [Block user](#blocking-users). +- Remove report. This will: + - Remove the abuse report from the list. + - Remove access restrictions for the reported user. + +The following is an example of the **Abuse Reports** page:  -## Blocked users +### Blocking users + +A blocked user cannot log in or access any repositories, but all of their data +remains. + +Blocking a user: + +- Leaves them in the abuse report list. +- Changes the **Block user** button to a disabled **Already blocked** button. + +The user will be notified with the +[following message](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/app/workers/email_receiver_worker.rb#L38): -Blocking a user will not remove the abuse report from the list. +```text +Your account has been blocked. If you believe this is in error, contact a staff member. +``` -Instead, the block button will be disabled and explain that the user is "Already blocked". -You are still able to remove the user and/or report if necessary. +After blocking, you can still either: + +- Remove the user and report if necessary. +- Remove the report. + +The following is an example of a blocked user listed on the **Abuse Reports** +page:  + +NOTE: **Note:** +Users can be [blocked](../../api/users.md#block-user) and +[unblocked](../../api/users.md#unblock-user) using the GitLab API. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 02445abdb37..01b6558bdbe 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Broadcast Messages GitLab can display messages to all users of a GitLab instance in a banner that appears in the UI. @@ -51,3 +55,15 @@ Once deleted, the broadcast message is removed from the list of broadcast messag NOTE: **Note:** Broadcast messages can be deleted while active. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index e34ba045c54..02c2efaa4f3 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -1,26 +1,49 @@ -# Custom instance-level project templates **[PREMIUM ONLY]** +--- +type: reference +--- -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing) 11.2. +# Custom instance-level project templates **(PREMIUM ONLY)** -When you create a new [project](../project/index.md), creating it based on custom project templates is -a convenient bootstrap option. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. -GitLab administrators can configure a GitLab group that serves as template -source for an entire GitLab instance under **Admin area > Settings > Custom project templates**. +GitLab administrators can configure the group where all the custom project +templates are sourced. + +Every project directly under the group namespace will be +available to the user if they have access to them. For example: + +- Public project in the group will be available to every logged in user. +- Private projects will be available only if the user is a member of the project. + +Repository and database information that are copied over to each new project are +identical to the data exported with +[GitLab's Project Import/Export](../project/settings/import_export.md). NOTE: **Note:** To set project templates at a group level, see [Custom group-level project templates](../group/custom_project_templates.md). -Within this section, you can configure the group where all the custom project -templates are sourced. Every project directly under the group namespace will be -available to the user if they have access to them. For example, every public -project in the group will be available to every logged in user. +## Configuring -However, private projects will be available only if the user is a member of the project. +GitLab administrators can configure a GitLab group that serves as template +source for an entire GitLab instance by: + +1. Navigating to **Admin area > Settings > Templates**. +1. Expanding **Custom project templates**. +1. Selecting a group to use. +1. Pressing **Save changes**. NOTE: **Note:** Projects below subgroups of the template group are **not** supported. -Repository and database information that are copied over to each new project are -identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index d99b87cbc5c..39753fd885e 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -2,7 +2,7 @@ type: howto --- -# Geo nodes admin area **[PREMIUM ONLY]** +# Geo nodes admin area **(PREMIUM ONLY)** You can configure various settings for GitLab Geo nodes. For more information, see [Geo documentation](../../administration/geo/replication/index.md). @@ -61,6 +61,12 @@ 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**. +CAUTION: **Warning:** +We recommend using an HTTPS connection while configuring the Geo nodes. To avoid +breaking communication between **primary** and **secondary** nodes when using +HTTPS, customize your Internal URL to point to a load balancer with TLS +terminated at the load balancer. + ## Multiple secondary nodes behind a load balancer In GitLab 11.11, **secondary** nodes can use identical external URLs as long as @@ -83,4 +89,4 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. -->
\ No newline at end of file +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/admin_area/img/abuse_report_blocked_user.png b/doc/user/admin_area/img/abuse_report_blocked_user.png Binary files differindex 0cb4c7bb8ac..435d8dfe821 100644 --- a/doc/user/admin_area/img/abuse_report_blocked_user.png +++ b/doc/user/admin_area/img/abuse_report_blocked_user.png diff --git a/doc/user/admin_area/img/abuse_reports_page.png b/doc/user/admin_area/img/abuse_reports_page.png Binary files differindex 81dbe976cda..30e932211cb 100644 --- a/doc/user/admin_area/img/abuse_reports_page.png +++ b/doc/user/admin_area/img/abuse_reports_page.png diff --git a/doc/user/admin_area/img/broadcast_messages.png b/doc/user/admin_area/img/broadcast_messages.png Binary files differindex 926d38ae049..f0ae92f8c17 100644 --- a/doc/user/admin_area/img/broadcast_messages.png +++ b/doc/user/admin_area/img/broadcast_messages.png diff --git a/doc/user/admin_area/img/license_details.png b/doc/user/admin_area/img/license_details.png Binary files differindex 2085bb437ad..3e980d9316d 100644 --- a/doc/user/admin_area/img/license_details.png +++ b/doc/user/admin_area/img/license_details.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 91c771764f8..9bc0f64b68d 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -2,7 +2,7 @@ type: reference --- -# GitLab Admin Area **[CORE ONLY]** +# GitLab Admin Area **(CORE ONLY)** The Admin Area provides a web UI for administering some features of GitLab self-managed instances. @@ -18,22 +18,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](#administer-users), [groups](#administer-groups), [jobs](#administer-jobs), [Runners](#administer-runners), and [Gitaly servers](#administer-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](../../push_rules/push_rules.md) 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. | +| Section | Description | +|:------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [Runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | +| Monitoring | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit logs](#audit-log-premium-only). | +| 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](../../push_rules/push_rules.md) 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 @@ -46,16 +46,20 @@ To access the Dashboard, either: The Dashboard is the default view of the Admin Area, and is made up of the following sections: -| Section | Description | -|------------|---------------| -| Projects | The total number of projects, up to 10 of the latest projects, and the option of creating a new project. | -| Users | The total number of users, up to 10 of the latest users, and the option of creating a new user. | -| Groups | The total number of groups, up to 10 of the latest groups, and the option of creating a new group. | -| Statistics | Totals of all elements of the GitLab instance. | +| Section | Description | +|:-----------|:---------------------------------------------------------------------------------------------------------------------------------------------------------| +| Projects | The total number of projects, up to 10 of the latest projects, and the option of creating a new project. | +| Users | The total number of users, up to 10 of the latest users, and the option of creating a new user. | +| Groups | The total number of groups, up to 10 of the latest groups, and the option of creating a new group. | +| Statistics | Totals of all elements of the GitLab instance. | | Features | All features available on the GitLab instance. Enabled features are marked with a green circle icon, and disabled features are marked with a power icon. | -| Components | The major components of GitLab and the version number of each. A link to the Gitaly Servers is also included. | +| Components | The major components of GitLab and the version number of each. A link to the Gitaly Servers is also included. | -## Administer Projects +## Overview section + +The following topics document the **Overview** section of the Admin Area. + +### Administering Projects You can administer all projects in the GitLab instance from the Admin Area's Projects page. @@ -95,7 +99,7 @@ You can combine the filter options. For example, to list only public projects wi 1. Click the **Public** tab. 1. Enter `score` in the **Filter by name...** input box. -## Administer Users +### Administering Users You can administer all users in the GitLab instance from the Admin Area's Users page. @@ -120,7 +124,7 @@ To search for users, enter your criteria in the search field. The user search is insensitive, and applies partial matching to name and username. To search for an email address, you must provide the complete email address. -## Administer Groups +### Administering Groups You can administer all groups in the GitLab instance from the Admin Area's Groups page. @@ -139,7 +143,7 @@ insensitive, and applies partial matching. To [Create a new group](../group/index.md#create-a-new-group) click **New group**. -## Administer Jobs +### Administering Jobs You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. @@ -163,9 +167,9 @@ For each job, the following details are listed: | Timing | Duration of the job, and how long ago the job completed. | | Coverage | Percentage of tests coverage. | -## Administer Runners +### Administering Runners -You can adminster all Runners in the GitLab instance from the Admin Area's **Runners** page. See +You can administer all Runners in the GitLab instance from the Admin Area's **Runners** page. See [GitLab Runner](https://docs.gitlab.com/runner/) for more information on Runner itself. To access the **Runners** page, go to **Admin Area > Overview > Runners**. @@ -182,7 +186,7 @@ the sort order to *Last Contacted* from the dropdown beside the search field. To search Runners' descriptions: 1. In the **Search or filter results...** field, type the description of the Runner you want to -find. + find. 1. Press Enter. You can also filter Runners by status, type, and tag. To filter: @@ -209,7 +213,7 @@ For each Runner, the following attributes are listed: You can also edit, pause, or remove each Runner. -## Administer Gitaly servers +### Administering Gitaly servers You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** page. For more details, see [Gitaly](../../administration/gitaly/index.md). @@ -225,3 +229,66 @@ For each Gitaly server, the following details are listed: | Server version | Gitaly version | | Git version | Version of Git installed on the Gitaly server | | Up to date | Indicates if the Gitaly server version is the latest version available. A green dot indicates the server is up to date. | + +## Monitoring section + +The following topics document the **Monitoring** section of the Admin Area. + +### System Info + +The **System Info** page provides the following statistics: + +| Field | Description | +| :----------- | :---------- | +| CPU | Number of CPU cores available | +| Memory Usage | Memory in use, and total memory available | +| Disk Usage | Disk space in use, and total disk space available | +| Uptime | Approximate uptime of the GitLab instance | + +These statistics are updated only when you navigate to the **System Info** page, or you refresh the page in your browser. + +### Background Jobs + +The **Background Jobs** page displays the Sidekiq dashboard. Sidekiq is used by GitLab to +perform processing in the background. + +The Sidekiq dashboard consists of the following elements: + +- A tab per jobs' status. +- A breakdown of background job statistics. +- A live graph of **Processed** and **Failed** jobs, with a selectable polling interval. +- An historical graph of **Processed** and **Failed** jobs, with a selectable time span. +- Redis statistics, including: + - Version number + - Uptime, measured in days + - Number of connections + - Current memory usage, measured in MB + - Peak memory usage, measured in MB + +### Logs + +The **Logs** page provides access to the following log files: + +| Log file | Contents | +| :---------------------- | :------- | +| `application.log` | GitLab user activity | +| `git_json.log` | Failed GitLab interaction with Git repositories | +| `production.log` | Requests received from Unicorn, and the actions taken to serve those requests | +| `sidekiq.log` | Background jobs | +| `repocheck.log` | Repository activity | +| `integrations_json.log` | Activity between GitLab and integrated systems | +| `kubernetes.log` | Kubernetes activity | + +The contents of these log files can be useful when troubleshooting a problem. Access is available to GitLab admins, without requiring direct access to the log files. + +For details of these log files and their contents, see [Log system](../../administration/logs.md). + +The content of each log file is listed in chronological order. To minimize performance issues, a maximum 2000 lines of each log file are shown. + +### Requests Profiles + +The **Requests Profiles** page contains the token required for profiling. For more details, see [Request Profiling](../../administration/monitoring/performance/request_profiling.md). + +### Audit Log **(PREMIUM ONLY)** + +The **Audit Log** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change. diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index eba27548f86..1d15be89bd5 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -2,7 +2,7 @@ type: reference --- -# Labels administration **[CORE ONLY]** +# Labels administration **(CORE ONLY)** In the Admin Area, you can manage labels for the GitLab instance. For more details, see [Labels](../project/labels.md). diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 8ddb9c3d707..f5864e1f828 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -2,7 +2,7 @@ type: howto --- -# Activate all GitLab Enterprise Edition functionality with a license **[STARTER ONLY]** +# 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 @@ -30,22 +30,22 @@ 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**. + 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 diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index f80d4e9d2aa..35e7b6fb541 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -41,42 +41,51 @@ The readiness and liveness probes will provide a report of system health in JSON ```json { - "queues_check" : { - "status" : "ok" + "db_check":{ + "status":"ok" }, - "redis_check" : { - "status" : "ok" + "redis_check":{ + "status":"ok" }, - "shared_state_check" : { - "status" : "ok" + "cache_check":{ + "status":"ok" }, - "db_check" : { - "status" : "ok" + "queues_check":{ + "status":"ok" }, - "cache_check" : { - "status" : "ok" + "shared_state_check":{ + "status":"ok" + }, + "gitaly_check":{ + "status":"ok", + "labels":{ + "shard":"default" + } + } } -} ``` `liveness` probe example output: ```json { - "cache_check" : { - "status" : "ok" + "db_check":{ + "status":"ok" + }, + "redis_check":{ + "status":"ok" }, - "db_check" : { - "status" : "ok" + "cache_check":{ + "status":"ok" }, - "redis_check" : { - "status" : "ok" + "queues_check":{ + "status":"ok" }, - "queues_check" : { - "status" : "ok" + "shared_state_check":{ + "status":"ok" }, - "shared_state_check" : { - "status" : "ok" + "gitaly_check":{ + "status":"ok" } } ``` diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 001e4b6bf48..6faab685b26 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -4,7 +4,18 @@ type: reference # Account and limit settings -## Repository size limit **[STARTER]** +## Max attachment size + +You can change the maximum file size for attachments in comments and replies in GitLab. +Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**. +From here, you can increase or decrease by changing the value in `Maximum attachment size (MB)`. + +NOTE: **Note:** +If you choose a size larger than what is currently configured for the web server, +you will likely get errors. See the [troubleshooting section](#troubleshooting) for more +details. + +## Repository size limit **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/740) in [GitLab Enterprise Edition 8.12](https://about.gitlab.com/2016/09/22/gitlab-8-12-released/#limit-project-size-ee). > Available in [GitLab Starter](https://about.gitlab.com/pricing/). @@ -41,22 +52,28 @@ These settings can be found within: - The path `/admin/application_settings`. The first push of a new project, including LFS objects, will be checked for size -and **will** be rejected if the sum of their sizes exceeds the maximum allowed +and **will** be rejected if the sum of their sizes exceeds the maximum allowed repository size. +**Note:** The repository size limit includes repository files and LFS, and does not include artifacts. + For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). NOTE: **Note:** -For GitLab.com, the repository size limit is 10 GB. +GitLab.com repository size [is set by GitLab](../../gitlab_com/index.md#repository-size-limit). + +## Troubleshooting + +### 413 Request Entity Too Large -<!-- ## Troubleshooting +If you are attaching a file to a comment or reply in GitLab and receive the `413 Request Entity Too Large` +error, it is likely caused by having a [max attachment size](#max-attachment-size) +larger than what the web server is configured to allow. -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +If you wanted to increase the max attachment size to 200m in a GitLab +[Omnibus](https://docs.gitlab.com/omnibus/) install, for example, you might need to +add the line below to `/etc/gitlab/gitlab.rb` before increasing the max attachment size: -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +``` +nginx['client_max_body_size'] = "200m" +``` diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index d2605cbfb5e..bd76b052422 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -2,14 +2,14 @@ type: reference --- -# Continuous Integration and Deployment Admin settings **[CORE ONLY]** +# Continuous Integration and Deployment Admin settings **(CORE ONLY)** In this area, you will find settings for Auto DevOps, Runners and job artifacts. You can find it in the admin area, under **Settings > Continuous Integration and Deployment**.  -## Auto DevOps **[CORE ONLY]** +## Auto DevOps **(CORE ONLY)** To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: @@ -26,7 +26,7 @@ From now on, every existing project and newly created ones that don't have a If you want to disable it for a specific project, you can do so in [its settings](../../../topics/autodevops/index.md#enablingdisabling-auto-devops). -## Maximum artifacts size **[CORE ONLY]** +## Maximum artifacts size **(CORE ONLY)** 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 @@ -38,7 +38,7 @@ To change it: 1. Change the value of maximum artifacts size (in MB). 1. Hit **Save changes** for the changes to take effect. -## Default artifacts expiration **[CORE ONLY]** +## Default artifacts expiration **(CORE ONLY)** The default expiration time of the [job artifacts](../../../administration/job_artifacts.md) can be set in the Admin area of your GitLab instance. The syntax of duration is @@ -54,7 +54,7 @@ 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]** +## Shared Runners pipeline minutes quota **(STARTER ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1078) in GitLab Starter 8.16. @@ -89,60 +89,12 @@ 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. +You can see an overview of the pipeline minutes quota of all projects of +a group in the **Usage Quotas** page available to the group page settings list.  - -## Extra Shared Runners pipeline minutes quota - -NOTE: **Note:** -Only available on GitLab.com. - -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: - -  - -Be aware that: - -1. If you have purchased extra CI minutes before the purchase of a paid plan, -we will calculate a pro-rated charge for your paid plan. That means you may -be charged for less than one year since your subscription was previously -created with the extra CI minutes. -1. Once the extra CI minutes has been assigned to a Group they cannot be transferred -to a different Group. -1. 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. - -## What happens when my CI minutes quota run out - -When the CI minutes quota run out, an email is sent automatically to notifies the owner(s) of the group/namespace which -includes a link to [purchase more minutes](https://customers.gitlab.com/plans). - -If you are not the owner of the group, you will need to contact them to let them know they need to -[purchase more minutes](https://customers.gitlab.com/plans). - -## Archive jobs **[CORE ONLY]** +## Archive jobs **(CORE ONLY)** Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some of the capabilities of the jobs (metadata needed to run the job), @@ -169,3 +121,23 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> + +## Required pipeline configuration **(PREMIUM ONLY)** + +GitLab administrators can force a pipeline configuration to run on every +pipeline. + +The configuration applies to all pipelines for a GitLab instance and is +sourced from: + +- The [instance template repository](instance_template_repository.md). +- GitLab-supplied configuration. + +To set required pipeline configuration: + +1. Go to **Admin area > Settings > CI/CD**. +1. Expand the **Required pipeline configuration** section. +1. Select the required configuration from the provided dropdown. +1. Click **Save changes**. + + diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 9555a695b13..490163c1816 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -10,18 +10,17 @@ You can customize some of the content in emails sent from your GitLab instance. 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]** +## 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. - - +1. Go to **Admin Area > Settings > Preferences** (`/admin/application_settings/preferences`). +1. Expand the **Email** section. +1. Enter your text in the **Additional text** field. +1. Click **Save**. [ee-5031]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5031 [eep]: https://about.gitlab.com/pricing/ @@ -35,11 +34,13 @@ This configuration option sets the email hostname for [private commit emails](.. In order to change this option: -1. Go to **Admin area > Settings** (`/admin/application_settings`). -1. Under the **Email** section, change the **Custom hostname (for private commit emails)** field. -1. Hit **Save** for the changes to take effect. +1. Go to **Admin Area > Settings > Preferences** (`/admin/application_settings/preferences`). +1. Expand the **Email** section. +1. Enter the desire hostname in the **Custom hostname (for private commit emails)** field. +1. Click **Save changes**. -NOTE: **Note**: Once the hostname gets configured, every private commit email using the previous hostname, will not get +NOTE: **Note:** +Once the hostname gets configured, every private commit email using the previous hostname, will not get recognized by GitLab. This can directly conflict with certain [Push rules](../../../push_rules/push_rules.md) such as `Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`. @@ -53,4 +54,4 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. -->
\ No newline at end of file +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 11c0867da17..4fde7477490 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -2,10 +2,10 @@ type: reference --- -# External authorization control **[CORE ONLY]** +# 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. +> [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. > [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27056) to > [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. @@ -76,13 +76,19 @@ service with this body: { "user_identifier": "jane@acme.org", "project_classification_label": "project-label", - "user_ldap_dn": "CN=Jane Doe,CN=admin,DC=acme" + "user_ldap_dn": "CN=Jane Doe,CN=admin,DC=acme", + "identities": [ + { "provider": "ldap", "extern_uid": "CN=Jane Doe,CN=admin,DC=acme" }, + { "provider": "bitbucket", "extern_uid": "2435223452345" } + ] } ``` The `user_ldap_dn` is optional and is only sent when the user is logged in through LDAP. +`identities` will contain the details of all the identities associated with the user. This will be an empty array if there are no identities associated with the user. + When the external authorization service responds with a status code 200, the user is granted access. When the external service responds with a status code 401 or 403, the user is denied access. In any case, the request is cached for 6 hours. diff --git a/doc/user/admin_area/settings/img/additional_minutes.png b/doc/user/admin_area/settings/img/additional_minutes.png Binary files differdeleted file mode 100644 index d148ed79b92..00000000000 --- a/doc/user/admin_area/settings/img/additional_minutes.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/admin_required_pipeline.png b/doc/user/admin_area/settings/img/admin_required_pipeline.png Binary files differnew file mode 100644 index 00000000000..501b1e3ba0a --- /dev/null +++ b/doc/user/admin_area/settings/img/admin_required_pipeline.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 differdeleted file mode 100644 index 0cc88b8a48f..00000000000 --- a/doc/user/admin_area/settings/img/buy_btn.png +++ /dev/null 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 differdeleted file mode 100644 index cf4ad34ead7..00000000000 --- a/doc/user/admin_area/settings/img/buy_minutes_card.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/email_confirmation.png b/doc/user/admin_area/settings/img/email_confirmation.png Binary files differnew file mode 100644 index 00000000000..987aa10c3ce --- /dev/null +++ b/doc/user/admin_area/settings/img/email_confirmation.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 differdeleted file mode 100644 index ed0a80d10ce..00000000000 --- a/doc/user/admin_area/settings/img/email_settings.png +++ /dev/null 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 differindex d94b609ad6f..318527426bd 100644 --- a/doc/user/admin_area/settings/img/group_pipelines_quota.png +++ b/doc/user/admin_area/settings/img/group_pipelines_quota.png diff --git a/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png b/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png Binary files differnew file mode 100644 index 00000000000..c32eb93c8a8 --- /dev/null +++ b/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png diff --git a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png Binary files differnew file mode 100644 index 00000000000..53dc0e4ac87 --- /dev/null +++ b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index eed087ae52b..2a12614e325 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -2,7 +2,7 @@ type: index --- -# Admin Area settings **[CORE ONLY]** +# Admin Area settings **(CORE ONLY)** In the Admin Area **Settings** page, you can find various options for your GitLab instance like sign-up restrictions, account limits and quota, metrics, etc. @@ -10,7 +10,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]** +- [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) @@ -18,7 +18,8 @@ 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]** +- [User and IP rate limits](user_and_ip_rate_limits.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 index 91286a67c31..f2ba131d17b 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -2,10 +2,10 @@ type: reference --- -# Instance template repository **[PREMIUM ONLY]** +# 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. +> [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. ## Overview diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md new file mode 100644 index 00000000000..8e53a6995fb --- /dev/null +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -0,0 +1,22 @@ +--- +type: reference +--- + +# Rate limits on raw endpoints **(CORE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30829) in GitLab 12.2. + +This setting allows you to rate limit the requests to raw endpoints, defaults to `300` requests per minute. +It can be modified in **Admin Area > Network > Performance Optimization**. + +For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/controllers/application_controller.rb` will be blocked. Access to the raw file will be released after 1 minute. + + + +This limit is: + +- Applied independently per project, per commit and per file path. +- Not applied per IP address. +- Active by default. To disable, set the option to `0`. + +Requests over the rate limit are logged into `auth.log`. diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index cebf36c7ec1..1b1bcbcd6e8 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -4,19 +4,26 @@ type: reference # Sign-up restrictions -You can block email addresses of specific domains, or whitelist only some -specific domains via the **Application Settings** in the Admin area. +You can use sign-up restrictions to require user email confirmation, as well as +to blacklist or whitelist email addresses belonging to specific domains. >**Note**: These restrictions are only applied during sign-up. An admin is able to add a user through the admin panel with a disallowed domain. Also note that the users can change their email addresses after signup to disallowed domains. +## Require email confirmation + +You can send confirmation emails during sign-up and require that users confirm +their email address before they are allowed to sign in. + + + ## Whitelist email domains > [Introduced][ce-598] in GitLab 7.11.0 -You can restrict users to only signup using email addresses matching the given +You can restrict users to only sign up using email addresses matching the given domains list. ## Blacklist email domains @@ -24,17 +31,23 @@ domains list. > [Introduced][ce-5259] in GitLab 8.10. With this feature enabled, you can block email addresses of a specific domain -from creating an account on your GitLab server. This is particularly useful to -prevent spam. Disposable email addresses are usually used by malicious users to -create dummy accounts and spam issues. +from creating an account on your GitLab server. This is particularly useful +to prevent malicious users from creating spam accounts with disposable email +addresses. ## Settings -This feature can be activated via the **Application Settings** in the Admin area, -and you have the option of entering the list manually, or uploading a file with -the list. +To access this feature: + +1. Navigate to the **Settings > General** in the Admin area. +1. Expand the **Sign-up restrictions** section. + +For the blacklist, you can enter the list manually or upload a `.txt` file that +contains list entries. + +For the whitelist, you must enter the list manually. -Both whitelist and blacklist accept wildcards, so for example, you can use +Both the whitelist and blacklist accept wildcards. For example, you can use `*.company.com` to accept every `company.com` subdomain, or `*.io` to block all domains ending in `.io`. Domains should be separated by a whitespace, semicolon, comma, or a new line. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index a5f8d05f662..a1bce5a6c69 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -17,7 +17,7 @@ To enforce acceptance of a Terms of Service and Privacy Policy: 1. Go to **Admin Area > Settings > General**. 1. Expand the **Terms of Service and Privacy Policy** section. 1. Check the **Require all users to accept Terms of Service and Privacy Policy when they access -GitLab.** checkbox. + GitLab.** checkbox. 1. Input the text of the **Terms of Service and Privacy Policy**. Markdown formatting can be used in this input box. 1. Click **Save changes**. 1. When you are presented with the **Terms of Service** statement, click **Accept terms**. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 652d6ad2cdd..516600c9d99 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -10,7 +10,7 @@ to perform various actions. All statistics are opt-out, you can enable/disable them from the admin panel under **Admin area > Settings > Metrics and profiling > Usage statistics**. -## Version check **[CORE ONLY]** +## Version check **(CORE ONLY)** If enabled, version check will inform you if a new version is available and the importance of it through a status. This is shown on the help page (i.e. `/help`) @@ -33,7 +33,7 @@ secure. If you disable version check, this information will not be collected. Enable or disable the version check at **Admin area > Settings > Usage statistics**. -## Usage ping **[CORE ONLY]** +## Usage ping **(CORE ONLY)** > [Introduced][ee-557] in GitLab Enterprise Edition 8.10. More statistics [were added][ee-735] in GitLab Enterprise Edition @@ -52,8 +52,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). - +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 @@ -78,7 +78,7 @@ production: &base usage_ping_enabled: false ``` -## Instance statistics visibility **[CORE ONLY]** +## Instance statistics visibility **(CORE ONLY)** Once usage ping is enabled, GitLab will gather data from other instances and will be able to show [usage statistics](../../instance_statistics/index.md) diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md new file mode 100644 index 00000000000..e3a495750f2 --- /dev/null +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -0,0 +1,32 @@ +--- +type: reference +--- + +# User and IP rate limits + +Rate limiting is a common technique used to improve the security and durability +of a web application. For more details, see +[Rate limits](../../../security/rate_limits.md). + +The following limits can be enforced in **Admin Area > Network > User and +IP rate limits**: + +- Unauthenticated requests +- Authenticated API requests +- Authenticated web requests + +These limits are disabled by default. + + + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> 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 a1229484388..bf59f49b993 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -4,12 +4,15 @@ type: reference # Visibility and access controls -GitLab allows admins to: +GitLab allows administrators to: - Control access and visibility to GitLab resources including branches and projects. - Select from which hosting sites code can be imported into GitLab. - Select the protocols permitted to access GitLab. - Enable or disable repository mirroring. +- Prevent non-administrators from deleting projects + ([introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5615) in GitLab 12.0). + **(PREMIUM ONLY)** To access the visibility and access control options: diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md new file mode 100644 index 00000000000..b7389c8689d --- /dev/null +++ b/doc/user/analytics/cycle_analytics.md @@ -0,0 +1,182 @@ +# Cycle Analytics + +> - Introduced prior to GitLab 12.2 at the project level. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2 at the group level (enabled by feature flag `analytics`). + +Cycle Analytics measures the time spent to go from an [idea to production] - also known +as cycle time - for each of your projects. Cycle Analytics displays the median time for an idea to +reach production, along with the time typically spent in each DevOps stage along the way. + +Cycle Analytics is useful in order to quickly determine the velocity of a given +project. It points to bottlenecks in the development process, enabling management +to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. + +Cycle Analytics is tightly coupled with the [GitLab flow] and +calculates a separate median for each stage. + +## Overview + +Cycle Analytics is available: + +- From GitLab 12.2, at the group level in the analytics workspace at + **Analytics > Cycle Analytics**. **(PREMIUM)** + + In the future, multiple groups will be selectable which will effectively make this an + instance-level feature. + + NOTE: **Note:** + Requires the [analytics workspace](index.md) to be enabled. + +- At the project level via **Project > Cycle Analytics**. + +There are seven stages that are tracked as part of the Cycle Analytics calculations. + +- **Issue** (Tracker) + - Time to schedule an issue (by milestone or by adding it to an issue board) +- **Plan** (Board) + - Time to first commit +- **Code** (IDE) + - Time to create a merge request +- **Test** (CI) + - Time it takes GitLab CI/CD to test your code +- **Review** (Merge Request/MR) + - Time spent on code review +- **Staging** (Continuous Deployment) + - Time between merging and deploying to production +- **Production** (Total) + - Total lifecycle time; i.e. the velocity of the project or team + +## How the data is measured + +Cycle Analytics records cycle time and data based on the project issues with the +exception of the staging and production stages, where only data deployed to +production are measured. + +Specifically, if your CI is not set up and you have not defined a `production` +or `production/*` [environment], then you will not have any data for those stages. + +Each stage of Cycle Analytics is further described in the table below. + +| **Stage** | **Description** | +| --------- | --------------- | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list](../project/issue_board.md#creating-a-new-list) created for it. | +| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | +| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the issue closing pattern is not present in the merge request description, the MR is not considered to the measurement time of the stage. | +| Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | +| Review | Measures the median time taken to review the merge request that has closing issue pattern, between its creation and until it's merged. | +| Staging | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the [environment] set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. | +| Production| The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. | + +--- + +How this works, behind the scenes: + +1. Issues and merge requests are grouped together in pairs, such that for each + `<issue, merge request>` pair, the merge request has the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) + for the corresponding issue. All other issues and merge requests are **not** + considered. +1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified + by the UI - default is 90 days). So it prohibits these pairs from being considered. +1. For the remaining `<issue, merge request>` pairs, we check the information that + we need for the stages, like issue creation date, merge request merge time, + etc. + +To sum up, anything that doesn't follow [GitLab flow] will not be tracked and the +Cycle Analytics dashboard will not present any data for: + +- merge requests that do not close an issue. +- issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. +- staging and production stages, if the project has no `production` or `production/*` + environment. + +## Example workflow + +Below is a simple fictional workflow of a single cycle that happens in a +single day passing through all seven stages. Note that if a stage does not have +a start and a stop mark, it is not measured and hence not calculated in the median +time. It is assumed that milestones are created and CI for testing and setting +environments is configured. + +1. Issue is created at 09:00 (start of **Issue** stage). +1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of + **Plan** stage). +1. Start working on the issue, create a branch locally and make one commit at + 12:00. +1. Make a second commit to the branch which mentions the issue number at 12.30 + (stop of **Plan** stage / start of **Code** stage). +1. Push branch and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) + in its description at 14:00 (stop of **Code** stage / start of **Test** and + **Review** stages). +1. The CI starts running your scripts defined in [`.gitlab-ci.yml`][yml] and + takes 5min (stop of **Test** stage). +1. Review merge request, ensure that everything is OK and merge the merge + request at 19:00. (stop of **Review** stage / start of **Staging** stage). +1. Now that the merge request is merged, a deployment to the `production` + environment starts and finishes at 19:30 (stop of **Staging** stage). +1. The cycle completes and the sum of the median times of the previous stages + is recorded to the **Production** stage. That is the time between creating an + issue and deploying its relevant merge request to production. + +From the above example you can conclude the time it took each stage to complete +as long as their total time: + +- **Issue**: 2h (11:00 - 09:00) +- **Plan**: 1h (12:00 - 11:00) +- **Code**: 2h (14:00 - 12:00) +- **Test**: 5min +- **Review**: 5h (19:00 - 14:00) +- **Staging**: 30min (19:30 - 19:00) +- **Production**: Since this stage measures the sum of median time off all + previous stages, we cannot calculate it if we don't know the status of the + stages before. In case this is the very first cycle that is run in the project, + then the **Production** time is 10h 30min (19:30 - 09:00) + +A few notes: + +- In the above example we demonstrated that it doesn't matter if your first + commit doesn't mention the issue number, you can do this later in any commit + of the branch you are working on. +- You can see that the **Test** stage is not calculated to the overall time of + the cycle since it is included in the **Review** process (every MR should be + tested). +- The example above was just **one cycle** of the seven stages. Add multiple + cycles, calculate their median time and the result is what the dashboard of + Cycle Analytics is showing. + +## Permissions + +The current permissions on the Project Cycle Analytics dashboard are: + +- Public projects - anyone can access +- Internal projects - any authenticated user can access +- Private projects - any member Guest and above can access + +You can [read more about permissions][permissions] in general. + +NOTE: **Note:** +As of GitLab 12.2, the project-level page is deprecated. You should access +project-level Cycle Analytics from **Analytics > Cycle Analytics** in the top +navigation bar. We will ensure that the same project-level functionality is available +to CE users in the new analytics space. + +For Cycle Analytics functionality introduced in GitLab 12.2 and later: + +- Users must have Reporter access or above. +- Features are available only on + [Premium or Silver tiers](https://about.gitlab.com/pricing/) and above. + +## More resources + +Learn more about Cycle Analytics in the following resources: + +- [Cycle Analytics feature page](https://about.gitlab.com/features/cycle-analytics/) +- [Cycle Analytics feature preview](https://about.gitlab.com/2016/09/16/feature-preview-introducing-cycle-analytics/) +- [Cycle Analytics feature highlight](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/) + +[ce-5986]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5986 +[ce-20975]: https://gitlab.com/gitlab-org/gitlab-ce/issues/20975 +[environment]: ../../ci/yaml/README.md#environment +[GitLab flow]: ../../workflow/gitlab_flow.md +[idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab +[permissions]: ../permissions.md +[yml]: ../../ci/yaml/README.md diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md new file mode 100644 index 00000000000..ec719c0b4a1 --- /dev/null +++ b/doc/user/analytics/index.md @@ -0,0 +1,22 @@ +# Analytics workspace + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in GitLab 12.2 (enabled using `analytics` feature flag). + +The Analytics workspace will make it possible to aggregate analytics across +GitLab, so that users can view information across multiple projects and groups +in one place. + +To access the centralized analytics workspace: + +1. Ensure it's enabled. Requires a GitLab administrator to enable it with the `analytics` feature + flag. +1. Once enabled, click on **Analytics** from the top navigation bar. + +## Available analytics + +From the centralized analytics workspace, the following analytics are available: + +- [Cycle Analytics](cycle_analytics.md). + +NOTE: **Note:** +Project-level Cycle Analytics are still available at a project's **Project > Cycle Analytics**. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index a24374dff1d..86491c7d74e 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,4 +1,8 @@ -# Container Scanning **[ULTIMATE]** +--- +type: reference, howto +--- + +# Container Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. @@ -10,7 +14,7 @@ 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 +You can take advantage of Container Scanning by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto Container Scanning](../../../topics/autodevops/index.md#auto-container-scanning-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -40,11 +44,14 @@ To enable Container Scanning in your pipeline, you need: [`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. +- Docker `18.09.03` or higher installed on the machine where the Runners are + running. If you're using the shared Runners on GitLab.com, this is already + the case. - 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: - ``` + ```text $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA ``` @@ -52,32 +59,16 @@ To enable Container Scanning in your pipeline, you need: [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). +## Configuration -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. +For GitLab 11.9 and later, to enable Container Scanning, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +in that template. -To enable Container Scanning using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -86,12 +77,12 @@ include: 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. +1. Create a `container_scanning` job in your CI/CD pipeline. +1. 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 +The results 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 @@ -103,95 +94,6 @@ If you want to whitelist some specific vulnerabilities, you can do so by definin 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/README.html#predefined-environment-variables - CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG - CI_APPLICATION_TAG: $CI_COMMIT_SHA - CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1 - 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:${CLAIR_LOCAL_SCAN_VERSION} - - 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/README.html#predefined-environment-variables - CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG - CI_APPLICATION_TAG: $CI_COMMIT_SHA - CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1 - 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:${CLAIR_LOCAL_SCAN_VERSION} - - 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 @@ -202,3 +104,25 @@ vulnerabilities in your groups and projects. Read more about the 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). + +## Vulnerabilities database update + +For more information about the vulnerabilities database update, check the +[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). + +## Troubleshooting + +### docker: Error response from daemon: failed to copy xattrs + +When the GitLab Runner uses the Docker executor and NFS is used +(e.g., `/var/lib/docker` is on an NFS mount), Container Scanning might fail with +an error like the following: + +```text +docker: Error response from daemon: failed to copy xattrs: failed to set xattr "security.selinux" on /path/to/file: operation not supported. +``` + +This is a result of a bug in Docker which is now [fixed](https://github.com/containerd/continuity/pull/138 "fs: add WithAllowXAttrErrors CopyOpt"). +To prevent the error, ensure the Docker version that the Runner is using is +`18.09.03` or higher. For more information, see +[issue #10241](https://gitlab.com/gitlab-org/gitlab-ee/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index a722aa88f9d..fa84f995e58 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,8 +1,17 @@ -# Dynamic Application Security Testing (DAST) **[ULTIMATE]** +--- +type: reference, howto +--- + +# 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. +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. + 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, @@ -14,7 +23,7 @@ Dynamic Application Security Testing (DAST) comes into place. 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 +You can take advantage of DAST by either [including the CI job](#configuration) 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). @@ -51,30 +60,16 @@ applications while you are developing and testing your applications. To run a DAST job, you need GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -## 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 +## Configuration -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). +For GitLab 11.9 and later, to enable DAST, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`DAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +in that template. -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: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -84,22 +79,22 @@ variables: DAST_WEBSITE: https://example.com ``` +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. + 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 +The results 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 +### Authenticated scan It's also possible to authenticate the user before performing the DAST checks: @@ -117,12 +112,12 @@ variables: 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 +The results 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 +### 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: @@ -135,7 +130,7 @@ variables: DAST_FULL_SCAN_ENABLED: "true" ``` -#### Customizing the DAST settings +### Customizing the DAST settings The DAST settings can be changed through environment variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -155,7 +150,7 @@ variables: 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 +### 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 @@ -176,78 +171,27 @@ 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] -``` +## Available variables + +DAST can be [configured](#customizing-the-dast-settings) using environment variables. +Since it's a wrapper around the ZAP scanning scripts +([baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) +or [full](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) scan), it +accepts all arguments those scripts recognize (the arguments are the same). +The choice of the scan type depends on the `DAST_FULL_SCAN_ENABLED` environment +variable value. + +| Environment variable | Required | Description | +|-----------------------------| ----------|--------------------------------------------------------------------------------| +| `DAST_WEBSITE` | yes | The URL of the website to scan. | +| `DAST_AUTH_URL` | no | The authentication URL of the website to scan. | +| `DAST_USERNAME` | no | The username to authenticate to in the website. | +| `DAST_PASSWORD` | no | The password to authenticate to in the website. | +| `DAST_USERNAME_FIELD` | no | The name of username field at the sign-in HTML form. | +| `DAST_PASSWORD_FIELD` | no | The name of password field at the sign-in HTML form. | +| `DAST_AUTH_EXCLUDE_URLS` | no | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. | +| `DAST_TARGET_AVAILABILITY_TIMEOUT` | no | Time limit in seconds to wait for target availability. Scan is attempted nevertheless if it runs out. Integer. Defaults to `60`. | +| `DAST_FULL_SCAN_ENABLED` | no | Switches the tool to execute [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | ## Security Dashboard @@ -259,3 +203,20 @@ vulnerabilities in your groups and projects. Read more about the 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). + +## Vulnerabilities database update + +For more information about the vulnerabilities database update, check the +[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png Binary files differnew file mode 100644 index 00000000000..af9cee08d71 --- /dev/null +++ b/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md new file mode 100644 index 00000000000..38c38bbd8a9 --- /dev/null +++ b/doc/user/application_security/dependency_list/index.md @@ -0,0 +1,49 @@ +# Dependency List **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. + +The Dependency list allows you to see your project's dependencies, and key +details about them, including their known vulnerabilities. To see it, +navigate to **Security & Compliance > Dependency List** in your project's +sidebar. + +## Requirements + +1. The [Dependency Scanning](../dependency_scanning/index.md) CI job must be + configured for your project. +1. Your project uses at least one of the + [languages and package managers](../dependency_scanning/index.md#supported-languages-and-package-managers) + supported by Gemnasium. + +## Viewing dependencies + + + +Dependencies are displayed with the following information: + +| Field | Description | +| --------- | ----------- | +| Status | Displays whether or not the dependency has any known vulnerabilities | +| Component | The dependency's name | +| Version | The exact locked version of the dependency your project uses | +| Packager | The packager used to install the depedency | +| Location | A link to the packager-specific lockfile in your project that declared the dependency | + +Dependencies shown are initially sorted by their names. They can also be sorted +by the packager they were installed by, or by the severity of their known +vulnerabilities. + +There is a second list under the `Vulnerable components` tab displaying only +those dependencies with known vulnerabilities. If there are none, this tab is +disabled. + +### Vulnerabilities + +If a dependency has known vulnerabilities, they can be viewed by clicking on the +`Status` cell of that dependency. The severity and description of each +vulnerability will then be displayed below it. + +## Downloading the Dependency List + +Your project's full list of dependencies and their details can be downloaded in +`JSON` format by clicking on the download button. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md new file mode 100644 index 00000000000..3b4b341739b --- /dev/null +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -0,0 +1,133 @@ +# Dependency Scanning Analyzers **(ULTIMATE)** + +Dependency Scanning relies on underlying third party tools that are wrapped into +what we call "Analyzers". An analyzer is a +[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) +that wraps a particular tool to: + +- Expose its detection logic. +- Handle its execution. +- Convert its output to the common format. + +This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common). + +Dependency Scanning supports the following official analyzers: + +- [`bundler-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) +- [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) +- [`gemnasium-maven`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven) +- [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) +- [`retire.js`](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) + +The analyzers are published as Docker images that Dependency Scanning will use +to launch dedicated containers for each analysis. + +Dependency Scanning is pre-configured with a set of **default images** that are +maintained by GitLab, but users can also integrate their own **custom images**. + +## Official default analyzers + +Any custom change to the official analyzers can be achieved by using an +[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings). + +### Using a custom Docker mirror + +You can switch to a custom Docker registry that provides the official analyzer +images under a different prefix. For instance, the following instructs Dependency +Scanning to pull `my-docker-registry/gl-images/gemnasium` +instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium`. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_ANALYZER_IMAGE_PREFIX: my-docker-registry/gl-images +``` + +This configuration requires that your custom registry provides images for all +the official analyzers. + +### Selecting specific analyzers + +You can select the official analyzers you want to run. Here's how to enable +`bundler-audit` and `gemnasium` while disabling all the other default ones. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DEFAULT_ANALYZERS: "bundler-audit,gemnasium" +``` + +`bundler-audit` runs first. When merging the reports, Dependency Scanning will +remove the duplicates and will keep the `bundler-audit` entries. + +### Disabling default analyzers + +Setting `DS_DEFAULT_ANALYZERS` to an empty string will disable all the official +default analyzers. In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DEFAULT_ANALYZERS: "" +``` + +That's needed when one totally relies on [custom analyzers](#custom-analyzers). + +## Custom analyzers + +You can provide your own analyzers as a comma separated list of Docker images. +Here's how to add `analyzers/nugget` and `analyzers/perl` to the default images. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_ANALYZER_IMAGES: "my-docker-registry/analyzers/nugget,amy-docker-registry/nalyzers/perl" +``` + +The values must be the full path to the container registry images, +like what you would feed to the `docker pull` command. + +NOTE: **Note:** +This configuration doesn't benefit from the integrated detection step. Dependency +Scanning has to fetch and spawn each Docker image to establish whether the +custom analyzer can scan the source code. + +## Analyzers data + +The following table lists the data available for each official analyzer. + +| Property \ Tool | Gemnasium | bundler-audit | Retire.js | +|---------------------------------------|:------------------:|:------------------:|:------------------:| +| Severity | 𐄂 | ✓ | ✓ | +| Title | ✓ | ✓ | ✓ | +| File | ✓ | ⚠ | ✓ | +| Start line | 𐄂 | 𐄂 | 𐄂 | +| End line | 𐄂 | 𐄂 | 𐄂 | +| External ID (e.g., CVE) | ✓ | ✓ | ⚠ | +| URLs | ✓ | ✓ | ✓ | +| Internal doc/explanation | ✓ | 𐄂 | 𐄂 | +| Solution | ✓ | ✓ | 𐄂 | +| Confidence | 𐄂 | 𐄂 | 𐄂 | +| Affected item (e.g. class or package) | ✓ | ✓ | ✓ | +| Source code extract | 𐄂 | 𐄂 | 𐄂 | +| Internal ID | ✓ | 𐄂 | 𐄂 | +| Date | ✓ | 𐄂 | 𐄂 | +| Credits | ✓ | 𐄂 | 𐄂 | + +- ✓ => we have that data +- ⚠ => we have that data but it's partially reliable, or we need to extract that data from unstructured content +- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. + +The values provided by these tools are heterogeneous so they are sometimes +normalized into common values (e.g., `severity`, `confidence`, etc). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index f3bf743ad03..3148ec63c79 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -1,4 +1,8 @@ -# Dependency Scanning **[ULTIMATE]** +--- +type: reference, howto +--- + +# Dependency Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. @@ -8,7 +12,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. 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) +You can take advantage of Dependency Scanning by either [including the CI job](#configuration) 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). @@ -46,43 +50,45 @@ this is enabled by default. 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). +| Language (package managers) | Supported | Scan tool(s) | +|----------------------------- | --------- | ------------ | +| Java ([Gradle](https://gradle.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/13075 "Dependency Scanning for Gradle" )) | not available | +| Java ([Maven](https://maven.apache.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js) | +| Go ([Golang](https://golang.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7132 "Dependency Scanning for Go")) | not available | +| PHP ([Composer](https://getcomposer.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Python ([Pipfile](https://docs.pipenv.org/en/latest/basics/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available | +| Python ([poetry](https://poetry.eustace.io/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7006 "Support Poetry in Dependency Scanning")) | not available | +| Ruby ([gem](https://rubygems.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | -## Configuring Dependency Scanning +## Remote checks -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). +While some tools pull a local database to check vulnerabilities, some others +like Gemnasium require sending data to GitLab central servers to analyze them: -This can be done in two ways: +1. Gemnasium scans the dependencies of your project locally and sends a list of + packages to GitLab central servers. +1. The servers return the list of known vulnerabilities for all versions of + these packages. +1. The client picks up the relevant vulnerabilities by comparing with the versions + of the packages that are used by the project. -- 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. +The Gemnasium client does **NOT** send the exact package versions your project relies on. -### Including the provided template +You can disable the remote checks by [using](#customizing-the-dependency-scanning-settings) +the `DS_DISABLE_REMOTE_CHECKS` environment variable and setting it to `true`. -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). +## Configuration -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. +For GitLab 11.9 and later, to enable Dependency Scanning, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +that template. -To enable Dependency Scanning using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -92,22 +98,15 @@ include: 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 +The results 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 +### Customizing the Dependency Scanning settings -The Dependency Scanning settings can be changed through environment variables by using the +The Dependency Scanning settings can be changed through [environment variables](#available-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: @@ -116,13 +115,13 @@ include: template: Dependency-Scanning.gitlab-ci.yml variables: - DEP_SCAN_DISABLE_REMOTE_CHECKS: true + DS_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 +### 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 @@ -137,88 +136,34 @@ dependency_scanning: 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] -``` +### Available variables + +Dependency Scanning can be [configured](#customizing-the-dependency-scanning-settings) +using environment variables. + +| Environment variable | Function | +|-------------------------------- |----------| +| `DS_ANALYZER_IMAGES` | Comma separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). | +| `DS_ANALYZER_IMAGE_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | +| `DS_ANALYZER_IMAGE_TAG` | Override the Docker tag of the official default images. Read more about [customizing analyzers](analyzers.md). | +| `DS_PYTHON_VERSION` | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12296) in GitLab 12.1)| +| `DS_PIP_DEPENDENCY_PATH` | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12412) in GitLab 12.2) | +| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | +| `DS_DISABLE_REMOTE_CHECKS` | Do not send any data to GitLab. Used in the [Gemnasium analyzer](#remote-checks). | +| `DS_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to `0` to disable). | +| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | +| `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | +| `DS_PULL_ANALYZER_IMAGE_TIMEOUT` | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | +| `DS_RUN_ANALYZER_TIMEOUT` | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | +| `PIP_INDEX_URL` | Base URL of Python Package Index (default `https://pypi.org/simple`). | +| `PIP_EXTRA_INDEX_URL` | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. | ## Reports JSON format CAUTION: **Caution:** The JSON report artifacts are not a public API of Dependency Scanning and their format may change in future. -The Dependency Scanning tool emits a JSON report file. Here is an example of a structure for a report will all important parts of +The Dependency Scanning tool emits a JSON report file. Here is an example of the report structure with all important parts of it highlighted: ```json-doc @@ -343,10 +288,10 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].severity` | How much the vulnerability impacts the software. Possible values: `Undefined` (an analyzer has not provided this info), `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. | | `vulnerabilities[].confidence` | How reliable the vulnerability's assessment is. Possible values: `Undefined` (an analyzer has not provided this info), `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, `Confirmed`. | | `vulnerabilities[].solution` | Explanation of how to fix the vulnerability. Optional. | -| `vulnerabilities[].scanner` | A node that describes the analyzer used find this vulnerability. | +| `vulnerabilities[].scanner` | A node that describes the analyzer used to find this vulnerability. | | `vulnerabilities[].scanner.id` | Id of the scanner as a snake_case string. | | `vulnerabilities[].scanner.name` | Name of the scanner, for display purposes. | -| `vulnerabilities[].location` | A node that tells which class and/or method is affected by the vulnerability. | +| `vulnerabilities[].location` | A node that tells where the vulnerability is located. | | `vulnerabilities[].location.file` | Path to the dependencies file (e.g., `yarn.lock`). Optional. | | `vulnerabilities[].location.dependency` | A node that describes the dependency of a project where the vulnerability is located. | | `vulnerabilities[].location.dependency.package` | A node that provides the information on the package where the vulnerability is located. | @@ -360,7 +305,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].links` | An array of references to external documentation pieces or articles that describe the vulnerability further. Optional. | | `vulnerabilities[].links[].name` | Name of the vulnerability details link. Optional. | | `vulnerabilities[].links[].url` | URL of the vulnerability details document. Optional. | -| `remediations` | An array of objects containing information on cured vulnerabilities along with patch diffs to apply. | +| `remediations` | An array of objects containing information on cured vulnerabilities along with patch diffs to apply. Empty if no remediations provided by an underlying analyzer. | | `remediations[].fixes` | An array of strings that represent references to vulnerabilities fixed by this particular remediation. | | `remediations[].fixes[].cve` | A string value that describes a fixed vulnerability occurrence in the same format as `vulnerabilities[].cve`. | | `remediations[].summary` | Overview of how the vulnerabilities have been fixed. | @@ -377,19 +322,35 @@ vulnerabilities in your groups and projects. Read more about the 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). -## Dependency List +## Vulnerabilities database update + +For more information about the vulnerabilities database update, check the +[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075) -in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +## Dependency List **(ULTIMATE)** -An additional benefit of Dependency Scanning is the ability to get a list of your project's dependencies with their versions. +An additional benefit of Dependency Scanning is the ability to view your +project's dependencies and their known vulnerabilities. Read more about +the [Dependency List](../dependency_list/index.md). -This list can be generated only for [supported languages and package managers](#supported-languages-and-package-managers). +## Versioning and release process -To see the generated dependency list, navigate to the Dependency List page under your project's left sidebar menu **Project > Dependency List**. +Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). ## Contributing to the vulnerability database You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project to find a vulnerability in the Gemnasium database. -You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md).
\ No newline at end of file +You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> 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 differindex 7d70e8299f5..4c38862e68f 100644 --- a/doc/user/application_security/img/create_issue_with_list_hover.png +++ b/doc/user/application_security/img/create_issue_with_list_hover.png diff --git a/doc/user/application_security/img/dismissed_info.png b/doc/user/application_security/img/dismissed_info.png Binary files differindex 64d5cf26ed2..b4470b664d2 100644 --- a/doc/user/application_security/img/dismissed_info.png +++ b/doc/user/application_security/img/dismissed_info.png diff --git a/doc/user/application_security/img/interactive_reports.png b/doc/user/application_security/img/interactive_reports.png Binary files differindex 373b39104db..1b2ef0d3da9 100644 --- a/doc/user/application_security/img/interactive_reports.png +++ b/doc/user/application_security/img/interactive_reports.png diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png Binary files differindex 7443b9b6eea..d86b89a5f99 100644 --- a/doc/user/application_security/img/vulnerability_solution.png +++ 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 index 679847b76d7..83ea0ea3386 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,23 +1,59 @@ -# GitLab Secure **[ULTIMATE]** +--- +type: reference, howto +--- -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. +# 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. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview of application security with GitLab, see +[Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84). ## Security scanning tools GitLab can scan and report any vulnerabilities found in your project. -| Secure scanning tools | Description | +| Secure scanning tool | 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. | +| [Container Scanning](container_scanning/index.md) **(ULTIMATE)** | Scan Docker containers for known vulnerabilities. | +| [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their 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. | + +## Maintenance and update of the vulnerabilities database + +The various scanning tools and the vulnerabilities database are updated regularly. + +| Secure scanning tool | Vulnerabilities database updates | +|:-------------------------------------------------------------|-------------------------------------------| +| [Container Scanning](container_scanning/index.md) | Uses `clair` underneath and the latest `clair-db` version is used for each job run by running the [`latest` docker image tag](https://gitlab.com/gitlab-org/gitlab-ee/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Rubygems), `retire.js` (for NPM packages) and `gemnasium` (GitLab's own tool for all libraries). `bundler-audit` and `retire.js` both fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. | +| [Dynamic Application Security Testing (DAST)](dast/index.md) | Updated weekly on Sundays. The underlying tool, `zaproxy`, downloads fresh rules at startup. | +| [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab is wrapping](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | + +You don't have to update GitLab to benefit from the latest vulnerabilities definitions, +but you may have to in the future. + +The security tools are released as Docker images, and the vendored job definitions +to enable them are using the `x-y-stable` image tags that get overridden each time a new +release of the tools is pushed. The Docker images are updated to match the +previous GitLab releases, so they automatically get the latest versions of the +scanning tools without the user having to do anything. + +This workflow comes with some drawbacks and there's a +[plan to change this](https://gitlab.com/gitlab-org/gitlab-ee/issues/9725). ## Interacting with the vulnerabilities @@ -31,7 +67,7 @@ Each security vulnerability in the merge request report or the 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. + will place a ~~strikethrough~~ 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. @@ -92,16 +128,16 @@ 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. +1. Ensure your local project has the same commit checked out that was used to generate the patch. +1. Run `git apply remediation.patch`. +1. 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. +> [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 @@ -112,3 +148,47 @@ If this action is available there will be a **Create merge request** button in t Clicking on this button will create a merge request to apply the solution onto the source branch.  + +## Security approvals in merge requests **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing) 12.2. + +Merge Request Approvals can be configured to require approval from a member +of your security team when a vulnerability would be introduced by a merge request. + +This threshold is defined as `high`, `critical`, or `unknown` +severity. When any vulnerabilities are present within a merge request, an +approval will be required from the `Vulnerability-Check` approver group. + +### Enabling Security Approvals within a project + +To enable Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) +must be created with the case-sensitive name `Vulnerability-Check`. This approval +group must be set with an "Approvals required" count greater than zero. + +Once this group has been added to your project, the approval rule will be enabled +for all Merge Requests. + +Any code changes made will cause the count of approvals required to reset. + +An approval will be required when a security report: + +- Contains a new vulnerability of `high`, `critical`, or `unknown` severity. +- Is not generated during pipeline execution. + +An approval will be optional when a security report: + +- Contains no new vulnerabilities. +- Contains only new vulnerabilities of `low` or `medium` severity. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/license_management/img/license_management_add_license.png b/doc/user/application_security/license_management/img/license_management_add_license.png Binary files differnew file mode 100644 index 00000000000..c9a5dc14c57 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_add_license.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 differindex 0763130c375..fbf90bec7fd 100644 --- a/doc/user/application_security/license_management/img/license_management_decision.png +++ b/doc/user/application_security/license_management/img/license_management_decision.png diff --git a/doc/user/application_security/license_management/img/license_management_search.png b/doc/user/application_security/license_management/img/license_management_search.png Binary files differnew file mode 100644 index 00000000000..b3ffd8d95a1 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_search.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 differindex b5490e59074..2e3e8888e93 100644 --- a/doc/user/application_security/license_management/img/license_management_settings.png +++ 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 index 7878dc77084..c324848c703 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -1,4 +1,8 @@ -# License Management **[ULTIMATE]** +--- +type: reference, howto +--- + +# License Management **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. @@ -8,7 +12,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. 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) +You can take advantage of License Management by either [including the job](#configuration) 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). @@ -44,44 +48,37 @@ library whose license is incompatible with yours. 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/) | +| Language | Package managers | Scan Tool | +|------------|-------------------------------------------------------------------|----------------------------------------------------------| +| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Go | [Godep](https://github.com/tools/godep), go get ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), gvt ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), glide ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), dep ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), trash ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) and govendor ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), [go mod](https://github.com/golang/go/wiki/Modules) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| .NET | [Nuget](https://www.nuget.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Python | [pip](https://pip.pypa.io/en/stable/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Ruby | [gem](https://rubygems.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Erlang | [rebar](https://www.rebar3.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) , [CocoaPods v0.39 and below](https://cocoapods.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Elixir | [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| C++/C | [conan](https://conan.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Scala | [sbt](https://www.scala-sbt.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Rust | [cargo](https://crates.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| PHP | [composer](https://getcomposer.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| ## 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. +## Configuration -### Including the provided template +For GitLab 11.9 and later, to enable License Management, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +that 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: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -91,14 +88,17 @@ include: 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 +The results 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 +The License Management 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 [License Management documentation](https://gitlab.com/gitlab-org/security-products/license-management#settings). + +### Installing custom dependencies > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. @@ -126,7 +126,7 @@ variables: In this example, `my-custom-install-script.sh` is a shell script at the root directory of your project. -#### Overriding the template +### 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 @@ -141,7 +141,7 @@ license_management: CI_DEBUG_TRACE: "true" ``` -#### Configuring Maven projects +### 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. @@ -165,65 +165,21 @@ 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 +### Selecting the version of Python -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `license_management` -job can be added: +> [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -```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: +License Management uses Python 2.7 and pip 10.0 by default. +If your project requires Python 3, you can switch to Python 3.5 and pip 19.1 +by setting the `LM_PYTHON_VERSION` environment variable to `3`. ```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: +include: + template: License-Management.gitlab-ci.yml -```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] + variables: + LM_PYTHON_VERSION: 3 ``` ## Project policies for License Management @@ -242,16 +198,29 @@ To approve or blacklist a license: 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. + - 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. +To modify an existing license: + +1. In the **License Management** list, click the **Approved/Declined** dropdown to change it to the desired status. +  +Searching for Licenses: + +1. Use the **Search** box to search for a specific license. + +  + ## License Management report under pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) @@ -262,3 +231,15 @@ pipeline ID that has a `license_management` job to see the Licenses tab with the licenses (if any).  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md new file mode 100644 index 00000000000..f730a25a9fc --- /dev/null +++ b/doc/user/application_security/sast/analyzers.md @@ -0,0 +1,144 @@ +--- +table_display_block: true +--- + +# SAST Analyzers **(ULTIMATE)** + +SAST relies on underlying third party tools that are wrapped into what we call +"Analyzers". An analyzer is a +[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) +that wraps a particular tool to: + +- Expose its detection logic. +- Handle its execution. +- Convert its output to the common format. + +This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common). + +SAST supports the following official analyzers: + +- [`bandit`](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) (Bandit) +- [`brakeman`](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) (Brakeman) +- [`eslint`](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) (ESLint (Javascript)) +- [`flawfinder`](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) (Flawfinder) +- [`gosec`](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) (Gosec) +- [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) (NodeJsScan) +- [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP CS security-audit) +- [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) (PMD (Apex only)) +- [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) (Secrets (Gitleaks, TruffleHog & Diffence secret detectors)) +- [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET)) +- [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) +- [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) +- [`tslint`](https://gitlab.com/gitlab-org/security-products/analyzers/tslint) (TSLint (Typescript)) + +The analyzers are published as Docker images that SAST will use to launch +dedicated containers for each analysis. + +SAST is pre-configured with a set of **default images** that are maintained by +GitLab, but users can also integrate their own **custom images**. + +## Official default analyzers + +Any custom change to the official analyzers can be achieved by using an +[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings). + +### Using a custom Docker mirror + +You can switch to a custom Docker registry that provides the official analyzer +images under a different prefix. For instance, the following instructs +SAST to pull `my-docker-registry/gl-images/bandit` +instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/bandit`. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_ANALYZER_IMAGE_PREFIX: my-docker-registry/gl-images +``` + +This configuration requires that your custom registry provides images for all +the official analyzers. + +### Selecting specific analyzers + +You can select the official analyzers you want to run. Here's how to enable +`bandit` and `flawfinder` while disabling all the other default ones. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_DEFAULT_ANALYZERS: "bandit,flawfinder" +``` + +`bandit` runs first. When merging the reports, SAST will +remove the duplicates and will keep the `bandit` entries. + +### Disabling default analyzers + +Setting `SAST_DEFAULT_ANALYZERS` to an empty string will disable all the official +default analyzers. In `.gitlab-ci.yml` define: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_DEFAULT_ANALYZERS: "" +``` + +That's needed when one totally relies on [custom analyzers](#custom-analyzers). + +## Custom Analyzers + +You can provide your own analyzers as a comma separated list of Docker images. +Here's how to add `analyzers/csharp` and `analyzers/perl` to the default images: +In `.gitlab-ci.yml` define: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_ANALYZER_IMAGES: "my-docker-registry/analyzers/csharp,amy-docker-registry/analyzers/perl" +``` + +The values must be the full path to the container registry images, +like what you would feed to the `docker pull` command. + +NOTE: **Note:** +This configuration doesn't benefit from the integrated detection step. +SAST has to fetch and spawn each Docker image to establish whether the +custom analyzer can scan the source code. + +## Analyzers Data + +| Property \ Tool | Apex | Bandit | Brakeman | ESLint security | Find Sec Bugs | Flawfinder | Go AST Scanner | NodeJsScan | Php CS Security Audit | Security code Scan (.NET) | TSLint Security | Sobelow | +| --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :-------------: | :----------------: | +| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | 𐄂 | +| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | +| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| End line | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | 𐄂 | +| Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | +| End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | 𐄂 | +| External id (e.g. CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | +| Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | +| Affected item (e.g. class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | + +- ✓ => we have that data +- ⚠ => we have that data but it's partially reliable, or we need to extract it from unstructured content +- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. + +The values provided by these tools are heterogeneous so they are sometimes +normalized into common values (e.g., `severity`, `confidence`, etc). diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 11361f8ad89..2f15d997b5b 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,4 +1,8 @@ -# Static Application Security Testing (SAST) **[ULTIMATE]** +--- +type: reference, howto +--- + +# 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. @@ -13,7 +17,7 @@ to learn how to protect your organization. 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 +You can take advantage of SAST by either [including the CI job](#configuration) 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). @@ -55,6 +59,7 @@ The following table shows which languages, package managers and frameworks are s |-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------| | .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 | +| Apex (Salesforce) | [pmd](https://pmd.github.io/pmd/index.html) | 12.1 | | 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 | @@ -73,30 +78,16 @@ 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). +## Configuration -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. +For GitLab 11.9 and later, to enable SAST, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +that template. -To enable SAST using the provided template, add the following to your `.gitlab-ci.yml` -file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -106,14 +97,14 @@ include: 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 +The results 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 +### 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`. @@ -134,7 +125,7 @@ variables: 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 +### 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 @@ -149,84 +140,64 @@ sast: CI_DEBUG_TRACE: "true" ``` -### Manual job definition for GitLab 11.5 and later +### Available variables -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `sast` -job can be added: +SAST can be [configured](#customizing-the-sast-settings) using environment variables. -```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 -``` +#### Docker images -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. +The following are Docker image-related variables. -### Manual job definition for GitLab 11.4 and earlier (deprecated) +| Environment variable | Description | +|-------------------------------|--------------------------------------------------------------------------------| +| `SAST_ANALYZER_IMAGES` | Comma separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). | +| `SAST_ANALYZER_IMAGE_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | +| `SAST_ANALYZER_IMAGE_TAG` | Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | -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. +### Vulnerability filters -For GitLab 11.4 and earlier, the SAST job should look like: +Some analyzers make it possible to filter out vulnerabilities under a given threshold. -```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] -``` +| `SAST_BANDIT_EXCLUDED_PATHS` | - | comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html) | +| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | +| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | +| `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. | +| `SAST_GOSEC_LEVEL` | 0 | Ignore gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | +| `SAST_EXCLUDED_PATHS` | - | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | + +### Timeouts + +The following variables configure timeouts. + +| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". | +| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". | +| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m".| + +### Analyzer settings + +Some analyzers can be customized with environment variables. + +| Environment variable | Analyzer | Description | +|-------------------------|----------|----------| +| `ANT_HOME` | spotbugs | The `ANT_HOME` environment variable. | +| `ANT_PATH` | spotbugs | Path to the `ant` executable. | +| `GRADLE_PATH` | spotbugs | Path to the `gradle` executable. | +| `JAVA_OPTS` | spotbugs | Additional arguments for the `java` executable. | +| `JAVA_PATH` | spotbugs | Path to the `java` executable. | +| `MAVEN_CLI_OPTS` | spotbugs | Additional arguments for the `mvn` or `mvnw` executable. | +| `MAVEN_PATH` | spotbugs | Path to the `mvn` executable. | +| `MAVEN_REPO_PATH` | spotbugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | +| `SBT_PATH` | spotbugs | Path to the `sbt` executable. | +| `FAIL_NEVER` | spotbugs | Set to `1` to ignore compilation failure. | ## Reports JSON format CAUTION: **Caution:** The JSON report artifacts are not a public API of SAST and their format may change in the future. -The SAST tool emits a JSON report report file. Here is an example of a structure for a report will all important parts of +The SAST tool emits a JSON report report file. Here is an example of the report structure with all important parts of it highlighted: ```json-doc @@ -269,10 +240,9 @@ it highlighted: "url": "https://cwe.mitre.org/data/definitions/330.html" } ] - }, + }, { "category": "sast", - // "name" may be omitted because it could be not reported by a particular analyzer "message": "Probable insecure usage of temp file/directory.", "cve": "python/hardcoded/hardcoded-tmp.py:4ad6d4c40a8c263fc265f3384724014e0a4f8dd6200af83e51ff120420038031:B108", "severity": "Medium", @@ -297,7 +267,7 @@ it highlighted: "url": "https://docs.openstack.org/bandit/latest/plugins/b108_hardcoded_tmp_directory.html" } ] - }, + }, ], "remediations": [] } @@ -318,10 +288,10 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].severity` | How much the vulnerability impacts the software. Possible values: `Undefined` (an analyzer has not provided this info), `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. | | `vulnerabilities[].confidence` | How reliable the vulnerability's assessment is. Possible values: `Undefined` (an analyzer has not provided this info), `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, `Confirmed`. | | `vulnerabilities[].solution` | Explanation of how to fix the vulnerability. Optional. | -| `vulnerabilities[].scanner` | A node that describes the analyzer used find this vulnerability. | +| `vulnerabilities[].scanner` | A node that describes the analyzer used to find this vulnerability. | | `vulnerabilities[].scanner.id` | Id of the scanner as a snake_case string. | | `vulnerabilities[].scanner.name` | Name of the scanner, for display purposes. | -| `vulnerabilities[].location` | A node that tells which class and/or method is affected by the vulnerability. | +| `vulnerabilities[].location` | A node that tells where the vulnerability is located. | | `vulnerabilities[].location.file` | Path to the file where the vulnerability is located. Optional. | | `vulnerabilities[].location.start_line` | The first line of the code affected by the vulnerability. Optional. | | `vulnerabilities[].location.end_line` | The last line of the code affected by the vulnerability. Optional. | @@ -331,7 +301,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (e.g., `bandit_test_id` for [Bandit analyzer](https://wiki.openstack.org/wiki/Security/Projects/Bandit)). | | `vulnerabilities[].identifiers[].name` | Name of the identifier for display purposes. | | `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purposes. | -| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. | +| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. | ## Secret detection @@ -364,3 +334,20 @@ vulnerabilities in your groups and projects. Read more about the 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). + +## Vulnerabilities database update + +For more information about the vulnerabilities database update, check the +[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/security_dashboard/img/dashboard.png b/doc/user/application_security/security_dashboard/img/dashboard.png Binary files differdeleted file mode 100644 index a75168b1ce4..00000000000 --- a/doc/user/application_security/security_dashboard/img/dashboard.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png Binary files differnew file mode 100644 index 00000000000..85ab124f74c --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_security_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 differindex f0dad6c54d0..baa136fd885 100644 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png +++ 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 index 19eeb06a259..ac8c1ac0354 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -1,4 +1,8 @@ -# GitLab Security Dashboard **[ULTIMATE]** +--- +type: reference, howto +--- + +# 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. @@ -16,9 +20,9 @@ To benefit from the Security Dashboard you must first configure one of the The Security Dashboard supports the following reports: - [Container Scanning](../container_scanning/index.md) -- [DAST](../dast/index.md) +- [Dynamic Application Security Testing](../dast/index.md) - [Dependency Scanning](../dependency_scanning/index.md) -- [SAST](../sast/index.md) +- [Static Application Security Testing](../sast/index.md) ## Requirements @@ -26,8 +30,8 @@ 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. +1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports). +1. [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 @@ -43,13 +47,13 @@ for your project. Use it to find and fix vulnerabilities affecting the ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6709) in - [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5. +> [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**. +**Security** tab. Once you're on the dashboard, at the top you should see a series of filters for: @@ -58,7 +62,7 @@ Once you're on the dashboard, at the top you should see a series of filters for: - 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. @@ -102,3 +106,15 @@ That way, reports are created even if no code change happens. When using [Auto DevOps](../../../topics/autodevops/index.md), use [special environment variables](../../../topics/autodevops/index.md#environment-variables) to configure daily security scans. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md new file mode 100644 index 00000000000..862316b57da --- /dev/null +++ b/doc/user/asciidoc.md @@ -0,0 +1,375 @@ +# AsciiDoc + +GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5. +Consult the [Asciidoctor User Manual](https://asciidoctor.org/docs/user-manual/) for a complete Asciidoctor reference. + +## Syntax + +Here's a brief reference of the most commonly used AsciiDoc syntax. +You can find the full documentation for the AsciiDoc syntax at <https://asciidoctor.org/docs>. + +### Paragraphs + +```asciidoc +A normal paragraph. +Line breaks are not preserved. +``` + +Line comments, which are lines that start with `//`, are skipped: + +``` +// this is a comment +``` + +A blank line separates paragraphs. + +A paragraph with the `[%hardbreaks]` option will preserve line breaks: + +```asciidoc +[%hardbreaks] +This paragraph carries the `hardbreaks` option. +Notice how line breaks are now preserved. +``` + +An indented (literal) paragraph disables text formatting, +preserves spaces and line breaks, and is displayed in a +monospaced font: + +```asciidoc + This literal paragraph is indented with one space. + As a consequence, *text formatting*, spaces, + and lines breaks will be preserved. +``` + +An admonition paragraph grabs the reader's attention: + +```asciidoc +NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs. + +TIP: Lists can be indented. Leading whitespace is not significant. +``` + +### Text Formatting + +**Constrained (applied at word boundaries)** + +```asciidoc +*strong importance* (aka bold) +_stress emphasis_ (aka italic) +`monospaced` (aka typewriter text) +"`double`" and '`single`' typographic quotes ++passthrough text+ (substitutions disabled) +`+literal text+` (monospaced with substitutions disabled) +``` + +**Unconstrained (applied anywhere)** + +```asciidoc +**C**reate+**R**ead+**U**pdate+**D**elete +fan__freakin__tastic +``mono``culture +``` + +**Replacements** + +```asciidoc +A long time ago in a galaxy far, far away... +(C) 1976 Arty Artisan +I believe I shall--no, actually I won't. +``` + +**Macros** + +```asciidoc +// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements, etc. +The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow]. +The pass:c[->] operator is often referred to as the stabby lambda. +Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}]. +// activate stem support by adding `:stem:` to the document header +stem:[sqrt(4) = 2] +``` + +### Attributes + +```asciidoc +// define attributes in the document header +:name: value +``` + +```asciidoc +:url-gem: https://rubygems.org/gems/asciidoctor + +You can download and install Asciidoctor {asciidoctor-version} from {url-gem}. +C{pp} is not required, only Ruby. +Use a leading backslash to output a word enclosed in curly braces, like \{name}. +``` + +### Links + +```asciidoc +https://example.org/page[A webpage] +link:../path/to/file.txt[A local file] +xref:document.adoc[A sibling document] +mailto:hello@example.org[Email to say hello!] +``` + +### Anchors + +```asciidoc +[[idname,reference text]] +// or written using normal block attributes as `[#idname,reftext=reference text]` +A paragraph (or any block) with an anchor (aka ID) and reftext. + +See <<idname>> or <<idname,optional text of internal link>>. + +xref:document.adoc#idname[Jumps to anchor in another document]. + +This paragraph has a footnote.footnote:[This is the text of the footnote.] +``` + +### Lists + +#### Unordered + +```asciidoc +* level 1 +** level 2 +*** level 3 +**** level 4 +***** etc. +* back at level 1 ++ +Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block). + +.Some Authors +[circle] +- Edgar Allen Poe +- Sheri S. Tepper +- Bill Bryson +``` + +#### Ordered + +```asciidoc +. Step 1 +. Step 2 +.. Step 2a +.. Step 2b +. Step 3 + +.Remember your Roman numerals? +[upperroman] +. is one +. is two +. is three +``` + +#### Checklist + +```asciidoc +* [x] checked +* [ ] not checked +``` + +#### Callout + +```asciidoc +// enable callout bubbles by adding `:icons: font` to the document header +[,ruby] +---- +puts 'Hello, World!' # <1> +---- +<1> Prints `Hello, World!` to the console. +``` + +#### Description + +```asciidoc +first term:: description of first term +second term:: +description of second term +``` + +### Document Structure + +#### Header + +```asciidoc += Document Title +Author Name <author@example.org> +v1.0, 2019-01-01 +``` + +#### Sections + +```asciidoc += Document Title (Level 0) +== Level 1 +=== Level 2 +==== Level 3 +===== Level 4 +====== Level 5 +== Back at Level 1 +``` + +#### Includes + +```asciidoc +include::basics.adoc[] + +// define -a allow-uri-read to allow content to be read from URI +include::https://example.org/installation.adoc[] +``` + +### Blocks + +```asciidoc +-- +open - a general-purpose content wrapper; useful for enclosing content to attach to a list item +-- +``` + +```asciidoc +// recognized types include CAUTION, IMPORTANT, NOTE, TIP, and WARNING +// enable admonition icons by setting `:icons: font` in the document header +[NOTE] +==== +admonition - a notice for the reader, ranging in severity from a tip to an alert +==== +``` + +```asciidoc +==== +example - a demonstration of the concept being documented +==== +``` + +```asciidoc +.Toggle Me +[%collapsible] +==== +collapsible - these details are revealed by clicking the title +==== +``` + +```asciidoc +**** +sidebar - auxiliary content that can be read independently of the main content +**** +``` + +```asciidoc +.... +literal - an exhibit that features program output +.... +``` + +```asciidoc +---- +listing - an exhibit that features program input, source code, or the contents of a file +---- +``` + +```asciidoc +[,language] +---- +source - a listing that is embellished with (colorized) syntax highlighting +---- +``` + +~~~asciidoc +\```language +fenced code - a shorthand syntax for the source block +\``` +~~~ + +```asciidoc +[,attribution,citetitle] +____ +quote - a quotation or excerpt; attribution with title of source are optional +____ +``` + +```asciidoc +[verse,attribution,citetitle] +____ +verse - a literary excerpt, often a poem; attribution with title of source are optional +____ +``` + +```asciidoc +++++ +pass - content passed directly to the output document; often raw HTML +++++ +``` + +```asciidoc +// activate stem support by adding `:stem:` to the document header +[stem] +++++ +x = y^2 +++++ +``` + +```asciidoc +//// +comment - content which is not included in the output document +//// +``` + +### Tables + +```asciidoc +.Table Attributes +[cols=>1h;2d,width=50%,frame=topbot] +|=== +| Attribute Name | Values + +| options +| header,footer,autowidth + +| cols +| colspec[;colspec;...] + +| grid +| all \| cols \| rows \| none + +| frame +| all \| sides \| topbot \| none + +| stripes +| all \| even \| odd \| none + +| width +| (0%..100%) + +| format +| psv {vbar} csv {vbar} dsv +|=== +``` + +### Multimedia + +```asciidoc +image::screenshot.png[block image,800,450] + +Press image:reload.svg[reload,16,opts=interactive] to reload the page. + +video::movie.mp4[width=640,start=60,end=140,options=autoplay] + +video::aHjpOzsQ9YI[youtube] + +video::300817511[vimeo] +``` + +### Breaks + +```asciidoc +// thematic break (aka horizontal rule) +--- +``` + +```asciidoc +// page break +<<< +``` diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index e4fd08a582c..1b1d126b726 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -7,7 +7,7 @@ When you're collaborating online, you get fewer opportunities for high-fives and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md), -[snippets](snippets.md), and anywhere you can have a discussion. +[snippets](snippets.md), and anywhere you can have a thread.  diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index b520c4fb579..096730f800c 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -1,15 +1,18 @@ # GitLab Managed Apps GitLab provides **GitLab Managed Apps**, a one-click install for various applications which can -be added directly to your configured cluster. These applications are -needed for [Review Apps](../../ci/review_apps/index.md) and -[deployments](../../ci/environments.md) when using [Auto DevOps](../../topics/autodevops/index.md). +be added directly to your configured cluster. + +These applications are needed for [Review Apps](../../ci/review_apps/index.md) +and [deployments](../../ci/environments.md) when using [Auto DevOps](../../topics/autodevops/index.md). + You can install them after you -[create a cluster](../project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). +[create a cluster](../project/clusters/index.md#adding-and-removing-clusters). ## Installing applications Applications managed by GitLab will be installed onto the `gitlab-managed-apps` namespace. + This namespace: - Is different from the namespace used for project deployments. @@ -19,8 +22,10 @@ This namespace: To see a list of available applications to install: 1. For a: - - Project-level cluster, navigate to your project's **Operations > Kubernetes**. - - Group-level cluster, navigate to your group's **Kubernetes** page. + - [Project-level cluster](../project/clusters/index.md), + navigate to your project's **Operations > Kubernetes**. + - [Group-level cluster](../group/clusters/index.md), + navigate to your group's **Kubernetes** page. Install Helm first as it's used to install other applications. @@ -94,7 +99,7 @@ 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. +implications](../project/clusters/index.md#security-implications) before doing so. NOTE: **Note:** The @@ -111,7 +116,7 @@ file. [Ingress](https://kubernetes.github.io/ingress-nginx/) 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] or deploy your own web apps. +DevOps](../../topics/autodevops/index.md) or deploy your own web apps. NOTE: **Note:** The @@ -159,9 +164,9 @@ file. When installing JupyterHub onto your Kubernetes cluster, [JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) is automatically provisioned and configured using the authenticated user's: -- Name -- Email -- Newly created access token +- Name. +- Email. +- Newly created access token. JupyterLab's Git extension enables full version control of your notebooks as well as issuance of Git commands within Jupyter. Git commands can be issued via the **Git** tab on the left panel or via Jupyter's command line prompt. @@ -232,8 +237,10 @@ The applications below can be upgraded. To upgrade an application: 1. For a: - - Project-level cluster, navigate to your project's **Operations > Kubernetes**. - - Group-level cluster, navigate to your group's **Kubernetes** page. + - [Project-level cluster](../project/clusters/index.md), + navigate to your project's **Operations > Kubernetes**. + - [Group-level cluster](../group/clusters/index.md), + navigate to your group's **Kubernetes** page. 1. Select your cluster. 1. If an upgrade is available, the **Upgrade** button is displayed. Click the button to upgrade. @@ -251,13 +258,21 @@ The applications below can be uninstalled. | Application | GitLab version | Notes | | ----------- | -------------- | ----- | +| Cert-Manager | 12.2+ | The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish to [back up your configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html) or [revoke your certificates](https://letsencrypt.org/docs/revoking/) | +| GitLab Runner | 12.2+ | Any running pipelines will be canceled. | +| Helm | 12.2+ | The associated Tiller pod will be deleted and cannot be restored. | +| Ingress | 12.1+ | The associated load balancer and IP will be deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. | +| JupyterHub | 12.1+ | All data not committed to GitLab will be deleted and cannot be restored. | +| Knative | 12.1+ | The associated IP will be deleted and cannot be restored. | | Prometheus | 11.11+ | All data will be deleted and cannot be restored. | To uninstall an application: 1. For a: - - Project-level cluster, navigate to your project's **Operations > Kubernetes**. - - Group-level cluster, navigate to your group's **Kubernetes** page. + - [Project-level cluster](../project/clusters/index.md), + navigate to your project's **Operations > Kubernetes**. + - [Group-level cluster](../group/clusters/index.md), + navigate to your group's **Kubernetes** page. 1. Select your cluster. 1. Click the **Uninstall** button for the application. @@ -287,4 +302,3 @@ To avoid installation errors: kubectl get secrets/tiller-secret -n gitlab-managed-apps -o "jsonpath={.data['ca\.crt']}" | base64 -d > b.pem diff a.pem b.pem ``` - diff --git a/doc/user/clusters/img/jupyter-gitclone.png b/doc/user/clusters/img/jupyter-gitclone.png Binary files differindex 41d467f806a..aff194dea43 100644 --- a/doc/user/clusters/img/jupyter-gitclone.png +++ b/doc/user/clusters/img/jupyter-gitclone.png diff --git a/doc/user/discussions/img/automatically_resolve_outdated_discussions.png b/doc/user/discussions/img/automatically_resolve_outdated_discussions.png Binary files differindex ba129e7a618..a6fc4b0aef1 100644 --- a/doc/user/discussions/img/automatically_resolve_outdated_discussions.png +++ b/doc/user/discussions/img/automatically_resolve_outdated_discussions.png diff --git a/doc/user/discussions/img/btn_new_issue_for_all_discussions.png b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png Binary files differdeleted file mode 100644 index 3306bf2e60e..00000000000 --- a/doc/user/discussions/img/btn_new_issue_for_all_discussions.png +++ /dev/null diff --git a/doc/user/discussions/img/btn_new_issue_for_all_threads.png b/doc/user/discussions/img/btn_new_issue_for_all_threads.png Binary files differnew file mode 100644 index 00000000000..5d86e0ca016 --- /dev/null +++ b/doc/user/discussions/img/btn_new_issue_for_all_threads.png diff --git a/doc/user/discussions/img/commit_comment_mr_context.png b/doc/user/discussions/img/commit_comment_mr_context.png Binary files differindex b363e0035e8..68f58a57757 100644 --- a/doc/user/discussions/img/commit_comment_mr_context.png +++ b/doc/user/discussions/img/commit_comment_mr_context.png diff --git a/doc/user/discussions/img/commit_comment_mr_discussions_tab.png b/doc/user/discussions/img/commit_comment_mr_discussions_tab.png Binary files differindex 2b06cdcc055..d88f08eae26 100644 --- a/doc/user/discussions/img/commit_comment_mr_discussions_tab.png +++ b/doc/user/discussions/img/commit_comment_mr_discussions_tab.png diff --git a/doc/user/discussions/img/discussion_comment.png b/doc/user/discussions/img/discussion_comment.png Binary files differindex 206ddebf54b..3fec5962363 100644 --- a/doc/user/discussions/img/discussion_comment.png +++ b/doc/user/discussions/img/discussion_comment.png diff --git a/doc/user/discussions/img/discussion_view.png b/doc/user/discussions/img/discussion_view.png Binary files differdeleted file mode 100644 index 3a2b766ed7e..00000000000 --- a/doc/user/discussions/img/discussion_view.png +++ /dev/null diff --git a/doc/user/discussions/img/image_resolved_discussion.png b/doc/user/discussions/img/image_resolved_discussion.png Binary files differindex ed00b5c77fe..f6e5a3b66ae 100644 --- a/doc/user/discussions/img/image_resolved_discussion.png +++ b/doc/user/discussions/img/image_resolved_discussion.png diff --git a/doc/user/discussions/img/make_suggestion.png b/doc/user/discussions/img/make_suggestion.png Binary files differindex 20acc1417da..a24e29770aa 100644 --- a/doc/user/discussions/img/make_suggestion.png +++ b/doc/user/discussions/img/make_suggestion.png diff --git a/doc/user/discussions/img/merge_request_commits_tab.png b/doc/user/discussions/img/merge_request_commits_tab.png Binary files differindex 41a3648f390..267f3a720dc 100644 --- a/doc/user/discussions/img/merge_request_commits_tab.png +++ b/doc/user/discussions/img/merge_request_commits_tab.png diff --git a/doc/user/discussions/img/mr_review_resolve.png b/doc/user/discussions/img/mr_review_resolve.png Binary files differindex 34176f3fa8e..ced33682459 100644 --- a/doc/user/discussions/img/mr_review_resolve.png +++ 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 differindex e4adb5f2c2d..2f0be3b6d06 100644 --- a/doc/user/discussions/img/mr_review_resolve2.png +++ 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 differindex 920ea05ad66..f345c52e941 100644 --- a/doc/user/discussions/img/mr_review_second_comment.png +++ 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 differindex 1fb54348547..61b45431c9e 100644 --- a/doc/user/discussions/img/mr_review_second_comment_added.png +++ 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 differindex 38b44bda0d2..08b4c6bb82b 100644 --- a/doc/user/discussions/img/mr_review_start.png +++ 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 differindex da895ceb89f..4bef38f7808 100644 --- a/doc/user/discussions/img/mr_review_unresolve.png +++ 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 differindex a824b806e4a..79da61bb556 100644 --- a/doc/user/discussions/img/mr_review_unresolve2.png +++ b/doc/user/discussions/img/mr_review_unresolve2.png diff --git a/doc/user/discussions/img/multi-line-suggestion-preview.png b/doc/user/discussions/img/multi-line-suggestion-preview.png Binary files differindex 4288d0ba034..476c50b9098 100644 --- a/doc/user/discussions/img/multi-line-suggestion-preview.png +++ b/doc/user/discussions/img/multi-line-suggestion-preview.png diff --git a/doc/user/discussions/img/multi-line-suggestion-syntax.png b/doc/user/discussions/img/multi-line-suggestion-syntax.png Binary files differindex df0c99b84ef..80424d1f056 100644 --- a/doc/user/discussions/img/multi-line-suggestion-syntax.png +++ b/doc/user/discussions/img/multi-line-suggestion-syntax.png diff --git a/doc/user/discussions/img/new_issue_for_thread.png b/doc/user/discussions/img/new_issue_for_thread.png Binary files differnew file mode 100644 index 00000000000..28b76adf7fe --- /dev/null +++ b/doc/user/discussions/img/new_issue_for_thread.png diff --git a/doc/user/discussions/img/onion_skin_view.png b/doc/user/discussions/img/onion_skin_view.png Binary files differindex 91c3b396844..81bb4a2c85a 100644 --- a/doc/user/discussions/img/onion_skin_view.png +++ b/doc/user/discussions/img/onion_skin_view.png diff --git a/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png Binary files differnew file mode 100644 index 00000000000..bd0aaca79b2 --- /dev/null +++ b/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png diff --git a/doc/user/discussions/img/pending_review_comment.png b/doc/user/discussions/img/pending_review_comment.png Binary files differindex 916ef5b7452..70a66b3f4f0 100644 --- a/doc/user/discussions/img/pending_review_comment.png +++ b/doc/user/discussions/img/pending_review_comment.png diff --git a/doc/user/discussions/img/preview_issue_for_thread.png b/doc/user/discussions/img/preview_issue_for_thread.png Binary files differnew file mode 100644 index 00000000000..a9d7ab598be --- /dev/null +++ b/doc/user/discussions/img/preview_issue_for_thread.png diff --git a/doc/user/discussions/img/preview_issue_for_threads.png b/doc/user/discussions/img/preview_issue_for_threads.png Binary files differnew file mode 100644 index 00000000000..8757decb178 --- /dev/null +++ b/doc/user/discussions/img/preview_issue_for_threads.png diff --git a/doc/user/discussions/img/reply_to_comment_button.png b/doc/user/discussions/img/reply_to_comment_button.png Binary files differindex d362b19785c..d327d1c3e27 100644 --- a/doc/user/discussions/img/reply_to_comment_button.png +++ b/doc/user/discussions/img/reply_to_comment_button.png diff --git a/doc/user/discussions/img/resolve_comment_button.png b/doc/user/discussions/img/resolve_comment_button.png Binary files differindex 7c19fac31a2..0a3ed03a69c 100644 --- a/doc/user/discussions/img/resolve_comment_button.png +++ b/doc/user/discussions/img/resolve_comment_button.png diff --git a/doc/user/discussions/img/resolve_thread_button.png b/doc/user/discussions/img/resolve_thread_button.png Binary files differnew file mode 100644 index 00000000000..ca0a3e50550 --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_button.png diff --git a/doc/user/discussions/img/resolve_thread_issue_notice.png b/doc/user/discussions/img/resolve_thread_issue_notice.png Binary files differnew file mode 100644 index 00000000000..30a65b8fbd4 --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_issue_notice.png diff --git a/doc/user/discussions/img/resolve_thread_open_issue.png b/doc/user/discussions/img/resolve_thread_open_issue.png Binary files differnew file mode 100644 index 00000000000..2dd4ea3cb1b --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_open_issue.png diff --git a/doc/user/discussions/img/review_comment_quickactions.png b/doc/user/discussions/img/review_comment_quickactions.png Binary files differindex bd9880c329a..276def6381f 100644 --- a/doc/user/discussions/img/review_comment_quickactions.png +++ 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 differindex 4bf53a81b9c..e69a58dbb91 100644 --- a/doc/user/discussions/img/review_preview.png +++ b/doc/user/discussions/img/review_preview.png diff --git a/doc/user/discussions/img/suggestion.png b/doc/user/discussions/img/suggestion.png Binary files differindex 68a67e6ae5e..f7962305a15 100644 --- a/doc/user/discussions/img/suggestion.png +++ b/doc/user/discussions/img/suggestion.png diff --git a/doc/user/discussions/img/swipe_view.png b/doc/user/discussions/img/swipe_view.png Binary files differindex 82d6e52173c..e6f5e5053af 100644 --- a/doc/user/discussions/img/swipe_view.png +++ b/doc/user/discussions/img/swipe_view.png diff --git a/doc/user/discussions/img/thread_view.png b/doc/user/discussions/img/thread_view.png Binary files differnew file mode 100644 index 00000000000..e2db44aa604 --- /dev/null +++ b/doc/user/discussions/img/thread_view.png diff --git a/doc/user/discussions/img/threads_resolved.png b/doc/user/discussions/img/threads_resolved.png Binary files differnew file mode 100644 index 00000000000..ffb1233f2ee --- /dev/null +++ b/doc/user/discussions/img/threads_resolved.png diff --git a/doc/user/discussions/img/two_up_view.png b/doc/user/discussions/img/two_up_view.png Binary files differindex d9e90708e87..3b6ddfbe1be 100644 --- a/doc/user/discussions/img/two_up_view.png +++ b/doc/user/discussions/img/two_up_view.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 20eabdada79..6891682141c 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,18 +1,18 @@ -# Discussions +# Threads The ability to contribute conversationally is offered throughout GitLab. You can leave a comment in the following places: - issues -- epics **[ULTIMATE]** +- epics **(ULTIMATE)** - merge requests - snippets - commits - commit diffs There are standard comments, and you also have the option to create a comment -in the form of a threaded discussion. A comment can also be [turned into a discussion](#start-a-discussion-by-replying-to-a-standard-comment) +in the form of a thread. A comment can also be [turned into a thread](#start-a-thread-by-replying-to-a-standard-comment) when it receives a reply. The comment area supports [Markdown] and [quick actions]. You can edit your own @@ -21,187 +21,190 @@ higher can also edit a comment made by someone else. You can also reply to a comment notification email to reply to the comment if [Reply by email] is configured for your GitLab instance. Replying to a standard comment -creates another standard comment. Replying to a discussion comment creates a reply in the -discussion thread. Email replies support [Markdown] and [quick actions], just as if you replied from the web. +creates another standard comment. Replying to a threaded comment creates a reply in the thread. Email replies support +[Markdown] and [quick actions], just as if you replied from the web. -## Resolvable comments and discussions +## Resolvable comments and threads > **Notes:** > > - The main feature was [introduced][ce-5022] in GitLab 8.11. -> - Resolvable discussions can be added only to merge request diffs. +> - Resolvable threads can be added only to merge request diffs. -Discussion resolution helps keep track of progress during planning or code review. +Thread resolution helps keep track of progress during planning or code review. -Every standard comment or discussion thread in merge requests, commits, commit diffs, and +Every standard comment or thread in merge requests, commits, commit diffs, and snippets is initially displayed as unresolved. They can then be individually resolved by anyone with at least Developer access to the project or by the author of the change being reviewed. -The need to resolve all standard comments or discussions prevents you from forgetting -to address feedback and lets you hide discussions that are no longer relevant. +The need to resolve all standard comments or threads prevents you from forgetting +to address feedback and lets you hide threads that are no longer relevant. -!["A discussion between two people on a piece of code"][discussion-view] + -### Commit discussions in the context of a merge request +### Commit threads in the context of a merge request > [Introduced][ce-31847] in GitLab 10.3. -For reviewers with commit-based workflow, it may be useful to add discussions to -specific commit diffs in the context of a merge request. These discussions will +For reviewers with commit-based workflow, it may be useful to add threads to +specific commit diffs in the context of a merge request. These threads will persist through a commit ID change when: - force-pushing after a rebase - amending a commit -This functionality is also demonstrated in the video [How to use Merge Request Commit Discussions](https://www.youtube.com/watch?v=TviJH6oRboo). - -To create a commit diff discussion: +To create a commit diff thread: 1. Navigate to the merge request **Commits** tab. A list of commits that constitute the merge request will be shown. -  +  1. Navigate to a specific commit, click on the **Changes** tab (where you will only be presented diffs from the selected commit), and leave a comment. -  +  -1. Any discussions created this way will be shown in the merge request's +1. Any threads created this way will be shown in the merge request's **Discussions** tab and are resolvable. -  +  -Discussions created this way will only appear in the original merge request +Threads created this way will only appear in the original merge request and not when navigating to that commit under your project's **Repository > Commits** page. TIP: **Tip:** -When a link of a commit reference is found in a discussion inside a merge +When a link of a commit reference is found in a thread inside a merge request, it will be automatically converted to a link in the context of the current merge request. -### Jumping between unresolved discussions +### Jumping between unresolved threads When a merge request has a large number of comments it can be difficult to track -what remains unresolved. You can jump between unresolved discussions with the -Jump button next to the Reply field on a discussion. +what remains unresolved. You can jump between unresolved threads with the +Jump button next to the Reply field on a thread. + +You can also jump to the first unresolved thread from the button next to the +resolved threads tracker. -You can also jump to the first unresolved discussion from the button next to the -resolved discussions tracker. +You can also use keyboard shortcuts to navigate among threads: -!["3/4 discussions resolved"][discussions-resolved] +- Use <kbd>n</kbd> to jump to the next unresolved thread. +- Use <kbd>p</kbd> to jump to the previous unresolved thread. -### Marking a comment or discussion as resolved + -You can mark a discussion as resolved by clicking the **Resolve discussion** -button at the bottom of the discussion. +### Marking a comment or thread as resolved -!["Resolve discussion" button][resolve-discussion-button] +You can mark a thread as resolved by clicking the **Resolve thread** +button at the bottom of the thread. + + Alternatively, you can mark each comment as resolved individually. -!["Resolve comment" button][resolve-comment-button] + -### Move all unresolved discussions in a merge request to an issue +### Move all unresolved threads in a merge request to an issue > [Introduced][ce-8266] in GitLab 9.1 -To continue all open discussions from a merge request in a new issue, click the -**Resolve all discussions in new issue** button. +To continue all open threads from a merge request in a new issue, click the +**Resolve all threads in new issue** button. - + -Alternatively, when your project only accepts merge requests [when all discussions -are resolved](#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved), +Alternatively, when your project only accepts merge requests [when all threads +are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), there will be an **open an issue to resolve them later** link in the merge request widget. - + This will prepare an issue with its content referring to the merge request and -the unresolved discussions. +the unresolved threads. - + -Hitting **Submit issue** will cause all discussions to be marked as resolved and +Hitting **Submit issue** will cause all threads to be marked as resolved and add a note referring to the newly created issue. - + You can now proceed to merge the merge request from the UI. -### Moving a single discussion to a new issue +### Moving a single thread to a new issue > [Introduced][ce-8266] in GitLab 9.1 -To create a new issue for a single discussion, you can use the **Resolve this -discussion in a new issue** button. +To create a new issue for a single thread, you can use the **Resolve this +thread in a new issue** button. - + This will direct you to a new issue prefilled with the content of the -discussion, similar to the issues created for delegating multiple -discussions at once. Saving the issue will mark the discussion as resolved and -add a note to the merge request discussion referencing the new issue. +thread, similar to the issues created for delegating multiple +threads at once. Saving the issue will mark the thread as resolved and +add a note to the merge request thread referencing the new issue. - + -### Only allow merge requests to be merged if all discussions are resolved +### Only allow merge requests to be merged if all threads are resolved > [Introduced][ce-7125] in GitLab 8.14. -You can prevent merge requests from being merged until all discussions are +You can prevent merge requests from being merged until all threads are resolved. Navigate to your project's settings page, select the -**Only allow merge requests to be merged if all discussions are resolved** check +**Only allow merge requests to be merged if all threads are resolved** check box and hit **Save** for the changes to take effect. - + -From now on, you will not be able to merge from the UI until all discussions +From now on, you will not be able to merge from the UI until all threads are resolved. - + -### Automatically resolve merge request diff discussions when they become outdated +### Automatically resolve merge request diff threads when they become outdated > [Introduced][ce-14053] in GitLab 10.0. -You can automatically resolve merge request diff discussions on lines modified +You can automatically resolve merge request diff threads on lines modified with a new push. Navigate to your project's settings page, select the **Automatically resolve -merge request diffs discussions on lines changed with a push** check box and hit +merge request diffs threads on lines changed with a push** check box and hit **Save** for the changes to take effect. - + -From now on, any discussions on a diff will be resolved by default if a push -makes that diff section outdated. Discussions on lines that don't change and -top-level resolvable discussions are not automatically resolved. +From now on, any threads on a diff will be resolved by default if a push +makes that diff section outdated. Threads on lines that don't change and +top-level resolvable threads are not automatically resolved. -## Commit discussions +## Commit threads -You can add comments and discussion threads to a particular commit under your +You can add comments and threads to a particular commit under your project's **Repository > Commits**. CAUTION: **Attention:** -Discussions created this way will be lost if the commit ID changes after a +Threads created this way will be lost if the commit ID changes after a force push. ## Threaded discussions > [Introduced][ce-7527] in GitLab 9.1. -While resolvable discussions are only available to merge request diffs, -discussions can also be added without a diff. You can start a specific -discussion which will look like a thread, on issues, commits, snippets, and +While resolvable threads are only available to merge request diffs, +threads can also be added without a diff. You can start a specific +thread which will look like a thread, on issues, commits, snippets, and merge requests. To start a threaded discussion, click on the **Comment** button toggle dropdown, -select **Start discussion** and click **Start discussion** when you're ready to +select **Start thread** and click **Start thread** when you're ready to post the comment.  @@ -209,56 +212,57 @@ post the comment. This will post a comment with a single thread to allow you to discuss specific comments in greater detail. - + -## Image discussions +## Image threads > [Introduced][ce-14061] in GitLab 10.1. -Sometimes a discussion is revolved around an image. With image discussions, -you can easily target a specific coordinate of an image and start a discussion -around it. Image discussions are available in merge requests and commit detail views. +Sometimes a thread is revolved around an image. With image threads, +you can easily target a specific coordinate of an image and start a thread +around it. Image threads are available in merge requests and commit detail views. -To start an image discussion, hover your mouse over the image. Your mouse pointer +To start an image thread, hover your mouse over the image. Your mouse pointer should convert into an icon, indicating that the image is available for commenting. -Simply click anywhere on the image to create a new discussion. +Simply click anywhere on the image to create a new thread. - + After you click on the image, a comment form will be displayed that would be the start -of your discussion. Once you save your comment, you will see a new badge displayed on -top of your image. This badge represents your discussion. +of your thread. Once you save your comment, you will see a new badge displayed on +top of your image. This badge represents your thread. >**Note:** -This discussion badge is typically associated with a number that is only used as a visual -reference for each discussion. In the merge request discussion tab, -this badge will be indicated with a comment icon since each discussion will render a new +This thread badge is typically associated with a number that is only used as a visual +reference for each thread. In the merge request thread tab, +this badge will be indicated with a comment icon since each thread will render a new image section. -Image discussions also work on diffs that replace an existing image. In this diff view -mode, you can toggle the different view modes and still see the discussion point badges. +Image threads also work on diffs that replace an existing image. In this diff view +mode, you can toggle the different view modes and still see the thread point badges. | 2-up | Swipe | Onion Skin | | :-----------: | :----------: | :----------: | |  |  |  | -Image discussions also work well with resolvable discussions. Resolved discussions +Image threads also work well with resolvable threads. Resolved threads on diffs (not on the merge request discussion tab) will appear collapsed on page load and will have a corresponding badge counter to match the counter on the image. - + ## Lock discussions > [Introduced][ce-14531] in GitLab 10.1. -For large projects with many contributors, it may be useful to stop discussions +For large projects with many contributors, it may be useful to stop threads in issues or merge requests in these scenarios: -- The project maintainer has already resolved the discussion and it is not helpful - for continued feedback. The project maintainer has already directed new conversation +- The project maintainer has already resolved the thread and it is not helpful + for continued feedback. +- The project maintainer has already directed new conversation to newer issues or merge requests. -- The people participating in the discussion are trolling, abusive, or otherwise +- The people participating in the thread are trolling, abusive, or otherwise being unproductive. In these cases, a user with Developer permissions or higher in the project can lock (and unlock) @@ -282,7 +286,7 @@ 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]** +## Merge Request Reviews **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4213) in GitLab 11.4. @@ -300,7 +304,7 @@ 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. +- **Finish 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.  @@ -317,20 +321,20 @@ This will add the comment to the review.  -### Resolving/Unresolving discussions +### Resolving/Unresolving threads -Review comments can also resolve/unresolve [resolvable discussions](#resolvable-comments-and-discussions). +Review comments can also resolve/unresolve [resolvable threads](#resolvable-comments-and-threads). When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve -the discussion once published. +the thread once published.  - -If a particular pending comment will resolve or unresolve the discussion, this will be shown on the pending +If a particular pending comment will resolve or unresolve the thread, this will be shown on the pending comment itself.  - + + ### Submitting a review @@ -339,8 +343,8 @@ 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. + 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. @@ -356,7 +360,7 @@ Replying to this email will, consequentially, create a new comment on the associ > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26723) in GitLab 11.5. For issues with many comments like activity notes and user comments, sometimes -finding useful information can be hard. There is a way to filter comments from single notes and discussions for merge requests and issues. +finding useful information can be hard. There is a way to filter comments from single notes and threads for merge requests and issues. From a merge request's **Discussion** tab, or from an epic/issue overview, find the filter's dropdown menu on the right side of the page, from which you can choose one of the following options: @@ -376,7 +380,7 @@ from any device you're logged into. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. As a reviewer, you're able to suggest code changes with a simple -markdown syntax in Merge Request Diff discussions. Then, the +markdown syntax in Merge Request Diff threads. Then, the Merge Request author (or other users with appropriate [permission](../permissions.md)) is able to apply these suggestions with a click, which will generate a commit in @@ -385,21 +389,21 @@ the Merge Request authored by the user that applied them. 1. Choose a line of code to be changed, add a new comment, then click on the **Insert suggestion** icon in the toolbar: -  +  1. In the comment, add your suggestion to the pre-populated code block: -  +  1. Click **Comment**. - The suggestions in the comment can be applied by the merge request author - directly from the merge request: + The suggestions in the comment can be applied by the merge request author + directly from the merge request: -  +  Once the author applies a suggestion, it will be marked with the **Applied** label, -the discussion will be automatically resolved, and GitLab will create a new commit +the thread 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. @@ -413,8 +417,8 @@ Custom commit messages will be introduced by > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310) in GitLab 11.10. Reviewers can also suggest changes to multiple lines with a single suggestion -within Merge Request diff discussions by adjusting the range offsets. The -offsets are relative to the position of the diff discussion, and specify the +within Merge Request diff threads by adjusting the range offsets. The +offsets are relative to the position of the diff thread, and specify the range to be replaced by the suggestion when it is applied.  @@ -430,25 +434,26 @@ Suggestions covering multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line, allowing up to 200 changed lines per suggestion. -## Start a discussion by replying to a standard comment +## Start a thread by replying to a standard comment > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30299) in GitLab 11.9 -To reply to a standard (non-discussion) comment, you can use the **Reply to comment** button. +To reply to a standard (non-thread) comment, you can use the **Reply to comment** button.  -The **Reply to comment** button is only displayed if you have permissions to reply to an existing discussion, or start a discussion from a standard comment. +The **Reply to comment** button is only displayed if you have permissions to reply to an existing thread, or start a thread from a standard comment. Clicking on the **Reply to comment** button will bring the reply area into focus and you can type your reply.  -Relying to a non-discussion comment will convert the non-discussion comment to a -threaded discussion once the reply is submitted. This conversion is considered an edit +Replying to a non-thread comment will convert the non-thread comment to a +thread once the reply is submitted. This conversion is considered an edit to the original comment, so a note about when it was last edited will appear underneath it. -This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff discussions are not supported yet. +This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are +not supported yet. [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125 diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 2fb6cec55fa..d21a325d401 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -1,7 +1,7 @@ # GitLab.com settings In this page you will find information about the settings that are used on -[GitLab.com](https://about.gitlab.com/pricing). +[GitLab.com](https://about.gitlab.com/pricing/). ## SSH host keys fingerprints @@ -73,21 +73,20 @@ or over the size limit, you can [reduce your repository size with Git](../projec ## IP range -GitLab.com, CI/CD, and related services are deployed into Google Cloud Platform (GCP). Any -IP based firewall can be configured by looking up all -[IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges). +GitLab.com, CI/CD, and related services are deployed into Google Cloud Platform (GCP). Any +IP based firewall can be configured by looking up all +[IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges). [Static endpoints](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/5071) are being considered. ## Shared Runners -Shared Runners on GitLab.com run in [autoscale mode] and powered by -Google Cloud Platform. Autoscaling means reduced -waiting times to spin up CI/CD jobs, and isolated VMs for each project, -thus maximizing security. -They're free to use for public open source projects and limited to 2000 CI -minutes per month per group for private projects. Read about all -[GitLab.com plans](https://about.gitlab.com/pricing/). +Shared Runners on GitLab.com run in [autoscale mode] and powered by Google Cloud Platform. +Autoscaling means reduced waiting times to spin up CI/CD jobs, and isolated VMs for each project, +thus maximizing security. They're free to use for public open source projects and limited +to 2000 CI minutes per month per group for private projects. More minutes +[can be purchased](../../subscriptions/index.md#extra-shared-runners-pipeline-minutes), if +needed. Read about all [GitLab.com plans](https://about.gitlab.com/pricing/). All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, CoreOS and the latest Docker Engine installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default @@ -113,57 +112,6 @@ Below are the shared Runners settings. The full contents of our `config.toml` are: -**DigitalOcean** - -```toml -concurrent = X -check_interval = 1 -metrics_server = "X" -sentry_dsn = "X" - -[[runners]] - name = "docker-auto-scale" - request_concurrency = X - url = "https://gitlab.com/" - token = "SHARED_RUNNER_TOKEN" - executor = "docker+machine" - environment = [ - "DOCKER_DRIVER=overlay2" - ] - limit = X - [runners.docker] - image = "ruby:2.5" - privileged = true - [runners.machine] - IdleCount = 20 - IdleTime = 1800 - OffPeakPeriods = ["* * * * * sat,sun *"] - OffPeakTimezone = "UTC" - OffPeakIdleCount = 5 - OffPeakIdleTime = 1800 - MaxBuilds = 1 - MachineName = "srm-%s" - MachineDriver = "digitalocean" - MachineOptions = [ - "digitalocean-image=X", - "digitalocean-ssh-user=core", - "digitalocean-region=nyc1", - "digitalocean-size=s-2vcpu-2gb", - "digitalocean-private-networking", - "digitalocean-tags=shared_runners,gitlab_com", - "engine-registry-mirror=http://INTERNAL_IP_OF_OUR_REGISTRY_MIRROR", - "digitalocean-access-token=DIGITAL_OCEAN_ACCESS_TOKEN", - ] - [runners.cache] - Type = "s3" - BucketName = "runner" - Insecure = true - Shared = true - ServerAddress = "INTERNAL_IP_OF_OUR_CACHE_SERVER" - AccessKey = "ACCESS_KEY" - SecretKey = "ACCESS_SECRET_KEY" -``` - **Google Cloud Platform** ```toml @@ -179,20 +127,25 @@ sentry_dsn = "X" token = "SHARED_RUNNER_TOKEN" executor = "docker+machine" environment = [ - "DOCKER_DRIVER=overlay2" + "DOCKER_DRIVER=overlay2", + "DOCKER_TLS_CERTDIR=" ] limit = X [runners.docker] image = "ruby:2.5" privileged = true + volumes = [ + "/certs/client", + "/dummy-sys-class-dmi-id:/sys/class/dmi/id:ro" # Make kaniko builds work on GCP. + ] [runners.machine] - IdleCount = 20 - IdleTime = 1800 + IdleCount = 50 + IdleTime = 3600 OffPeakPeriods = ["* * * * * sat,sun *"] OffPeakTimezone = "UTC" - OffPeakIdleCount = 5 - OffPeakIdleTime = 1800 - MaxBuilds = 1 + OffPeakIdleCount = 15 + OffPeakIdleTime = 3600 + MaxBuilds = 1 # For security reasons we delete the VM after job has finished so it's not reused. MachineName = "srm-%s" MachineDriver = "google" MachineOptions = [ @@ -203,17 +156,18 @@ sentry_dsn = "X" "google-tags=gitlab-com,srm", "google-use-internal-ip", "google-zone=us-east1-d", + "engine-opt=mtu=1460", # Set MTU for container interface, for more information check https://gitlab.com/gitlab-org/gitlab-runner/issues/3214#note_82892928 "google-machine-image=PROJECT/global/images/IMAGE", - "engine-registry-mirror=http://INTERNAL_IP_OF_OUR_REGISTRY_MIRROR" + "engine-opt=ipv6", # This will create IPv6 interfaces in the containers. + "engine-opt=fixed-cidr-v6=fc00::/7", + "google-operation-backoff-initial-interval=2" # Custom flag from forked docker-machine, for more information check https://github.com/docker/machine/pull/4600 ] [runners.cache] - Type = "s3" - BucketName = "runner" - Insecure = true + Type = "gcs" Shared = true - ServerAddress = "INTERNAL_IP_OF_OUR_CACHE_SERVER" - AccessKey = "ACCESS_KEY" - SecretKey = "ACCESS_SECRET_KEY" + [runners.cache.gcs] + CredentialsFile = "/path/to/file" + BucketName = "bucket-name" ``` ## Sidekiq @@ -223,7 +177,7 @@ and the following environment variables: | Setting | GitLab.com | Default | |-------- |----------- |-------- | -| `SIDEKIQ_MEMORY_KILLER_MAX_RSS` | `1000000` | `1000000` | +| `SIDEKIQ_MEMORY_KILLER_MAX_RSS` | `1000000` | `2000000` | | `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_SIGNAL` | `SIGKILL` | - | | `SIDEKIQ_LOG_ARGUMENTS` | `1` | - | @@ -260,7 +214,7 @@ The list of GitLab.com specific settings (and their defaults) is as follows: | hot_standby_feedback | on | off | | log_autovacuum_min_duration | 0 | -1 | | log_checkpoints | on | off | -| log_line_prefix | `%t [%p]: [%l-1] ` | empty | +| log_line_prefix | `%t [%p]: [%l-1]` | empty | | log_min_duration_statement | 1000 | -1 | | log_temp_files | 0 | -1 | | maintenance_work_mem | 2048MB | 16 MB | @@ -298,6 +252,82 @@ Web front-ends: - `memory_limit_min` = 1024MiB - `memory_limit_max` = 1280MiB +## GitLab.com-specific rate limits + +NOTE: **Note:** +See [Rate limits](../../security/rate_limits.md) for administrator +documentation. + +IP blocks usually happen when GitLab.com receives unusual traffic from a single +IP address that the system views as potentially malicious based on rate limit +settings. After the unusual traffic ceases, the IP address will be automatically +released depending on the type of block, as described below. + +If you receive a `403 Forbidden` error for all requests to GitLab.com, please +check for any automated processes that may be triggering a block. For +assistance, contact [GitLab Support](https://support.gitlab.com) +with details, such as the affected IP address. + +### HAProxy API throttle + +GitLab.com responds with HTTP status code `429` to API requests that exceed 10 +requests +per second per IP address. + +The following example headers are included for all API requests: + +``` +RateLimit-Limit: 600 +RateLimit-Observed: 6 +RateLimit-Remaining: 594 +RateLimit-Reset: 1563325137 +RateLimit-ResetTime: Wed, 17 Jul 2019 00:58:57 GMT +``` + +Source: + +- Search for `rate_limit_http_rate_per_minute` and `rate_limit_sessions_per_second` in [GitLab.com's current HAProxy settings](https://gitlab.com/gitlab-cookbooks/gitlab-haproxy/blob/master/attributes/default.rb). + +### Rack Attack initializer + +Details of rate limits enforced by [Rack Attack](../../security/rack_attack.md). + +#### Protected paths throttle + +GitLab.com responds with HTTP status code `429` to POST requests at protected +paths that exceed 10 requests per **minute** per IP address. + +See the source below for which paths are protected. This includes user creation, +user confirmation, user sign in, and password reset. + +This header is included in responses to blocked requests: + +``` +Retry-After: 60 +``` + +Source: + +- Search for `rate_limit_requests_per_period`, `rate_limit_period`, and `rack_attack_protected_paths` in [GitLab.com's current Rails app settings](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb). + +#### Git and container registry failed authentication ban + +GitLab.com responds with HTTP status code 403 for 1 hour, if 30 failed +authentication requests were received in a 3-minute period from a single IP address. + +This applies only to Git requests and container registry (`/jwt/auth`) requests +(combined). + +This limit is reset by requests that authenticate successfully. For example, 29 +failed authentication requests followed by 1 successful request, followed by 29 +more failed authentication requests would not trigger a ban. + +No response headers are provided. + +### Admin Area settings + +GitLab.com does not currently use these settings. + ## GitLab.com at scale In addition to the GitLab Enterprise Edition Omnibus install, GitLab.com uses @@ -352,3 +382,11 @@ High Performance TCP/HTTP Load Balancer: [unicorn-worker-killer]: https://rubygems.org/gems/unicorn-worker-killer "unicorn-worker-killer" [4010]: https://gitlab.com/gitlab-com/infrastructure/issues/4010 "Find a good value for maximum timeout for Shared Runners" [4070]: https://gitlab.com/gitlab-com/infrastructure/issues/4070 "Configure per-runner timeout for shared-runners-manager-X on GitLab.com" + +## Group and project settings + +On GitLab.com, projects, groups, and snippets created +after July 2019 have the `Internal` visibility setting disabled. + +You can read more about the change in the +[relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388). diff --git a/doc/user/group/bulk_editing/img/bulk-editing.png b/doc/user/group/bulk_editing/img/bulk-editing.png Binary files differnew file mode 100644 index 00000000000..ca1662a781b --- /dev/null +++ b/doc/user/group/bulk_editing/img/bulk-editing.png diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md new file mode 100644 index 00000000000..ea48b0b9fef --- /dev/null +++ b/doc/user/group/bulk_editing/index.md @@ -0,0 +1,31 @@ +# Bulk editing issues, merge requests, and epics at the group level **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7249) for issues in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12719) for merge requests in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7250) for epics in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +## Editing milestones and labels + +> **Notes:** +> +> - A permission level of `Reporter` or higher is required in order to manage issues. +> - A permission level of `Developer` or higher is required in order to manage merge requests. +> - A permission level of `Reporter` or higher is required in order to manage epics. + +By using the bulk editing feature: + +- Milestones can be updated simultaneously across multiple issues or merge requests. +- Labels can be updated simultaneously across multiple issues, merge requests, or epics. + + + +To bulk update group issues, merge requests, or epics: + +1. Navigate to the issues, merge requests, or epics list. +1. Click **Edit issues**, **Edit merge requests**, or **Edit epics**. + - This will open a sidebar on the right-hand side where editable fields + for milestones and labels will be displayed. + - Checkboxes will also appear beside each issue, merge request, or epic. +1. Check the checkbox beside each issue, merge request, or epic to be edited. +1. Select the desired new values from the sidebar. +1. Click **Update all**. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 3c5e820c1ca..d41f44f85cc 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -5,7 +5,6 @@ type: reference # Group-level Kubernetes clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in GitLab 11.6. -> Group Cluster integration is currently in [Beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga). ## Overview @@ -42,7 +41,7 @@ to the group containing the project if the project's cluster is available and no In the case of sub-groups, GitLab will use the cluster of the closest ancestor group to the project, provided the cluster is not disabled. -## Multiple Kubernetes clusters **[PREMIUM]** +## Multiple Kubernetes clusters **(PREMIUM)** With GitLab Premium, you can associate more than one Kubernetes clusters to your group. That way you can have different clusters for different environments, @@ -57,10 +56,6 @@ differentiate the new cluster from the rest. > [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 @@ -86,12 +81,12 @@ the [Auto DevOps](../../../topics/autodevops/index.md) stages. The domain should have a wildcard DNS configured to the Ingress IP address. -## Environment scopes **[PREMIUM]** +## Environment scopes **(PREMIUM)** 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](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium) +[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables) work. While evaluating which environment matches the environment scope of a @@ -142,13 +137,12 @@ The result will then be: - The Staging cluster will be used for the `deploy to staging` job. - The Production cluster will be used for the `deploy to production` job. -## Unavailable features - -The following features are not currently available for group-level clusters: +## Security of Runners -1. Terminals (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55487)). -1. Pod logs (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55488)). -1. Deployment boards (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55489)). +For important information about securely configuring GitLab Runners, see +[Security of +Runners](../../project/clusters/index.md#security-of-gitlab-runners) +documentation for project-level clusters. <!-- ## Troubleshooting diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 7e6cb24a51e..a0dd5cd497d 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -2,9 +2,10 @@ type: reference --- -# Contribution Analytics **[STARTER]** +# Contribution Analytics **(STARTER)** -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. +> - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3090) for subgroups in GitLab 12.2. ## Overview @@ -21,9 +22,9 @@ page. ## Use cases - Analyze your team's contributions over a period of time, and offer a bonus for the top -contributors. + contributors. - Identify opportunities for improvement with group members who may benefit from additional -support. + support. ## Using Contribution Analytics @@ -54,13 +55,13 @@ Select the desired period from the calendar dropdown. Contributions per group member are also presented in tabular format. Click a column header to sort the table by that column: -* 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 +- 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  diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index aa088d2fcdb..7cdba8cf2b5 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -2,9 +2,9 @@ type: reference --- -# Custom group-level project templates **[PREMIUM]** +# Custom group-level project templates **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing) 11.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6. When you create a new [project](../project/index.md), creating it based on custom project templates is a convenient bootstrap option. @@ -24,7 +24,7 @@ project in the group will be available to every logged in user. However, private projects will be available only if the user is a member of the project. NOTE: **Note:** -Projects of nested subgroups of a selected template source cannot be used. +Only direct subgroups can be set as the template source. Projects of nested subgroups of a selected template source cannot be used. Repository and database information that are copied over to each new project are identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md index 4fc2d8e9509..771468fbba8 100644 --- a/doc/user/group/dependency_proxy/index.md +++ b/doc/user/group/dependency_proxy/index.md @@ -1,4 +1,4 @@ -# Dependency Proxy **[PREMIUM]** +# Dependency Proxy **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. diff --git a/doc/user/group/epics/img/bulk_editing.png b/doc/user/group/epics/img/bulk_editing.png Binary files differnew file mode 100644 index 00000000000..85610bef83e --- /dev/null +++ b/doc/user/group/epics/img/bulk_editing.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 differindex 7a953189270..9d1be88549d 100644 --- a/doc/user/group/epics/img/button_reopen_epic.png +++ b/doc/user/group/epics/img/button_reopen_epic.png diff --git a/doc/user/group/epics/img/containing_epic.png b/doc/user/group/epics/img/containing_epic.png Binary files differindex 5ed693e6d6a..dc13d55e2bc 100644 --- a/doc/user/group/epics/img/containing_epic.png +++ 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 differindex dbda98e4351..c55d302ec29 100644 --- a/doc/user/group/epics/img/epic_view.png +++ b/doc/user/group/epics/img/epic_view.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 2e4106f55e5..5968b91c9b7 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -2,7 +2,7 @@ type: reference, howto --- -# Epics **[ULTIMATE]** +# Epics **(ULTIMATE)** > Introduced in [GitLab Ultimate][ee] 10.2. @@ -97,6 +97,22 @@ have a [start or due date](#start-date-and-due-date), then you can see a 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. +## Updating epics + +### Using bulk editing + +To apply labels across multiple epics: + +1. Go to the Epics list. +1. Click **Edit epics**. + - Checkboxes will appear beside each epic. + - A sidebar on the right-hand side will appear, with an editable field for labels. +1. Check the checkbox beside each epic to be edited. +1. Select the desired labels. +1. Click **Update all**. + + + ## Deleting an epic NOTE: **Note:** @@ -202,21 +218,21 @@ You may also consult the [group permissions table][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). + These text fields also fully support + [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). -## Comment, or start a discussion +## Comment, or start a thread 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. +- Click "Start thread": start a thread within that epic's discussion to discuss specific points. ## Award emoji - You can [award an emoji](../../award_emojis.md) to that epic or its comments. -## Notifications +## 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 differindex d9caae1a223..f0586772218 100644 --- a/doc/user/group/img/group_file_template_dropdown.png +++ 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 differindex ca42f7726db..5e07974bc86 100644 --- a/doc/user/group/img/group_file_template_settings.png +++ b/doc/user/group/img/group_file_template_settings.png diff --git a/doc/user/group/img/group_storage_usage_quota.png b/doc/user/group/img/group_storage_usage_quota.png Binary files differnew file mode 100644 index 00000000000..c5d81ad7a8b --- /dev/null +++ b/doc/user/group/img/group_storage_usage_quota.png diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 97d309caf7c..d1d4f3740b0 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -41,12 +41,13 @@ You can create groups for numerous reasons. To name a couple: - Make it easier to `@mention` all of your team at once in issues and merge requests by creating a group and including the appropriate members. For example, you could create a group for your company members, and create a [subgroup](subgroups/index.md) for each individual team. Let's say you create a group called `company-team`, and you create subgroups in this group for the individual teams `backend-team`, `frontend-team`, and `production-team`. - - When you start a new implementation from an issue, you add a comment: - _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_ - - When your backend team needs help from frontend, they add a comment: - _"`@company-team/frontend-team` could you help us here please?"_ - - When the frontend team completes their implementation, they comment: - _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_ + +- When you start a new implementation from an issue, you add a comment: + _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_ +- When your backend team needs help from frontend, they add a comment: + _"`@company-team/frontend-team` could you help us here please?"_ +- When the frontend team completes their implementation, they comment: + _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_ ## Namespaces @@ -77,6 +78,10 @@ Issues and merge requests are part of projects. For a given group, you can view [issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all projects in that group, together in a single list view. +### Bulk editing issues and merge requests + +For details, see [bulk editing issues and merge requests](../group/bulk_editing/index.md). + ## Create a new group > For a list of words that are not allowed to be used as group names see the @@ -86,11 +91,11 @@ To create a new Group, either: - In the top menu, click **Groups** and then **Your Groups**, and click the green button **New group**. -  +  - Or, in the top menu, expand the `plus` sign and choose **New group**. -  +  Add the following information: @@ -99,15 +104,15 @@ Add the following information: 1. The **Group name** will automatically populate the URL. Optionally, you can change it. This is the name that displays in group views. The name can contain only: - - Alphanumeric characters - - Underscores - - Dashes and dots - - Spaces + - Alphanumeric characters + - Underscores + - Dashes and dots + - Spaces 1. The **Group URL** is the namespace under which your projects will be hosted. The URL can contain only: - - Alphanumeric characters - - Underscores - - Dashes and dots (it cannot start with dashes or end in a dot) + - Alphanumeric characters + - Underscores + - Dashes and dots (it cannot start with dashes or end in a dot) 1. Optionally, you can add a brief description to tell others what this group is about. 1. Optionally, choose an avatar for your group. @@ -161,12 +166,12 @@ There are two different ways to add a new project to a group: - Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md). -  +  - While you are creating a project, select a group namespace you've already created from the dropdown menu. -  +  ### Default project-creation level @@ -199,7 +204,7 @@ 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]** +## Epics **(ULTIMATE)** > Introduced in [GitLab Ultimate][ee] 10.2. @@ -209,13 +214,15 @@ milestones. [Learn more about Epics.](epics/index.md) -## Group Security Dashboard **[ULTIMATE]** +## 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]** +## Insights **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. Configure the Insights that matter for your groups or projects, allowing users to explore data such as: @@ -268,9 +275,10 @@ be unique. To change your group path: -1. Navigate to your group's **Settings > General**. -1. Enter a new name under **Group path**. -1. Click **Save group**. +1. Navigate to your group's **Settings > General** page. +1. Expand the **Path, transfer, remove** section. +1. Enter a new name under **Change group path**. +1. Click **Change group path**. CAUTION: **Caution:** It is currently not possible to rename a namespace if it contains a @@ -303,7 +311,7 @@ To enable this feature, navigate to the group settings page. Select  -#### Member Lock **[STARTER]** +#### Member Lock **(STARTER)** Member lock lets a group owner prevent any new project membership to all of the projects within a group, allowing tighter control over project membership. @@ -323,7 +331,58 @@ 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]** +#### IP access restriction **(ULTIMATE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1985) in +[GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. + +To make sure only people from within your organization can access particular +resources, you have the option to restrict access to groups and their +underlying projects, issues, etc, by IP address. This can help ensure that +particular content doesn't leave the premises, while not blocking off access to +the entire instance. + +Add whitelisted IP subnet using CIDR notation to the group settings and anyone +coming from a different IP address won't be able to access the restricted +content. + +Restriction currently applies to UI, API access is not restricted. +To avoid accidental lock-out, admins and group owners are are able to access +the group regardless of the IP restriction. + +#### Allowed domain restriction **(PREMIUM ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7297) in +[GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +You can restrict access to groups and their underlying projects by +allowing only users with email addresses in particular domains to be added to the group. + +Add email domains you want to whitelist and users with emails from different +domains won't be allowed to be added to this group. + +Some domains cannot be restricted. These are the most popular public email domains, such as: + +- `gmail.com` +- `yahoo.com` +- `hotmail.com` +- `aol.com` +- `msn.com` +- `hotmail.co.uk` +- `hotmail.fr` +- `live.com` +- `outlook.com` +- `icloud.com` + +To enable this feature: + +1. Navigate to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section, and enter domain name into **Restrict membership by email** field. +1. Click **Save changes**. + +This will enable the domain-checking for all new users added to the group from this moment on. + +#### 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 @@ -347,11 +406,22 @@ To enable this feature, navigate to the group settings page, expand the  -#### Group-level project templates **[PREMIUM]** +#### Group-level project templates **(PREMIUM)** Define project templates at a group level by setting a group as the template source. [Learn more about group-level project templates](custom_project_templates.md). +#### Disabling email notifications + +You can disable all email notifications related to the group, which also includes +it's subgroups and projects. + +To enable this feature: + +1. Navigate to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section, and select **Disable email notifications**. +1. Click **Save changes**. + ### Advanced settings - **Projects**: View all projects within that group, add members to each project, @@ -359,20 +429,28 @@ Define project templates at a group level by setting a group as the template sou - **Webhooks**: Configure [webhooks](../project/integrations/webhooks.md) for your group. - **Kubernetes cluster integration**: Connect your GitLab group with [Kubernetes clusters](clusters/index.md). - **Audit Events**: View [Audit Events](../../administration/audit_events.md) - for the group. **[STARTER ONLY]** + 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]** +#### Storage usage quota **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. + +A group owner can check the aggregated storage usage for all the project in a group, sub-groups included, in the **Storage** tab of the **Usage Quotas** page available to the group page settings list. + + + +## 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]** +## Issues analytics **(PREMIUM)** With [GitLab Issues Analytics](issues_analytics/index.md), you can see a bar chart of the number of issues created each month in your groups. -## Dependency Proxy **[PREMIUM]** +## Dependency Proxy **(PREMIUM)** Use GitLab as a [dependency proxy](dependency_proxy/index.md) for upstream Docker images. 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 differindex 791d0e4bcdf..0e338b99e4c 100644 --- a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png +++ 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 differindex 0af0073e448..d181a1e94c3 100644 --- a/doc/user/group/insights/img/insights_group_configuration.png +++ b/doc/user/group/insights/img/insights_group_configuration.png diff --git a/doc/user/group/insights/img/insights_sidebar_link.png b/doc/user/group/insights/img/insights_sidebar_link.png Binary files differindex 64bbd1fc4d3..f7b0c2daae3 100644 --- a/doc/user/group/insights/img/insights_sidebar_link.png +++ b/doc/user/group/insights/img/insights_sidebar_link.png diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 1aba5d0986b..f0e7f7239c1 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -2,10 +2,9 @@ type: reference, howto --- -# Insights **[ULTIMATE]** +# Insights **(ULTIMATE)** -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag. -> **Generally Available** (GA) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. 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 diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 46d5c1e2e09..dc4b057789f 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -2,7 +2,7 @@ type: reference --- -# Issues Analytics **[PREMIUM]** +# Issues Analytics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. diff --git a/doc/user/group/roadmap/img/roadmap_view.png b/doc/user/group/roadmap/img/roadmap_view.png Binary files differindex ff41a2e0441..2be3849ba1b 100644 --- a/doc/user/group/roadmap/img/roadmap_view.png +++ 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 index 683c715c8d5..a72cd990706 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -2,9 +2,9 @@ type: reference --- -# Roadmap **[ULTIMATE]** +# Roadmap **(ULTIMATE)** -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.5. +> 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 @@ -30,7 +30,7 @@ Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-ep ## Timeline duration -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.0. +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. Roadmap supports the following date ranges: 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 differindex 98b83d0cb0f..e03c50ceb01 100644 --- a/doc/user/group/saml_sso/img/group_saml_configuration_information.png +++ 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 differindex d95acb5075f..487be4faeba 100644 --- a/doc/user/group/saml_sso/img/group_saml_settings.png +++ 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 differindex 3b70e3fbe83..c9e095dc89a 100644 --- a/doc/user/group/saml_sso/img/scim_advanced.png +++ 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 differindex c9f6b71f5b0..933d8fb6f36 100644 --- a/doc/user/group/saml_sso/img/scim_attribute_mapping.png +++ b/doc/user/group/saml_sso/img/scim_attribute_mapping.png diff --git a/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png Binary files differnew file mode 100644 index 00000000000..f9c63970f16 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png diff --git a/doc/user/group/saml_sso/img/scim_provisioning_status.png b/doc/user/group/saml_sso/img/scim_provisioning_status.png Binary files differnew file mode 100644 index 00000000000..41466ec9276 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_provisioning_status.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 differindex 7eb52bf6ea2..bf9347716e9 100644 --- a/doc/user/group/saml_sso/img/scim_token.png +++ 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 differindex 0561443b5f4..9d53a9bf407 100644 --- a/doc/user/group/saml_sso/img/unlink_group_saml.png +++ 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 index fcfd638f185..e3f657af564 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -2,7 +2,7 @@ type: reference, howto --- -# SAML SSO for GitLab.com Groups **[SILVER ONLY]** +# SAML SSO for GitLab.com Groups **(SILVER ONLY)** > Introduced in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.0. @@ -35,6 +35,8 @@ SSO enforcement was: 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 cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. +However, users will not be prompted to log via SSO on each visit. GitLab will check whether a user has authenticated through the SSO link, and will only prompt the user to login via SSO if it has been longer than 7 days. + We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab-ee/issues/9152) in the future. ### NameID @@ -69,7 +71,7 @@ Once you've set up your identity provider to work with GitLab, you'll need to co 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 **Enable SAML authentication for this group** toggle switch. 1. Click the **Save changes** button.  diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 96cc523f4ec..5d136ad62da 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -2,7 +2,7 @@ type: howto, reference --- -# SCIM provisioning using SAML SSO for Groups **[SILVER ONLY]** +# 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. @@ -24,28 +24,28 @@ The following identity providers are supported: ## Requirements -- [Group SSO](index.md) needs to be configured. +- [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 + 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: @@ -53,70 +53,86 @@ Once [Single sign-on](index.md) has been configured, we can: 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 +## Identity Provider configuration -### Configuration on Azure +### 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 SAML application that was created during [Single sign-on](index.md) setup now needs to be set up for SCIM. -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). +1. Check the configuration for your GitLab SAML app and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab. -Note the following: +  + +1. Set up automatic provisioning and administrative credentials by following the + [Provisioning users and groups to applications that support SCIM](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim) section in Azure's SCIM setup documentation. + +During this configuration, note the following: - The `Tenant URL` and `secret token` are the ones retrieved in the -[previous step](#gitlab-configuration). + [previous step](#gitlab-configuration). - Should there be any problems with the availability of GitLab or similar -errors, the notification email set will get those. + errors, the notification email set will get those. +- It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox. - For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled. -You can then test the connection clicking on `Test Connection`. +You can then test the connection by clicking on **Test Connection**. If the connection is successful, be sure to save your configuration before moving on. See below for [troubleshooting](#troubleshooting). + +#### Configure attribute mapping + +1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure the attribute mapping. +1. Click **Delete** next to the `mail` mapping. +1. Map `userPrincipalName` to `emails[type eq "work"].value` and change it's **Matching precedence** to `2`. +1. Map `mailNickname` to `userName`. +1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to `objectId`, **Target attribute** to `id`, **Match objects using this attribute** to `Yes`, and **Matching precedence** to `1`. +1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to `objectId`, and **Target attribute** to `externalId`. +1. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`. -### Synchronize Azure Active Directory users + Save your changes and you should have the following configuration: -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: - -  + NOTE: **Note:** If you used a unique identifier **other than** `objectId`, be sure to map it instead to both `id` and `externalId`. + +1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**. -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. - -  + 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`. + 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. +  + + 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. -<!-- ## Troubleshooting +## Troubleshooting + +### Testing Azure connection: invalid credentials + +When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. + +### Azure: (Field) can't be blank sync error + +When checking the Audit Logs for the Provisioning, you can sometimes see the +error `Namespace can't be blank, Name can't be blank, and User can't be blank.` + +This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +As a workaround, try an alternate mapping: -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +1. Follow the Azure mapping instructions from above. +1. Delete the `name.formatted` target attribute entry. +1. Change the `displayName` source attribute to have `name.formatted` target attribute. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 79ae94dd9ef..2eb3fae1a85 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -5,8 +5,7 @@ type: reference, howto, concepts # Subgroups NOTE: **Note:** -[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2772) in GitLab 9.0. Not available when using MySQL as external -database (support removed in GitLab 9.3 [due to performance reasons](https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600)). +[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2772) in GitLab 9.0. Subgroups, also known as nested groups or hierarchical groups, allow you to have up to 20 levels of groups. @@ -21,16 +20,6 @@ By using subgroups you can do the following: - **Make it easier to manage people and control visibility.** Give people different [permissions](../../permissions.md#group-members-permissions) depending on their group [membership](#membership). -## Database Requirements - -Subgroups are only supported when you use PostgreSQL. Supporting subgroups on MySQL in an -efficient way is not possible due to MySQL's limitations. - -See the following links for more information: - -- <https://gitlab.com/gitlab-org/gitlab-ce/issues/30472> -- <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10885> - ## Overview A group can have many subgroups inside it, and at the same time a group can have @@ -39,39 +28,39 @@ only 1 parent group. It resembles a directory behavior or a nested items list: - Group 1 - Group 1.1 - Group 1.2 - - Group 1.2.1 - - Group 1.2.2 - - Group 1.2.2.1 + - Group 1.2.1 + - Group 1.2.2 + - Group 1.2.2.1 In a real world example, imagine maintaining a GNU/Linux distribution with the first group being the name of the distribution, and subsequent groups split as follows: - Organization Group - GNU/Linux distro - Category Subgroup - Packages - - (project) Package01 - - (project) Package02 + - (project) Package01 + - (project) Package02 - Category Subgroup - Software - - (project) Core - - (project) CLI - - (project) Android app - - (project) iOS app + - (project) Core + - (project) CLI + - (project) Android app + - (project) iOS app - Category Subgroup - Infra tools - - (project) Ansible playbooks + - (project) Ansible playbooks Another example of GitLab as a company would be the following: - Organization Group - GitLab - Category Subgroup - Marketing - - (project) Design - - (project) General + - (project) Design + - (project) General - Category Subgroup - Software - - (project) GitLab CE - - (project) GitLab EE - - (project) Omnibus GitLab - - (project) GitLab Runner - - (project) GitLab Pages daemon + - (project) GitLab CE + - (project) GitLab EE + - (project) Omnibus GitLab + - (project) GitLab Runner + - (project) GitLab Pages daemon - Category Subgroup - Infra tools - - (project) Chef cookbooks + - (project) Chef cookbooks - Category Subgroup - Executive team --- @@ -85,27 +74,37 @@ structure. ## Creating a subgroup -NOTE: **Note:** -You must be an Owner of a group to create a subgroup. For -more information check the [permissions table](../../permissions.md#group-members-permissions). -For a list of words that are not allowed to be used as group names see the +To create a subgroup you must either be an Owner or a Maintainer of the +group, depending on the group's setting. + +By default, groups created in: + +- GitLab 12.2 or later allow both Owners and Maintainers to create subgroups. +- GitLab 12.1 or earlier only allow Owners to create subgroups. + +This setting can be for any group by an Owner or Administrator. + +For more information check the +[permissions table](../../permissions.md#group-members-permissions). For a list +of words that are not allowed to be used as group names see the [reserved names](../../reserved_names.md). -Users can always create subgroups if they are explicitly added as an Owner to -a parent group, even if group creation is disabled by an administrator in their -settings. + +Users can always create subgroups if they are explicitly added as an Owner (or +Maintainer, if that setting is enabled) to a parent group, even if group +creation is disabled by an administrator in their settings. To create a subgroup: 1. In the group's dashboard expand the **New project** split button, select **New subgroup** and click the **New subgroup** button. -  +  1. Create a new group like you would normally do. Notice that the parent group namespace is fixed under **Group path**. The visibility level can differ from the parent group. -  +  1. Click the **Create group** button and you will be taken to the new group's dashboard page. diff --git a/doc/user/img/color_inline_colorchip_render_gfm.png b/doc/user/img/color_inline_colorchip_render_gfm.png Binary files differdeleted file mode 100644 index 6f93dbeeb10..00000000000 --- a/doc/user/img/color_inline_colorchip_render_gfm.png +++ /dev/null diff --git a/doc/user/img/markdown_inline_diffs_tags_rendered.png b/doc/user/img/markdown_inline_diffs_tags_rendered.png Binary files differdeleted file mode 100644 index 4279a20b5a0..00000000000 --- a/doc/user/img/markdown_inline_diffs_tags_rendered.png +++ /dev/null diff --git a/doc/user/img/math_inline_sup_render_gfm.png b/doc/user/img/math_inline_sup_render_gfm.png Binary files differdeleted file mode 100644 index 3ee2abb14df..00000000000 --- a/doc/user/img/math_inline_sup_render_gfm.png +++ /dev/null diff --git a/doc/user/img/task_list_ordered_render_gfm.png b/doc/user/img/task_list_ordered_render_gfm.png Binary files differdeleted file mode 100644 index 98ec791e958..00000000000 --- a/doc/user/img/task_list_ordered_render_gfm.png +++ /dev/null diff --git a/doc/user/index.md b/doc/user/index.md index 1fc4e4c43cf..c93f64cd528 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -2,7 +2,7 @@ description: 'Read through the GitLab User documentation to learn how to use, configure, and customize GitLab and GitLab.com to your own needs.' --- -# User documentation +# User Docs Welcome to GitLab! We're glad to have you here! @@ -66,7 +66,7 @@ With GitLab Enterprise Edition, you can also: - Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md). - Scan your code for vulnerabilities and [display them in merge requests](application_security/sast/index.md). -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. +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. ## Projects @@ -124,12 +124,12 @@ merge requests, code snippets, and commits. When performing inline reviews to implementations to your codebase through merge requests you can -gather feedback through [resolvable discussions](discussions/index.md#resolvable-comments-and-discussions). +gather feedback through [resolvable threads](discussions/index.md#resolvable-comments-and-threads). ### GitLab Flavored Markdown (GFM) Read through the [GFM documentation](markdown.md) to learn how to apply -the best of GitLab Flavored Markdown in your discussions, comments, +the best of GitLab Flavored Markdown in your threads, comments, issues and merge requests descriptions, and everywhere else GMF is supported. @@ -148,12 +148,12 @@ requests you're assigned to. [Snippets](snippets.md) are code blocks that you want to store in GitLab, from which you have quick access to. You can also gather feedback on them through -[discussions](#discussions). +[Discussions](#Discussions). ## Integrations [Integrate GitLab](../integration/README.md) with your preferred tool, -such as Trello, JIRA, etc. +such as Trello, Jira, etc. ## Webhooks @@ -173,7 +173,7 @@ Learn what is [Git](../topics/git/index.md) and its best practices. See [various statistics](instance_statistics/index.md) of your GitLab instance. -## Operations Dashboard **[PREMIUM]** +## Operations Dashboard **(PREMIUM)** See [Operations Dashboard](operations_dashboard/index.md) for a summary of each project's operational health. diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 894f83d3c75..f557dcf4b3c 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -1,7 +1,6 @@ # Instance-level Kubernetes clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/39840) in GitLab 11.11. -> Instance-level cluster integration is currently in [Beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga). ## Overview diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 31c8093ced7..6cfc8b6429b 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,15 +1,20 @@ # GitLab Markdown -This markdown guide is **valid for GitLab's system markdown entries and files**. -It is not valid for the [GitLab documentation website](https://docs.gitlab.com) -nor [GitLab's main website](https://about.gitlab.com), as they both use -[Kramdown](https://kramdown.gettalong.org) as their markdown engine. -The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). -Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference. +This markdown guide is **valid only for GitLab's internal markdown rendering system for entries and files**. +It is **not** valid for the [GitLab documentation website](https://docs.gitlab.com) +or [GitLab's main website](https://about.gitlab.com), as they both use +[Kramdown](https://kramdown.gettalong.org) as their markdown engine. The documentation +website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). +Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) +for a complete Kramdown reference. + +NOTE: **Note:** We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md). ## GitLab Flavored Markdown (GFM) -GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add additional useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). +GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/) +(which is based on standard Markdown) in several ways to add additional useful functionality. +It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). You can use GFM in the following areas: @@ -20,37 +25,31 @@ 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. - -> **Notes:** -> -> We encourage you to view this document as [rendered by GitLab itself](markdown.md). -> -> As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown -processing of all new issues, merge requests, comments, and other Markdown content -in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the -repositories are also processed with CommonMark. As of 11.8, the [Redcarpet -Ruby library][redcarpet] has been removed and all issues/comments, including -those from pre-11.1, are now processed using [CommonMark Ruby -Library][commonmarker]. -> -> The documentation website had its [markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108) -in October 2018. -> -> _Where there are significant differences, we will try to call them out in this document._ +- 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 [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup) +for more information. -### Transitioning to CommonMark +### Transition from Redcarpet to CommonMark + +Since 11.1, GitLab uses the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker) +for Markdown processing of all new issues, merge requests, comments, and other Markdown +content in the GitLab system. Since 11.3, wiki pages and Markdown files (`*.md`) in +repositories are also processed with CommonMark. As of 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet) +has been removed and all issues and comments, including those from pre-11.1, are now processed +using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker). + +The documentation website had its [markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/108) +in October 2018. -You may have older issues/merge requests or Markdown documents in your -repository that were written using some of the nuances of RedCarpet's version +You may have older issues, merge requests, or Markdown documents in your +repository that were written using some of the nuances of GitLab's RedCarpet version of Markdown. Since CommonMark uses a slightly stricter syntax, these documents -may now display a little strangely since we've transitioned to CommonMark. -Numbered lists with nested lists in particular can be displayed incorrectly. +may now display a little differently since we've transitioned to CommonMark. -It is usually quite easy to fix. In the case of a nested list such as this: +It is usually quite easy to fix. For example, numbered lists with nested lists may +render incorrectly: ```markdown 1. Chocolate @@ -58,7 +57,14 @@ It is usually quite easy to fix. In the case of a nested list such as this: - milk ``` -simply add a space to each nested item: +1. Chocolate + - dark + - milk + +--- + +Simply add a space to each nested item to align the `-` with the first character of +the top list item (`C` in this case): ```markdown 1. Chocolate @@ -66,776 +72,925 @@ simply add a space to each nested item: - milk ``` -In the documentation below, we try to highlight some of the differences. +1. Chocolate + - dark + - milk + +NOTE: **Note:** We will flag any significant differences between Redcarpet and CommonMark + markdown in this document. If you have a large volume of Markdown files, it can be tedious to determine -if they will be displayed correctly or not. You can use the +if they will display correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) -tool (not an officially supported product) to generate a list of files and +tool (not an officially supported product) to generate a list of files, and the differences between how RedCarpet and CommonMark render the files. It can give -you a great idea if anything needs to be changed - many times nothing will need -to changed. +an indication if anything needs to be changed - often nothing will need +to change. + +### GFM extends standard markdown + +GitLab makes full use of the standard (CommonMark) formatting, but also includes additional +functionality useful for GitLab users. + +It makes use of [new markdown features](#new-GFM-markdown-extensions), +not found in standard markdown: + +- [Color "chips" written in HEX, RGB or HSL](#colors) +- [Diagrams and flowcharts using Mermaid](#diagrams-and-flowcharts-using-mermaid) +- [Emoji](#emoji) +- [Front matter](#front-matter) +- [Inline diffs](#inline-diff) +- [Math equations and symbols written in LaTeX](#math) +- [Special GitLab references](#special-gitlab-references) +- [Task Lists](#task-lists) +- [Wiki specific markdown](#wiki-specific-markdown) + +It also has [extended markdown features](#standard-markdown-and-extensions-in-gitlab), without +changing how standard markdown is used: + +| Standard markdown | Extended markdown in GitLab | +| ------------------------------------- | ------------------------- | +| [blockquotes](#blockquotes) | [multiline blockquotes](#multiline-blockquote) | +| [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) | +| [emphasis](#emphasis) | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis) +| [headers](#headers) | [linkable Header IDs](#header-ids-and-links) | +| [images](#images) | [embedded videos](#videos) | +| [linebreaks](#line-breaks) | [more linebreak control](#newlines) | +| [links](#links) | [automatically linking URLs](#url-auto-linking) | + +## New GFM markdown extensions -### Newlines +### Colors -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colors). -GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec]. +It is possible to have color written in HEX, RGB or HSL format rendered with a color +indicator. -A paragraph is simply one or more consecutive lines of text, separated by one or -more blank lines. -Line-breaks, or soft returns, are rendered if you end a line with two or more spaces: +Supported formats (named colors are not supported): -<!-- (Do *NOT* remove the two ending whitespaces in the following line.) --> -<!-- (They are needed for the Markdown text to render correctly.) --> - Roses are red [followed by two or more spaces] - Violets are blue +- HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` +- RGB: `` `RGB[A](R, G, B[, A])` `` +- HSL: `` `HSL[A](H, S, L[, A])` `` - Sugar is sweet +Color written inside backticks will be followed by a color "chip": -<!-- (Do *NOT* remove the two ending whitespaces in the following line.) --> -<!-- (They are needed for the Markdown text to render correctly.) --> -Roses are red -Violets are blue +```markdown +`#F00` +`#F00A` +`#FF0000` +`#FF0000AA` +`RGB(0,255,0)` +`RGB(0%,100%,0%)` +`RGBA(0,255,0,0.3)` +`HSL(540,70%,50%)` +`HSLA(540,70%,50%,0.3)` +``` -Sugar is sweet +`#F00` +`#F00A` +`#FF0000` +`#FF0000AA` +`RGB(0,255,0)` +`RGB(0%,100%,0%)` +`RGBA(0,255,0,0.3)` +`HSL(540,70%,50%)` +`HSLA(540,70%,50%,0.3)` -### Multiple underscores in words +### Diagrams and flowcharts using Mermaid -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15107) in +GitLab 10.3. -It is not reasonable to italicize just _part_ of a word, especially when you're -dealing with code and names that often appear with multiple underscores. -Therefore, GFM ignores multiple underscores in words: +It is possible to generate diagrams and flowcharts from text using [Mermaid](https://mermaidjs.github.io/). +Visit the official page for more details. - perform_complicated_task +In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block: - do_this_and_do_that_and_another_thing +~~~ +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` +~~~ -perform_complicated_task +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` -do_this_and_do_that_and_another_thing +#### Subgraphs + +NOTE: **Note:** GitLab 12.1 and up now [requires quotes around subgraph +titles that contain multiple words](https://github.com/knsv/mermaid/pull/845). + +Subgraphs can also be included: -### URL auto-linking +~~~ +```mermaid +graph TB + + SubGraph1 --> SubGraph1Flow + subgraph "SubGraph 1 Flow" + SubGraph1Flow(SubNode 1) + SubGraph1Flow -- Choice1 --> DoChoice1 + SubGraph1Flow -- Choice2 --> DoChoice2 + end + + subgraph "Main Graph" + Node1[Node 1] --> Node2[Node 2] + Node2 --> SubGraph1[Jump to SubGraph1] + SubGraph1 --> FinalThing[Final Thing] +end +``` +~~~ -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#url-auto-linking +```mermaid +graph TB + + SubGraph1 --> SubGraph1Flow + subgraph "SubGraph 1 Flow" + SubGraph1Flow(SubNode 1) + SubGraph1Flow -- Choice1 --> DoChoice1 + SubGraph1Flow -- Choice2 --> DoChoice2 + end + + subgraph "Main Graph" + Node1[Node 1] --> Node2[Node 2] + Node2 --> SubGraph1[Jump to SubGraph1] + SubGraph1 --> FinalThing[Final Thing] +end +``` -GFM will autolink almost any URL you copy and paste into your text: +### Emoji - * https://www.google.com - * https://google.com/ - * ftp://ftp.us.debian.org/debian/ - * smb://foo/bar/baz - * irc://irc.freenode.net/gitlab - * http://localhost:3000 +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji). -* https://www.google.com -* https://google.com/ -* ftp://ftp.us.debian.org/debian/ -* <a href="smb://foo/bar/baz">smb://foo/bar/baz</a> -* <a href="irc://irc.freenode.net/gitlab">irc://irc.freenode.net/gitlab</a> -* http://localhost:3000 +```md +Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: -### Multiline blockquote +:zap: You can use emoji anywhere GFM is supported. :v: -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote +You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. -On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines, -GFM supports multiline blockquotes fenced by <code>>>></code>: +If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. +Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: ``` ->>> -If you paste a message from somewhere else -that +Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0">. Well we have a gift for you: -spans +<img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0"> -multiple lines, +You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0">. People will <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0"> you for that. -you can quote that without having to manually prepend `>` to every line! ->>> -``` +If you are new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes. -<blockquote dir="auto"> -<p>If you paste a message from somewhere else</p> -<p>that</p> -<p>spans</p> -<p>multiple lines,</p> -<p>you can quote that without having to manually prepend <code>></code> to every line!</p> -</blockquote> +Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0"> -### Code and syntax highlighting +> **Note:** The emoji example above uses hard-coded images for this documentation. The emoji, +when rendered within GitLab, may appear different depending on the OS and browser used. -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting +Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. -_GitLab uses the [Rouge Ruby library][rouge] for syntax highlighting. For a -list of supported languages visit the Rouge website._ +NOTE: **Note:** On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) +to get full native emoji support. Ubuntu 18.04 (like many modern Linux distros) has +this font installed by default. -Blocks of code are either fenced by lines with three back-ticks <code>```</code>, -or are indented with four spaces. Only the fenced code blocks support syntax -highlighting: +### Front matter -``` -Inline `code` has `back-ticks around` it. -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331) + in GitLab 11.6. -Inline `code` has `back-ticks around` it. +Front matter is metadata included at the beginning of a markdown document, preceding +its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/), +[Hugo](https://gohugo.io/content-management/front-matter/), and many other applications. -Example: +When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, +in a box at the top of the document, before the rendered HTML content. To view an example, +you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/README.md). - ```javascript - var s = "JavaScript syntax highlighting"; - alert(s); - ``` +In GitLab, front matter is only used in Markdown files and wiki pages, not the other +places where Markdown formatting is supported. It must be at the very top of the document, +and must be between delimiters, as explained below. - ```python - def function(): - #indenting works just fine in the fenced code block - s = "Python syntax highlighting" - print s - ``` +The following delimeters are supported: - ```ruby - require 'redcarpet' - markdown = Redcarpet.new("Hello World!") - puts markdown.to_html - ``` +- YAML (`---`): - ``` - No language indicated, so no syntax highlighting. - s = "There is no highlighting for this." - But let's throw in a <b>tag</b>. - ``` + ~~~yaml + --- + title: About Front Matter + example: + language: yaml + --- + ~~~ -becomes: +- TOML (`+++`): -```javascript -var s = "JavaScript syntax highlighting"; -alert(s); -``` + ~~~toml + +++ + title = "About Front Matter" + [example] + language = "toml" + +++ + ~~~ -```python -def function(): - #indenting works just fine in the fenced code block - s = "Python syntax highlighting" - print s -``` +- JSON (`;;;`): -```ruby -require 'redcarpet' -markdown = Redcarpet.new("Hello World!") -puts markdown.to_html -``` + ~~~json + ;;; + { + "title": "About Front Matter" + "example": { + "language": "json" + } + } + ;;; + ~~~ -``` -No language indicated, so no syntax highlighting. -s = "There is no highlighting for this." -But let's throw in a <b>tag</b>. +Other languages are supported by adding a specifier to any of the existing +delimiters. For example: + +```php +---php +$title = "About Front Matter"; +$example = array( + 'language' => "php", +); +--- ``` ### Inline diff -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff). -With inline diffs tags you can display {+ additions +} or [- deletions -]. +With inline diff tags you can display `{+ additions +}` or `[- deletions -]`. -The wrapping tags can be either curly braces or square brackets. - -Examples: +The wrapping tags can be either curly braces or square brackets: -``` -- {+ additions +} -- [+ additions +] -- {- deletions -} -- [- deletions -] +```markdown +- {+ addition 1 +} +- [+ addition 2 +] +- {- deletion 3 -} +- [- deletion 4 -] ``` -becomes: +- {+ addition 1 +} +- [+ addition 2 +] +- {- deletion 3 -} +- [- deletion 4 -] - +--- -However the wrapping tags cannot be mixed as such: +However the wrapping tags cannot be mixed: -``` -- {+ additions +] -- [+ additions +} -- {- deletions -] -- [- deletions -} +```markdown +- {+ addition +] +- [+ addition +} +- {- deletion -] +- [- deletion -} ``` -### Emoji - -```md -Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: - -:zap: You can use emoji anywhere GFM is supported. :v: +### Math -You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math). -If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. +It is possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/Khan/KaTeX). -Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: +Math written between dollar signs `$` will be rendered inline with the text. Math written +inside a [code block](#code-spans-and-blocks) with the language declared as `math`, will be rendered +on a separate line: -Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. +~~~ +This math is inline $`a^2+b^2=c^2`$. -On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. +This is on a separate line -Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +```math +a^2+b^2=c^2 ``` +~~~ -Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0">. Well we have a gift for you: +This math is inline $`a^2+b^2=c^2`$. -<img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0"> - -You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0">. People will <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0"> you for that. - -If you are new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes. - -Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0"> +This is on a separate line -Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. +```math +a^2+b^2=c^2 +``` -On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. +_Be advised that KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ -Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +NOTE: **Note:** This also works for the asciidoctor `:stem: latexmath`. For details see +the [asciidoctor user manual](http://asciidoctor.org/docs/user-manual/#activating-stem-support). ### Special GitLab references -GFM recognizes special references. - -You can easily reference e.g. an issue, a commit, a team member or even the whole team within a project. +GFM recognizes special GitLab related references. For example, you can easily reference +an issue, a commit, a team member or even the whole team within a project. GFM will turn +that reference into a link so you can navigate between them easily. -GFM will turn that reference into a link so you can navigate between them easily. +Additionally, GFM recognizes certain cross-project references, and also has a shorthand +version to reference other projects from the same namespace. GFM will recognize the following: -| input | references | -|:---------------------------|:--------------------------------| -| `@user_name` | specific user | -| `@group_name` | specific group | -| `@all` | entire team | -| `namespace/project>` | project | -| `#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 | -| `%123` | project milestone by ID | -| `%v1.23` | one-word milestone by name | -| `%"release candidate"` | multi-word milestone by name | -| `9ba12248` | specific commit | -| `9ba12248...b19a04f5` | commit range comparison | -| `[README](doc/README)` | repository file references | -| `[README](doc/README#L13)` | repository file line references | - -GFM also recognizes certain cross-project references: - -| input | references | -|:----------------------------------------|:------------------------| -| `namespace/project#123` | issue | -| `namespace/project!123` | merge request | -| `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 | - -It also has a shorthand version to reference other projects from the same namespace: - -| input | references | -|:------------------------------|:------------------------| -| `project#123` | issue | -| `project!123` | merge request | -| `project%123` | project milestone | -| `project$123` | snippet | -| `project@9ba12248` | specific commit | -| `project@9ba12248...b19a04f5` | commit range comparison | -| `project~"Some label"` | issues with given label | +| references | input | cross-project reference | shortcut within same namespace | +| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | +| specific user | `@user_name` | | | +| specific group | `@group_name` | | | +| entire team | `@all` | | | +| project | `namespace/project>` | | | +| issue | ``#123`` | `namespace/project#123` | `project#123` | +| merge request | `!123` | `namespace/project!123` | `project!123` | +| snippet | `$123` | `namespace/project$123` | `project$123` | +| epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | +| label by ID | `~123` | `namespace/project~123` | `project~123` | +| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | +| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | +| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | +| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | +| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | +| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | +| repository file references | `[README](doc/README)` | | | +| repository file line references | `[README](doc/README#L13)` | | | ### Task lists -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists). -You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so: +You can add task lists anywhere markdown is supported, but you can only "click" to +toggle the boxes if they are in issues, merge requests, or comments. In other places +you must edit the markdown manually to change the status by adding or removing the `x`. -``` +To create a task list, add a specially-formatted Markdown list. You can use either +unordered or ordered lists: + +```markdown - [x] Completed task - [ ] Incomplete task - - [ ] Sub-task 1 - - [x] Sub-task 2 - - [ ] Sub-task 3 -``` + - [ ] Sub-task 1 + - [x] Sub-task 2 + - [ ] Sub-task 3 - +1. [x] Completed task +1. [ ] Incomplete task + 1. [ ] Sub-task 1 + 1. [x] Sub-task 2 +``` -Tasks formatted as ordered lists are supported as well: +- [x] Completed task +- [ ] Incomplete task + - [ ] Sub-task 1 + - [x] Sub-task 2 + - [ ] Sub-task 3 -``` 1. [x] Completed task 1. [ ] Incomplete task - 1. [ ] Sub-task 1 - 1. [x] Sub-task 2 -``` + 1. [ ] Sub-task 1 + 1. [x] Sub-task 2 - +### Wiki-specific Markdown -Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes. +The following examples show how links inside wikis behave. -### Videos +#### Wiki - Direct page link -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos +A link which just includes the slug for a page will point to that page, +_at the base level of the wiki_. -Image tags with a video extension are automatically converted to a video player. +This snippet would link to a `documentation` page at the root of your wiki: -The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`. +```markdown +[Link to Documentation](documentation) +``` - Here's a sample video: +#### Wiki - Direct file link -  +Links with a file extension point to that file, _relative to the current page_. -Here's a sample video: +If the snippet below was placed on a page at `<your_wiki>/documentation/related`, +it would link to `<your_wiki>/documentation/file.md`: -<div class="video-container"> - <video src="img/markdown_video.mp4" width="400" controls="true" data-setup="{}" data-title="Sample Video"></video> - <p><a href="img/markdown_video.mp4" target="_blank" rel="noopener noreferrer" title="Download 'Sample Video'">Sample Video</a></p> -</div> +```markdown +[Link to File](file.md) +``` -### Math +#### Wiki - Hierarchical link -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math +A link can be constructed relative to the current wiki page using `./<page>`, +`../<page>`, etc. -It is possible to have math written with the LaTeX syntax rendered using [KaTeX][katex]. +If this snippet was placed on a page at `<your_wiki>/documentation/main`, +it would link to `<your_wiki>/documentation/related`: -Math written inside ```$``$``` will be rendered inline with the text. +```markdown +[Link to Related Page](./related) +``` -Math written inside triple back quotes, with the language declared as `math`, will be rendered on a separate line. +If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, +it would link to `<your_wiki>/documentation/main`: -Example: +```markdown +[Link to Related Page](../main) +``` - This math is inline $`a^2+b^2=c^2`$. +If this snippet was placed on a page at `<your_wiki>/documentation/main`, +it would link to `<your_wiki>/documentation/related.md`: - This is on a separate line - ```math - a^2+b^2=c^2 - ``` +```markdown +[Link to Related Page](./related.md) +``` -Becomes: +If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, +it would link to `<your_wiki>/documentation/main.md`: -This math is inline . +```markdown +[Link to Related Page](../main.md) +``` -This is on a separate line +#### Wiki - Root link -<img src="./img/math_inline_sup_render_gfm.png" > +A link starting with a `/` is relative to the wiki root. -_Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._ +This snippet links to `<wiki_root>/documentation`: ->**Note:** -This also works for the asciidoctor `:stem: latexmath`. For details see the [asciidoctor user manual][asciidoctor-manual]. +```markdown +[Link to Related Page](/documentation) +``` -### Colors +This snippet links to `<wiki_root>/miscellaneous.md`: -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colors +```markdown +[Link to Related Page](/miscellaneous.md) +``` -It is possible to have color written in HEX, RGB or HSL format rendered with a color indicator. +### Embedding metrics in GitLab Flavored Markdown -Color written inside backticks will be followed by a color "chip". +Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab flavored Markdown](../user/project/integrations/prometheus.md#embedding-metric-charts-within-gitlab-flavored-markdown) for more details. -Examples: +## Standard markdown and extensions in GitLab - `#F00` - `#F00A` - `#FF0000` - `#FF0000AA` - `RGB(0,255,0)` - `RGB(0%,100%,0%)` - `RGBA(0,255,0,0.7)` - `HSL(540,70%,50%)` - `HSLA(540,70%,50%,0.7)` +All standard markdown formatting should work as expected within GitLab. Some standard +functionality is extended with additional features, without affecting the standard usage. +If a functionality is extended, the new option will be listed as a sub-section. -Becomes: +### Blockquotes - +Blockquotes are an easy way to highlight information, such as a side-note. It is generated +by starting the lines of the blockquote with `>`: -#### Supported formats: +```markdown +> Blockquotes are very handy to emulate reply text. +> This line is part of the same quote. -* HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` -* RGB: `` `RGB[A](R, G, B[, A])` `` -* HSL: `` `HSL[A](H, S, L[, A])` `` +Quote break. -### Mermaid +> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +``` -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15107) in -GitLab 10.3. -> -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#mermaid +> Blockquotes are very handy to emulate reply text. +> This line is part of the same quote. -It is possible to generate diagrams and flowcharts from text using [Mermaid](https://mermaidjs.github.io/). +Quote break. -In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block. +> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. -Example: +#### Multiline blockquote - ```mermaid - graph TD; - A-->B; - A-->C; - B-->D; - C-->D; - ``` +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote). -Becomes: +GFM extends the standard markdown standard by also supporting multiline blockquotes +fenced by `>>>`: -```mermaid -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; ``` +>>> +If you paste a message from somewhere else -For details see the [Mermaid official page](https://mermaidjs.github.io/). - -### Front matter +that spans multiple lines, -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331) - in GitLab 11.6. +you can quote that without having to manually prepend `>` to every line! +>>> +``` -Front matter is metadata included at the beginning of a markdown document, preceding -its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/) and [Hugo](https://gohugo.io/content-management/front-matter/), -and many other applications. +>>> +If you paste a message from somewhere else -In GitLab, front matter is only used in Markdown files and wiki pages, not the other places where Markdown formatting is supported. -When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, in a box at the top of the document, before the rendered HTML content. -To view an example, you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/README.md). +that spans multiple lines, -The following delimeters are supported: +you can quote that without having to manually prepend `>` to every line! +>>> -- YAML (`---`): +### Code spans and blocks - ``` - --- - title: About Front Matter - example: - language: yaml - --- - ``` +You can easily highlight anything that should be viewed as code and not simple text. -- TOML (`+++`): +Simple inline code is easily highlighted with single backticks `` ` ``: - ``` - +++ - title = "About Front Matter" - [example] - language = "toml" - +++ - ``` +```markdown +Inline `code` has `back-ticks around` it. +``` -- JSON (`;;;`): +Inline `code` has `back-ticks around` it. - ``` - ;;; - { - "title": "About Front Matter" - "example": { - "language": "json" - } - } - ;;; - ``` +--- -Other languages are supported by adding a specifier to any of the existing -delimiters. For example: +Similarly, a whole block of code can be fenced with triple backticks ```` ``` ````, +triple tildes (`~~~`), or indended 4 or more spaces to achieve a similar effect for +a larger body of code. +~~~ ``` ----php -$title = "About Front Matter"; -$example = array( - 'language' => "php", -); ---- +def function(): + #indenting works just fine in the fenced code block + s = "Python code" + print s ``` -## Standard Markdown - -### Headers + Using 4 spaces + is like using + 3-backtick fences. +~~~ ``` -# H1 -## H2 -### H3 -#### H4 -##### H5 -###### H6 +~~~ +Tildes are OK too. +~~~ +``` -Alternatively, for H1 and H2, an underline-ish style: +The three examples above render as: -Alt-H1 -====== +``` +def function(): + #indenting works just fine in the fenced code block + s = "Python code" + print s +``` -Alt-H2 ------- +``` +Using 4 spaces +is like using +3-backtick fences. ``` -#### Header IDs and links +~~~ +Tildes are OK too. +~~~ -All Markdown-rendered headers automatically get IDs, which can be linked to, except in comments. +#### Colored code and syntax highlighting -On hover, a link to those IDs becomes visible to make it easier to copy the link to the header to use it somewhere else. +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). -The IDs are generated from the content of the header according to the following rules: +GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax +highlighting in code blocks. For a list of supported languages visit the +[Rouge project wiki](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers). +Syntax highlighting is only supported in code blocks, it is not possible to highlight +code when it is inline. -1. All text is converted to lowercase. -1. All non-word text (e.g., punctuation, HTML) is removed. -1. All spaces are converted to hyphens. -1. Two or more hyphens in a row are converted to one. -1. If a header with the same ID has already been generated, a unique - incrementing number is appended, starting at 1. +Blocks of code are fenced by lines with three back-ticks ```` ``` ```` or three tildes `~~~`, and have +the language identified at the end of the first fence: -For example: +~~~ +```javascript +var s = "JavaScript syntax highlighting"; +alert(s); +``` +```python +def function(): + #indenting works just fine in the fenced code block + s = "Python syntax highlighting" + print s ``` -# This header has spaces in it -## This header has a :thumbsup: in it -# This header has Unicode in it: 한글 -## This header has spaces in it -### This header has spaces in it -## This header has 3.5 in it (and parentheses) + +```ruby +require 'redcarpet' +markdown = Redcarpet.new("Hello World!") +puts markdown.to_html ``` -Would generate the following link IDs: +``` +No language indicated, so no syntax highlighting. +s = "There is no highlighting for this." +But let's throw in a <b>tag</b>. +``` +~~~ -1. `this-header-has-spaces-in-it` -1. `this-header-has-a-in-it` -1. `this-header-has-unicode-in-it-한글` -1. `this-header-has-spaces-in-it-1` -1. `this-header-has-spaces-in-it-2` -1. `this-header-has-3-5-in-it-and-parentheses` +The four examples above render as: + +```javascript +var s = "JavaScript syntax highlighting"; +alert(s); +``` -Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID. +```python +def function(): + #indenting works just fine in the fenced code block + s = "Python syntax highlighting" + print s +``` + +```ruby +require 'redcarpet' +markdown = Redcarpet.new("Hello World!") +puts markdown.to_html +``` + +``` +No language indicated, so no syntax highlighting. +s = "There is no highlighting for this." +But let's throw in a <b>tag</b>. +``` ### Emphasis +There are multiple ways to emphasize text in markdown. You can italicize, bold, strikethrough, +as well as combine these emphasis styles together. + Examples: -``` +```markdown Emphasis, aka italics, with *asterisks* or _underscores_. -Strong emphasis, aka bold, with **asterisks** or __underscores__. +Strong emphasis, aka bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` -Becomes: - Emphasis, aka italics, with *asterisks* or _underscores_. -Strong emphasis, aka bold, with **asterisks** or __underscores__. +Strong emphasis, aka bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ -### Lists +NOTE: **Note:** Strikethrough is not part of the core Markdown standard, but is part of GFM. -Examples: +#### Multiple underscores in words and mid-word emphasis -``` -1. First ordered list item -2. Another item - * Unordered sub-list. -1. Actual numbers don't matter, just that it's a number - 1. Ordered sub-list -4. And another item. +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words). -* Unordered list can use asterisks -- Or minuses -+ Or pluses +It is not usually useful to italicize just _part_ of a word, especially when you're +dealing with code and names that often appear with multiple underscores. As a result, +GFM extends the standard markdown standard by ignoring multiple underlines in words, +to allow better rendering of markdown documents discussing code: + +```md +perform_complicated_task + +do_this_and_do_that_and_another_thing + +but_emphasis is_desired _here_ ``` -Becomes: +perform_complicated_task -1. First ordered list item -2. Another item - * Unordered sub-list. -1. Actual numbers don't matter, just that it's a number - 1. Ordered sub-list -4. And another item. +do_this_and_do_that_and_another_thing -* Unordered list can use asterisks -- Or minuses -+ Or pluses +but_emphasis is_desired _here_ -If a list item contains multiple paragraphs, -each subsequent paragraph should be indented to the same level as the start of the list item text +--- -Example: +If you wish to emphasize only a part of a word, it can still be done with asterisks: + +```md +perform*complicated*task +do*this*and*do*that*and*another thing ``` -1. First ordered list item - Second paragraph of first item. +perform*complicated*task -2. Another item +do*this*and*do*that*and*another thing + +### Footnotes + +Footnotes add a link to a note rendered at the end of a markdown file: + +```markdown +You can add footnotes to your text as follows.[^1] + +[^1]: This is my awesome footnote (later in file). ``` -Becomes: +You can add footnotes to your text as follows.[^1] -1. First ordered list item +[^1]: This is my awesome footnote (later in file). - Paragraph of first item. +### Headers -2. Another item +```markdown +# H1 +## H2 +### H3 +#### H4 +##### H5 +###### H6 -If the paragraph of the first item is not indented with the proper number of spaces, -the paragraph will appear outside the list, instead of properly indented under the list item. +Alternatively, for H1 and H2, an underline-ish style: -Example: +Alt-H1 +====== +Alt-H2 +------ ``` -1. First ordered list item - Paragraph of first item. +#### Header IDs and links -2. Another item -``` +GFM extends the standard markdown standard so that all Markdown-rendered headers automatically +get IDs, which can be linked to, except in comments. -Becomes: +On hover, a link to those IDs becomes visible to make it easier to copy the link to +the header to use it somewhere else. -1. First ordered list item +The IDs are generated from the content of the header according to the following rules: - Paragraph of first item. +1. All text is converted to lowercase. +1. All non-word text (e.g., punctuation, HTML) is removed. +1. All spaces are converted to hyphens. +1. Two or more hyphens in a row are converted to one. +1. If a header with the same ID has already been generated, a unique + incrementing number is appended, starting at 1. -2. Another item +Example: -### Links +``` +# This header has spaces in it +## This header has a :thumbsup: in it +# This header has Unicode in it: 한글 +## This header has spaces in it +### This header has spaces in it +## This header has 3.5 in it (and parentheses) +``` + +Would generate the following link IDs: + +1. `this-header-has-spaces-in-it` +1. `this-header-has-a-in-it` +1. `this-header-has-unicode-in-it-한글` +1. `this-header-has-spaces-in-it-1` +1. `this-header-has-spaces-in-it-2` +1. `this-header-has-3-5-in-it-and-parentheses` + +Note that the Emoji processing happens before the header IDs are generated, so the +Emoji is converted to an image which is then removed from the ID. -There are two ways to create links, inline-style and reference-style. +### Horizontal Rule + +It's very simple to create a horizontal rule, by using three or more hyphens, asterisks, +or underscores: ```markdown -[I'm an inline-style link](https://www.google.com) -[I'm a link to a repository file in the same directory](index.md) -[I am an absolute reference within the repository](/doc/user/index.md) -[I'm a relative link to the Milestones page](../README.md) +Three or more hyphens, -[I link to a section on a different markdown page, using a header ID](index.md#overview) -[I link to a different section on the same page, using the header ID](#header-ids-and-links) +--- -[I'm a reference-style link][Arbitrary case-insensitive reference text] -[You can use numbers for reference-style link definitions][1] -Or leave it empty and use the [link text itself][] +asterisks, -Some text to show that the reference links can follow later. +*** -[arbitrary case-insensitive reference text]: https://www.mozilla.org -[1]: http://slashdot.org -[link text itself]: https://www.reddit.com +or underscores + +___ ``` ->**Note:** -Relative links do not allow referencing project files in a wiki page or wiki -page in a project file. The reason for this is that, in GitLab, wiki is always -a separate Git repository. For example, `[I'm a reference-style link](style)` -will point the link to `wikis/style` when the link is inside of a wiki markdown file. +Three or more hyphens, + +--- + +asterisks, + +*** + +or underscores + +___ ### Images Examples: - Here's our logo (hover to see the title text): - - Inline-style: -  +```markdown +Inline-style (hover to see title text): - Reference-style: - ![alt text1][logo] + - [logo]: img/markdown_logo.png +Reference-style (hover to see title text): -Becomes: +![alt text1][logo] -Here's our logo: +[logo]: img/markdown_logo.png "Title Text" +``` -Inline-style: +Inline-style (hover to see title text): - + -Reference-style: +Reference-style (hover to see title text): ![alt text][logo] -[logo]: img/markdown_logo.png +[logo]: img/markdown_logo.png "Title Text" -### Blockquotes +#### Videos -Examples: +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos). -``` -> Blockquotes are very handy in email to emulate reply text. -> This line is part of the same quote. +Image tags that link to files with a video extension are automatically converted to +a video player. The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`: -Quote break. +```md +Here's a sample video: -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. + ``` -Becomes: - -> Blockquotes are very handy in email to emulate reply text. -> This line is part of the same quote. - -Quote break. +Here's a sample video: -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. + ### Inline HTML -You can also use raw HTML in your Markdown, and it'll mostly work pretty well. +> To see the markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-html). -See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes. In addition to the default `SanitizationFilter` whitelist, GitLab allows `span`, `abbr`, `details` and `summary` elements. +You can also use raw HTML in your Markdown, and it'll usually work pretty well. -Examples: +See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) +class for the list of allowed HTML tags and attributes. In addition to the default +`SanitizationFilter` whitelist, GitLab allows `span`, `abbr`, `details` and `summary` elements. -``` +```html <dl> <dt>Definition list</dt> <dd>Is something people use sometimes.</dd> <dt>Markdown in HTML</dt> - <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd> + <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>always</b> work.</dd> </dl> ``` -Becomes: - <dl> <dt>Definition list</dt> <dd>Is something people use sometimes.</dd> <dt>Markdown in HTML</dt> - <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd> + <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>always</b> work.</dd> +</dl> + +--- + +It is still possible to use markdown inside HTML tags, but only if the lines containing markdown +are separated into their own lines: + +```html +<dl> + <dt>Markdown in HTML</dt> + <dd>Does *not* work **very** well. HTML tags will always work.</dd> + + <dt>Markdown in HTML</dt> + <dd> + + Does *not* work **very** well. HTML tags will always work. + + </dd> +</dl> +``` + +<!-- Note: The example below uses HTML to force correct rendering on docs.gitlab.com, markdown will be fine in GitLab --> + +<dl> + <dt>Markdown in HTML</dt> + <dd>Does *not* work **very** well. HTML tags will always work.</dd> + + <dt>Markdown in HTML</dt> + <dd> + + Does <em>not</em> work <b>very</b> well. HTML tags will always work. + + </dd> </dl> #### Details and Summary -Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) tags. This is especially useful for collapsing long logs so they take up less screen space. +> To see the markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#details-and-summary). + +Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) +and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) +tags. This is especially useful for collapsing long logs so they take up less screen space. +```html <p> <details> <summary>Click me to collapse/fold.</summary> @@ -846,8 +1001,23 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded. </details> </p> +``` + +<p> +<details> +<summary>Click me to collapse/fold.</summary> -**Note:** Markdown inside these tags is supported, as long as you have a blank line after the `</summary>` tag and before the `</details>` tag, as shown in the example. +These details <em>will</em> remain <strong>hidden</strong> until expanded. + +<pre><code>PASTE LOGS HERE</code></pre> + +</details> +</p> + +--- + +Markdown inside these tags is supported as well, as long as you have a blank line +after the `</summary>` tag and before the `</details>` tag, as shown in the example: ```html <details> @@ -855,237 +1025,313 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded. These details _will_ remain **hidden** until expanded. - PASTE LOGS HERE +PASTE LOGS HERE </details> ``` -### Horizontal Rule +<!-- Note: The example below uses HTML to force correct rendering on docs.gitlab.com, markdown will be fine in GitLab --> -Examples: +<details> +<summary>Click me to collapse/fold.</summary> -``` -Three or more... +These details <em>will</em> remain <b>hidden</b> until expanded. ---- +PASTE LOGS HERE -Hyphens +</details> -*** +### Line Breaks -Asterisks +A line break will be inserted (a new paragraph will start) if the previous text is +ended with two newlines, i.e. you hit <kbd>Enter</kbd> twice in a row. If you only +use one newline (hit <kbd>Enter</kbd> once), the next sentence will be part of the +same paragraph. This is useful if you want to keep long lines from wrapping, and keep +them easily editable: -___ +```markdown +Here's a line for us to start with. + +This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*. -Underscores +This line is also a separate paragraph, but... +These lines are only separated by single newlines, +so they *do not break* and just follow the previous lines +in the *same paragraph*. ``` -Becomes: +Here's a line for us to start with. -Three or more... +This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*. ---- +This line is also a separate paragraph, but... +These lines are only separated by single newlines, +so they *do not break* and just follow the previous lines +in the *same paragraph*. -Hyphens +#### Newlines -*** +GFM adheres to the markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/). -Asterisks +A paragraph is simply one or more consecutive lines of text, separated by one or +more blank lines (i.e. two newlines at the end of the first paragraph), as [explained above](#line-breaks). -___ +If you need more control over line-breaks or soft returns, you can add a single line-break +by ending a line with a backslash, or two or more spaces. Two newlines in a row will create a new +paragraph, with a blank line in between: -Underscores +```markdown +First paragraph. +Another line in the same paragraph. +A third line in the same paragraph, but this time ending with two spaces.{space}{space} +A new line directly under the first paragraph. + +Second paragraph. +Another line, this time ending with a backslash.\ +A new line due to the previous backslash. +``` -### Line Breaks +<!-- (Do *NOT* remove the two ending whitespaces in the third line) --> +<!-- (They are needed for the Markdown text to render correctly) --> -A good way to learn how line breaks work is to experiment and discover -- hit <kbd>Enter</kbd> once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. The "Preview" tab is your friend. +First paragraph. +Another line in the same paragraph. +A third line in the same paragraph, but this time ending with two spaces. +A new line directly under the first paragraph. -Here are some things to try out: +<!-- (Do *NOT* remove the two ending whitespaces in the second line) --> +<!-- (They are needed for the Markdown text to render correctly on docs.gitlab.com, the backslash works fine inside GitLab itself) --> -Examples: +Second paragraph. +Another line, this time ending with a backslash. +A new line due to the previous backslash. -``` -Here's a line for us to start with. +### Links -This line is separated from the one above by two newlines, so it will be a *separate paragraph*. +There are two ways to create links, inline-style and reference-style: -This line is also a separate paragraph, but... -This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*. +```md +- This is an [inline-style link](https://www.google.com) +- This is a [link to a repository file in the same directory](index.md) +- This is a [relative link to a readme one directory higher](../README.md) +- This is a [link that also has title text](https://www.google.com "This link takes you to Google!") -This line is also a separate paragraph, and... -This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*) +Using header ID anchors: + +- This links to [a section on a different markdown page, using a "#" and the header ID](index.md#overview) +- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) + +Using references: + +- This is a [reference-style link, see below][Arbitrary case-insensitive reference text] +- You can [use numbers for reference-style link definitions, see below][1] +- Or leave it empty and use the [link text itself][], see below. + +Some text to show that the reference links can follow later. -spaces. +[arbitrary case-insensitive reference text]: https://www.mozilla.org +[1]: http://slashdot.org +[link text itself]: https://www.reddit.com ``` -Becomes: +- This is an [inline-style link](https://www.google.com) +- This is a [link to a repository file in the same directory](index.md) +- This is a [relative link to a readme one directory higher](../README.md) +- This is a [link that also has title text](https://www.google.com "This link takes you to Google!") -Here's a line for us to start with. +Using header ID anchors: -This line is separated from the one above by two newlines, so it will be a *separate paragraph*. +- This links to [a section on a different markdown page, using a "#" and the header ID](index.md#overview) +- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) -This line is also a separate paragraph, but... -This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*. +Using references: -This line is also a separate paragraph, and... -This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*) +- This is a [reference-style link, see below][Arbitrary case-insensitive reference text] +- You can [use numbers for reference-style link definitions, see below][1] +- Or leave it empty and use the [link text itself][], see below. -spaces. +Some text to show that the reference links can follow later. -### Tables +[arbitrary case-insensitive reference text]: https://www.mozilla.org +[1]: http://slashdot.org +[link text itself]: https://www.reddit.com -Tables aren't part of the core Markdown spec, but they are part of GFM. +NOTE: **Note:** Relative links do not allow the referencing of project files in a wiki +page, or a wiki page in a project file. The reason for this is that a wiki is always +in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)` +will point the link to `wikis/style` only when the link is inside of a wiki markdown file. -Example: +#### URL auto-linking -``` -| header 1 | header 2 | -| -------- | -------- | -| cell 1 | cell 2 | -| cell 3 | cell 4 | +GFM will autolink almost any URL you put into your text: + +```markdown +- https://www.google.com +- https://google.com/ +- ftp://ftp.us.debian.org/debian/ +- smb://foo/bar/baz +- irc://irc.freenode.net/gitlab +- http://localhost:3000 ``` -Becomes: +- <https://www.google.com> +- <https://google.com/> +- <ftp://ftp.us.debian.org/debian/> +- <smb://foo/bar/baz> +- <irc://irc.freenode.net/gitlab> +- <http://localhost:3000> -| header 1 | header 2 | -| -------- | -------- | -| cell 1 | cell 2 | -| cell 3 | cell 4 | +### Lists -**Note:** The row of dashes between the table header and body must have at least three dashes in each column. +Ordered and unordered lists can be easily created. Add the number you want the list +to start with, like `1.`, followed by a space, at the start of each line for ordered lists. +After the first number, it does not matter what number you use, ordered lists will be +numbered automatically by vertical order, so repeating `1.` for all items in the +same list is common. If you start with a number other than `1.`, it will use that as the first +number, and count up from there. -By including colons in the header row, you can align the text within that column. +Add a `*`, `-` or `+`, followed by a space, at the start of each line for unordered lists, but +you should not use a mix of them. -Example: +Examples: -``` -| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | -| :----------- | :------: | ------------: | :----------- | :------: | ------------: | -| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | -| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +```md +1. First ordered list item +2. Another item + - Unordered sub-list. +1. Actual numbers don't matter, just that it's a number + 1. Ordered sub-list + 1. Next ordered sub-list item +4. And another item. + +* Unordered lists can use asterisks + +- Or minuses + ++ Or pluses ``` -Becomes: +<!-- The "2." and "4." in the example above are changed to "1." below, only to match the standards on docs.gitlab.com --> -| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | -| :----------- | :------: | ------------: | :----------- | :------: | ------------: | -| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | -| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +1. First ordered list item +1. Another item + - Unordered sub-list. +1. Actual numbers don't matter, just that it's a number + 1. Ordered sub-list + 1. Next ordered sub-list item +1. And another item. -### Footnotes +- Unordered lists can use asterisks -Example: +- Or minuses -``` -You can add footnotes to your text as follows.[^2] -[^2]: This is my awesome footnote. -``` +- Or pluses -Becomes: +--- -You can add footnotes to your text as follows.[^2] +If a list item contains multiple paragraphs, each subsequent paragraph should be indented +to the same level as the start of the list item text. -### Superscripts / Subscripts +Example: -CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts. +```markdown +1. First ordered list item -``` -The formula for water is H<sub>2</sub>O -while the equation for the theory of relativity is E = mc<sup>2</sup>. + Second paragraph of first item. + +1. Another item ``` -The formula for water is H<sub>2</sub>O while the equation for the theory of relativity is E = mc<sup>2</sup>. +1. First ordered list item -## Wiki-specific Markdown + Second paragraph of first item. -The following examples show how links inside wikis behave. +1. Another item -### Wiki - Direct page link +--- -A link which just includes the slug for a page will point to that page, -_at the base level of the wiki_. +If the paragraph of the first item is not indented with the proper number of spaces, +the paragraph will appear outside the list, instead of properly indented under the list item. -This snippet would link to a `documentation` page at the root of your wiki: +Example: -```markdown -[Link to Documentation](documentation) ``` +1. First ordered list item -### Wiki - Direct file link - -Links with a file extension point to that file, _relative to the current page_. - -If this snippet was placed on a page at `<your_wiki>/documentation/related`, -it would link to `<your_wiki>/documentation/file.md`: + Paragraph of first item. -```markdown -[Link to File](file.md) +1. Another item ``` -### Wiki - Hierarchical link +1. First ordered list item -A link can be constructed relative to the current wiki page using `./<page>`, -`../<page>`, etc. + Paragraph of first item. -- If this snippet was placed on a page at `<your_wiki>/documentation/main`, - it would link to `<your_wiki>/documentation/related`: +1. Another item - ```markdown - [Link to Related Page](related) - ``` +### Superscripts / Subscripts -- If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, - it would link to `<your_wiki>/documentation/main`: +CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that +Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts: + +```html +The formula for water is H<sub>2</sub>O +while the equation for the theory of relativity is E = mc<sup>2</sup>. +``` - ```markdown - [Link to Related Page](../main) - ``` +The formula for water is H<sub>2</sub>O +while the equation for the theory of relativity is E = mc<sup>2</sup>. -- If this snippet was placed on a page at `<your_wiki>/documentation/main`, - it would link to `<your_wiki>/documentation/related.md`: +### Tables - ```markdown - [Link to Related Page](related.md) - ``` +Tables aren't part of the core Markdown spec, but they are part of GFM. -- If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, - it would link to `<your_wiki>/documentation/main.md`: +1. The first line contains the headers, separated by "pipes" (`|`). +1. The second line separates the headers from the cells, and must contain three or more dashes. +1. The third, and any following lines, contain the cell values. + - You **can't** have cells separated over many lines in the markdown, they must be kept to single lines, + but they can be very long. You can also include HTML `<br>` tags to force newlines if needed. + - The cell sizes **don't** have to match each other. They are flexible, but must be separated + by pipes (`|`). + - You **can** have blank cells. - ```markdown - [Link to Related Page](../main.md) - ``` +Example: -### Wiki - Root link +```markdown +| header 1 | header 2 | header 3 | +| --- | ------ |----------| +| cell 1 | cell 2 | cell 3 | +| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. | +| cell 7 | | cell <br> 9 | +``` -A link starting with a `/` is relative to the wiki root. +| header 1 | header 2 | header 3 | +| --- | ------ |---------:| +| cell 1 | cell 2 | cell 3 | +| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. | +| cell 7 | | cell <br> 9 | -- This snippet links to `<wiki_root>/documentation`: +Additionally, you can choose the alignment of text within columns by adding colons (`:`) +to the sides of the "dash" lines in the second row. This will affect every cell in the column. - ```markdown - [Link to Related Page](/documentation) - ``` +> Note that the headers are always right aligned [within GitLab itself itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#tables). -- This snippet links to `<wiki_root>/miscellaneous.md`: +```markdown +| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | +| :--- | :---: | ---: | :----------- | :------: | ------------: | +| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | +| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +``` - ```markdown - [Link to Related Page](/miscellaneous.md) - ``` +| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | +| :--- | :---: | ---: | :----------- | :------: | ------------: | +| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | +| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | ## References - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). -- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. -- The detailed specification for CommonMark can be found in the [CommonMark Spec][commonmark-spec] +- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) + at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. +- The detailed specification for CommonMark can be found in the [CommonMark Spec](https://spec.commonmark.org/current/) - The [CommonMark Dingus](http://try.commonmark.org) is a handy tool for testing CommonMark syntax. - -[^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com -[^2]: This is my awesome footnote. - -[markdown.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md -[rouge]: http://rouge.jneen.net/ "Rouge website" -[redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website" -[katex]: https://github.com/Khan/KaTeX "KaTeX website" -[katex-subset]: https://katex.org/docs/supported.html "Macros supported by KaTeX" -[asciidoctor-manual]: http://asciidoctor.org/docs/user-manual/#activating-stem-support "Asciidoctor user manual" -[commonmarker]: https://github.com/gjtorikian/commonmarker -[commonmark-spec]: https://spec.commonmark.org/current/ 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 differindex 9d6a509ea72..d4db5e88672 100644 --- 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 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 differindex ee33eee8134..7dbec81c18a 100644 --- a/doc/user/operations_dashboard/img/index_operations_dashboard_with_projects.png +++ 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 index 66362f27299..8c4d387190a 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -1,9 +1,6 @@ -# Operations Dashboard **[PREMIUM]** +# 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. +> [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. @@ -16,9 +13,9 @@ 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. +For GitLab.com, you can add your project to the Operations Dashboard for free if +your project is public. If your project is private, the group it belongs to must +have a [Silver](https://about.gitlab.com/pricing/) plan. To add a project to the dashboard: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 5b348b1ac60..9ecc8a80b3a 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -17,7 +17,10 @@ will be unassigned automatically. GitLab [administrators](../administration/index.md) receive all permissions. To add or import a user, you can follow the -[project members documentation](../user/project/members/index.md). +[project members documentation](project/members/index.md). + +For information on eligible approvers for Merge Requests, see +[Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers). ## Principles behind permissions @@ -40,10 +43,12 @@ The following table depicts the various user permission levels in a project. |---------------------------------------------------|---------|------------|-------------|----------|--------| | Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Leave comments | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View Insights charts **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View approved/blacklisted licenses **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View license management reports **[ULTIMATE]** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View Security reports **[ULTIMATE]** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View approved/blacklisted licenses **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View license management reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View Security reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View Dependency list **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View [Design Management](project/issues/design_management.md) pages **(PREMIUM)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control-core-only) | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -57,10 +62,9 @@ The following table depicts the various user permission levels in a project. | View confidential issues | (*2*) | ✓ | ✓ | ✓ | ✓ | | Assign issues | | ✓ | ✓ | ✓ | ✓ | | Label issues | | ✓ | ✓ | ✓ | ✓ | -| Lock issue discussions | | ✓ | ✓ | ✓ | ✓ | +| Lock issue threads | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | -| Manage related issues **[STARTER]** | | ✓ | ✓ | ✓ | ✓ | -| Create issue from vulnerability **[ULTIMATE]** | | ✓ | ✓ | ✓ | ✓ | +| Manage related issues **(STARTER)** | | ✓ | ✓ | ✓ | ✓ | | Manage labels | | ✓ | ✓ | ✓ | ✓ | | Create code snippets | | ✓ | ✓ | ✓ | ✓ | | See a commit status | | ✓ | ✓ | ✓ | ✓ | @@ -69,8 +73,9 @@ The following table depicts the various user permission levels in a project. | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | View project statistics | | ✓ | ✓ | ✓ | ✓ | | View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | -| Pull from [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **[PREMIUM]** | | ✓ | ✓ | ✓ | ✓ | -| Publish to [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **[PREMIUM]** | | | ✓ | ✓ | ✓ || +| Pull from [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| Publish to [Maven repository](project/packages/maven_repository.md) or [NPM registry](project/packages/npm_registry.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ || +| Upload [Design Management](project/issues/design_management.md) files **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Create new branches | | | ✓ | ✓ | ✓ | | Push to non-protected branches | | | ✓ | ✓ | ✓ | | Force push to non-protected branches | | | ✓ | ✓ | ✓ | @@ -78,7 +83,7 @@ The following table depicts the various user permission levels in a project. | Create new merge request | | | ✓ | ✓ | ✓ | | Assign merge requests | | | ✓ | ✓ | ✓ | | Label merge requests | | | ✓ | ✓ | ✓ | -| Lock merge request discussions | | | ✓ | ✓ | ✓ | +| Lock merge request threads | | | ✓ | ✓ | ✓ | | Manage/Accept merge requests | | | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | | Stop environments | | | ✓ | ✓ | ✓ | @@ -88,18 +93,20 @@ 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 | | | ✓ | ✓ | ✓ | -| Use security dashboard **[ULTIMATE]** | | | ✓ | ✓ | ✓ | -| Dismiss vulnerability **[ULTIMATE]** | | | ✓ | ✓ | ✓ | +| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| View vulnerabilities in Dependency list **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| Create issue from vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | Apply code change suggestions | | | ✓ | ✓ | ✓ | | Create and edit wiki pages | | | ✓ | ✓ | ✓ | +| Rewrite/remove Git tags | | | ✓ | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | -| Run Web IDE's Interactive Web Terminals **[ULTIMATE ONLY]** | | | | ✓ | ✓ | +| Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Enable/disable branch protection | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | | Turn on/off protected branch push for devs | | | | ✓ | ✓ | | Enable/disable tag protections | | | | ✓ | ✓ | -| Rewrite/remove Git tags | | | | ✓ | ✓ | | Edit project | | | | ✓ | ✓ | | Add deploy keys to project | | | | ✓ | ✓ | | Configure project hooks | | | | ✓ | ✓ | @@ -110,7 +117,7 @@ The following table depicts the various user permission levels in a project. | Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | | Remove GitLab Pages | | | | ✓ | ✓ | | Manage clusters | | | | ✓ | ✓ | -| Manage license policy **[ULTIMATE]** | | | | ✓ | ✓ | +| Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | | Manage Error Tracking | | | | ✓ | ✓ | | Delete wiki pages | | | | ✓ | ✓ | @@ -119,8 +126,9 @@ The following table depicts the various user permission levels in a project. | Transfer project to another namespace | | | | | ✓ | | Remove project | | | | | ✓ | | Delete issues | | | | | ✓ | -| Force push to protected branches [^4] | | | | | | -| Remove protected branches [^4] | | | | | | +| Disable notification emails | | | | | ✓ | +| Force push to protected branches (*4*) | | | | | | +| Remove protected branches (*4*) | | | | | | - (*1*): All users are able to perform this action on public and internal projects, but not private projects. - (*2*): Guest users can only view the confidential issues they created themselves @@ -154,7 +162,7 @@ to learn more. ### Cycle Analytics permissions Find the current permissions on the Cycle Analytics dashboard on -the [documentation on Cycle Analytics permissions](project/cycle_analytics.md#permissions). +the [documentation on Cycle Analytics permissions](analytics/cycle_analytics.md#permissions). ### Issue Board permissions @@ -164,7 +172,7 @@ and drag issues around. Read though the [documentation on Issue Boards permissions](project/issue_board.md#permissions) to learn more. -### File Locking permissions **[PREMIUM]** +### File Locking permissions **(PREMIUM)** 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. @@ -199,19 +207,24 @@ group. | Action | Guest | Reporter | Developer | Maintainer | Owner | |-------------------------------------------------|-------|----------|-----------|------------|-------| | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Insights charts **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group epic **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create/edit group epic **[ULTIMATE]** | | ✓ | ✓ | ✓ | ✓ | +| View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View group epic **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create/edit group epic **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | Manage group labels | | ✓ | ✓ | ✓ | ✓ | | Create project in group | | | ✓ | ✓ | ✓ | | Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | -| Enable/disable a dependency proxy **[PREMIUM]** | | | ✓ | ✓ | ✓ | +| Enable/disable a dependency proxy **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| Create subgroup | | | | ✓ (1) | ✓ | | Edit group | | | | | ✓ | -| Create subgroup | | | | | ✓ | | Manage group members | | | | | ✓ | | Remove group | | | | | ✓ | -| Delete group epic **[ULTIMATE]** | | | | | ✓ | +| Delete group epic **(ULTIMATE)** | | | | | ✓ | | View group Audit Events | | | | | ✓ | +| Disable notification emails | | | | | ✓ | + +- (1): Groups can be set to [allow either Owners or Owners and + Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) ### Subgroup permissions @@ -222,6 +235,19 @@ nested groups if you have membership in one of its parents. To learn more, read through the documentation on [subgroups memberships](group/subgroups/index.md#membership). +## Guest User + +When a user is given `Guest` permissions on a project and/or group, and holds no +higher permission level on any other project or group on the instance, the user +is considered a guest user by GitLab and will not consume a license seat. +There is no other specific "guest" designation for newly created users. + +If the user is assigned a higher role on any projects or groups, the user will +take a license seat. If a user creates a project, the user becomes a `Maintainer` +on the project, resulting in the use of a license seat. To prevent a guest user +from creating projects, you can edit the user profile to mark the user as +[External](#external-users-permissions). + ## External users permissions In cases where it is desired that a user has access only to some internal or @@ -261,7 +287,7 @@ Here are some examples: Please be aware that this regex could lead to a DOS attack, [see](https://en.wikipedia.org/wiki/ReDoS?) ReDos on Wikipedia. -## Auditor users **[PREMIUM ONLY]** +## Auditor users **(PREMIUM ONLY)** >[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/998) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.17. @@ -362,3 +388,8 @@ for details about the pipelines security model. Since GitLab 8.15, LDAP user permissions can now be manually overridden by an admin user. Read through the documentation on [LDAP users permissions](../administration/auth/how_to_configure_ldap_gitlab_ee/index.html) to learn more. + +## Project aliases + +Project aliases can only be read, created and deleted by a GitLab administrator. +Read through the documentation on [Project aliases](../user/project/index.md#project-aliases-premium-only) to learn more. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 304a7984191..5b0954195f8 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,37 +1,87 @@ -# Deleting a User Account +--- +type: howto +--- + +# Deleting a User account + +Users can be deleted from a GitLab instance, either by: + +- The user themselves. +- An administrator. NOTE: **Note:** Deleting a user will delete all projects in that user namespace. -- As a user, you can delete your own account by navigating to **Settings** > **Account** and selecting **Delete account** -- As an admin, you can delete a user account by navigating to the **Admin Area**, selecting the **Users** tab, selecting a user, and clicking on **Delete user** +## As a user + +As a user, you can delete your own account by: + +1. Clicking on your avatar. +1. Navigating to **Settings > Account**. +1. Selecting **Delete account**. + +## As an administrator + +As an administrator, you can delete a user account by: + +1. Navigating to **Admin Area > Overview > Users**. +1. Selecting a user. +1. Under the **Account** tab, clicking: + - **Delete user** to delete only the user but maintaining their + [associated records](#associated-records). + - **Delete user and contributions** to delete the user and + their associated records. + +### Blocking a user + +In addition to blocking a user +[via an abuse report](../../admin_area/abuse_reports.md#blocking-users), +a user can be blocked directly from the Admin area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Selecting a user. +1. Under the **Account** tab, click **Block user**. ## Associated Records -> Introduced for issues in [GitLab 9.0][ce-7393], and for merge requests, award - emoji, notes, and abuse reports in [GitLab 9.1][ce-10467]. - Hard deletion from abuse reports and spam logs was introduced in - [GitLab 9.1][ce-10273], and from the API in [GitLab 9.3][ce-11853]. +> - Introduced for issues in +> [GitLab 9.0](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7393). +> - Introduced for merge requests, award emoji, notes, and abuse reports in +> [GitLab 9.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467). +> - Hard deletion from abuse reports and spam logs was introduced in +> [GitLab 9.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10273), +> and from the API in +> [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11853). When a user account is deleted, not all associated records are deleted with it. Here's a list of things that will **not** be deleted: -- Issues that the user created -- Merge requests that the user created -- Notes that the user created -- Abuse reports that the user reported -- Award emoji that the user created +- Issues that the user created. +- Merge requests that the user created. +- Notes that the user created. +- Abuse reports that the user reported. +- Award emoji that the user created. Instead of being deleted, these records will be moved to a system-wide -user with the username "Ghost User", whose sole purpose is to act as a container for such records. Any commits made by a deleted user will still display the username of the original user. +user with the username "Ghost User", whose sole purpose is to act as a container +for such records. Any commits made by a deleted user will still display the +username of the original user. -When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md) or spam log, these associated +When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md) +or spam log, these associated records are not ghosted and will be removed, along with any groups the user -is a sole owner of. Administrators can also request this behaviour when +is a sole owner of. Administrators can also request this behavior when deleting users from the [API](../../../api/users.md#user-deletion) or the -admin area. +Admin Area. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. -[ce-7393]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7393 -[ce-10273]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10273 -[ce-10467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467 -[ce-11853]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11853 +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/profile/account/img/2fa.png b/doc/user/profile/account/img/2fa.png Binary files differdeleted file mode 100644 index bb464efa685..00000000000 --- a/doc/user/profile/account/img/2fa.png +++ /dev/null diff --git a/doc/user/profile/account/img/2fa_auth.png b/doc/user/profile/account/img/2fa_auth.png Binary files differdeleted file mode 100644 index 0caaed10805..00000000000 --- a/doc/user/profile/account/img/2fa_auth.png +++ /dev/null diff --git a/doc/user/profile/account/img/2fa_u2f_authenticate.png b/doc/user/profile/account/img/2fa_u2f_authenticate.png Binary files differdeleted file mode 100644 index ff2e936764d..00000000000 --- a/doc/user/profile/account/img/2fa_u2f_authenticate.png +++ /dev/null diff --git a/doc/user/profile/account/img/2fa_u2f_register.png b/doc/user/profile/account/img/2fa_u2f_register.png Binary files differdeleted file mode 100644 index 1cc142aa851..00000000000 --- a/doc/user/profile/account/img/2fa_u2f_register.png +++ /dev/null diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index df413a11af0..e2b1a20a605 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,3 +1,7 @@ +--- +type: howto +--- + # Two-Factor Authentication Two-factor Authentication (2FA) provides an additional level of security to your @@ -10,17 +14,18 @@ is to know your username and password *and* have access to your one time passwor ## Overview -> **Note:** -When you enable 2FA, don't forget to back up your recovery codes. - -In addition to one time authenticators (TOTP), GitLab supports U2F (universal 2nd factor) devices as -the second factor of authentication. Once enabled, in addition to supplying your username and -password to login, you'll be prompted to activate your U2F device (usually by pressing -a button on it), and it will perform secure authentication on your behalf. +TIP: **Tip:** +When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)! -The U2F workflow is [supported by](https://caniuse.com/#search=U2F) Google Chrome, Opera, and Firefox. +In addition to time-based one time passwords (TOTP), GitLab supports U2F +(universal 2nd factor) devices as the second factor of authentication. Once +enabled, in addition to supplying your username and password to log in, you'll +be prompted to activate your U2F device (usually by pressing a button on it), +and it will perform secure authentication on your behalf. -We recommend that you set up 2FA with both a [one-time password authenticator](#enable-2fa-via-one-time-password-authenticator) and a [U2F device](#enable-2fa-via-u2f-device), so you can still access your account +It is highly recommended that you set up 2FA with both a +[one-time password authenticator](#enable-2fa-via-one-time-password-authenticator) +and a [U2F device](#enable-2fa-via-u2f-device), so you can still access your account if you lose your U2F device. ## Enabling 2FA @@ -30,41 +35,52 @@ or a U2F device. ### Enable 2FA via one time password authenticator -**In GitLab:** - -1. Log in to your GitLab account. -1. Go to your **Profile Settings**. -1. Go to **Account**. -1. Click **Enable Two-factor Authentication**. - - - -**On your phone:** - -1. Install a compatible application. We recommend [Google Authenticator] - \(proprietary\) or [FreeOTP] \(open source\). -1. In the application, add a new entry in one of two ways: - - Scan the code with your phone's camera to add the entry automatically. - - Enter the details provided to add the entry manually. - -**In GitLab:** - -1. Enter the six-digit pin number from the entry on your phone into the **Pin - code** field. -1. Click **Submit**. +To enable 2FA: + +1. **In GitLab:** + 1. Log in to your GitLab account. + 1. Go to your **Profile Settings**. + 1. Go to **Account**. + 1. Click **Enable Two-factor Authentication**. +1. **On your device (usually your phone):** + 1. Install a compatible application, like: + - [Authenticator](https://mattrubin.me/authenticator/): open source app for iOS devices. + - [andOTP](https://github.com/andOTP/andOTP): feature rich open source app for Android which supports PGP encrypted backups. + - [FreeOTP](https://freeotp.github.io/): open source app for Android. + - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en): proprietary app for iOS and Android. + 1. In the application, add a new entry in one of two ways: + - Scan the code presented in GitLab with your device's camera to add the + entry automatically. + - Enter the details provided to add the entry manually. +1. **In GitLab:** + 1. Enter the six-digit pin number from the entry on your device into the **Pin + code** field. + 1. Click **Submit**. If the pin you entered was correct, you'll see a message indicating that Two-Factor Authentication has been enabled, and you'll be presented with a list -of recovery codes. +of [recovery codes](#recovery-codes). Make sure you download them and keep them +in a safe place. ### Enable 2FA via U2F device -> **Notes:** -> -> - GitLab officially only supports [Yubikey] U2F devices. -> - Support for U2F devices was added in GitLab 8.8. +GitLab officially only supports [YubiKey](https://www.yubico.com/products/yubikey-hardware/) +U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/). + +The U2F workflow is [supported by](https://caniuse.com/#search=U2F) the +following desktop browsers: + +- Chrome +- Edge +- Firefox (disabled by default) +- Opera -**In GitLab:** +NOTE: **Note:** +For Firefox, you can enable the FIDO U2F API in +[about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). +Search for `security.webauth.u2f` and double click on it to toggle to `true`. + +To set up 2FA with a U2F device: 1. Log in to your GitLab account. 1. Go to your **Profile Settings**. @@ -77,20 +93,21 @@ of recovery codes. You will see a message indicating that your device was successfully set up. Click on **Register U2F Device** to complete the process. - - -## Recovery Codes +## Recovery codes -> **Note:** +NOTE: **Note:** Recovery codes are not generated for U2F devices. -Should you ever lose access to your one time password authenticator, you can use one of the ten provided -backup codes to login to your account. We suggest copying them, printing them, or downloading them using -the **Download codes** button for storage in a safe place. - CAUTION: **Caution:** Each code can be used only once to log in to your account. +Immediately after successfully enabling two-factor authentication, you'll be +prompted to download a set of set recovery codes. Should you ever lose access +to your one time password authenticator, you can use one of them to log in to +your account. We suggest copying them, printing them, or downloading them using +the **Download codes** button for storage in a safe place. If you choose to +download them, the file will be called **gitlab-recovery-codes.txt**. + If you lose the recovery codes or just want to generate new ones, you can do so [using SSH](#generate-new-recovery-codes-using-ssh). @@ -100,24 +117,26 @@ Logging in with 2FA enabled is only slightly different than a normal login. Enter your username and password credentials as you normally would, and you'll be presented with a second prompt, depending on which type of 2FA you've enabled. -### Log in via mobile application +### Log in via a one-time password -Enter the pin from your one time password authenticator's application or a recovery code to log in. - - +When asked, enter the pin from your one time password authenticator's application or a +recovery code to log in. ### Log in via U2F device -1. Click **Login via U2F Device**. -1. A light will start blinking on your device. Activate it by pressing its button. +To log in via a U2F device: -You will see a message indicating that your device responded to the authentication request. -Click on **Authenticate via U2F Device** to complete the process. +1. Click **Login via U2F Device**. +1. A light will start blinking on your device. Activate it by touching/pressing + its button. - +You will see a message indicating that your device responded to the authentication +request and you will be automatically logged in. ## Disabling 2FA +If you ever need to disable 2FA: + 1. Log in to your GitLab account. 1. Go to your **Profile Settings**. 1. Go to **Account**. @@ -130,7 +149,8 @@ applications and U2F devices. When 2FA is enabled, you can no longer use your normal account password to authenticate with Git over HTTPS on the command line or when using -[GitLab's API][api], you must use a [personal access token][pat] instead. +[GitLab's API](../../../api/README.md). You must use a +[personal access token](../personal_access_tokens.md) instead. ## Recovery options @@ -149,7 +169,6 @@ codes. If you saved these codes, you can use one of them to sign in. To use a recovery code, enter your username/email and password on the GitLab sign-in page. When prompted for a two-factor code, enter the recovery code. -> **Note:** Once you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved. @@ -157,41 +176,45 @@ recovery codes you saved. Users often forget to save their recovery codes when enabling two-factor authentication. If an SSH key is added to your GitLab account, you can generate -a new set of recovery codes with SSH. +a new set of recovery codes with SSH: + +1. Run: -1. Run `ssh git@gitlab.example.com 2fa_recovery_codes`. -1. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes. + ```sh + ssh git@gitlab.example.com 2fa_recovery_codes + ``` - ```sh - $ ssh git@gitlab.example.com 2fa_recovery_codes - Are you sure you want to generate new two-factor recovery codes? - Any existing recovery codes you saved will be invalidated. (yes/no) +1. You will then be prompted to confirm that you want to generate new codes. + Continuing this process invalidates previously saved codes: - yes + ```sh + Are you sure you want to generate new two-factor recovery codes? + Any existing recovery codes you saved will be invalidated. (yes/no) - Your two-factor authentication recovery codes are: + yes - 119135e5a3ebce8e - 11f6v2a498810dcd - 3924c7ab2089c902 - e79a3398bfe4f224 - 34bd7b74adbc8861 - f061691d5107df1a - 169bf32a18e63e7f - b510e7422e81c947 - 20dbed24c5e74663 - df9d3b9403b9c9f0 + Your two-factor authentication recovery codes are: - During sign in, use one of the codes above when prompted for your - two-factor code. Then, visit your Profile Settings and add a new device - so you do not lose access to your account again. - ``` + 119135e5a3ebce8e + 11f6v2a498810dcd + 3924c7ab2089c902 + e79a3398bfe4f224 + 34bd7b74adbc8861 + f061691d5107df1a + 169bf32a18e63e7f + b510e7422e81c947 + 20dbed24c5e74663 + df9d3b9403b9c9f0 + + During sign in, use one of the codes above when prompted for your + two-factor code. Then, visit your Profile Settings and add a new device + so you do not lose access to your account again. + ``` 1. Go to the GitLab sign-in page and enter your username/email and password. When prompted for a two-factor code, enter one of the recovery codes obtained from the command-line output. -> **Note:** After signing in, visit your **Profile settings > Account** immediately to set up two-factor authentication with a new device. @@ -220,8 +243,14 @@ Sign in and re-enable two-factor authentication as soon as possible. - The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because the U2F key has only been registered on `first.host.xyz`. -[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en -[FreeOTP]: https://freeotp.github.io/ -[YubiKey]: https://www.yubico.com/products/yubikey-hardware/ -[api]: ../../../api/README.md -[pat]: ../personal_access_tokens.md +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 28e3f4904a9..2d7bd25fc27 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -1,14 +1,31 @@ +--- +type: howto +--- + # Active Sessions > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17867) > in GitLab 10.8. GitLab lists all devices that have logged into your account. This allows you to -review the sessions. +review the sessions, and revoke any you don't recognize. ## Listing all active sessions -1. On the upper right corner, click on your avatar and go to your **Settings**. -1. Navigate to the **Active Sessions** tab. +1. Click your avatar. +1. Select **Settings**. +1. Click **Active Sessions** in the sidebar.  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/profile/img/active_sessions_list.png b/doc/user/profile/img/active_sessions_list.png Binary files differindex 1e242ac4710..41173c7eee5 100644 --- a/doc/user/profile/img/active_sessions_list.png +++ b/doc/user/profile/img/active_sessions_list.png diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 61a30a775b0..e5ccc8ee758 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -1,7 +1,12 @@ +--- +type: index, howto +--- + # User account -When signed into their GitLab account, users can customize their -experience according to the best approach to their cases. +Each GitLab account has a user profile, and settings. Your [profile](#user-profile) +contains information about you, and your GitLab activity. Your [settings](#profile-settings) +allow you to customize some aspects of GitLab to suit yourself. ## Signing in @@ -10,8 +15,10 @@ See the [authentication topic](../../topics/authentication/index.md) for more de ## User profile -Your profile is available from the up-right corner menu bar (user's avatar) > **Profile**, -or from `https://example.gitlab.com/username`. +To access your profile: + +1. Click on your avatar. +1. Select **Profile**. On your profile page, you will see the following information: @@ -20,12 +27,15 @@ On your profile page, you will see the following information: - Groups: [groups](../group/index.md) you're a member of - Contributed projects: [projects](../project/index.md) you contributed to - Personal projects: your personal projects (respecting the project's visibility level) +- Starred projects: projects you starred - Snippets: your personal code [snippets](../snippets.md#personal-snippets) ## Profile settings -You can edit your account settings by navigating from the up-right corner menu bar -(user's avatar) > **Settings**, or visiting `https://example.gitlab.com/profile`. +To access your profile settings: + +1. Click on your avatar. +1. Select **Settings**. From there, you can: @@ -56,8 +66,8 @@ before proceeding. To change your `username`: 1. Navigate to your [profile's](#profile-settings) **Settings > Account**. -1. Enter a new username under "Change username". -1. Hit **Update username**. +1. Enter a new username under **Change username**. +1. Click **Update username**. CAUTION: **Caution:** It is currently not possible to change your username if it contains a @@ -82,16 +92,20 @@ The following information will be hidden from the user profile page (`https://gi - Groups tab - Contributed projects tab - Personal projects tab +- Starred projects tab - Snippets tab To enable private profile: -1. Navigate to your personal [profile settings](#profile-settings). -1. Check the "Private profile" option. -1. Hit **Update profile settings**. +1. Click your avatar. +1. Select **Profile**. +1. Click **Edit profile** (pencil icon). +1. Check the **Private profile** option in the **Main settings** section. +1. Click **Update profile settings**. NOTE: **Note:** -You and GitLab admins can see your the abovementioned information on your profile even if it is private. +All your profile information can be seen by yourself, and GitLab admins, even if +the **Private profile** option is enabled. ## Add details of external accounts @@ -99,9 +113,15 @@ GitLab allows you to add links to certain other external accounts you might have To add links to other accounts: -1. Navigate to your **User Settings > Profile**. -1. In the **Main settings** section, locate and fill out fields for links to external accounts like Skype and Twitter. -1. Click the **Update profile settings** button. +1. Click your avatar. +1. Select **Profile**. +1. Click **Edit profile** (pencil icon). +1. Complete the desired fields for external accounts, in the **Main settings** + section: + - Skype + - Twitter + - LinkedIn +1. Click **Update profile settings**. ## Private contributions @@ -111,9 +131,11 @@ Enabling private contributions will include contributions to private projects, i To enable private contributions: -1. Navigate to your personal [profile settings](#profile-settings). -1. Check the "Private contributions" option. -1. Hit **Update profile settings**. +1. Click on your avatar. +1. Select **Profile**. +1. Click **Edit profile** (pencil icon). +1. Check the **Private contributions** option. +1. Click **Update profile settings**. ## Current status @@ -124,22 +146,24 @@ This may be helpful when you are out of office or otherwise not available. Other users can then take your status into consideration when responding to your issues or assigning work to you. Please be aware that your status is publicly visible even if your [profile is private](#private-profile). +Status messages are restricted to 100 characters of plain text. +They may however contain emoji codes such as `I'm on vacation :palm_tree:`. + To set your current status: -1. Open the user menu in the top-right corner of the navigation bar. -1. Hit **Set status**, or **Edit status** if you have already set a status. -1. Set the emoji and/or status message to your liking. -1. Hit **Set status**. Alternatively, you can also hit **Remove status** to remove your user status entirely. +1. Click your avatar. +1. Click **Set status**, or **Edit status** if you have already set a status. +1. Set the desired emoji and/or status message. +1. Click **Set status**. Alternatively, you can click **Remove status** to remove your user status entirely. or -1. Navigate to your personal [profile settings](#profile-settings). -1. In the text field below `Your status`, enter your status message. -1. Select an emoji from the dropdown if you like. -1. Hit **Update profile settings**. - -Status messages are restricted to 100 characters of plain text. -They may however contain emoji codes such as `I'm on vacation :palm_tree:`. +1. Click your avatar. +1. Select **Profile**. +1. Click **Edit profile** (pencil icon). +1. Enter your status message in the **Your status** text field. +1. Click **Add status emoji** (smiley face), and select the desired emoji. +1. Click **Update profile settings**. You can also set your current status [using the API](../../api/users.md#user-status). @@ -147,39 +171,42 @@ You can also set your current status [using the API](../../api/users.md#user-sta > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21598) in GitLab 11.4. -A commit email, is the email that will be displayed in every Git-related action done through the -GitLab interface. +A commit email is an email address displayed in every Git-related action carried out through the GitLab interface. -You are able to select from the list of your own verified emails which email you want to use as the commit email. +Any of your own verified email addresses can be used as the commit email. -To change it: +To change your commit email: -1. Open the user menu in the top-right corner of the navigation bar. -1. Hit **Commit email** selection box. +1. Click your avatar. +1. Select **Profile**. +1. Click **Edit profile** (pencil icon). +1. Click **Commit email** dropdown. 1. Select any of the verified emails. -1. Hit **Update profile settings**. +1. Click **Update profile settings**. ### Private commit email > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22560) in GitLab 11.5. GitLab provides the user with an automatically generated private commit email option, -which allows the user to not make their email information public. +which allows the user to keep their email information private. To enable this option: -1. Open the user menu in the top-right corner of the navigation bar. -1. Hit **Commit email** selection box. +1. Click your avatar. +1. Select **Profile**. +1. Click **Edit profile** (pencil icon). +1. Click **Commit email** dropdown. 1. Select **Use a private email** option. -1. Hit **Update profile settings**. +1. Click **Update profile settings**. Once this option is enabled, every Git-related action will be performed using the private commit email. -In order to stay fully annonymous, you can also copy this private commit email +To stay fully anonymous, you can also copy this private commit email and configure it on your local machine using the following command: -``` -git config --global user.email "YOUR_PRIVATE_COMMIT_EMAIL" +```sh +git config --global user.email <your email address> ``` ## Troubleshooting @@ -202,3 +229,15 @@ to get you a new `_gitlab_session` and keep you signed in through browser restar After your `remember_user_token` expires and your `_gitlab_session` is cleared/expired, you will be asked to sign in again to verify your identity (which is for security reasons). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 0b224fc7e01..d556daa3460 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -1,3 +1,7 @@ +--- +type: concepts, howto +--- + # Personal access tokens > [Introduced][ce-3749] in GitLab 8.8. @@ -40,7 +44,7 @@ the following table. | Scope | Introduced in | Description | | ------------------ | ------------- | ----------- | | `read_user` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed. | -| `api` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) | Grants complete access to the API and Container Registry (read/write). | +| `api` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | | `read_registry` | [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) | Allows to read (pull) [container registry] images if a project is private and authorization is required. | | `sudo` | [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14838) | Allows performing API actions as any user in the system (if the authenticated user is an admin). | | `read_repository` | [GitLab 10.7](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894) | Allows read-only access (pull) to the repository through git clone. | @@ -52,3 +56,15 @@ the following table. [container registry]: ../project/container_registry.md [users]: ../../api/users.md [usage]: ../../api/README.md#personal-access-tokens + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index b61216b7b67..82a6d2b3703 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -1,11 +1,17 @@ +--- +type: concepts, howto +--- + # Profile preferences A user's profile preferences page allows the user to customize various aspects of GitLab to their liking. -To navigate to your profile's preferences, click your avatar icon in the top -right corner, select **Settings** and then choose **Preferences** from the -left sidebar. +To navigate to your profile's preferences: + +1. Click your avatar. +1. Select **Settings**. +1. Click **Preferences** in the sidebar. ## Navigation theme @@ -15,7 +21,7 @@ and left side navigation. Using individual color themes might help you differentiate between your different GitLab instances. -The default palette is Indigo. You can choose between 10 different themes: +The default theme is Indigo. You can choose between 10 themes: - Indigo - Light Indigo @@ -39,7 +45,7 @@ for syntax highlighting. For a list of supported languages visit the rouge websi Changing this setting allows you to customize the color theme when viewing any syntax highlighted code on GitLab. -The default syntax theme is White, and you can choose among 5 different colors: +The default syntax theme is White, and you can choose among 5 different themes: - White - Dark @@ -79,7 +85,17 @@ 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]** +- Operations Dashboard **(PREMIUM)** + +### Group overview content + +The **Group overview content** dropdown allows you to choose what information is +displayed on a group’s home page. + +You can choose between 2 options: + +- Details (default) +- [Security dashboard](../application_security/security_dashboard/index.md) **(ULTIMATE)** ### Project overview content @@ -102,7 +118,7 @@ Select your preferred language from a list of supported languages. ### First day of the week -The first day of the week can be customised for calendar views and date pickers. +The first day of the week can be customized for calendar views and date pickers. You can choose one of the following options as the first day of the week: @@ -111,3 +127,15 @@ You can choose one of the following options as the first day of the week: - Monday If you select **System Default**, the system-wide default setting will be used. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md new file mode 100644 index 00000000000..9ebf7f821a1 --- /dev/null +++ b/doc/user/project/autocomplete_characters.md @@ -0,0 +1,48 @@ +# Autocomplete characters + +The autocomplete characters provide a quick way of entering field values into +Markdown fields. When you start typing a word in a Markdown field with one of +the following characters, GitLab progressively autocompletes against a set of +matching values. The string matching is not case sensitive. + +| Character | Autocompletes | +| :-------- | :------------ | +| `~` | Labels | +| `%` | Milestones | +| `@` | Users and groups | +| `#` | Issues | +| `!` | Merge requests | +| `&` | Epics | +| `$` | Snippets | +| `:` | Emoji | +| `/` | Quick Actions | + +Up to 5 of the most relevant matches are displayed in a popup list. When you +select an item from the list, the value is entered in the field. The more +characters you enter, the more precise the matches are. + +Autocomplete characters are useful when combined with [Quick Actions](quick_actions.md). + +## Example + +Assume your GitLab instance includes the following users: + +| Username | Name | +| :-------------- | :--- | +| alessandra | Rosy Grant | +| lawrence.white | Kelsey Kerluke | +| leanna | Rosemarie Rogahn | +| logan_gutkowski | Lee Wuckert | +| shelba | Josefine Haley | + +In an Issue comment, entering `@l` results in the following popup list +appearing. Note that user `shelba` is not included, because the list includes +only the 5 users most relevant to the Issue. + + + +If you continue to type, `@le`, the popup list changes to the following. The +popup now only includes users where `le` appears in their username, or a word in +their name. + + diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 8849dd2d684..cd3e5f5a63c 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -17,10 +17,10 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. Navigate to your project's **Settings > General > Badges**. -1. Under "Link", enter the URL that the badges should point to and under - "Badge image URL" the URL of the image that should be displayed. -1. Submit the badge by clicking the **Add badge** button. +1. Navigate to your project's **Settings > General > Badges**. +1. Under "Link", enter the URL that the badges should point to and under + "Badge image URL" the URL of the image that should be displayed. +1. Submit the badge by clicking the **Add badge** button. After adding a badge to a project, you can see it in the list below the form. You can edit it by clicking on the pen icon next to it or to delete it by @@ -39,10 +39,10 @@ project, consider adding them on the [project level](#project-badges) or use To add a new badge to a group: -1. Navigate to your group's **Settings > General > Badges**. -1. Under "Link", enter the URL that the badges should point to and under - "Badge image URL" the URL of the image that should be displayed. -1. Submit the badge by clicking the **Add badge** button. +1. Navigate to your group's **Settings > General > Badges**. +1. Under "Link", enter the URL that the badges should point to and under + "Badge image URL" the URL of the image that should be displayed. +1. Submit the badge by clicking the **Add badge** button. After adding a badge to a group, you can see it in the list below the form. You can edit the badge by clicking on the pen icon next to it or to delete it diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index d0c7daf4692..f4733620640 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -13,13 +13,20 @@ by using the bulk editing feature.  NOTE: **Note:** -Bulk editing of issues and merge requests is only available at the project level. +Bulk editing issues and merge requests is also available at the group level. +For more details, see [bulk editing group issues and merge requests](../group/bulk_editing/index.md). -To update multiple project issues or merge requests at the same time, navigate to -their respective lists and click **Edit issues** or **Edit merge requests** available -in the tab bar. This will open a sidebar on the right-hand side of your screen -where editable fields will be displayed. Checkboxes will also appear to the left-hand -side of eachissue or merge request for you to select the items you want to update. +To update multiple project issues or merge requests at the same time: -Once you have selected all relevant items, choose the appropriate fields and their -values from the sidebar and click **Update all** to apply your changes. +1. Navigate to their respective list. + +1. Click **Edit issues** or **Edit merge requests**. + + - This will open a sidebar on the right-hand side of your screen + where editable fields will be displayed. + + - Checkboxes will also appear beside each issue or merge request. + +1. Check the checkboxes of each items to be edited. +1. Choose the appropriate fields and their values from the sidebar. +1. Click **Update all**. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index cce862b0911..5068d2757be 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,4 +1,4 @@ -# Canary Deployments **[PREMIUM]** +# Canary Deployments **(PREMIUM)** > [Introduced][ee-1659] in [GitLab Premium][eep] 9.1. @@ -44,7 +44,7 @@ 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] + pods with `track: canary`. To get started quickly, you can use the [Auto Deploy](../../ci/autodeploy/index.md) template for canary deployments that GitLab provides. Depending on the deploy, the label should be either `stable` or `canary`. @@ -62,7 +62,6 @@ 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 diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index ea09f9f1547..28f3420de35 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -40,97 +40,97 @@ then click **Add an existing Kubernetes cluster**. A few details from the EKS cluster will be required to connect it to GitLab: -1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to - authenticate to the EKS cluster. We will use the certificate created by default. - Open a shell and use `kubectl` to retrieve it: +1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to + authenticate to the EKS cluster. We will use the certificate created by default. + Open a shell and use `kubectl` to retrieve it: - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate with: + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate with: - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` -1. **Create admin token**: A `cluster-admin` token is required to install and - manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller - and creates limited service accounts for each application. To create the - token we will create an admin service account as follows: +1. **Create admin token**: A `cluster-admin` token is required to install and + manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller + and creates limited service accounts for each application. To create the + token we will create an admin service account as follows: - 2.1. Create a file called `eks-admin-service-account.yaml` with contents: + 2.1. Create a file called `eks-admin-service-account.yaml` with contents: - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: eks-admin - namespace: kube-system - ``` + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: eks-admin + namespace: kube-system + ``` - 2.2. Apply the service account to your cluster: + 2.2. Apply the service account to your cluster: - ```bash - kubectl apply -f eks-admin-service-account.yaml - ``` + ```bash + kubectl apply -f eks-admin-service-account.yaml + ``` - Output: + Output: - ```bash - serviceaccount "eks-admin" created - ``` + ```bash + serviceaccount "eks-admin" created + ``` - 2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: + 2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: eks-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: eks-admin - namespace: kube-system - ``` + ```yaml + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: eks-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: eks-admin + namespace: kube-system + ``` - 2.4. Apply the cluster role binding to your cluster: + 2.4. Apply the cluster role binding to your cluster: - ```bash - kubectl apply -f eks-admin-cluster-role-binding.yaml - ``` + ```bash + kubectl apply -f eks-admin-cluster-role-binding.yaml + ``` - Output: + Output: - ```bash - clusterrolebinding "eks-admin" created - ``` + ```bash + clusterrolebinding "eks-admin" created + ``` - 2.5. Retrieve the token for the `eks-admin` service account: + 2.5. Retrieve the token for the `eks-admin` service account: - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') - ``` + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') + ``` - Copy the `<authentication_token>` value from the output: + Copy the `<authentication_token>` value from the output: - ```yaml - Name: eks-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=eks-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + ```yaml + Name: eks-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=eks-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - Type: kubernetes.io/service-account-token + Type: kubernetes.io/service-account-token - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` 1. The API server endpoint is also required, so GitLab can connect to the cluster. This is displayed on the AWS EKS console, when viewing the EKS cluster details. @@ -253,7 +253,7 @@ With RBAC disabled and services deployed, [Auto DevOps](../../../../topics/autodevops/index.md) can now be leveraged to build, test, and deploy the app. -[Enable Auto DevOps](../../../../topics/autodevops/index.md#enablingdisabling-auto-devops-at-the-project-level) +[Enable Auto DevOps](../../../../topics/autodevops/index.md#at-the-project-level) if not already enabled. If a wildcard DNS entry was created resolving to the Load Balancer, enter it in the `domain` field under the Auto DevOps settings. Otherwise, the deployed app will not be externally available outside of the cluster. diff --git a/doc/user/project/clusters/img/k8s_cluster_monitoring.png b/doc/user/project/clusters/img/k8s_cluster_monitoring.png Binary files differindex e449893a606..0a8c5043c65 100644 --- a/doc/user/project/clusters/img/k8s_cluster_monitoring.png +++ b/doc/user/project/clusters/img/k8s_cluster_monitoring.png diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index dc21db603d6..cf3a3fef79f 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,30 +1,113 @@ -# Connecting GitLab with a Kubernetes cluster +# Kubernetes clusters -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in GitLab 10.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in GitLab 10.1 for projects. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in +> GitLab 11.6 for [groups](../../group/clusters/index.md). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/39840) in +> GitLab 11.11 for [instances](../../instance/clusters/index.md). -Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes -cluster in a few steps. +GitLab provides many features with a Kubernetes integration. Kubernetes can be +integrated with projects, but also: + +- [Groups](../../group/clusters/index.md). +- [Instances](../../instance/clusters/index.md). + +NOTE: **Scalable app deployment with GitLab and Google Cloud Platform** +[Watch the webcast](https://about.gitlab.com/webcast/scalable-app-deploy/) and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform (GCP) in a few clicks. ## Overview -With one or more Kubernetes clusters associated to your project, you can use -[Review Apps](../../../ci/review_apps/index.md), deploy your applications, run -your pipelines, use it with [Auto DevOps](../../../topics/autodevops/index.md), -and much more, all from within GitLab. +Using the GitLab project Kubernetes integration, you can: + +- Use [Review Apps](../../../ci/review_apps/index.md). +- Run [pipelines](../../../ci/pipelines.md). +- [Deploy](#deploying-to-a-kubernetes-cluster) your applications. +- Detect and [monitor Kubernetes](#kubernetes-monitoring). +- Use it with [Auto DevOps](#auto-devops). +- Use [Web terminals](#web-terminals). +- Use [Deploy Boards](#deploy-boards-premium). **(PREMIUM)** +- Use [Canary Deployments](#canary-deployments-premium). **(PREMIUM)** +- View [Pod logs](#pod-logs-ultimate). **(ULTIMATE)** + +You can also: + +- Connect and deploy to an [Amazon EKS cluster](eks_and_gitlab/index.html). +- Run serverless workloads on [Kubernetes with Knative](serverless/index.md). + +### Deploy Boards **(PREMIUM)** + +GitLab's Deploy Boards offer a consolidated view of the current health and +status of each CI [environment](../../../ci/environments.md) 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. + +[Read more about Deploy Boards](../deploy_boards.md) + +### Canary Deployments **(PREMIUM)** + +Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) +and visualize your canary deployments right inside the Deploy Board, without +the need to leave GitLab. + +[Read more about Canary Deployments](../canary_deployments.md) + +### Pod logs **(ULTIMATE)** + +GitLab makes it easy to view the logs of running pods in connected Kubernetes clusters. By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. + +[Read more about Kubernetes pod logs](kubernetes_pod_logs.md) + +### Kubernetes monitoring -There are two options when adding a new cluster to your project; either associate -your account with Google Kubernetes Engine (GKE) so that you can [create new -clusters](#adding-and-creating-a-new-gke-cluster-via-gitlab) from within GitLab, -or provide the credentials to an [existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster). +Automatically detect and monitor Kubernetes metrics. Automatic monitoring of +[NGINX ingress](../integrations/prometheus_library/nginx.md) is also supported. + +[Read more about Kubernetes monitoring](../integrations/prometheus_library/kubernetes.md) + +### Auto DevOps + +Auto DevOps automatically detects, builds, tests, deploys, and monitors your +applications. + +To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring) +you will need the Kubernetes project integration enabled. + +[Read more about Auto DevOps](../../../topics/autodevops/index.md) + +NOTE: **Note** +Kubernetes clusters can be used without Auto DevOps. + +### Web terminals NOTE: **Note:** -From [GitLab 11.6](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) you -can also associate a Kubernetes cluster to your groups and from -[GitLab 11.11](https://gitlab.com/gitlab-org/gitlab-ce/issues/39840), -to the GitLab instance. Learn more about [group-level](../../group/clusters/index.md) -and [instance-level](../../instance/clusters/index.md) Kubernetes clusters. +Introduced in GitLab 8.15. You must be the project owner or have `maintainer` permissions +to use terminals. Support is limited to the first container in the +first pod of your environment. + +When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals) +support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in +Docker and Kubernetes, so you get a new shell session within your existing +containers. To use this integration, you should deploy to Kubernetes using +the deployment variables above, ensuring any deployments, replica sets, and +pods are annotated with: + +- `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` +- `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` -## Adding and creating a new GKE cluster via GitLab +`$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of +the CI variables. + +## Adding and removing clusters + +There are two options when adding a new cluster to your project: + +- Associate your account with Google Kubernetes Engine (GKE) to + [create new clusters](#add-new-gke-cluster) from within GitLab. +- Provide credentials to an + [existing Kubernetes cluster](#add-existing-kubernetes-cluster). + +### Add new GKE cluster TIP: **Tip:** Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial), @@ -36,7 +119,7 @@ The [Google authentication integration](../../../integration/google.md) must be enabled in GitLab at the instance level. If that's not the case, ask your GitLab administrator to enable it. On GitLab.com, this is enabled. -### Requirements +#### Requirements Before creating your first cluster on Google Kubernetes Engine with GitLab's integration, make sure the following requirements are met: @@ -46,15 +129,15 @@ integration, make sure the following requirements are met: - The Kubernetes Engine API and related service are enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). -### Creating the cluster +#### Creating the cluster If all of the above requirements are met, you can proceed to create and add a new Kubernetes cluster to your project: 1. Navigate to your project's **Operations > Kubernetes** page. - NOTE: **Note:** - You need Maintainer [permissions] and above to access the Kubernetes page. + NOTE: **Note:** + You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. 1. Click **Add Kubernetes cluster**. 1. Click **Create with Google Kubernetes Engine**. @@ -71,7 +154,6 @@ new Kubernetes cluster to your project: - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - **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](#rbac-cluster-resources) 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. @@ -86,130 +168,167 @@ account](#access-controls). Starting from [GitLab creation process will explicitly request that basic authentication and client certificate is enabled. -## Adding an existing Kubernetes cluster +NOTE: **Note:** +Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ce/issues/55902), all GKE clusters created by GitLab are RBAC enabled. Take a look at the [RBAC section](#rbac-cluster-resources) for more information. + +### Add existing Kubernetes cluster + +NOTE: **Note:** +Kubernetes integration is not supported for arm64 clusters. See the issue [Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-ce/issues/64044) for details. To add an existing Kubernetes cluster to your project: 1. Navigate to your project's **Operations > Kubernetes** page. - NOTE: **Note:** - You need Maintainer [permissions] and above to access the Kubernetes page. + NOTE: **Note:** + You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. 1. Click **Add Kubernetes cluster**. 1. Click **Add an existing Kubernetes cluster** and fill in the details: - - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - - **Environment scope** (required) - The - [associated environment](#setting-the-environment-scope-premium) to this cluster. - - **API URL** (required) - - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes - exposes several APIs, we want the "base" URL that is common to all of them, - e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. - - Get the API URL by running this command: - - ```sh - kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' - ``` - - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default. - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate by running this command: - - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - - **Token** - - GitLab authenticates against Kubernetes using service tokens, which are - scoped to a particular `namespace`. - **The token used should belong to a service account with - [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - privileges.** To create this service account: - - 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab-admin - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab-admin - namespace: kube-system - ``` - - 1. Apply the service account and cluster role binding to your cluster: - - ```bash - kubectl apply -f gitlab-admin-service-account.yaml - ``` - - Output: - - ```bash - serviceaccount "gitlab-admin" created - clusterrolebinding "gitlab-admin" created - ``` - - 1. Retrieve the token for the `gitlab-admin` service account: - - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: gitlab-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - NOTE: **Note:** - For GKE clusters, you will need the - `container.clusterRoleBindings.create` permission to create a cluster - 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. - - The project namespace is not necessarily the namespace of the secret, if - you're using a secret with broader permissions, like the secret from `default`. - - You should **not** use `default` as the project namespace. - - If you or someone created a secret specifically for the project, usually - with limited permissions, the secret's namespace and project namespace may - be the same. + - **Kubernetes cluster name** (required) - The name you wish to give the cluster. + - **Environment scope** (required) - The + [associated environment](#setting-the-environment-scope-premium) to this cluster. + - **API URL** (required) - + It's the URL that GitLab uses to access the Kubernetes API. Kubernetes + exposes several APIs, we want the "base" URL that is common to all of them, + e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + + Get the API URL by running this command: + + ```sh + kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' + ``` + + - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default. + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate by running this command: + + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` + + - **Token** - + GitLab authenticates against Kubernetes using service tokens, which are + scoped to a particular `namespace`. + **The token used should belong to a service account with + [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + privileges.** To create this service account: + + 1. Create a file called `gitlab-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab-admin + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` + + 1. Apply the service account and cluster role binding to your cluster: + + ```bash + kubectl apply -f gitlab-admin-service-account.yaml + ``` + + Output: + + ```bash + serviceaccount "gitlab-admin" created + clusterrolebinding "gitlab-admin" created + ``` + + 1. Retrieve the token for the `gitlab-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: gitlab-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + + NOTE: **Note:** + For GKE clusters, you will need the + `container.clusterRoleBindings.create` permission to create a cluster + 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. + - The project namespace is not necessarily the namespace of the secret, if + you're using a secret with broader permissions, like the secret from `default`. + - You should **not** use `default` as the project namespace. + - If you or someone created a secret specifically for the project, usually + with limited permissions, the secret's namespace and project namespace may + be the same. 1. Finally, click the **Create Kubernetes cluster** button. After a couple of minutes, your cluster will be ready to go. You can now proceed to install some [pre-defined applications](#installing-applications). -## Security implications +### Enabling or disabling integration + +After you have successfully added your cluster information, you can enable the +Kubernetes cluster integration: + +1. Click the **Enabled/Disabled** switch +1. Hit **Save** for the changes to take effect + +To disable the Kubernetes cluster integration, follow the same procedure. + +### Removing integration + +NOTE: **Note:** +You need Maintainer [permissions](../../permissions.md) and above to remove a Kubernetes cluster integration. + +NOTE: **Note:** +When you remove a cluster, you only remove its relation to GitLab, not the +cluster itself. To remove the cluster, you can do so by visiting the GKE +dashboard or using `kubectl`. + +To remove the Kubernetes cluster integration from your project, simply click the +**Remove integration** button. You will then be able to follow the procedure +and add a Kubernetes cluster again. + +## Cluster configuration + +This section covers important considerations for configuring Kubernetes +clusters with GitLab. + +### Security implications CAUTION: **Important:** The whole cluster security is based on a model where [developers](../../permissions.md) @@ -220,15 +339,11 @@ 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 +### 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 @@ -243,7 +358,7 @@ 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 +### Base domain > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8. @@ -261,7 +376,7 @@ you can either: - Create an `A` record that points to the Ingress IP address with your domain provider. - Enter a wildcard DNS address using a service such as nip.io or xip.io. For example, `192.168.1.1.xip.io`. -## Access controls +### Access controls When creating a cluster in GitLab, you will be asked if you would like to create either: @@ -272,13 +387,9 @@ NOTE: **Note:** [RBAC](#rbac-cluster-resources) is recommended and the GitLab default. GitLab creates the necessary service accounts and privileges to install and run -[GitLab managed applications](#installing-applications). When GitLab creates the cluster: - -- A `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace - to manage the newly created cluster. -- A project service account with [`edit` - privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - is created in the GitLab-created project namespace for [deployment jobs](#deployment-variables). +[GitLab managed applications](#installing-applications). When GitLab creates the cluster, +a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace +to manage the newly created cluster. NOTE: **Note:** Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/51716) in GitLab 11.5. @@ -291,47 +402,53 @@ Helm will also create additional service accounts and other resources for each installed application. Consult the documentation of the Helm charts for each application for details. -If you are [adding an existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster), +If you are [adding an existing Kubernetes cluster](#add-existing-kubernetes-cluster), ensure the token of the account has administrator privileges for the cluster. The resources created by GitLab differ depending on the type of cluster. -### ABAC cluster resources +#### ABAC cluster resources GitLab creates the following resources for ABAC clusters. -| Name | Type | Details | Created when | -|:------------------|:---------------------|:----------------------------------|:---------------------------| -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `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 | Deploying to a cluster | -| Project namespace | `Secret` | Token for project ServiceAccount | Deploying to a cluster | +| Name | Type | Details | Created when | +|:----------------------|:---------------------|:-------------------------------------|:---------------------------| +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `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 | +| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | +| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | +| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | -### RBAC cluster resources +#### RBAC cluster resources GitLab creates the following resources for RBAC clusters. -| Name | Type | Details | Created when | -|:------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:---------------------------| -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster | -| `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 | 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 | +| Name | Type | Details | Created when | +|:----------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:---------------------------| +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster | +| `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 | +| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | +| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | +| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | +| Environment 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). +Environment-specific resources are only created if your cluster is [managed by GitLab](#gitlab-managed-clusters). -### Security of GitLab Runners +NOTE: **Note:** +If your cluster was created before GitLab 12.2, it will use a single namespace for all project environments. + +#### Security of GitLab Runners GitLab Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode) enabled by default, which allows them to execute special commands and running -Docker in Docker. This functionality is needed to run some of the [Auto DevOps] +Docker in Docker. This functionality is needed to run some of the +[Auto DevOps](../../../topics/autodevops/index.md) jobs. This implies the containers are running in privileged mode and you should, therefore, be aware of some important details. @@ -340,10 +457,81 @@ turn can do almost everything that the host can do. Be aware of the inherent security risk associated with performing `docker run` operations on arbitrary images as they effectively have root access. -If you don't want to use GitLab Runner in privileged mode, first make sure that -you don't have it installed via the applications, and then use the -[Runner's Helm chart](../../../install/kubernetes/gitlab_runner_chart.md) to -install it manually. +If you don't want to use GitLab Runner in privileged mode, either: + +- Use shared Runners on GitLab.com. They don't have this security issue. +- Set up your own Runners using configuration described at + [Shared Runners](../../gitlab_com/index.md#shared-runners). This involves: + 1. Making sure that you don't have it installed via + [the applications](#installing-applications). + 1. Installing a Runner + [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). + +### Setting the environment scope **(PREMIUM)** + +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](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables) 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 +cluster in a project, and a validation error will occur if otherwise. +Also, jobs that don't have an environment keyword set will not be able to access any cluster. + +For example, let's say the following Kubernetes clusters exist in a project: + +| Cluster | Environment scope | +| ----------- | ----------------- | +| Development | `*` | +| Production | `production` | + +And the following environments are set in +[`.gitlab-ci.yml`](../../../ci/yaml/README.md): + +```yaml +stages: +- test +- deploy + +test: + stage: test + script: sh test + +deploy to staging: + stage: deploy + script: make deploy + environment: + name: staging + url: https://staging.example.com/ + +deploy to production: + stage: deploy + script: make deploy + environment: + name: production + url: https://example.com/ +``` + +The result will then be: + +- The Development cluster details will be available in the `deploy to staging` + job. +- The production cluster details will be available in the `deploy to production` + job. +- No cluster details will be available in the `test` job because it doesn't + define any environment. + +### Multiple Kubernetes clusters **(PREMIUM)** + +> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. + +With GitLab Premium, you can associate more than one Kubernetes cluster to your +project. That way you can have different clusters for different environments, +like dev, staging, production, etc. + +Simply add another cluster, like you did the first time, and make sure to +[set an environment scope](#setting-the-environment-scope-premium) that will +differentiate the new cluster with the rest. ## Installing applications @@ -352,7 +540,7 @@ cluster. For more information on installing, upgrading, uninstalling, and troubleshooting applications for your project cluster, see [Gitlab Managed Apps](../../clusters/applications.md). -## Getting the external endpoint +### Getting the external endpoint NOTE: **Note:** With the following procedure, a load balancer must be installed in your cluster @@ -363,7 +551,7 @@ to obtain the endpoint. You can use either In order to publish your web application, you first need to find the endpoint which will be either an IP address or a hostname associated with your load balancer. -### Automatically determining the external endpoint +#### Automatically determining the external endpoint > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17052) in GitLab 10.6. @@ -378,7 +566,7 @@ and your cluster runs on Google Kubernetes Engine: If GitLab is still unable to determine the endpoint of your Ingress or Knative application, you can manually determine it by following the steps below. -### Manually determining the external endpoint +#### Manually determining the external endpoint If the cluster is on GKE, click the **Google Kubernetes Engine** link in the **Advanced settings**, or go directly to the @@ -417,7 +605,7 @@ Otherwise, you can list the IP addresses of all load balancers: kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' ``` -### Using a static IP +#### Using a static IP By default, an ephemeral external IP address is associated to the cluster's load balancer. If you associate the ephemeral IP with your DNS and the IP changes, @@ -427,79 +615,27 @@ reserved IP. Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). -### Pointing your DNS at the external endpoint +#### Pointing your DNS at the external endpoint Once you've set up the external endpoint, you should associate it with a [wildcard DNS record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) such as `*.example.com.` in order to be able to reach your apps. If your external endpoint is an IP address, use an A record. If your external endpoint is a hostname, use a CNAME record. -## Multiple Kubernetes clusters **[PREMIUM]** - -> Introduced in [GitLab Premium][ee] 10.3. - -With GitLab Premium, you can associate more than one Kubernetes clusters to your -project. That way you can have different clusters for different environments, -like dev, staging, production, etc. - -Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope-premium) that will -differentiate the new cluster with the rest. - -## Setting the environment scope **[PREMIUM]** - -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](../../../ci/variables/README.md#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 -cluster in a project, and a validation error will occur if otherwise. -Also, jobs that don't have an environment keyword set will not be able to access any cluster. +## Deploying to a Kubernetes cluster ---- - -For example, let's say the following Kubernetes clusters exist in a project: - -| Cluster | Environment scope | -| ----------- | ----------------- | -| Development | `*` | -| Staging | `staging` | -| Production | `production` | +A Kubernetes cluster can be the destination for a deployment job. If -And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md): +- The cluster is integrated with GitLab, special + [deployment variables](#deployment-variables) are made available to your job + and configuration is not required. You can immediately begin interacting with + the cluster from your jobs using tools such as `kubectl` or `helm`. +- You don't use GitLab's cluster integration you can still deploy to your + cluster. However, you will need configure Kubernetes tools yourself + using [environment variables](../../../ci/variables/README.md#creating-a-custom-environment-variable) + before you can interact with the cluster from your jobs. -```yaml -stages: -- test -- deploy - -test: - stage: test - script: sh test - -deploy to staging: - stage: deploy - script: make deploy - environment: - name: staging - url: https://staging.example.com/ - -deploy to production: - stage: deploy - script: make deploy - environment: - name: production - url: https://example.com/ -``` - -The result will then be: - -- The development cluster will be used for the "test" job. -- The staging cluster will be used for the "deploy to staging" job. -- The production cluster will be used for the "deploy to production" job. - -## Deployment variables +### Deployment variables The Kubernetes cluster integration exposes the following [deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the @@ -508,8 +644,8 @@ GitLab CI/CD build environment. | Variable | Description | | -------- | ----------- | | `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [project service account](#access-controls). | -| `KUBE_NAMESPACE` | The Kubernetes namespace is auto-generated if not specified. The default value is `<project_name>-<project_id>`. You can overwrite it to use different one if needed, otherwise the `KUBE_NAMESPACE` variable will receive the default value. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](#access-controls). | +| `KUBE_NAMESPACE` | The Kubernetes namespace is auto-generated if not specified. The default value is `<project_name>-<project_id>-<environment>`. You can overwrite it to use different one if needed, otherwise the `KUBE_NAMESPACE` variable will receive the default value. | | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | @@ -519,12 +655,16 @@ NOTE: **NOTE:** Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. -### Troubleshooting failed deployment jobs +NOTE: **Note:** +If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be set to `<project_name>-<project_id>`. + +### Troubleshooting -GitLab will create a namespace and service account specifically for your -deployment jobs. On project level clusters, this happens when the cluster -is created. On group level clusters, resources are created immediately -before the deployment job starts. +Before the deployment jobs starts, GitLab creates the following specifically for +the deployment job: + +- A namespace. +- A service account. However, sometimes GitLab can not create them. In such instances, your job will fail with the message: @@ -534,115 +674,24 @@ This job failed because the necessary resources were not successfully created. To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog). -Common reasons for failure include: +Reasons for failure include: -- The token you gave GitLab did not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) +- The token you gave GitLab does not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) privileges required by GitLab. - Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching [`environment:name`](../../../ci/environments.md#defining-environments). If your job has no `environment:name` set, it will not be passed the Kubernetes credentials. -## Monitoring your Kubernetes cluster **[ULTIMATE]** +NOTE: **NOTE:** +Project-level clusters upgraded from GitLab 12.0 or older may be configured +in a way that causes this error. Ensure you deselect the +[GitLab-managed cluster](#gitlab-managed-clusters) option if you want to manage +namespaces and service accounts yourself. + +## Monitoring your Kubernetes cluster **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4701) in [GitLab Ultimate][ee] 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. 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 - -After you have successfully added your cluster information, you can enable the -Kubernetes cluster integration: - -1. Click the **Enabled/Disabled** switch -1. Hit **Save** for the changes to take effect - -You can now start using your Kubernetes cluster for your deployments. - -To disable the Kubernetes cluster integration, follow the same procedure. - -## Removing the Kubernetes cluster integration - -NOTE: **Note:** -You need Maintainer [permissions] and above to remove a Kubernetes cluster integration. - -NOTE: **Note:** -When you remove a cluster, you only remove its relation to GitLab, not the -cluster itself. To remove the cluster, you can do so by visiting the GKE -dashboard or using `kubectl`. - -To remove the Kubernetes cluster integration from your project, simply click the -**Remove integration** button. You will then be able to follow the procedure -and add a Kubernetes cluster again. - -## What you can get with the Kubernetes integration - -Here's what you can do with GitLab if you enable the Kubernetes integration. - -### Deploy Boards **[PREMIUM]** - -GitLab's Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../../ci/environments.md) 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. - -[Read more about Deploy Boards](../deploy_boards.md) - -### Canary Deployments **[PREMIUM]** - -Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) -and visualize your canary deployments right inside the Deploy Board, without -the need to leave GitLab. - -[Read more about Canary Deployments](../canary_deployments.md) - -### Pod logs **[ULTIMATE]** - -GitLab makes it easy to view the logs of running pods in connected Kubernetes clusters. By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. - -[Read more about Kubernetes pod logs](kubernetes_pod_logs.md) - -### Kubernetes monitoring - -Automatically detect and monitor Kubernetes metrics. Automatic monitoring of -[NGINX ingress](../integrations/prometheus_library/nginx.md) is also supported. - -[Read more about Kubernetes monitoring](../integrations/prometheus_library/kubernetes.md) - -### Auto DevOps - -Auto DevOps automatically detects, builds, tests, deploys, and monitors your -applications. - -To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring) -you will need the Kubernetes project integration enabled. - -[Read more about Auto DevOps](../../../topics/autodevops/index.md) - -### Web terminals - -NOTE: **Note:** -Introduced in GitLab 8.15. You must be the project owner or have `maintainer` permissions -to use terminals. Support is limited to the first container in the -first pod of your environment. - -When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals) -support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in -Docker and Kubernetes, so you get a new shell session within your existing -containers. To use this integration, you should deploy to Kubernetes using -the deployment variables above, ensuring any pods you create are labelled with -`app=$CI_ENVIRONMENT_SLUG`. GitLab will do the rest! - -### Integrating Amazon EKS cluster with GitLab - -- Learn how to [connect and deploy to an Amazon EKS cluster](eks_and_gitlab/index.md). - -### Serverless - -- [Run serverless workloads on Kubernetes with Knative.](serverless/index.md) - -[permissions]: ../../permissions.md -[ee]: https://about.gitlab.com/pricing/ -[Auto DevOps]: ../../../topics/autodevops/index.md diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 368031070c1..163f3befeee 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,10 +1,14 @@ -# Kubernetes Pod Logs **[ULTIMATE]** +# 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. +NOTE: **Kubernetes + GitLab** +Everything you need to build, test, deploy, and run your app at scale. +[Learn more](https://about.gitlab.com/solutions/kubernetes/). + ## 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](../deploy_boards.md): @@ -12,9 +16,9 @@ By displaying the logs directly in GitLab, developers can avoid having to manage 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](../deploy_boards.md). 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 diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index c67b12fb91a..8df27976662 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,28 +1,27 @@ # Runbooks -Runbooks are a collection of documented procedures that explain how to -carry out a particular process, be it starting, stopping, debugging, +Runbooks are a collection of documented procedures that explain how to +carry out a particular process, be it starting, stopping, debugging, or troubleshooting a particular system. Using [Jupyter Notebooks](https://jupyter.org/) and the [Rubix library](https://github.com/Nurtch/rubix), users can get started writing their own executable runbooks. - ## Overview -Historically, runbooks took the form of a decision tree or a detailed -step-by-step guide depending on the condition or system. +Historically, runbooks took the form of a decision tree or a detailed +step-by-step guide depending on the condition or system. -Modern implementations have introduced the concept of an "executable -runbooks", where, along with a well-defined process, operators can execute +Modern implementations have introduced the concept of an "executable +runbooks", where, along with a well-defined process, operators can execute pre-written code blocks or database queries against a given environment. ## Executable Runbooks > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4. -The JupyterHub app offered via GitLab’s Kubernetes integration now ships -with Nurtch’s Rubix library, providing a simple way to create DevOps +The JupyterHub app offered via GitLab’s Kubernetes integration now ships +with Nurtch’s Rubix library, providing a simple way to create DevOps runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it simple to create common Kubernetes and AWS workflows, you can also create them manually without Rubix. @@ -35,33 +34,33 @@ for an overview of how this is accomplished in GitLab!** To create an executable runbook, you will need: -1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. - The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). -1. **Helm Tiller** - 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 +1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. + The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#add-new-gke-cluster). +1. **Helm Tiller** - 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. -1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based +1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications. -1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across - a team. Jupyter Notebooks provide a web-based interactive programming environment +1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across + a team. Jupyter Notebooks provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. ## Nurtch -Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is -an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. -Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified -down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) +Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is +an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. +Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified +down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) for more information. ## Configure an executable runbook with GitLab -Follow this step-by-step guide to configure an executable runbook in GitLab using +Follow this step-by-step guide to configure an executable runbook in GitLab using the components outlined above and the preloaded demo runbook. ### 1. Add a Kubernetes cluster -Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) +Follow the steps outlined in [Add new GKE cluster](../index.md#add-new-gke-cluster) to add a Kubernetes cluster to your project. ### 2. Install Helm Tiller, Ingress, and JupyterHub @@ -80,13 +79,13 @@ Once Ingress has been installed successfully, click the **Install** button next ### 3. Login to JupyterHub and start the server -Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click -**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This +Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click +**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This will redirect to GitLab in order to authorize JupyterHub to use your GitLab account. Click **Authorize**.  -Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. +Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. The server will take a couple of seconds to start. ### 4. Configure access @@ -103,7 +102,7 @@ Double-click the "Nurtch-DevOps-Demo.ipynb" runbook.  -The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find +The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find entries for both your `PRIVATE_TOKEN` and your `PROJECT_ID`. Enter both these values, conserving the single quotes as follows: ```sql @@ -111,7 +110,7 @@ PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' PROJECT_ID = '1234567' ``` -Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your +Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your access token. In this example our variable name is `PRIVATE_TOKEN`. ```sql @@ -120,8 +119,8 @@ VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value ### 5. Configure an operation -For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query -a postgres database. The first 4 lines of the section define the variables that are required for this query to function. +For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query +a postgres database. The first 4 lines of the section define the variables that are required for this query to function. ```sql %env DB_USER={project.variables.get('DB_USER').value} @@ -134,10 +133,10 @@ Create the matching variables in your project's **Settings >> CI/CD >> Variables  -Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be +Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be displayed in-line as follows:  -You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the -[Nurtch Documentation](http://docs.nurtch.com/) for more information.
\ No newline at end of file +You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the +[Nurtch Documentation](http://docs.nurtch.com/) for more information. diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png Binary files differindex 351e40b77d5..7b5d6497f0e 100644 --- a/doc/user/project/clusters/serverless/img/dns-entry.png +++ b/doc/user/project/clusters/serverless/img/dns-entry.png diff --git a/doc/user/project/clusters/serverless/img/function-details-loaded.png b/doc/user/project/clusters/serverless/img/function-details-loaded.png Binary files differindex 34465c5c087..2f0d61f8032 100644 --- a/doc/user/project/clusters/serverless/img/function-details-loaded.png +++ b/doc/user/project/clusters/serverless/img/function-details-loaded.png diff --git a/doc/user/project/clusters/serverless/img/function-endpoint.png b/doc/user/project/clusters/serverless/img/function-endpoint.png Binary files differnew file mode 100644 index 00000000000..a38fe2cb6c2 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/function-endpoint.png diff --git a/doc/user/project/clusters/serverless/img/function-execution.png b/doc/user/project/clusters/serverless/img/function-execution.png Binary files differindex 93b0b6d802d..f60dd277081 100644 --- a/doc/user/project/clusters/serverless/img/function-execution.png +++ b/doc/user/project/clusters/serverless/img/function-execution.png diff --git a/doc/user/project/clusters/serverless/img/install-knative.png b/doc/user/project/clusters/serverless/img/install-knative.png Binary files differindex ecc2f8fb481..1dc830848f2 100644 --- a/doc/user/project/clusters/serverless/img/install-knative.png +++ b/doc/user/project/clusters/serverless/img/install-knative.png diff --git a/doc/user/project/clusters/serverless/img/serverless-page.png b/doc/user/project/clusters/serverless/img/serverless-page.png Binary files differindex a872fda7740..8dce3cb1f70 100644 --- a/doc/user/project/clusters/serverless/img/serverless-page.png +++ b/doc/user/project/clusters/serverless/img/serverless-page.png diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 2cda850f24e..bcf9a677a40 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -24,34 +24,33 @@ To run Knative on Gitlab, you will need: 1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started: - - If you are planning on deploying functions, clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. - - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. + - If you are planning on deploying functions, clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. + - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. - The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). - The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. + The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#add-new-gke-cluster). + The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install - Knative. + Knative. 1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless - applications or functions onto your cluster. You can install the GitLab Runner - onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. + applications or functions onto your cluster. You can install the GitLab Runner + onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. 1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an - external IP address or hostname for all the applications served by Knative. You will be prompted to enter a - wildcard domain where your applications will be served. Configure your DNS server to use the - external IP address or hostname for that domain. + external IP address or hostname for all the applications served by Knative. You will be prompted to enter a + wildcard domain where your applications will be served. Configure your DNS server to use the + external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) - to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl) - and [TriggerMesh CLI](https://github.com/triggermesh/tm) CLIs to simplify the - deployment of services and functions to Knative. + to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl) + CLI to simplify the deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file - will contain the information for all the functions being hosted in the repository as well as a reference to the - runtime being used. + will contain the information for all the functions being hosted in the repository as well as a reference to the + runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): Knative requires a - `Dockerfile` in order to build your applications. It should be included at the root of your - project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions - using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). + `Dockerfile` in order to build your applications. It should be included at the root of your + project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions + using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). 1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. - See [Installing Applications](../index.md#installing-applications) for more information. + See [Installing Applications](../index.md#installing-applications) for more information. ## Installing Knative via GitLab's Kubernetes integration @@ -60,9 +59,9 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. 1. [Add a Kubernetes cluster](../index.md) and [install Helm](../index.md#installing-applications). 1. Once Helm has been successfully installed, scroll down to the Knative app section. Enter the domain to be used with - your application/functions (e.g. `example.com`) and click **Install**. + your application/functions (e.g. `example.com`) and click **Install**. -  +  1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../#manually-determining-the-external-endpoint). @@ -77,19 +76,90 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` pointing the ip address or hostname of the ingress. -  +  NOTE: **Note:** You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) on a given project but not both. The current implementation makes use of a `serverless.yml` file to signal a FaaS project. +## Using an existing installation of Knative + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/58941) in GitLab 12.0. + +NOTE: **Note:** +The "invocations" monitoring feature of GitLab serverless will not work when +adding an existing installation of Knative. + +It is also possible to use GitLab Serverless with an existing Kubernetes +cluster which already has Knative installed. + +You must do the following: + +1. Follow the steps to + [add an existing Kubernetes + cluster](../index.md#add-existing-kubernetes-cluster). + +1. Ensure GitLab can manage Knative: + - For a non-GitLab managed cluster, ensure that the service account for the token + provided can manage resources in the `serving.knative.dev` API group. + - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30235), + then GitLab will already have the required access and you can proceed to the next step. + + Otherwise, you need to manually grant GitLab's service account the ability to manage + resources in the `serving.knative.dev` API group. Since every GitLab service account + has the `edit` cluster role, the simplest way to do this is with an + [aggregated ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles) + adding rules to the default `edit` cluster role: First, save the following YAML as + `knative-serving-only-role.yaml`: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: knative-serving-only-role + labels: + rbac.authorization.k8s.io/aggregate-to-edit: "true" + rules: + - apiGroups: + - serving.knative.dev + resources: + - configurations + - configurationgenerations + - routes + - revisions + - revisionuids + - autoscalers + - services + verbs: + - get + - list + - create + - update + - delete + - patch + - watch + ``` + + Then run the following command: + + ```bash + kubectl apply -f knative-serving-only-role.yaml + ``` + + If you would rather grant permissions on a per service account basis, you can do this + using a `Role` and `RoleBinding` specific to the service account and namespace. + +1. Follow the steps to deploy [functions](#deploying-functions) + or [serverless applications](#deploying-serverless-applications) onto your + cluster. + ## Deploying functions > Introduced in GitLab 11.6. -Using functions is useful for dealing with independent -events without needing to maintain a complex unified infrastructure. This allows -you to focus on a single task that can be executed/scaled automatically and independently. +Using functions is useful for dealing with independent events without needing +to maintain a complex unified infrastructure. This allows you to focus on a +single task that can be executed/scaled automatically and independently. Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are offered: @@ -97,15 +167,21 @@ Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runt - node.js - Dockerfile -You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**. +`Dockerfile` presence is assumed when a runtime is not specified. -Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project): +You can find and import all the files referenced in this doc in the +**[functions example project](https://gitlab.com/knative-examples/functions)**. -1. Create a directory that will house the function. In this example we will create a directory called `echo` at the root of the project. +Follow these steps to deploy a function using the Node.js runtime to your +Knative instance (you can skip these steps if you've cloned the example +project): + +1. Create a directory that will house the function. In this example we will + create a directory called `echo` at the root of the project. 1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: - - Public, continue to the next step. - - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. + - Public, continue to the next step. + - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. 1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions. It must be included at the root of your repository: @@ -123,16 +199,16 @@ Follow these steps to deploy a function using the Node.js runtime to your Knativ environment: production ``` - This `.gitlab-ci.yml` creates jobs that invoke some predefined commands to - build and deploy your functions to your cluster. + This `.gitlab-ci.yml` creates jobs that invoke some predefined commands to + build and deploy your functions to your cluster. - `Serverless.gitlab-ci.yml` is a template that allows customization. - You can either import it with `include` parameter and use `extends` to - customize your jobs, or you can inline the entire template by choosing it - from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through - the user interface. + `Serverless.gitlab-ci.yml` is a template that allows customization. + You can either import it with `include` parameter and use `extends` to + customize your jobs, or you can inline the entire template by choosing it + from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through + the user interface. -2. `serverless.yml`: this file contains the metadata for your functions, +1. `serverless.yml`: this file contains the metadata for your functions, such as name, runtime, and environment. It must be included at the root of your repository. @@ -173,26 +249,27 @@ Explanation of the fields used above: | Parameter | Description | |-----------|-------------| -| `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh `tm` CLI. | +| `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh middleware. | | `environment` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are he variable contents. You may replace this with you own variables. | ### `functions` -In the `serverless.yml` example above, the function name is `echo` and the subsequent lines contain the function attributes. +In the `serverless.yml` example above, the function name is `echo` and the +subsequent lines contain the function attributes. | Parameter | Description | |-----------|-------------| | `handler` | The function's name. | | `source` | Directory with sources of a functions. | -| `runtime` | The runtime to be used to execute the function. | +| `runtime` (optional)| The runtime to be used to execute the function. When the runtime is not specified, we assume that `Dockerfile` is present in the function directory specified by `source`. | | `description` | A short description of the function. | | `environment` | Sets an environment variable for the specific function only. | -After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been -created, pushing a commit to your project will result in a -CI pipeline being executed which will deploy each function as a Knative service. -Once the deploy stage has finished, additional details for the function will -appear under **Operations > Serverless**. +After the `gitlab-ci.yml` template has been added and the `serverless.yml` file +has been created, pushing a commit to your project will result in a CI pipeline +being executed which will deploy each function as a Knative service. Once the +deploy stage has finished, additional details for the function will appear +under **Operations > Serverless**.  @@ -211,16 +288,17 @@ The sample function can now be triggered from any HTTP client using a simple `PO 1. Using curl (replace the URL on the last line with the URL of your application): - ```bash - curl \ - --header "Content-Type: application/json" \ - --request POST \ - --data '{"GitLab":"FaaS"}' \ - http://functions-echo.functions-1.functions.example.com/ - ``` - 2. Using a web-based tool (ie. postman, restlet, etc) + ```bash + curl \ + --header "Content-Type: application/json" \ + --request POST \ + --data '{"GitLab":"FaaS"}' \ + http://functions-echo.functions-1.functions.example.com/ + ``` + + 1. Using a web-based tool (ie. postman, restlet, etc) -  +  ## Deploying Serverless applications @@ -249,6 +327,8 @@ customize your jobs, or you can inline the entire template by choosing it from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through the user interface. +A `serverless.yml` file is not required when deploying serverless applications. + ### Deploy the application with Knative With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to @@ -263,27 +343,23 @@ Go to the **CI/CD > Pipelines** and click on the pipeline that deployed your app The output will look like this: ```bash -Running with gitlab-runner 11.5.0~beta.844.g96d88322 (96d88322) - on docker-auto-scale 72989761 -Using Docker executor with image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... -Pulling docker image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... -Using docker image sha256:6b3f6590a9b30bd7aafb9573f047d930c70066e43955b4beb18a1eee175f6de1 for gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... -Running on runner-72989761-project-4342902-concurrent-0 via runner-72989761-stg-srm-1541795796-27929c96... -Cloning repository... -Cloning into '/builds/danielgruesso/knative'... -Checking out 8671ad20 as master... -Skipping Git submodules setup -$ echo "$CI_REGISTRY_IMAGE" -registry.staging.gitlab.com/danielgruesso/knative -$ tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait -Deployment started. Run "tm -n knative-4342902 describe service knative" to see the details -Waiting for ready state....... -Service domain: knative.knative-4342902.example.com +Running with gitlab-runner 12.1.0-rc1 (6da35412) + on prm-com-gitlab-org ae3bfce3 +Using Docker executor with image registry.gitlab.com/gitlab-org/gitlabktl:latest ... +Running on runner-ae3bfc-concurrent-0 via runner-ae3bfc ... +Fetching changes... +Authenticating with credentials from job payload (GitLab Registry) +$ /usr/bin/gitlabktl application deploy +Welcome to gitlabktl tool +time="2019-07-15T10:51:07Z" level=info msg="deploying registry credentials" +Creating app-hello function +Waiting for app-hello ready state +Service app-hello URL: http://app-hello.serverless.example.com Job succeeded ``` -The second to last line, labeled **Service domain** contains the URL for the deployment. Copy and paste the domain into your -browser to see the app live. +The second to last line, labeled **Service domain** contains the URL for the +deployment. Copy and paste the domain into your browser to see the app live.  @@ -306,3 +382,274 @@ loading or is not available at this time._ It will appear upon the first access page, but should go away after a few seconds. If the message does not disappear, then it is possible that GitLab is unable to connect to the Prometheus instance running on the cluster. + +## Enabling TLS for Knative services + +By default, a GitLab serverless deployment will be served over `http`. In order to serve over `https` you +must manually obtain and install TLS certificates. + +The simplest way to accomplish this is to +use [Certbot to manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). Certbot is a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS. + +NOTE: **Note:** +The instructions below relate to installing and running Certbot on a Linux server and may not work on other operating systems. + +1. Install Certbot by running the + [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto). + On the command line of your server, run the following commands: + + ```sh + wget https://dl.eff.org/certbot-auto + sudo mv certbot-auto /usr/local/bin/certbot-auto + sudo chown root /usr/local/bin/certbot-auto + chmod 0755 /usr/local/bin/certbot-auto + /usr/local/bin/certbot-auto --help + ``` + + To check the integrity of the `certbot-auto` script, run: + + ```sh + wget -N https://dl.eff.org/certbot-auto.asc + gpg2 --keyserver ipv4.pool.sks-keyservers.net --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 + gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc /usr/local/bin/certbot-auto + ``` + + The output of the last command should look something like: + + ```sh + gpg: Signature made Mon 10 Jun 2019 06:24:40 PM EDT + gpg: using RSA key A2CFB51FA275A7286234E7B24D17C995CD9775F2 + gpg: key 4D17C995CD9775F2 marked as ultimately trusted + gpg: checking the trustdb + gpg: marginals needed: 3 completes needed: 1 trust model: pgp + gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u + gpg: next trustdb check due at 2027-11-22 + gpg: Good signature from "Let's Encrypt Client Team <letsencrypt-client@eff.org>" [ultimate] + ``` + +1. Run the following command to use Certbot to request a certificate + using DNS challenge during authorization: + + ```sh + ./certbot-auto certonly --manual --preferred-challenges dns -d '*.<namespace>.example.com' + ``` + + Where `<namespace>` is the namespace created by GitLab for your serverless project (composed of `<project_name>-<project_id>-<environment>`) and + `example.com` is the domain being used for your project. If you are unsure what the namespace of your project is, navigate + to the **Operations > Serverless** page of your project and inspect + the endpoint provided for your function/app. + +  + + In the above image, the namespace for the project is `node-function-11909507` and the domain is `knative.info`, thus + certificate request line would look like this: + + ```sh + ./certbot-auto certonly --manual --preferred-challenges dns -d '*.node-function-11909507.knative.info' + ``` + + The Certbot tool walks you through the steps of validating that you own each domain that you specify by creating TXT records in those domains. + After this process is complete, the output should look something like this: + + ```sh + IMPORTANT NOTES: + - Congratulations! Your certificate and chain have been saved at: + /etc/letsencrypt/live/namespace.example.com/fullchain.pem + Your key file has been saved at: + /etc/letsencrypt/live/namespace.example/privkey.pem + Your cert will expire on 2019-09-19. To obtain a new or tweaked + version of this certificate in the future, simply run certbot-auto + again. To non-interactively renew *all* of your certificates, run + "certbot-auto renew" + -----BEGIN PRIVATE KEY----- + - Your account credentials have been saved in your Certbot + configuration directory at /etc/letsencrypt. You should make a + secure backup of this folder now. This configuration directory will + also contain certificates and private keys obtained by Certbot so + making regular backups of this folder is ideal. + ``` + +1. Create certificate and private key files. Using the contents of the files + returned by Certbot, we'll create two files in order to create the + Kubernetes secret: + + Run the following command to see the contents of `fullchain.pem`: + + ```sh + sudo cat /etc/letsencrypt/live/node-function-11909507.knative.info/fullchain.pem + ``` + + Output should look like this: + + ```sh + -----BEGIN CERTIFICATE----- + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b4ag== + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + K2fcb195768c39e9a94cec2c2e30Qg== + -----END CERTIFICATE----- + ``` + + Create a file with the name `cert.pem` with the contents of the entire output. + + Once `cert.pem` is created, run the following command to see the contents of `privkey.pem`: + + ```sh + sudo cat /etc/letsencrypt/live/namespace.example/privkey.pem + ``` + + Output should look like this: + + ```sh + -----BEGIN PRIVATE KEY----- + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + -----BEGIN CERTIFICATE----- + fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 4f294d1eaca42b8692017b4262== + -----END PRIVATE KEY----- + ``` + + Create a new file with the name `cert.pk` with the contents of the entire output. + +1. Create a Kubernetes secret to hold your TLS certificate, `cert.pem`, and + the private key `cert.pk`: + + NOTE: **Note:** + Running `kubectl` commands on your cluster requires setting up access to the cluster first. + For clusters created on GKE, see + [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl). + For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + + ```sh + kubectl create --namespace istio-system secret tls istio-ingressgateway-certs \ + --key cert.pk \ + --cert cert.pem + ``` + + Where `cert.pem` and `cert.pk` are your certificate and private key files. Note that the `istio-ingressgateway-certs` secret name is required. + +1. Configure Knative to use the new secret that you created for HTTPS + connections. Run the + following command to open the Knative shared `gateway` in edit mode: + + ```sh + kubectl edit gateway knative-ingress-gateway --namespace knative-serving + ``` + + Update the gateway to include the following tls: section and configuration: + + ```sh + tls: + mode: SIMPLE + privateKey: /etc/istio/ingressgateway-certs/tls.key + serverCertificate: /etc/istio/ingressgateway-certs/tls.crt + ``` + + Example: + + ```sh + apiVersion: networking.istio.io/v1alpha3 + kind: Gateway + metadata: + # ... skipped ... + spec: + selector: + istio: ingressgateway + servers: + - hosts: + - "*" + port: + name: http + number: 80 + protocol: HTTP + - hosts: + - "*" + port: + name: https + number: 443 + protocol: HTTPS + tls: + mode: SIMPLE + privateKey: /etc/istio/ingressgateway-certs/tls.key + serverCertificate: /etc/istio/ingressgateway-certs/tls.crt + ``` + + After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services. + In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway` + to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index ae04616943f..96c4f16fe04 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,10 +1,12 @@ -# Code Owners **[STARTER]** +# Code Owners **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6916) +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6916) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. +> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-ce/issues/53182) added in GitLab Starter 12.1. -You can use a `CODEOWNERS` file to specify users that are responsible -for certain files in a repository. +You can use a `CODEOWNERS` file to specify users or +[shared groups](members/share_project_with_groups.md) +that are responsible for certain files in a repository. You can choose and add the `CODEOWNERS` file in three places: @@ -25,7 +27,8 @@ the given file. 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. +or more users or by the `@name` of one or more groups 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 @@ -54,8 +57,8 @@ Example `CODEOWNERS` file: # 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 +# Multiple codeowners can be specified, separated by spaces or tabs +CODEOWNERS @multiple @code @owners # Both usernames or email addresses can be used to match # users. Everything else will be ignored. For example this will @@ -63,6 +66,10 @@ CODEOWNERS @multiple @owners @tab-separated # owner for the LICENSE file LICENSE @legal this_does_not_match janedoe@gitlab.com +# Group names can be used to match groups and nested groups to specify +# them as owners for a file +README @group @group/with-nested/subgroup + # Ending a path in a `/` will specify the code owners for every file # nested in that directory, on any level /docs/ @all-docs diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 58b7fe33906..c9eb81b990c 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -1,13 +1,8 @@ # GitLab Container Registry -> **Notes:** -> > - [Introduced][ce-4040] in GitLab 8.8. > - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker > versions earlier than 1.10. -> - This document is about the user guide. To learn how to enable GitLab Container -> Registry across your GitLab instance, visit the -> [administrator documentation](../../administration/container_registry.md). > - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need > to pass a [personal access token][pat] instead of your password in order to > login to GitLab's Container Registry. @@ -16,28 +11,33 @@ With the Docker Container Registry integrated into GitLab, every project can have its own space to store its Docker images. +This document is the user guide. To learn how to enable GitLab Container +Registry across your GitLab instance, visit the +[administrator documentation](../../administration/container_registry.md). + You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>. ## Enable the Container Registry for your project -NOTE: **Note:** -If you cannot find the Container Registry entry under your project's settings, -that means that it is not enabled in your GitLab instance. Ask your administrator -to enable it. - -1. First, ask your system administrator to enable GitLab Container Registry - following the [administration documentation](../../administration/container_registry.md). - If you are using GitLab.com, this is enabled by default so you can start using - the Registry immediately. Currently there is a soft (10GB) size restriction for - registry on GitLab.com, as part of the [repository size limit](repository/index.html#repository-size). -1. Go to your [project's General settings](settings/index.md#sharing-and-permissions) +If you cannot find the **Packages > Container Registry** entry under your +project's sidebar, it is not enabled in your GitLab instance. Ask your +administrator to enable GitLab Container Registry following the +[administration documentation](../../administration/container_registry.md). + +If you are using GitLab.com, this is enabled by default so you can start using +the Registry immediately. Currently there is a soft (10GB) size restriction for +registry on GitLab.com, as part of the [repository size limit](repository/index.md). + +Once enabled for your GitLab instance, to enable Container Registry for your +project: + +1. Go to your project's **Settings > General** page. +1. Expand the **Visibility, project features, permissions** section and enable the **Container Registry** feature on your project. For new projects this might be enabled by default. For existing projects (prior GitLab 8.8), you will have to explicitly enable it. -1. Hit **Save changes** for the changes to take effect. You should now be able - to see the **Registry** link in the sidebar. - - +1. Press **Save changes** for the changes to take effect. You should now be able + to see the **Packages > Container Registry** link in the sidebar. ## Build and push images @@ -49,14 +49,14 @@ to enable it. > - To move or rename a repository with a container registry you will have to > delete all existing images. -If you visit the **Registry** link under your project's menu, you can see the -explicit instructions to login to the Container Registry using your GitLab -credentials. +If you visit the **Packages > Container Registry** link under your project's +menu, you can see the explicit instructions to login to the Container Registry +using your GitLab credentials. For example if the Registry's URL is `registry.example.com`, then you should be able to login with: -``` +```sh docker login registry.example.com ``` @@ -64,14 +64,14 @@ Building and publishing images should be a straightforward process. Just make sure that you are using the Registry URL with the namespace and project name that is hosted on GitLab: -``` +```sh docker build -t registry.example.com/group/project/image . docker push registry.example.com/group/project/image ``` Your image will be named after the following scheme: -``` +```text <registry URL>/<namespace>/<project>/<image> ``` @@ -79,7 +79,7 @@ GitLab supports up to three levels of image repository names. Following examples of image tags are valid: -``` +```text registry.example.com/group/project:some-tag registry.example.com/group/project/image:latest registry.example.com/group/project/my/image:rc1 @@ -90,7 +90,7 @@ registry.example.com/group/project/my/image:rc1 To download and run a container from images hosted in GitLab Container Registry, use `docker run`: -``` +```sh docker run [options] registry.example.com/group/project/image [arguments] ``` @@ -100,7 +100,7 @@ For more information on running Docker containers, visit the ## Control Container Registry from within GitLab GitLab offers a simple Container Registry management panel. Go to your project -and click **Registry** in the project menu. +and click **Packages > Container Registry** in the project menu. This view will show you all tags in your project and will easily allow you to delete them. @@ -113,6 +113,7 @@ This feature requires GitLab 8.8 and GitLab Runner 1.2. Make sure that your GitLab Runner is configured to allow building Docker images by following the [Using Docker Build](../../ci/docker/using_docker_build.md) and [Using the GitLab Container Registry documentation](../../ci/docker/using_docker_build.md#using-the-gitlab-container-registry). +Alternatively, you can [build images with Kaniko](../../ci/docker/using_kaniko.md) if the Docker builds are not an option for you. ## Using with private projects @@ -167,9 +168,23 @@ curl localhost:5001/debug/health curl localhost:5001/debug/vars ``` +#### Docker connection error + +A Docker connection error can occur when there are special characters in either the group, +project or branch name. Special characters can include: + +- Leading underscore +- Trailing hyphen/dash +- Double hyphen/dash + +To get around this, you can [change the group path](../group/index.md#changing-a-groups-path), +[change the project path](../project/settings/index.md#renaming-a-repository) or chanage the branch +name. + ### Advanced Troubleshooting ->**NOTE:** The following section is only recommended for experts. +NOTE: **Note:** +The following section is only recommended for experts. Sometimes it's not obvious what is wrong, and you may need to dive deeper into the communication between the Docker client and the Registry to find out @@ -181,7 +196,7 @@ diagnose a problem with the S3 setup. A user attempted to enable an S3-backed Registry. The `docker login` step went fine. However, when pushing an image, the output showed: -``` +```text The push refers to a repository [s3-testing.myregistry.com:4567/root/docker-test/docker-image] dc5e59c14160: Pushing [==================================================>] 14.85 kB 03c20c1a019a: Pushing [==================================================>] 2.048 kB @@ -204,7 +219,7 @@ at the communication between the client and the Registry. The REST API between the Docker client and Registry is [described here](https://docs.docker.com/registry/spec/api/). Normally, one would just use Wireshark or tcpdump to capture the traffic and see where things went -wrong. However, since all communications between Docker clients and servers +wrong. However, since all communications between Docker clients and servers are done over HTTPS, it's a bit difficult to decrypt the traffic quickly even if you know the private key. What can we do instead? @@ -227,10 +242,10 @@ The following installation instructions assume you are running Ubuntu: Enter <kbd>CTRL</kbd>-<kbd>C</kbd> to quit. 1. Install the certificate from `~/.mitmproxy` to your system: - ```sh - sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt - sudo update-ca-certificates - ``` + ```sh + sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt + sudo update-ca-certificates + ``` If successful, the output should indicate that a certificate was added: diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index dc97a44fd68..87577c9ec88 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -1,161 +1,5 @@ -# Cycle Analytics - -Cycle Analytics measures the time spent to go from an [idea to production] - also known -as cycle time - for each of your projects. Cycle Analytics displays the median time for an idea to -reach production, along with the time typically spent in each DevOps stage along the way. - -Cycle Analytics is useful in order to quickly determine the velocity of a given -project. It points to bottlenecks in the development process, enabling management -to uncover, triage, and root-cause slowdowns in the software development life cycle. - -Cycle Analytics is tightly coupled with the [GitLab flow] and -calculates a separate median for each stage. - -## Overview - -You can find the Cycle Analytics page under your project's **Project ➔ Cycle -Analytics** tab. - - - -There are seven stages that are tracked as part of the Cycle Analytics calculations. - -- **Issue** (Tracker) - - Time to schedule an issue (by milestone or by adding it to an issue board) -- **Plan** (Board) - - Time to first commit -- **Code** (IDE) - - Time to create a merge request -- **Test** (CI) - - Time it takes GitLab CI/CD to test your code -- **Review** (Merge Request/MR) - - Time spent on code review -- **Staging** (Continuous Deployment) - - Time between merging and deploying to production -- **Production** (Total) - - Total lifecycle time; i.e. the velocity of the project or team - -## How the data is measured - -Cycle Analytics records cycle time and data based on the project issues with the -exception of the staging and production stages, where only data deployed to -production are measured. - -Specifically, if your CI is not set up and you have not defined a `production` -or `production/*` [environment], then you will not have any data for those stages. - -Below you can see in more detail what the various stages of Cycle Analytics mean. - -| **Stage** | **Description** | -| --------- | --------------- | -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list][board] created for it. | -| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | -| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern] to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the issue closing pattern is not present in the merge request description, the MR is not considered to the measurement time of the stage. | -| Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | -| Review | Measures the median time taken to review the merge request that has closing issue pattern, between its creation and until it's merged. | -| Staging | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the [environment] set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. | -| Production| The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. | - +--- +redirect_to: '../analytics/cycle_analytics.md' --- -Here's a little explanation of how this works behind the scenes: - -1. Issues and merge requests are grouped together in pairs, such that for each - `<issue, merge request>` pair, the merge request has the [issue closing pattern] - for the corresponding issue. All other issues and merge requests are **not** - considered. -1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified - by the UI - default is 90 days). So it prohibits these pairs from being considered. -1. For the remaining `<issue, merge request>` pairs, we check the information that - we need for the stages, like issue creation date, merge request merge time, - etc. - -To sum up, anything that doesn't follow the [GitLab flow] won't be tracked at all. -So, the Cycle Analytics dashboard won't present any data: - -- For merge requests that do not close an issue. -- For issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. -- For staging and production stages, if the project has no `production` or `production/*` - environment. - -## Example workflow - -Below is a simple fictional workflow of a single cycle that happens in a -single day passing through all seven stages. Note that if a stage does not have -a start and a stop mark, it is not measured and hence not calculated in the median -time. It is assumed that milestones are created and CI for testing and setting -environments is configured. - -1. Issue is created at 09:00 (start of **Issue** stage). -1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of - **Plan** stage). -1. Start working on the issue, create a branch locally and make one commit at - 12:00. -1. Make a second commit to the branch which mentions the issue number at 12.30 - (stop of **Plan** stage / start of **Code** stage). -1. Push branch and create a merge request that contains the [issue closing pattern] - in its description at 14:00 (stop of **Code** stage / start of **Test** and - **Review** stages). -1. The CI starts running your scripts defined in [`.gitlab-ci.yml`][yml] and - takes 5min (stop of **Test** stage). -1. Review merge request, ensure that everything is OK and merge the merge - request at 19:00. (stop of **Review** stage / start of **Staging** stage). -1. Now that the merge request is merged, a deployment to the `production` - environment starts and finishes at 19:30 (stop of **Staging** stage). -1. The cycle completes and the sum of the median times of the previous stages - is recorded to the **Production** stage. That is the time between creating an - issue and deploying its relevant merge request to production. - -From the above example you can conclude the time it took each stage to complete -as long as their total time: - -- **Issue**: 2h (11:00 - 09:00) -- **Plan**: 1h (12:00 - 11:00) -- **Code**: 2h (14:00 - 12:00) -- **Test**: 5min -- **Review**: 5h (19:00 - 14:00) -- **Staging**: 30min (19:30 - 19:00) -- **Production**: Since this stage measures the sum of median time off all - previous stages, we cannot calculate it if we don't know the status of the - stages before. In case this is the very first cycle that is run in the project, - then the **Production** time is 10h 30min (19:30 - 09:00) - -A few notes: - -- In the above example we demonstrated that it doesn't matter if your first - commit doesn't mention the issue number, you can do this later in any commit - of the branch you are working on. -- You can see that the **Test** stage is not calculated to the overall time of - the cycle since it is included in the **Review** process (every MR should be - tested). -- The example above was just **one cycle** of the seven stages. Add multiple - cycles, calculate their median time and the result is what the dashboard of - Cycle Analytics is showing. - -## Permissions - -The current permissions on the Cycle Analytics dashboard are: - -- Public projects - anyone can access -- Internal projects - any authenticated user can access -- Private projects - any member Guest and above can access - -You can [read more about permissions][permissions] in general. - -## More resources - -Learn more about Cycle Analytics in the following resources: - -- [Cycle Analytics feature page](https://about.gitlab.com/features/cycle-analytics/) -- [Cycle Analytics feature preview](https://about.gitlab.com/2016/09/16/feature-preview-introducing-cycle-analytics/) -- [Cycle Analytics feature highlight](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/) - -[board]: issue_board.md#creating-a-new-list -[ce-5986]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5986 -[ce-20975]: https://gitlab.com/gitlab-org/gitlab-ce/issues/20975 -[environment]: ../../ci/yaml/README.md#environment -[GitLab flow]: ../../workflow/gitlab_flow.md -[idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab -[issue closing pattern]: issues/automatic_issue_closing.md -[permissions]: ../permissions.md -[yml]: ../../ci/yaml/README.md +This document was moved to [another location](../analytics/cycle_analytics.md) diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 2f2a9c5eec3..0a83f2e894a 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,4 +1,4 @@ -# Deploy Boards **[PREMIUM]** +# Deploy Boards **(PREMIUM)** > [Introduced][ee-1589] in [GitLab Premium][ee] 9.0. @@ -59,14 +59,16 @@ specific environment, there are lot of uses cases. To name a few: To display the Deploy Boards for a specific [environment] you should: +1. Have [defined an environment](../../ci/environments.md#defining-environments) with a deploy stage. + 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). + 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. @@ -86,22 +88,18 @@ To display the Deploy Boards for a specific [environment] you should: Kubernetes. NOTE: **Note:** - The Kubernetes label of `app` is deprecated and may be removed in next major - release, GitLab 12.0. + Matching based on the Kubernetes `app` label was removed in [GitLab + 12.1](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/14020). + To migrate, please apply the required annotations (see above) and + re-deploy your application. -  +  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 @@ -127,6 +125,6 @@ version of your application. [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" +[autodeploy]: ../../topics/autodevops/index.md#auto-deploy "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/deploy_tokens/img/deploy_tokens.png b/doc/user/project/deploy_tokens/img/deploy_tokens.png Binary files differindex 55c537fd1d3..493de8e0fce 100644 --- a/doc/user/project/deploy_tokens/img/deploy_tokens.png +++ b/doc/user/project/deploy_tokens/img/deploy_tokens.png diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 92a29b68a22..164d1dddff0 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -15,7 +15,7 @@ You can create as many deploy tokens as you like from the settings of your proje 1. Go to the project you want to create Deploy Tokens for. 1. Go to **Settings** > **Repository**. 1. Click on "Expand" on **Deploy Tokens** section. -1. Choose a name and optionally an expiry date for the token. +1. Choose a name, expiry date (optional), and username (optional) for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Click on **Create deploy token**. 1. Save the deploy token somewhere safe. Once you leave or refresh @@ -39,6 +39,13 @@ the following table. | `read_repository` | Allows read-access to the repository through `git clone` | | `read_registry` | Allows read-access to [container registry] images if a project is private and authorization is required. | +## Deploy token custom username + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29639) in GitLab 12.1. + +The default username format is `gitlab+deploy-token-#{n}`. Some tools or platforms may not support this format, +in such case you can specify custom username to be used when creating the deploy token. + ## Usage ### Git clone a repository @@ -49,9 +56,9 @@ To download a repository using a Deploy Token, you just need to: 1. Take note of your `username` and `token`. 1. `git clone` the project using the Deploy Token: - ```sh - git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git - ``` + ```sh + git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git + ``` Replace `<username>` and `<deploy_token>` with the proper values. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 05ad15476ab..f53dc056010 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -25,14 +25,14 @@ 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. + 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. + 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. + stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc. ## Creating issue templates @@ -55,9 +55,10 @@ changes you made after picking the template and return it to its initial status.  -## Setting a default template for issues and merge requests **[STARTER]** +## Setting a default template for merge requests and issues **(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. @@ -65,20 +66,20 @@ changes you made after picking the template and return it to its initial status. > - 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 +with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, 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 +Go to your project's **Settings** and under the **Merge requests** header, click *Expand* and fill in the "Default description template +for merge requests" text area. Under the **Default issue template**, click *Expand* and fill in "Default description template for issues" text area. Since GitLab merge request and issues + 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 +effect. Now, every time a new merge request or issue is created, it will be pre-filled with the text you entered in the template(s). ## Description template example diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 3386eb9d0d4..dce8c3a97bc 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,8 +1,6 @@ -# File Locking **[PREMIUM]** +# File Locking **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 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. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9. 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 @@ -30,12 +28,51 @@ The file locking feature is useful in situations when: Locked directories are locked recursively, which means that everything that lies under them is also locked. +## Locking a file or a directory + +NOTE: **Note:** +Locking only works for the default branch you have set in the project's settings +(usually `master`). + +To lock a file: + +1. Navigate to your project's **Repository > Files**. +1. Pick the file you want to lock. +1. Click 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. + + + +Once locked, any merge request to the default branch will fail +to merge until the file becomes unlocked. + +## 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". + +You can unlock a file that yourself or someone else previously locked as long +as you have Maintainer or above [permissions](../permissions.md) to the project. + +## 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). + ## 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](../../user/permissions.md) to the repository; i.e., +Locks can be created by any person who has [push access](../permissions.md) 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. @@ -61,41 +98,3 @@ 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). - - diff --git a/doc/user/project/img/autocomplete_characters_example1_v12_0.png b/doc/user/project/img/autocomplete_characters_example1_v12_0.png Binary files differnew file mode 100644 index 00000000000..9c6fa923b80 --- /dev/null +++ b/doc/user/project/img/autocomplete_characters_example1_v12_0.png diff --git a/doc/user/project/img/autocomplete_characters_example2_v12_0.png b/doc/user/project/img/autocomplete_characters_example2_v12_0.png Binary files differnew file mode 100644 index 00000000000..b2e8a782a0b --- /dev/null +++ b/doc/user/project/img/autocomplete_characters_example2_v12_0.png diff --git a/doc/user/project/img/container_registry.png b/doc/user/project/img/container_registry.png Binary files differdeleted file mode 100644 index abbaf838538..00000000000 --- a/doc/user/project/img/container_registry.png +++ /dev/null diff --git a/doc/user/project/img/cycle_analytics_landing_page.png b/doc/user/project/img/cycle_analytics_landing_page.png Binary files differdeleted file mode 100644 index cf46098b9a4..00000000000 --- a/doc/user/project/img/cycle_analytics_landing_page.png +++ /dev/null diff --git a/doc/user/project/img/deploy_boards_kubernetes_label.png b/doc/user/project/img/deploy_boards_kubernetes_label.png Binary files differindex 19785c74d07..130ff2caa8a 100644 --- a/doc/user/project/img/deploy_boards_kubernetes_label.png +++ b/doc/user/project/img/deploy_boards_kubernetes_label.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 differdeleted file mode 100644 index ab314e83d06..00000000000 --- a/doc/user/project/img/description_templates_default_settings.png +++ /dev/null diff --git a/doc/user/project/img/description_templates_issue_settings.png b/doc/user/project/img/description_templates_issue_settings.png Binary files differnew file mode 100644 index 00000000000..53328108835 --- /dev/null +++ b/doc/user/project/img/description_templates_issue_settings.png diff --git a/doc/user/project/img/description_templates_merge_request_settings.png b/doc/user/project/img/description_templates_merge_request_settings.png Binary files differnew file mode 100644 index 00000000000..eda264f7f37 --- /dev/null +++ b/doc/user/project/img/description_templates_merge_request_settings.png diff --git a/doc/user/project/img/file_lock.png b/doc/user/project/img/file_lock.png Binary files differindex 33f96f20e91..e881442630b 100644 --- a/doc/user/project/img/file_lock.png +++ 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 differdeleted file mode 100644 index 5ff3d4d9dbd..00000000000 --- a/doc/user/project/img/file_lock_folders.png +++ /dev/null diff --git a/doc/user/project/img/file_lock_list.png b/doc/user/project/img/file_lock_list.png Binary files differdeleted file mode 100644 index 2c276335c83..00000000000 --- a/doc/user/project/img/file_lock_list.png +++ /dev/null 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 differindex 65bc3692da0..64bcc86ac0d 100644 --- a/doc/user/project/img/file_lock_merge_request_error_message.png +++ 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 differindex 8f4ef52aacd..ced14198da9 100644 --- a/doc/user/project/img/file_lock_repository_view.png +++ b/doc/user/project/img/file_lock_repository_view.png diff --git a/doc/user/project/img/issue_boards_multiple.png b/doc/user/project/img/issue_boards_multiple.png Binary files differindex 4b1a8356dc9..e6183360610 100644 --- a/doc/user/project/img/issue_boards_multiple.png +++ b/doc/user/project/img/issue_boards_multiple.png diff --git a/doc/user/project/img/key_value_labels.png b/doc/user/project/img/key_value_labels.png Binary files differdeleted file mode 100644 index bec901f127f..00000000000 --- a/doc/user/project/img/key_value_labels.png +++ /dev/null diff --git a/doc/user/project/img/labels_default.png b/doc/user/project/img/labels_default.png Binary files differdeleted file mode 100644 index 221c5cf55a2..00000000000 --- a/doc/user/project/img/labels_default.png +++ /dev/null diff --git a/doc/user/project/img/labels_default_v12_1.png b/doc/user/project/img/labels_default_v12_1.png Binary files differnew file mode 100644 index 00000000000..b36b5dac80b --- /dev/null +++ b/doc/user/project/img/labels_default_v12_1.png diff --git a/doc/user/project/img/labels_delete_v12_1.png b/doc/user/project/img/labels_delete_v12_1.png Binary files differnew file mode 100644 index 00000000000..566e0519fbe --- /dev/null +++ b/doc/user/project/img/labels_delete_v12_1.png diff --git a/doc/user/project/img/labels_drag_priority_v12_1.gif b/doc/user/project/img/labels_drag_priority_v12_1.gif Binary files differnew file mode 100644 index 00000000000..a568490da5f --- /dev/null +++ b/doc/user/project/img/labels_drag_priority_v12_1.gif diff --git a/doc/user/project/img/labels_epic_sidebar.png b/doc/user/project/img/labels_epic_sidebar.png Binary files differdeleted file mode 100644 index f8162d89e9d..00000000000 --- a/doc/user/project/img/labels_epic_sidebar.png +++ /dev/null diff --git a/doc/user/project/img/labels_epic_sidebar_v12_1.png b/doc/user/project/img/labels_epic_sidebar_v12_1.png Binary files differnew file mode 100644 index 00000000000..13fbab33e26 --- /dev/null +++ b/doc/user/project/img/labels_epic_sidebar_v12_1.png diff --git a/doc/user/project/img/labels_generate_default.png b/doc/user/project/img/labels_generate_default.png Binary files differdeleted file mode 100644 index 982a4df999c..00000000000 --- a/doc/user/project/img/labels_generate_default.png +++ /dev/null diff --git a/doc/user/project/img/labels_generate_default_v12_1.png b/doc/user/project/img/labels_generate_default_v12_1.png Binary files differnew file mode 100644 index 00000000000..cbdda2ab4dd --- /dev/null +++ b/doc/user/project/img/labels_generate_default_v12_1.png diff --git a/doc/user/project/img/labels_group_issues.png b/doc/user/project/img/labels_group_issues.png Binary files differdeleted file mode 100644 index cea1d304d31..00000000000 --- a/doc/user/project/img/labels_group_issues.png +++ /dev/null diff --git a/doc/user/project/img/labels_group_issues_v12_1.png b/doc/user/project/img/labels_group_issues_v12_1.png Binary files differnew file mode 100644 index 00000000000..3f8f93c1dfd --- /dev/null +++ b/doc/user/project/img/labels_group_issues_v12_1.png diff --git a/doc/user/project/img/labels_key_value_v12_1.png b/doc/user/project/img/labels_key_value_v12_1.png Binary files differnew file mode 100644 index 00000000000..52906b7b458 --- /dev/null +++ b/doc/user/project/img/labels_key_value_v12_1.png diff --git a/doc/user/project/img/labels_list.png b/doc/user/project/img/labels_list.png Binary files differdeleted file mode 100644 index 6940dde68bf..00000000000 --- a/doc/user/project/img/labels_list.png +++ /dev/null diff --git a/doc/user/project/img/labels_list_v12_1.png b/doc/user/project/img/labels_list_v12_1.png Binary files differnew file mode 100644 index 00000000000..47359d05f7f --- /dev/null +++ b/doc/user/project/img/labels_list_v12_1.png diff --git a/doc/user/project/img/new_label_from_sidebar.gif b/doc/user/project/img/labels_new_label_from_sidebar.gif Binary files differindex 572b29a86e1..572b29a86e1 100644 --- a/doc/user/project/img/new_label_from_sidebar.gif +++ b/doc/user/project/img/labels_new_label_from_sidebar.gif diff --git a/doc/user/project/img/labels_prioritized.png b/doc/user/project/img/labels_prioritized.png Binary files differdeleted file mode 100644 index 7ce2d08b38c..00000000000 --- a/doc/user/project/img/labels_prioritized.png +++ /dev/null diff --git a/doc/user/project/img/labels_prioritized_v12_1.png b/doc/user/project/img/labels_prioritized_v12_1.png Binary files differnew file mode 100644 index 00000000000..512c5d59a5a --- /dev/null +++ b/doc/user/project/img/labels_prioritized_v12_1.png diff --git a/doc/user/project/img/labels_promotion.png b/doc/user/project/img/labels_promotion.png Binary files differdeleted file mode 100644 index 762a3773692..00000000000 --- a/doc/user/project/img/labels_promotion.png +++ /dev/null diff --git a/doc/user/project/img/labels_promotion_v12_1.png b/doc/user/project/img/labels_promotion_v12_1.png Binary files differnew file mode 100644 index 00000000000..7cd8ff24e02 --- /dev/null +++ b/doc/user/project/img/labels_promotion_v12_1.png diff --git a/doc/user/project/img/labels_subscriptions.png b/doc/user/project/img/labels_subscriptions.png Binary files differdeleted file mode 100644 index f3c4235d051..00000000000 --- a/doc/user/project/img/labels_subscriptions.png +++ /dev/null diff --git a/doc/user/project/img/labels_subscriptions_v12_1.png b/doc/user/project/img/labels_subscriptions_v12_1.png Binary files differnew file mode 100644 index 00000000000..fa83b7db414 --- /dev/null +++ b/doc/user/project/img/labels_subscriptions_v12_1.png diff --git a/doc/user/project/img/service_desk_disabled.png b/doc/user/project/img/service_desk_disabled.png Binary files differindex 3ae64dcbe96..edae7e76986 100644 --- a/doc/user/project/img/service_desk_disabled.png +++ 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 differindex 329348e4b52..9c143ff58cd 100644 --- a/doc/user/project/img/service_desk_enabled.png +++ 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 differindex 485751fab0a..02d18c9debb 100644 --- a/doc/user/project/img/service_desk_issue_tracker.png +++ b/doc/user/project/img/service_desk_issue_tracker.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 1cc3bd3363d..e509e333313 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -31,12 +31,12 @@ to enable this if not already. ## How it works When issues/pull requests are being imported, the Bitbucket importer tries to find -the Bitbucket author/assignee in GitLab's database using the Bitbucket ID. For this -to work, the Bitbucket author/assignee should have signed in beforehand in GitLab -and **associated their Bitbucket account**. If the user is not -found in GitLab's database, the project creator (most of the times the current -user that started the import process) is set as the author, but a reference on -the issue about the original Bitbucket author is kept. +the Bitbucket author/assignee in GitLab's database using the Bitbucket `nickname`. +For this to work, the Bitbucket author/assignee should have signed in beforehand in GitLab +and **associated their Bitbucket account**. Their `nickname` must also match their Bitbucket +`username.`. If the user is not found in GitLab's database, the project creator +(most of the times the current user that started the import process) is set as the author, +but a reference on the issue about the original Bitbucket author is kept. The importer will create any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository will be imported under the user's @@ -49,17 +49,17 @@ namespace that started the import process. 1. Click on the "Bitbucket Cloud" button. -  +  1. Grant GitLab access to your Bitbucket account -  +  1. Click on the projects that you'd like to import or **Import all projects**. You can also select the namespace under which each project will be imported. -  +  [bb-import]: ../../../integration/bitbucket.md [social sign-in]: ../../profile/account/social_sign_in.md diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index d51a0c0ccca..28e211ee2ba 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -24,15 +24,16 @@ Import your projects from Bitbucket Server to GitLab with minimal effort. 1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds will be inserted as comments in the merge request. -1. Bitbucket Server allows multiple levels of threading. GitLab - import will collapse this into one discussion and quote part of the original - comment. +1. Bitbucket Server allows multiple levels of threading. GitLab import + will collapse this into one thread and quote part of the original comment. 1. Declined pull requests have unreachable commits, which prevents the GitLab importer from generating a proper diff. These pull requests will show up as empty changes. 1. Attachments in Markdown are currently not imported. 1. Task lists are not imported. 1. Emoji reactions are not imported +1. Project filtering does not support fuzzy search (only `starts with` or `full + match strings` are currently supported) ## How it works @@ -60,16 +61,16 @@ namespace that started the import process. 1. Sign in to GitLab and go to your dashboard. 1. Click on **New project**. 1. Click on the "Bitbucket Server" button. If the button is not present, enable the importer in - **Admin > Application Settings > Visibility and access controls > Import sources**. + **Admin > Application Settings > Visibility and access controls > Import sources**. -  +  1. Enter your Bitbucket Server credentials. -  +  1. Click on the projects that you'd like to import or **Import all projects**. - You can also select the namespace under which each project will be + You can also filter projects by name and select the namespace under which each project will be imported. -  +  diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 7f79ebf6353..cf48189fa6e 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -1,17 +1,21 @@ -# Gemnasium **[ULTIMATE]** +# 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) +Gemnasium was [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](../../application_security/sast/index.md), -[DAST](../../application_security/dast/index.md), -[Container Scanning](../../application_security/container_scanning/index.md) and more. +and is working on a [wide range of tools](../../application_security/index.md), +including: + +- [Dependency Scanning](../../application_security/dependency_scanning/index.md) +- [SAST](../../application_security/sast/index.md) +- [DAST](../../application_security/dast/index.md) +- [Container Scanning](../../application_security/container_scanning/index.md) + If you want to continue monitoring your dependencies, see the [Migrating to GitLab](#migrating-to-gitlab) section below. @@ -40,14 +44,14 @@ 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) +### 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](../../application_security/dependency_scanning/index.md). -### If your project is hosted on GitHub (https://github.com / GitHub Enterprise) +### 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 @@ -57,27 +61,27 @@ 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. + 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. + 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). + 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 @@ -85,16 +89,16 @@ back to both GitLab and GitHub when completed. 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 diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index e194d57e2e0..cdb7f837158 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -121,10 +121,10 @@ Depending your GitLab tier, [project mirroring](../../../workflow/repository_mir your imported project in sync with its GitHub copy. Additionally, you can configure GitLab to send pipeline status updates back GitHub with the -[GitHub Project Integration](../integrations/github.md). **[PREMIUM]** +[GitHub Project Integration](../integrations/github.md). **(PREMIUM)** If you import your project using [CI/CD for external repo](../../../ci/ci_cd_for_external_repos/index.md), then both -of the above are automatically configured. **[PREMIUM]** +of the above are automatically configured. **(PREMIUM)** ## Improving the speed of imports on self-hosted instances diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index f48a158e2d3..2f87f257754 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -1,21 +1,21 @@ # Project importing from GitLab.com to your private GitLab instance -You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if -GitLab.com integration is enabled on your GitLab instance. +You can import your existing GitLab.com projects to your GitLab instance, but keep in +mind that it is possible only if GitLab.com integration is enabled on your GitLab instance. [Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). To get to the importer page you need to go to "New project" page. >**Note:** -If you are interested in importing Wiki and Merge Request data to your new -instance, you'll need to follow the instructions for [project export](../settings/import_export.md) +If you are interested in importing Wiki and Merge Request data to your new instance, +you'll need to follow the instructions for [exporting a project](../settings/import_export.md#exporting-a-project-and-its-data) - + -Click on the "Import projects from GitLab.com" link and you will be redirected to GitLab.com +Go to the **Import Projects** tab, then click on **GitLab.com**, and you will be redirected to GitLab.com for permission to access your projects. After accepting, you'll be automatically redirected to the importer.  -To import a project, you can simple click "Import". The importer will import your repository and issues. +To import a project, click "Import". The importer will import your repository and issues. Once the importer is done, a new GitLab project will be created with your imported data. diff --git a/doc/user/project/import/img/bitbucket_server_import_select_project.png b/doc/user/project/import/img/bitbucket_server_import_select_project.png Binary files differdeleted file mode 100644 index e7fddef9955..00000000000 --- a/doc/user/project/import/img/bitbucket_server_import_select_project.png +++ /dev/null diff --git a/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png b/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png Binary files differnew file mode 100644 index 00000000000..1c344853cc8 --- /dev/null +++ b/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png diff --git a/doc/user/project/import/img/gitlab_new_project_page.png b/doc/user/project/import/img/gitlab_new_project_page.png Binary files differdeleted file mode 100644 index c673724f436..00000000000 --- a/doc/user/project/import/img/gitlab_new_project_page.png +++ /dev/null diff --git a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png Binary files differnew file mode 100644 index 00000000000..e79c27f32c0 --- /dev/null +++ b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 2b6927bd780..ecd491d8e5b 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -10,7 +10,7 @@ 1. [From Gitea](gitea.md) 1. [From Perforce](perforce.md) 1. [From SVN](svn.md) -1. [From TFS](tfs.md) +1. [From TFVC](tfvc.md) 1. [From repo by URL](repo_by_url.md) 1. [By uploading a manifest file (AOSP)](manifest.md) 1. [From Gemnasium](gemnasium.md) @@ -20,7 +20,7 @@ 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](../../../ci/ci_cd_for_external_repos/index.md). **[PREMIUM]** +There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** ## Migrating from self-hosted GitLab to GitLab.com @@ -34,7 +34,7 @@ This approach assumes all users from the self-hosted instance have already been If the users haven't been migrated yet, the user conducting the import will take the place of all references to the missing user(s). -If you need to migrate all data over, you can leverage our [api](../../../api/README.md) to migrate from self-hosted to GitLab.com. +If you need to migrate all data over, you can leverage our [api](../../../api/README.md) to migrate from self-hosted to GitLab.com. The order of assets to migrate from a self-hosted instance to GitLab is the following: 1. [Users](../../../api/users.md) @@ -54,5 +54,5 @@ perhaps from an old server to a new server for example, is to [back up the project](../../../raketasks/backup_restore.md), then restore it on the new server. -In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), +In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), refer to the instructions in [Migrating from self-hosted GitLab to GitLab.com](#migrating-from-self-hosted-gitlab-to-gitlabcom). diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index baf410d9c9e..161a4163e42 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -1,7 +1,6 @@ # Import multiple repositories by uploading a manifest file -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28811) in -GitLab 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28811) in GitLab 11.2. GitLab allows you to import all the required Git repositories based on a manifest file like the one used by the @@ -56,4 +55,4 @@ You can start the import with: to the import status page with projects list based on the manifest file. 1. Check the list and click **Import all repositories** to start the import. -  +  diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 5c624e3aff6..b8f89caba24 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -15,6 +15,12 @@ Currently, only the following basic fields are imported: - Created at - Closed at +## Users + +The assignee and author of a user are deducted from a Task's owner and +author: If a user with the same username has access to the namespace +of the project being imported into, then the user will be linked. + ## Enabling this feature While this feature is incomplete, a feature flag is required to enable it so that diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 4825b005a85..d175ee87f26 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -9,13 +9,13 @@ between the two, for more information consult your favorite search engine. There are two approaches to SVN to Git migration: 1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: - - Makes the GitLab repository to mirror the SVN project. - - Git and SVN repositories are kept in sync; you can use either one. - - Smoothens the migration process and allows to manage migration risks. + - Makes the GitLab repository to mirror the SVN project. + - Git and SVN repositories are kept in sync; you can use either one. + - Smoothens the migration process and allows to manage migration risks. 1. [Cut over migration](#cut-over-migration-with-svn2git) which: - - Translates and imports the existing data and history from SVN to Git. - - Is a fire and forget approach, good for smaller teams. + - Translates and imports the existing data and history from SVN to Git. + - Is a fire and forget approach, good for smaller teams. ## Smooth migration with a Git/SVN mirror using SubGit @@ -29,7 +29,7 @@ directly in a filesystem level. 1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). -1. Download SubGit from <https://subgit.com/download/>. +1. Download SubGit from <https://subgit.com/download>. 1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` command will be available at `/opt/subgit-VERSION/bin/subgit`. diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md index 8727c2ff6c3..7b3b11b9519 100644 --- a/doc/user/project/import/tfs.md +++ b/doc/user/project/import/tfs.md @@ -1,42 +1,5 @@ -# Migrating from TFS +--- +redirect_to: 'tfvc.md' +--- -[TFS](https://www.visualstudio.com/tfs/) is a set of tools developed by Microsoft -which also includes a centralized version control system (TFVC) similar to Git. - -In this document, we emphasize on the TFVC to Git migration. - -## TFVC vs Git - -The following list illustrates the main differences between TFVC and Git: - -- **Git is distributed** whereas TFVC is centralized using a client-server - architecture. This translates to Git having a more flexible workflow since - your working area is a copy of the entire repository. This decreases the - overhead when switching branches or merging for example, since you don't have - to communicate with a remote server. -- **Storage method.** Changes in CVS are per file (changeset), while in Git - a committed file(s) is stored in its entirety (snapshot). That means that's - very easy in Git to revert or undo a whole change. - -_Check also Microsoft's documentation on the -[comparison of Git and TFVC](https://www.visualstudio.com/en-us/docs/tfvc/comparison-git-tfvc) -and the Wikipedia article on -[comparing the different version control software](https://en.wikipedia.org/wiki/Comparison_of_version_control_software)._ - -## Why migrate - -Migrating to Git/GitLab there is: - -- **No licensing costs**, Git is GPL while TFVC is proprietary. -- **Shorter learning curve**, Git has a big community and a vast number of - tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). -- **Integration with modern tools**, migrating to Git and GitLab you can have - an open source end-to-end software development platform with built-in version - control, issue tracking, code review, CI/CD, and more. - -## How to migrate - -The best option to migrate from TFVC to Git is to use the -[`git-tfs`](https://github.com/git-tfs/git-tfs) tool. A specific guide for the -migration exists: -[Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md). +This document was moved to [another location](tfvc.md). diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md new file mode 100644 index 00000000000..375522b77d0 --- /dev/null +++ b/doc/user/project/import/tfvc.md @@ -0,0 +1,46 @@ +--- +type: concepts +--- + +# Migrating from TFVC to Git + +Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) +in 2019, is a set of tools developed by Microsoft which also includes +[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/overview) +(TFVC), a centralized version control system similar to Git. + +In this document, we focus on the TFVC to Git migration. + +## TFVC vs Git + +The main differences between TFVC and Git are: + +- **Git is distributed:** While TFVC is centralized using a client-server architecture, + Git is distributed. This translates to Git having a more flexible workflow since + you work with a copy of the entire repository. This allows you to quickly + switch branches or merge, for example, without needing to communicate with a remote server. +- **Storage:** Changes in a centralized version control system are per file (changeset), + while in Git a committed file is stored in its entirety (snapshot). That means that it is + very easy to revert or undo a whole change in Git. + +For more information, see: + +- Microsoft's [comparison of Git and TFVC](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/comparison-git-tfvc?view=azure-devops). +- The Wikipedia [comparison of version control software](https://en.wikipedia.org/wiki/Comparison_of_version_control_software). + +## Why migrate + +Advantages of migrating to Git/GitLab: + +- **No licensing costs:** Git is open source, while TFVC is proprietary. +- **Shorter learning curve:** Git has a big community and a vast number of + tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). +- **Integration with modern tools:** After migrating to Git and GitLab, you will have + an open source, end-to-end software development platform with built-in version + control, issue tracking, code review, CI/CD, and more. + +## How to migrate + +The best option to migrate from TFVC to Git is to use the [`git-tfs`](https://github.com/git-tfs/git-tfs) +tool. Read the [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) +guide for more details. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 587b4121e4e..30ff0e9ff07 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -17,7 +17,7 @@ When you create a project in GitLab, you'll have access to a large number of - [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]** + - [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)** - [Repositories](repository/index.md): Host your code in a fully integrated platform - [Branches](repository/branches/index.md): use Git branching strategies to @@ -34,11 +34,11 @@ When you create a project in GitLab, you'll have access to a large number of - [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]** + - [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](merge_requests/merge_request_approvals.md): Ask for approval before - implementing a change **[STARTER]** + implementing a change **(STARTER)** - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): Your Git diff tool right from GitLab's UI - [Review Apps](../../ci/review_apps/index.md): Live preview the results @@ -52,6 +52,9 @@ When you create a project in GitLab, you'll have access to a large number of templates for issue and merge request description fields for your project - [Slash commands (quick actions)](quick_actions.md): Textual shortcuts for common actions on issues or merge requests +- [Autocomplete characters](autocomplete_characters.md): Autocomplete + references to users, groups, issues, merge requests, and other GitLab + elements. - [Web IDE](web_ide/index.md) **GitLab CI/CD:** @@ -63,19 +66,19 @@ When you create a project in GitLab, you'll have access to a large number of to automatically set up your app's deployment - [Enable and disable GitLab CI](../../ci/enable_or_disable_ci.md) - [Pipelines](../../ci/pipelines.md): Configure and visualize - your GitLab CI/CD pipelines from the UI - - [Scheduled Pipelines](pipelines/schedules.md): Schedule a pipeline - to start at a chosen time - - [Pipeline Graphs](../../ci/pipelines.md#visualizing-pipelines): View your - entire pipeline from the UI - - [Job artifacts](pipelines/job_artifacts.md): Define, - browse, and download job artifacts - - [Pipeline settings](pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job), - 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 + your GitLab CI/CD pipelines from the UI + - [Scheduled Pipelines](pipelines/schedules.md): Schedule a pipeline + to start at a chosen time + - [Pipeline Graphs](../../ci/pipelines.md#visualizing-pipelines): View your + entire pipeline from the UI + - [Job artifacts](pipelines/job_artifacts.md): Define, + browse, and download job artifacts + - [Pipeline settings](pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job), + 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](operations/feature_flags.md): Feature flags allow you to ship a project in - different flavors by dynamically toggling certain functionality **[PREMIUM]** + different flavors by dynamically toggling certain functionality **(PREMIUM)** - [GitLab Pages](pages/index.md): Build, test, and deploy your static website with GitLab Pages @@ -84,18 +87,19 @@ 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. -- [Insights](insights/index.md): configure the Insights that matter for your projects. **[ULTIMATE]** -- [Security Dashboard](security_dashboard.md): Security Dashboard. **[ULTIMATE]** +- [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)** +- [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](packages/maven_repository.md): your private Maven repository in GitLab. **[PREMIUM]** -- [NPM packages](packages/npm_registry.md): your private NPM package registry in GitLab. **[PREMIUM]** -- [Code owners](code_owners.md): specify code owners for certain files **[STARTER]** -- [License Management](../application_security/license_management/index.md): approve and blacklist licenses for projects. **[ULTIMATE]** +- [Maven packages](packages/maven_repository.md): your private Maven repository in GitLab. **(PREMIUM)** +- [NPM packages](packages/npm_registry.md): your private NPM package registry in GitLab. **(PREMIUM)** +- [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** +- [License Management](../application_security/license_management/index.md): approve and blacklist licenses for projects. **(ULTIMATE)** +- [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** ### Project integrations @@ -131,7 +135,7 @@ 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]** +## CI/CD for external repositories **(PREMIUM)** Instead of importing a repository directly to GitLab, you can connect your repository as a CI/CD project. @@ -193,13 +197,35 @@ password <personal_access_token> To quickly access a project from the GitLab UI using the project ID, visit the `/projects/:id` URL in your browser or other tool accessing the project. +## Project aliases **(PREMIUM ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. + +When migrating repositories to GitLab and they are being accessed by other systems, +it's very useful to be able to access them using the same name especially when +they are a lot. It reduces the risk of changing significant number of Git URLs in +a large number of systems. + +GitLab provides a functionality to help with this. In GitLab, repositories are +usually accessed with a namespace and project name. It is also possible to access +them via a project alias. This feature is only available on Git over SSH. + +A project alias can be only created via API and only by GitLab administrators. +Follow the [Project Aliases API documentation](../../api/project_aliases.md) for +more details. + +Once an alias has been created for a project (e.g., an alias `gitlab-ce` for the +project `https://gitlab.com/gitlab-org/gitlab-ce`), the repository can be cloned +using the alias (e.g `git clone git@gitlab.com:gitlab-ce.git` instead of +`git clone git@gitlab.com:gitlab-org/gitlab-ce.git`). + ## Project APIs There are numerous [APIs](../../api/README.md) to use with your projects: - [Badges](../../api/project_badges.md) - [Clusters](../../api/project_clusters.md) -- [Discussions](../../api/discussions.md) +- [Threads](../../api/discussions.md) - [General](../../api/projects.md) - [Import/export](../../api/project_import_export.md) - [Issue Board](../../api/boards.md) @@ -212,3 +238,4 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Templates](../../api/project_templates.md) - [Traffic](../../api/project_statistics.md) - [Variables](../../api/project_level_variables.md) +- [Aliases](../../api/project_aliases.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 differindex eb96eb4a90f..5fd24265b32 100644 --- a/doc/user/project/insights/img/insights_example_bar_chart.png +++ 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 differindex 28aa81939d8..2e32df3e2b1 100644 --- 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 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 differindex 131dbedd35e..9460b104339 100644 --- a/doc/user/project/insights/img/insights_example_line_chart.png +++ 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 differindex 518ed7338f9..3480bce6738 100644 --- a/doc/user/project/insights/img/insights_example_pie_chart.png +++ 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 differindex aafec4b394e..a3fb50488f5 100644 --- a/doc/user/project/insights/img/insights_example_stacked_bar_chart.png +++ b/doc/user/project/insights/img/insights_example_stacked_bar_chart.png diff --git a/doc/user/project/insights/img/insights_sidebar_link.png b/doc/user/project/insights/img/insights_sidebar_link.png Binary files differindex aadb5745992..9fc449baf68 100644 --- a/doc/user/project/insights/img/insights_sidebar_link.png +++ b/doc/user/project/insights/img/insights_sidebar_link.png diff --git a/doc/user/project/insights/img/project_insights.png b/doc/user/project/insights/img/project_insights.png Binary files differindex 2d0292dda54..83674c94110 100644 --- a/doc/user/project/insights/img/project_insights.png +++ 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 index 2e2a27f112e..76a6a96eec5 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,7 +1,6 @@ -# Insights **[ULTIMATE]** +# Insights **(ULTIMATE)** -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag. -> **Generally Available** (GA) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. 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 diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 23f1ce7a15a..7c7263704f9 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -17,6 +17,6 @@ Once you have configured and enabled Custom Issue Tracker Service you'll see a l ## Referencing issues -- Issues are referenced with `ANYTHING-<ID>`, where `ANYTHING` can be any string and `<ID>` is a number used in the target project of the custom integration (example `PROJECT-143`). +- Issues are referenced with `ANYTHING-<ID>`, where `ANYTHING` can be any string and `<ID>` is a number used in the target project of the custom integration (example `PROJECT-143`). - `ANYTHING` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. -- So with the example above, `PROJECT-143` would refer to `https://customissuetracker.com/project-name/143`.
\ No newline at end of file +- So with the example above, `PROJECT-143` would refer to `https://customissuetracker.com/project-name/143`. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index cdb0e34fdf6..d0399f9193b 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,4 +1,4 @@ -# GitHub project integration **[PREMIUM]** +# GitHub project integration **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3836) in GitLab Premium 10.6. @@ -14,10 +14,10 @@ and is automatically configured on [GitHub import](../../../integration/github.m ### Complete these steps on GitHub -This integration requires a [GitHub API token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) +This integration requires a [GitHub API token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) with `repo:status` access granted: -1. Go to your "Personal access tokens" page at https://github.com/settings/tokens +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 diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 8e062ca627b..91de64be1fa 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,4 +1,4 @@ -# GitLab Slack application **[FREE ONLY]** +# GitLab Slack application **(FREE ONLY)** NOTE: **Note:** The GitLab Slack application is only configurable for GitLab.com. It will **not** diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 0fd847d415f..7a0540aa9e3 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -23,7 +23,7 @@ allow GitLab to send messages only to *one* room. 1. Find "Build Your Own!" and click "Create". 1. Select the desired room, name the integration "GitLab", and click "Create". 1. In the "Send messages to this room by posting this URL" column, you should -see a URL in the format: + see a URL in the format: ``` https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token> diff --git a/doc/user/project/integrations/img/embed_metrics.png b/doc/user/project/integrations/img/embed_metrics.png Binary files differnew file mode 100644 index 00000000000..6f9660c9aec --- /dev/null +++ b/doc/user/project/integrations/img/embed_metrics.png diff --git a/doc/user/project/integrations/img/github_configuration.png b/doc/user/project/integrations/img/github_configuration.png Binary files differindex 9f2d47921c7..5798b826681 100644 --- a/doc/user/project/integrations/img/github_configuration.png +++ b/doc/user/project/integrations/img/github_configuration.png diff --git a/doc/user/project/integrations/img/jira_add_user_to_group.png b/doc/user/project/integrations/img/jira_add_user_to_group.png Binary files differindex d8cf541a81e..b63a851a987 100644 --- a/doc/user/project/integrations/img/jira_add_user_to_group.png +++ b/doc/user/project/integrations/img/jira_add_user_to_group.png diff --git a/doc/user/project/integrations/img/jira_added_user_to_group.png b/doc/user/project/integrations/img/jira_added_user_to_group.png Binary files differindex b3e29a65d6e..f5120a8d42e 100644 --- a/doc/user/project/integrations/img/jira_added_user_to_group.png +++ b/doc/user/project/integrations/img/jira_added_user_to_group.png diff --git a/doc/user/project/integrations/img/jira_api_token.png b/doc/user/project/integrations/img/jira_api_token.png Binary files differindex 4fa7a46854e..d9d37713a4d 100644 --- a/doc/user/project/integrations/img/jira_api_token.png +++ b/doc/user/project/integrations/img/jira_api_token.png diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png Binary files differindex 14037bd0b47..a10a59a243d 100644 --- a/doc/user/project/integrations/img/jira_api_token_menu.png +++ b/doc/user/project/integrations/img/jira_api_token_menu.png diff --git a/doc/user/project/integrations/img/jira_create_new_group.png b/doc/user/project/integrations/img/jira_create_new_group.png Binary files differindex 84be3a94a45..4ab7a5eae4e 100644 --- a/doc/user/project/integrations/img/jira_create_new_group.png +++ b/doc/user/project/integrations/img/jira_create_new_group.png diff --git a/doc/user/project/integrations/img/jira_create_new_user.png b/doc/user/project/integrations/img/jira_create_new_user.png Binary files differindex 8460dc98ef9..c74933298e3 100644 --- a/doc/user/project/integrations/img/jira_create_new_user.png +++ b/doc/user/project/integrations/img/jira_create_new_user.png diff --git a/doc/user/project/integrations/img/jira_group_access.png b/doc/user/project/integrations/img/jira_group_access.png Binary files differindex 58cf114bd55..e33f2eed242 100644 --- a/doc/user/project/integrations/img/jira_group_access.png +++ b/doc/user/project/integrations/img/jira_group_access.png diff --git a/doc/user/project/integrations/img/jira_issue_reference.png b/doc/user/project/integrations/img/jira_issue_reference.png Binary files differindex 72c81460df7..db8bc4f0bb9 100644 --- a/doc/user/project/integrations/img/jira_issue_reference.png +++ b/doc/user/project/integrations/img/jira_issue_reference.png diff --git a/doc/user/project/integrations/img/jira_merge_request_close.png b/doc/user/project/integrations/img/jira_merge_request_close.png Binary files differindex 0f82ceba557..9a176daf5f4 100644 --- a/doc/user/project/integrations/img/jira_merge_request_close.png +++ b/doc/user/project/integrations/img/jira_merge_request_close.png diff --git a/doc/user/project/integrations/img/jira_service_close_comment.png b/doc/user/project/integrations/img/jira_service_close_comment.png Binary files differdeleted file mode 100644 index 9af0d38f098..00000000000 --- a/doc/user/project/integrations/img/jira_service_close_comment.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_service_close_issue.png b/doc/user/project/integrations/img/jira_service_close_issue.png Binary files differindex c85b1d1dd97..73d6498192c 100644 --- a/doc/user/project/integrations/img/jira_service_close_issue.png +++ b/doc/user/project/integrations/img/jira_service_close_issue.png diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png Binary files differdeleted file mode 100644 index 377b69d9d06..00000000000 --- a/doc/user/project/integrations/img/jira_service_page.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_service_page_v12_2.png b/doc/user/project/integrations/img/jira_service_page_v12_2.png Binary files differnew file mode 100644 index 00000000000..ba7dad9b438 --- /dev/null +++ b/doc/user/project/integrations/img/jira_service_page_v12_2.png diff --git a/doc/user/project/integrations/img/jira_user_management_link.png b/doc/user/project/integrations/img/jira_user_management_link.png Binary files differindex 43ef18da6c8..caecd1d71fc 100644 --- a/doc/user/project/integrations/img/jira_user_management_link.png +++ b/doc/user/project/integrations/img/jira_user_management_link.png diff --git a/doc/user/project/integrations/img/mattermost_configuration.png b/doc/user/project/integrations/img/mattermost_configuration.png Binary files differindex 75ef0310f2d..6abf5c5c8d6 100644 --- a/doc/user/project/integrations/img/mattermost_configuration.png +++ b/doc/user/project/integrations/img/mattermost_configuration.png diff --git a/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type.png Binary files differnew file mode 100644 index 00000000000..9fdb6dfddac --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_area_panel_type.png diff --git a/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.png Binary files differnew file mode 100644 index 00000000000..2d7dfb27b49 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_single_stat_panel_type.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 differindex a81dfe7da14..609c5e5196c 100644 --- a/doc/user/project/integrations/img/prometheus_service_alerts.png +++ b/doc/user/project/integrations/img/prometheus_service_alerts.png diff --git a/doc/user/project/integrations/img/slack_configuration.png b/doc/user/project/integrations/img/slack_configuration.png Binary files differindex a14d2969488..10d2cda6dc7 100644 --- a/doc/user/project/integrations/img/slack_configuration.png +++ b/doc/user/project/integrations/img/slack_configuration.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 234e3ad31cc..61f6f6c9412 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -39,21 +39,17 @@ a GitLab project with any single Jira project. If you have one Jira instance, you can pre-fill the settings page with a default template. See the [Services Templates][services-templates] docs. -Configuration happens via user name and password. Connecting to a Jira server -via CAS is not possible. - -In order to enable the Jira service in GitLab, you need to first configure the -project in Jira and then enter the correct values in GitLab. +In order to enable the Jira service in GitLab, you need to first configure the project in Jira and then enter the correct values in GitLab. ### Configuring Jira -When connecting to **JIRA Server**, which supports basic authentication, a **username and password** are required. Check the link below and proceed to the next step: +#### Jira Server -- [Setting up a user in JIRA server](jira_server_configuration.md) +When connecting to **Jira Server**, which supports basic authentication, a **username and password** are required. Note that connecting to a Jira server via CAS is not possible. [Set up a user in Jira Server](jira_server_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). -When connecting to **JIRA Cloud**, which supports authentication via API token, an **email and API token**, are required. Check the link below and proceed to the next step: +#### Jira Cloud -- [Setting up a user in JIRA cloud](jira_cloud_configuration.md) +When connecting to **Jira Cloud**, which supports authentication via API token, an **email and API token**, are required. [Set up a user in Jira Cloud](jira_cloud_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). ### Configuring GitLab @@ -68,7 +64,7 @@ When connecting to **JIRA Cloud**, which supports authentication via API token, > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. -To enable Jira integration in a project, navigate to the +To enable the Jira integration in a project, navigate to the [Integrations page](project_services.md#accessing-the-project-services), click the **Jira** service, and fill in the required details on the page as described in the table below. @@ -77,8 +73,8 @@ in the table below. | ----- | ----------- | | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://Jira.example.com`. | | `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. | -| `Username/Email` | Created when [configuring Jira step](#configuring-jira). Use `username` for **JIRA server** or `email` for **JIRA cloud**. | -| `Password/API token` |Created in [configuring Jira step](#configuring-jira). Use `password` for **JIRA server** or `API token` for **JIRA cloud**. | +| `Username/Email` | Created when [configuring Jira step](#configuring-jira). Use `username` for **Jira Server** or `email` for **Jira Cloud**. | +| `Password/API token` |Created in [configuring Jira step](#configuring-jira). Use `password` for **Jira Server** or `API token` for **Jira Cloud**. | | `Transition ID` | This is the ID of a transition that moves issues to the desired state. It is possible to insert transition ids separated by `,` or `;` which means the issue will be moved to each state after another using the given order. **Closing Jira issues via commits or Merge Requests won't work if you don't set the ID correctly.** | ### Obtaining a transition ID @@ -97,7 +93,7 @@ even if the status you are changing to is the same. After saving the configuration, your GitLab project will be able to interact with all Jira projects in your Jira instance and you'll see the Jira link on the GitLab project pages that takes you to the appropriate Jira project. - + ## Jira issues @@ -127,6 +123,12 @@ ENTITY_TITLE  +For example, the following commit will reference the Jira issue with `PROJECT-1` as its ID: + +```bash +git commit -m "PROJECT-1 Fix spelling and grammar" +``` + ### Closing Jira Issues Jira issues can be closed directly from GitLab by using trigger words in @@ -142,7 +144,7 @@ the same goal: - `Closes PROJECT-1` - `Fixes PROJECT-1` -where `PROJECT-1` is the issue ID of the Jira project. +where `PROJECT-1` is the ID of the Jira issue. > **Notes:** > @@ -174,8 +176,6 @@ with a link to the commit that resolved the issue.  - - ## Troubleshooting If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 849df707521..1d5a4a3d4c7 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,18 +1,20 @@ -# Creating an API token in JIRA cloud +# Creating an API token in Jira Cloud -An API token is needed when integrating with JIRA Cloud, follow the steps +An API token is needed when integrating with Jira Cloud, follow the steps below to create one: -1. Log in to <https://id.atlassian.com> with your email. -1. **Click API tokens**, then **Create API token**. +1. Log in to <https://id.atlassian.com/manage/api-tokens> with your email address. - + NOTE: **Note** + It is important that the user associated with this email address has *write* access + to projects in Jira. - +1. Click **Create API token**. -1. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab). + -NOTE: **Note** -It is important that the user associated with this email has 'write' access to projects in JIRA. + -The JIRA configuration is complete. You are going to need this new created token and the email you used to log in when [configuring GitLab in the next section](jira.md#configuring-gitlab). +1. Click **Copy to clipboard**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab). + +The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section. diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 13d65c4d8e4..1efd0ff3944 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,10 +1,10 @@ -# Creating a username and password for JIRA server +# Creating a username and password for Jira Server We need to create a user in Jira which will have access to all projects that need to integrate with GitLab. -As an example, we'll create a user named `gitlab` and add it to the `Jira-developers` -group. +As an example, we'll create a user named `gitlab` and add it to a new group +named `gitlab-developers`. NOTE: **Note** It is important that the Jira user created for the integration is given 'write' @@ -13,46 +13,46 @@ access to your Jira projects. This is covered in the process below. 1. Log in to your Jira instance as an administrator and under **Jira Administration** go to **User Management** to create a new user. -  +  1. The next step is to create a new user (e.g., `gitlab`) who has write access to projects in Jira. Enter the user's name and a _valid_ e-mail address since Jira sends a verification e-mail to set up the password. _**Note:** Jira creates the username automatically by using the e-mail prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create - an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password._ + an HTTP basic authentication password. You can do this by visiting the user + profile, looking up the username, and setting a password._ -  +  1. Create a `gitlab-developers` group. (We will give this group write access to Jira projects in a later step). Go to the **Groups** tab on the left, and select **Add group**. -  +  - Give it a name and click **Add group**. + Give it a name and click **Add group**. 1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**. The `gitlab-developers` group should be listed in the leftmost box as a selected group. Under **Add members to selected group(s)**, enter `gitlab`. -  - +  + Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box. This membership is saved automatically. - -  + +  1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**. To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. - + 1. Once your permission scheme is created, you'll be taken back to the permissions scheme list. - Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, + Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` from the dropdown. -  +  The Jira configuration is complete. Write down the new Jira username and its password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index d7fd75fd728..6e0f39956d3 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,5 +1,9 @@ # Mattermost Notifications Service +The Mattermost Notifications Service allows your GitLab project to send events (e.g., `issue created`) to your existing Mattermost team as notifications. This requires configurations in both Mattermost and GitLab. + +You can also use Mattermost slash commands to control GitLab inside Mattermost. This is the separately configured [Mattermost slash commands](mattermost_slash_commands.md). + ## On Mattermost To enable Mattermost integration you must create an incoming webhook integration: @@ -10,7 +14,7 @@ To enable Mattermost integration you must create an incoming webhook integration 1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. There might be some cases that Incoming Webhooks are blocked by admin, ask your mattermost admin to enable -it on `https://mattermost.example/admin_console/integrations/custom`. +it on **Mattermost System Console > Integrations > Integration Management**, or on **Mattermost System Console > Integrations > Custom Integrations** in Mattermost versions 5.11 and earlier. Display name override is not enabled by default, you need to ask your admin to enable it on that same section. diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 9c69437537a..a3a2568445e 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -6,6 +6,9 @@ Mattermost commands give users an extra interface to perform common operations from the chat environment. This allows one to, for example, create an issue as soon as the idea was discussed in Mattermost. +GitLab can also send events (e.g., `issue created`) to Mattermost as notifications. +This is the separately configured [Mattermost Notifications Service](mattermost.md). + ## Prerequisites Mattermost 3.4 and up is required. @@ -37,17 +40,13 @@ the administrator console. 1. Log in with an account that has admin privileges and navigate to the system console. -  - - --- +  1. Click **Custom integrations** and set **Enable Custom Slash Commands**, **Enable custom integrations to override usernames**, and **Override custom integrations to override profile picture icons** to true -  - - --- +  1. Click **Save** at the bottom to save the changes. @@ -59,14 +58,12 @@ the administrator console. A screen will appear with all the values you need to copy in Mattermost as described in the next step. Leave the window open. - >**Note:** - GitLab will propose some values for the Mattermost settings. The only one - required to copy-paste as-is is the **Request URL**, all the others are just - suggestions. - -  + NOTE: **Note:** + GitLab will propose some values for the Mattermost settings. The only one + required to copy-paste as-is is the **Request URL**, all the others are just + suggestions. - --- +  1. Proceed to the next step and create a slash command in Mattermost with the above values. @@ -80,44 +77,38 @@ in a new slash command. 1. Back to Mattermost, under your team page settings, you should see the **Integrations** option. -  - - --- +  1. Go to the **Slash Commands** integration and add a new one by clicking the **Add Slash Command** button. -  - - --- +  1. Fill in the options for the custom command as described in [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab). - >**Note:** - If you plan on connecting multiple projects, pick a slash command trigger - word that relates to your projects such as `/gitlab-project-name` or even - just `/project-name`. Only use `/gitlab` if you will only connect a single - project to your Mattermost team. + NOTE: **Note:** + If you plan on connecting multiple projects, pick a slash command trigger + word that relates to your projects such as `/gitlab-project-name` or even + just `/project-name`. Only use `/gitlab` if you will only connect a single + project to your Mattermost team. -  +  1. After you set up all the values, copy the token (we will use it below) and click **Done**. -  +  ### Step 4. Copy the Mattermost token into the Mattermost slash command service 1. In GitLab, paste the Mattermost token you copied in the previous step and check the **Active** checkbox. -  +  1. Click **Save changes** for the changes to take effect. ---- - You are now set to start using slash commands in Mattermost that talk to the GitLab project you configured. diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 1c64b275d6e..886094a6531 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -5,9 +5,9 @@ To set up the mock CI service server, respond to the following endpoints - `commit_status`: `#{project.namespace.path}/#{project.path}/status/#{sha}.json` - - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }` + - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }` - If the service returns a 404, it is interpreted as `pending` - `build_page`: `#{project.namespace.path}/#{project.path}/status/#{sha}` - - Just where the build is linked to, doesn't matter if implemented + - Just where the build is linked to, doesn't matter if implemented For an example of a mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service) diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 0bfee3bac99..67274e8d924 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -20,10 +20,10 @@ Below, you will find a list of the currently supported ones accompanied with com Click on the service links to see further configuration instructions and details. -| Service | Description | +| Service | Description | | ------- | ----------- | -| Asana | Asana - Teamwork without email | -| Assembla | Project Management Software (Source Commits Endpoint) | +| Asana | Asana - Teamwork without email | +| Assembla | Project Management Software (Source Commits Endpoint) | | [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server | | Buildkite | Continuous integration and deployments | | [Bugzilla](bugzilla.md) | Bugzilla issue tracker | @@ -34,12 +34,12 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | | Flowdock | Flowdock is a collaboration web app for technical teams | -| [GitHub](github.md) **[PREMIUM]** | Sends pipeline notifications to GitHub | +| [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | | [HipChat](hipchat.md) | Private group chat and IM | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | -| [JIRA](jira.md) | JIRA issue tracker | -| [Jenkins](../../../integration/jenkins.md) **[STARTER]** | An extendable open source continuous integration server | +| [Jira](jira.md) | Jira issue tracker | +| [Jenkins](../../../integration/jenkins.md) **(STARTER)** | An extendable open source continuous integration server | | JetBrains TeamCity CI | A continuous integration and build server | | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | @@ -47,8 +47,8 @@ Click on the service links to see further configuration instructions and details | Packagist | Update your project on Packagist, the main Composer repository | | Pipelines emails | Email the pipeline status to a list of recipients | | [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications | -| [Slack slash commands](slack_slash_commands.md) **[CORE ONLY]** | Use slash commands in Slack to control GitLab | -| [GitLab Slack application](gitlab_slack_application.md) **[FREE ONLY]** | Use Slack's official application | +| [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | +| [GitLab Slack application](gitlab_slack_application.md) **(FREE ONLY)** | Use Slack's official application | | PivotalTracker | Project Management Software (Source Commits Endpoint) | | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 751e8e44e60..aa7db97c413 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -18,6 +18,7 @@ Once enabled, GitLab will automatically detect metrics from known services in th ## Enabling Prometheus Integration ### Managed Prometheus on Kubernetes + > **Note**: [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28916) in GitLab 10.5 GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. @@ -39,9 +40,9 @@ Once you have a connected Kubernetes cluster with Helm installed, deploying a ma #### About managed Prometheus deployments -Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). +Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). -The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Ckubernetes_sd_config%3E) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - `prometheus.io/scrape` to `true` to enable monitoring of the resource. - `prometheus.io/port` to define the port of the metrics endpoint. @@ -66,9 +67,9 @@ Integration with Prometheus requires the following: Installing and configuring Prometheus to monitor applications is fairly straight forward. -1. [Install Prometheus](https://prometheus.io/docs/introduction/install/) +1. [Install Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) 1. Set up one of the [supported monitoring targets](prometheus_library/index.md) -1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/operating/configuration/#scrape_config) +1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) #### Configuration in GitLab @@ -93,11 +94,14 @@ GitLab will automatically scan the Prometheus server for metrics from known serv You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments.md#monitoring-environments). -### Adding additional metrics **[PREMIUM]** +### Adding additional metrics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3799) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. -Additional metrics can be monitored by adding them on the Prometheus integration page. Once saved, they will be displayed on the environment performance dashboard. +Custom metrics can be monitored by adding them on the Prometheus integration page. Once saved, they will be displayed on the environment performance dashboard provided that either: + +- A [connected Kubernetes cluster](../clusters/index.md#adding-and-removing-clusters) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration), or +- Prometheus is [manually configured](#manual-configuration-of-prometheus).  @@ -120,7 +124,152 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.htm To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`. -### Setting up alerts for Prometheus metrics **[ULTIMATE]** +### Defining custom dashboards per project + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/59974) in GitLab 12.1. + +By default, all projects include a GitLab-defined Prometheus dashboard, which +includes a few key metrics, but you can also define your own custom dashboards. + +NOTE: **Note:** +The custom metrics as defined below do not support alerts, unlike +[additional metrics](#adding-additional-metrics-premium). + +Dashboards have several components: + +- Panel groups, which comprise panels. +- Panels, which support one or more metrics. + +To configure a custom dashboard: + +1. Create a YAML file with the `.yml` extension under your repository's root + directory inside `.gitlab/dashboards/`. For example, create + `.gitlab/dashboards/prom_alerts.yml` with the following contents: + + ```yaml + dashboard: 'Dashboard Title' + panel_groups: + - group: 'Group Title' + panels: + - type: area-chart + title: "Chart Title" + y_label: "Y-Axis" + metrics: + - id: metric_of_ages + query_range: 'http_requests_total' + label: "Metric of Ages" + unit: "count" + ``` + + The above sample dashboard would display a single area chart. Each file should + define the layout of the dashboard and the Prometheus queries used to populate + data. + +1. Save the file, commit, and push to your repository. +1. Navigate to your project's **Operations > Metrics** and choose the custom + dashboard from the dropdown. + +NOTE: **Note:** +Configuration files nested under subdirectories of `.gitlab/dashboards` are not +supported and will not be available in the UI. + +The following tables outline the details of expected properties. + +**Dashboard properties:** + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. | +| `panel_groups` | array | yes | The panel groups which should be on the dashboard. | + +**Panel group (`panel_groups`) properties:** + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| `group` | string | required | Heading for the panel group. | +| `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | +| `panels` | array | required | The panels which should be in the panel group. | + +**Panel (`panels`) properties:** + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------- | +| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use. | +| `title` | string | yes | Heading for the panel. | +| `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. | +| `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | +| `metrics` | array | yes | The metrics which should be displayed in the panel. | + +**Metrics (`metrics`) properties:** + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](#setting-up-alerts-for-prometheus-metrics-ultimate) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/60319)). | +| `unit` | string | yes | Defines the unit of the query's return data. | +| `label` | string | no, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. | +| `query` | string | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | +| `query_range` | string | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | + +#### Panel types for dashboards + +The below panel types are supported in monitoring dashboards. + +##### Area + +To add an area panel type to a dashboard, look at the following sample dashboard file: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - type: area-chart + title: "Chart Title" + y_label: "Y-Axis" + metrics: + - id: 10 + query_range: 'http_requests_total' + label: "Metric of Ages" + unit: "count" +``` + +Note the following properties: + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| type | string | no | Type of panel to be rendered. Optional for area panel types | +| query_range | yes | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | + + + +##### Single Stat + +To add a single stat panel type to a dashboard, look at the following sample dashboard file: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - title: "Single Stat" + type: "single-stat" + metrics: + - id: 10 + query: 'max(go_memstats_alloc_bytes{job="prometheus"})' + unit: MB + label: "Total" +``` + +Note the following properties: + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| type | string | yes | Type of panel to be rendered. For single stat panel types, set to `single-stat` | +| query | string | yes | For single stat panel types, you must use an [instant query](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries) | + + + +### Setting up alerts for Prometheus metrics **(ULTIMATE)** #### Managed Prometheus instances @@ -156,11 +305,11 @@ receivers: ... ``` -### Taking action on incidents **[ULTIMATE]** +### Taking action on incidents **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. -Alerts can be used to trigger actions, like open an issue automatically. To configure the actions: +Alerts can be used to trigger actions, like open an issue automatically (enabled by default since `12.1`). To configure the actions: 1. Navigate to your project's **Settings > Operations > Incidents**. 1. Enable the option to create issues. @@ -168,7 +317,20 @@ Alerts can be used to trigger actions, like open an issue automatically. To conf 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. The author of the issue will be the GitLab Alert Bot. To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template. +Once enabled, an issue will be opened automatically when an alert is triggered which contains values extracted from [alert's payload](https://prometheus.io/docs/alerting/configuration/#webhook_config +): + +- Issue author: `GitLab Alert Bot` +- Issue title: Extract from `annotations/title`, `annotations/summary` or `labels/alertname` +- Alert `Summary`: A list of properties + - `starts_at`: Alert start time via `startsAt` + - `full_query`: Alert query extracted from `generatorURL` + - Optional list of attached annotations extracted from `annotations/*` +- Alert [GFM](../../markdown.md): GitLab Flavored Markdown from `annotations/gitlab_incident_markdown` + +To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template, which will apply to all incidents. To limit quick actions or other information to only specific types of alerts, use the `annotations/gitlab_incident_markdown` field. + +Since [version 12.2](https://gitlab.com/gitlab-org/gitlab-ce/issues/63373), GitLab will tag each incident issue with the `incident` label automatically. If the label does not yet exist, it will be created automatically as well. 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. @@ -192,6 +354,27 @@ Prometheus server.  +## Embedding metric charts within Gitlab Flavored Markdown + +> [Introduced][ce-29691] in GitLab 12.2. +> Requires [Kubernetes](prometheus_library/kubernetes.md) metrics. + +It is possible to display metrics charts within [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + +To display a metric chart, include a link of the form `https://<root_url>/<project>/environments/<environment_id>/metrics`. + +The following requirements must be met for the metric to unfurl: + +- The `<environment_id>` must correspond to a real environment. +- Prometheus must be monitoring the environment. +- The GitLab instance must be configured to receive data from the environment. +- The user must be allowed access to the monitoring dashboard for the environment ([Reporter or higher](../../permissions.md)). +- The dashboard must have data within the last 8 hours. + + If all of the above are true, then the metric will unfurl as seen below: + + + ## Troubleshooting If the "No data found" screen continues to appear, it could be due to: @@ -214,4 +397,5 @@ If the "No data found" screen continues to appear, it could be due to: [ci-environment-slug]: ../../../ci/variables/#predefined-environment-variables [ce-8935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935 [ce-10408]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10408 +[ce-29691]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29691 [promgldocs]: ../../../administration/monitoring/prometheus/index.md diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 66f1b587070..5049733abdd 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -18,9 +18,9 @@ The [Prometheus service](../prometheus.md) must be enabled. ## Configuring Prometheus to monitor for Cloudwatch metrics -To get started with Cloudwatch monitoring, you should install and configure the [Cloudwatch exporter](https://github.com/hnlq715/nginx-vts-exporter) which retrieves and parses the specified Cloudwatch metrics and translates them into a Prometheus monitoring endpoint. +To get started with Cloudwatch monitoring, you should install and configure the [Cloudwatch exporter](https://github.com/prometheus/cloudwatch_exporter) which retrieves and parses the specified Cloudwatch metrics and translates them into a Prometheus monitoring endpoint. -Right now, the only AWS resource supported is the Elastic Load Balancer, whose Cloudwatch metrics can be found [here](http://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). +Right now, the only AWS resource supported is the Elastic Load Balancer, whose Cloudwatch metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB monitoring, is [available for download](../samples/cloudwatch.yml). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index abb0c01ad18..90a725f271b 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,4 +1,5 @@ # Monitoring HAProxy + > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12621) in GitLab 9.4 GitLab has support for automatically detecting and monitoring HAProxy. This is provided by leveraging the [HAProxy Exporter](https://github.com/prometheus/haproxy_exporter), which translates HAProxy statistics into a Prometheus readable form. @@ -11,8 +12,8 @@ The [Prometheus service](../prometheus.md) must be enabled. | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) by (code) | -| HTTP Error Rate (%) | sum(rate(haproxy_frontend_http_requests_total{code="5xx",%{environment_filter}}[2m])) / sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) | +| Throughput (req/sec) | `sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) by (code)` | +| HTTP Error Rate (%) | `sum(rate(haproxy_frontend_http_requests_total{code="5xx",%{environment_filter}}[2m])) / sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m]))` | ## Configuring Prometheus to monitor for HAProxy metrics diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 8b1cf1a251a..9e17edf7d36 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -13,15 +13,15 @@ integration services must be enabled. - Average Memory Usage (MB): - ``` - avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024 - ``` + ``` + avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",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}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) - ``` + ``` + avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) + ``` ## Configuring Prometheus to monitor for Kubernetes metrics @@ -36,7 +36,7 @@ In order to isolate and only display relevant CPU and Memory metrics for a given Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. -## Displaying Canary metrics **[PREMIUM]** +## Displaying Canary metrics **(PREMIUM)** > Introduced in [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15201). @@ -48,12 +48,12 @@ These metrics expect the [Deployment](https://kubernetes.io/docs/concepts/worklo - 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 - ``` + ``` + 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)) - ``` + ``` + 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/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index c4fea178ab5..7db9629c002 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -14,9 +14,9 @@ NGINX server metrics are detected, which tracks the pages and content directly s | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code) | -| Latency (ms) | avg(nginx_server_requestMsec{%{environment_filter}}) | -| HTTP Error Rate (HTTP Errors / sec) | sum(rate(nginx_server_requests{code="5xx", %{environment_filter}}[2m])) | +| Throughput (req/sec) | `sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code)` | +| Latency (ms) | `avg(nginx_server_requestMsec{%{environment_filter}})` | +| HTTP Error Rate (HTTP Errors / sec) | `sum(rate(nginx_server_requests{code="5xx", %{environment_filter}}[2m]))` | ## Configuring Prometheus to monitor for NGINX metrics diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index de7fc93f0a4..fd743855a8c 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -14,9 +14,9 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(label_replace(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m]), "status_code", "${1}xx", "status", "(.)..")) by (status_code) | -| Latency (ms) | sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_sum{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_count{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 1000 | -| HTTP Error Rate (%) | sum(rate(nginx_ingress_controller_requests{status=~"5.*",namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 100 | +| Throughput (req/sec) | `sum(label_replace(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m]), "status_code", "${1}xx", "status", "(.)..")) by (status_code)` | +| Latency (ms) | `sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_sum{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_count{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 1000` | +| HTTP Error Rate (%) | `sum(rate(nginx_ingress_controller_requests{status=~"5.*",namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 100` | ## Configuring NGINX ingress monitoring diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 31ac53c0d14..b03787b3e0d 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -14,9 +14,9 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code) | -| Latency (ms) | avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}) | -| HTTP Error Rate (%) | sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100 | +| Throughput (req/sec) | `sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code)` | +| Latency (ms) | `avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"})` | +| HTTP Error Rate (%) | `sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100` | ## Configuring NGINX ingress monitoring diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index bac7eecfce4..25b000b2753 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -5,18 +5,18 @@ the **Redmine** service, and fill in the required details on the page as described in the table below. - | Field | Description | - | ----- | ----------- | - | `description` | A name for the issue tracker (to differentiate between instances, for example) | - | `project_url` | The URL to the project in Redmine which is being linked to this GitLab project | - | `issues_url` | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | - | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** | + | Field | Description | + | ----- | ----------- | + | `description` | A name for the issue tracker (to differentiate between instances, for example) | + | `project_url` | The URL to the project in Redmine which is being linked to this GitLab project | + | `issues_url` | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | + | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** | - Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. + Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. - As an example, below is a configuration for a project named gitlab-ci. + As an example, below is a configuration for a project named gitlab-ci. -  +  1. To disable the internal issue tracking system in a project, navigate to the General page, expand the [permissions](../settings/index.md#sharing-and-permissions) section and switch the **Issues** toggle to disabled. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index bb8d276c2fc..508e72b5753 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -6,7 +6,7 @@ The Slack Notifications Service allows your GitLab project to send events (e.g. ## Slack Configuration -1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook/). +1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). 1. Select the Slack channel where notifications will be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration. 1. Copy the **Webhook URL**, which we'll use later in the GitLab configuration. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 371e78ca3a4..813066c51ac 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,4 +1,4 @@ -# Slack slash commands **[CORE ONLY]** +# Slack slash commands **(CORE ONLY)** > Introduced in GitLab 8.15. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index d5f28ddabc1..84adb9637fc 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -24,7 +24,7 @@ to the webhook URL. In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver) to receive information from GitLab, and send it to another app, according to your needs. -We already have a [built-in receiver](http://docs.gitlab.com/ce/project_services/slack.html) +We already have a [built-in receiver](slack.md) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. ## Overview @@ -58,13 +58,13 @@ Navigate to the webhooks page by going to your project's If you are writing your own endpoint (web server) that will receive GitLab webhooks keep in mind the following things: -- Your endpoint should send its HTTP response as fast as possible. If - you wait too long, GitLab may decide the hook failed and retry it. -- Your endpoint should ALWAYS return a valid HTTP response. If you do - not do this then GitLab will think the hook failed and retry it. - Most HTTP libraries take care of this for you automatically but if - you are writing a low-level hook this is important to remember. -- GitLab ignores the HTTP status code returned by your endpoint. +- Your endpoint should send its HTTP response as fast as possible. If + you wait too long, GitLab may decide the hook failed and retry it. +- Your endpoint should ALWAYS return a valid HTTP response. If you do + not do this then GitLab will think the hook failed and retry it. + Most HTTP libraries take care of this for you automatically but if + you are writing a low-level hook this is important to remember. +- GitLab ignores the HTTP status code returned by your endpoint. ## Secret token @@ -326,7 +326,7 @@ X-Gitlab-Event: Issue Hook "current": 1 }, "updated_at": { - "previous": "2017-09-15 16:50:55 UTC", + "previous": "2017-09-15 16:50:55 UTC", "current": "2017-09-15 16:52:00 UTC" }, "labels": { @@ -888,7 +888,7 @@ X-Gitlab-Event: Merge Request Hook "current": 1 }, "updated_at": { - "previous": "2017-09-15 16:50:55 UTC", + "previous": "2017-09-15 16:50:55 UTC", "current":"2017-09-15 16:52:00 UTC" }, "labels": { diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 31020de5208..eaca5f8cfb8 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -28,11 +28,11 @@ Issue Boards** (version introduced in GitLab 8.11 - August 2016). ### Advanced features of Issue Boards With [GitLab Starter](https://about.gitlab.com/pricing/), you can create -[multiple issue boards](#multiple-issue-boards-starter) for a given project. **[STARTER]** +[multiple issue boards](#multiple-issue-boards-starter) for a given project. **(STARTER)** With [GitLab Premium](https://about.gitlab.com/pricing/), you can also create multiple issue boards for your groups, and add lists for [assignees](#assignee-lists-premium) and -[milestones](#milestone-lists-premium). **[PREMIUM]** +[milestones](#milestone-lists-premium). **(PREMIUM)** Check all the [advanced features of Issue Boards](#gitlab-enterprise-features-for-issue-boards) below. @@ -143,10 +143,10 @@ Create lists for each of your team members and quickly drag-and-drop issues onto - **Issue Board** - Each board represents a unique view for your issues. It can have multiple lists with each list consisting of issues represented by cards. - **List** - A column on the issue board that displays issues matching certain attributes. In addition to the default lists of 'Open' and 'Closed' issue, each additional list will show issues matching your chosen label or assignee. On the top of that list you can see the number of issues that belong to it. - - **Label list**: a list based on a label. It shows all opened issues with that label. - - **Assignee list**: a list which includes all issues assigned to a user. - - **Open** (default): shows all open issues that do not belong to one of the other lists. Always appears as the leftmost list. - - **Closed** (default): shows all closed issues. Always appears as the rightmost list. + - **Label list**: a list based on a label. It shows all opened issues with that label. + - **Assignee list**: a list which includes all issues assigned to a user. + - **Open** (default): shows all open issues that do not belong to one of the other lists. Always appears as the leftmost list. + - **Closed** (default): shows all closed issues. Always appears as the rightmost list. - **Card** - A box in the list that represents an individual issue. The information you can see on a card consists of the issue number, the issue title, the assignee, and the labels associated with the issue. You can drag cards from one list to another to change their label or assignee from that of the source list to that of the destination list. ## Permissions @@ -163,7 +163,7 @@ on the following sections. For a collection of [features per tier](#summary-of-features-per-tier), check the summary below. -### Multiple Issue Boards **[STARTER]** +### Multiple Issue Boards **(STARTER)** > Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee). @@ -188,7 +188,7 @@ NOTE: **Note:** The Multiple Issue Boards feature is available for **projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**. -### Configurable Issue Boards **[STARTER]** +### Configurable Issue Boards **(STARTER)** > Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration). @@ -208,7 +208,7 @@ If you don't have editing permission in a board, you're still able to see the co  -### Focus mode **[STARTER]** +### Focus mode **(STARTER)** > Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep). @@ -216,7 +216,7 @@ Click the button at the top right to toggle focus mode on and off. In focus mode  -### Sum of Issue Weights **[STARTER]** +### Sum of Issue Weights **(STARTER)** The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, @@ -224,7 +224,7 @@ especially in combination with [assignee lists](#assignee-lists-premium).  -### Group Issue Boards **[PREMIUM]** +### Group Issue Boards **(PREMIUM)** > Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards). @@ -240,7 +240,7 @@ one group issue board per group was made available in GitLab 10.6 Core.  -### Assignee lists **[PREMIUM]** +### Assignee lists **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium. @@ -259,7 +259,7 @@ To remove an assignee list, just as with a label list, click the trash icon.  -### Milestone lists **[PREMIUM]** +### Milestone lists **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6469) in GitLab 11.2 Premium. @@ -386,6 +386,10 @@ a given board inside your GitLab instance, any time those two issues are subsequ loaded in any board in the same instance (could be a different project board or a different group board, for example), that ordering will be maintained. +This ordering also affects [issue lists](issues/sorting_issue_lists.md). +Changing the order in an issue board changes the ordering in an issue list, +and vice versa. + ### Filtering issues You should be able to use the filters on top of your Issue Board to show only diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index c3e06b219ff..dab79327d6a 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -1,63 +1,5 @@ -# Automatic issue closing - ->**Notes:** -> -> - This is the user docs. In order to change the default issue closing pattern, -> follow the steps in the [administration docs]. -> - For performance reasons, automatic issue closing is disabled for the very -> first push from an existing repository. - -When a commit or merge request resolves one or more issues, it is possible to -automatically have these issues closed when the commit or merge request lands -in the project's default branch. - -If a commit message or merge request description contains a sentence matching -a certain regular expression, all issues referenced from the matched text will -be closed. This happens when the commit is pushed to a project's -[**default** branch](../repository/branches/index.md#default-branch), or when a -commit or merge request is merged into it. - -## Default closing pattern value - -When not specified, the default issue closing pattern as shown below will be -used: - -```bash -((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+) -``` - -Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's -source code that can match references to: - -- A local issue (`#123`). -- A cross-project issue (`group/project#123`). -- A link to an issue - (`https://gitlab.example.com/group/project/issues/123`). - --- - -This translates to the following keywords: - -- Close, Closes, Closed, Closing, close, closes, closed, closing -- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing -- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving -- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing - +redirect_to: 'managing_issues.md#closing-issues-automatically' --- -For example the following commit message: - -``` -Awesome commit message - -Fix #20, Fixes #21 and Closes group/otherproject#22. -This commit is also related to #17 and fixes #18, #19 -and https://gitlab.example.com/group/otherproject/issues/23. -``` - -will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed -to, as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as -it does not match the pattern. It works with multi-line commit messages as well -as one-liners when used with `git commit -m`. - -[administration docs]: ../../../administration/issue_closing_pattern.md +This document was moved to [another location](managing_issues.md#closing-issues-automatically). diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md index 1d88745af9f..04f1c8e1a4a 100644 --- a/doc/user/project/issues/closing_issues.md +++ b/doc/user/project/issues/closing_issues.md @@ -1,59 +1,5 @@ -# Closing Issues +--- +redirect_to: 'managing_issues.md#closing-issues' +--- -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -## Directly - -Whenever you decide that's no longer need for that issue, -close the issue using the close button: - - - -## Via Merge Request - -When a merge request resolves the discussion over an issue, you can -make it close that issue(s) when merged. - -All you need is to use a [keyword](automatic_issue_closing.md) -accompanying the issue number, add to the description of that MR. - -In this example, the keyword "closes" prefixing the issue number will create a relationship -in such a way that the merge request will close the issue when merged. - -Mentioning various issues in the same line also works for this purpose: - -```md -Closes #333, #444, #555 and #666 -``` - -If the issue is in a different repository rather then the MR's, -add the full URL for that issue(s): - -```md -Closes #333, #444, and https://gitlab.com/<username>/<projectname>/issues/<xxx> -``` - -All the following keywords will produce the same behaviour: - -- Close, Closes, Closed, Closing, close, closes, closed, closing -- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing -- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving - - - -If you use any other word before the issue number, the issue and the MR will -link to each other, but the MR will NOT close the issue(s) when merged. - - - -## From the Issue Board - -You can close an issue from [Issue Boards](../issue_board.md) by dragging an issue card -from its list and dropping into **Closed**. - - - -## Customizing the issue closing pattern - -Alternatively, a GitLab **administrator** can -[customize the issue closing pattern](../../../administration/issue_closing_pattern.md). +This document was moved to [another location](managing_issues.md#closing-issues). diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 2c755e0fb4d..c10ef564f0d 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -77,3 +77,49 @@ project's search results respectively. | Maintainer access | Guest access | | :-----------: | :----------: | |  |  | + +## Merge Requests for Confidential Issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/58583) in GitLab 12.1. + +To help prevent confidential information being leaked from a public project +in the process of resolving a confidential issue, confidential issues can be +resolved by creating a merge request from a private fork. + +The merge request created will target the default branch of the private fork, +not the default branch of the public upstream project. This prevents the merge +request, branch, and commits entering the public repository, and revealing +confidential information prematurely. When the confidential commits are ready +to be made public, this can be done by opening a merge request from the private +fork to the public upstream project. + +TIP: **Best practice:** +If you create a long-lived private fork in the same group or in a sub-group of +the original upstream, all the users with Developer membership to the public +project will also have the same permissions in the private project. This way, +all the Developers, who have access to view confidential issues, will have a +streamlined workflow for fixing them. + +### How it works + +On a confidential issue, a **Create confidential merge request** button is +available. Clicking on it will open a dropdown where you can choose to +**Create confidential merge request and branch** or **Create branch**: + +| Create confidential merge request | Create branch | +| :-------------------------------: | :-----------: | +|  |  | + +The **Project** dropdown includes the list of private forks the user is a member +of as at least a Developer and merge requests are enabled. + +Whenever the **Branch name** and **Source (branch or tag)** fields change, the +availability of the target or source branch will be checked. Both branches should +be available in the private fork selected. + +By clicking the **Create confidential merge request** button, GitLab will create +the branch and merge request in the private fork. When you choose +**Create branch**, GitLab will only create the branch. + +Once the branch is created in the private fork, developers can now push code to +that branch to fix the confidential issue. diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index c2916c79876..8eec29716c1 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -1,104 +1,5 @@ -# Create a new Issue +--- +redirect_to: 'managing_issues.md#create-a-new-issue' +--- -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -When you create a new issue, you'll be prompted to fill in -the information illustrated on the image below. - - - -Read through the [issue data and actions documentation](issue_data_and_actions.md#parts-of-an-issue) -to understand these fields one by one. - -## New issue from the Issue Tracker - -Navigate to your **Project's Dashboard** > **Issues** > **New Issue** to create a new issue: - - - -## New issue from an opened issue - -From an **opened issue** in your project, click **New Issue** to create a new -issue in the same project: - - - -## New issue from the project's dashboard - -From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown -menu with a few options. Select **New Issue** to create an issue in that project: - - - -## New issue from the Issue Board - -From an Issue Board, create a new issue by clicking on the plus sign (**+**) on the top of a list. -It opens a new issue for that project labeled after its respective list. - - - -## New issue via email - -At the bottom of a project's Issues List page, a link to **Email a new issue to this project** -is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured. - - - -When you click this link, an email address is displayed which belongs to you for creating issues in this project. -You can save this address as a contact in your email client for easy acceess. - -CAUTION: **Caution:** -This is a private email address, generated just for you. **Keep it to yourself**, -as anyone who gets ahold of it can create issues or merge requests as if they -were you. If the address is compromised, or you'd like it to be regenerated for -any reason, click **Email a new issue to this project** again and click the reset link. - -Sending an email to this address will create a new issue on your behalf for -this project, where: - -- The email subject becomes the issue title. -- The email body becomes the issue description. -- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. - -NOTE: **Note:** -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](../service_desk.md) 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 -field values using query string parameters in a URL. This is useful for embedding -a URL in an external HTML page, and also certain scenarios where you want the user to -create an issue with certain fields prefilled. - -The title, description, and description template fields can be prefilled using -this method. The description and description template fields cannot be pre-entered -in the same URL (since a description template just populates the description field). - -Follow these examples to form your new issue URL with prefilled fields. - -- For a new issue in the GitLab Community Edition project with a pre-entered title - and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` -- For a new issue in the GitLab Community Edition project with a pre-entered title - and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` +This document was moved to [another location](managing_issues.md#create-a-new-issue). diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index ff5b1f2ce50..ec9eb7b62bb 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -25,9 +25,8 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. -**Note:** Linking your first commit to your issue is going to be relevant -for tracking your process far ahead with -[GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/)). +NOTE: **Note:** Linking your first commit to your issue is going to be relevant +for tracking your process with [GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/). It will measure the time taken for planning the implementation of that issue, which is the time between creating an issue and making the first commit. @@ -35,28 +34,24 @@ which is the time between creating an issue and making the first commit. Mentioning related issues in merge requests and other issues is useful for your team members and collaborators to know that there are opened -issues around that same idea. +issues regarding the same topic. -You do that as explained above, when -[mentioning an issue from a commit message](#from-commit-messages). +You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages). -When mentioning the issue "A" in issue "B", the issue "A" will also -display a notification in its tracker. The same is valid for mentioning -issues in merge requests. +When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification +in its tracker. That is, you only need to mention the relationship once for it to +display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests).  ## From Merge Requests Mentioning issues in merge request comments works exactly the same way as -they do for [related issues](#from-related-issues). +they do for [related issues](#from-related-issues). When you mention an issue in a merge request description, it will simply [link the issue and merge request together](#from-related-issues). Additionally, -you can also [set an issue to close as soon as the merge request is merged](closing_issues.md#via-merge-request). +you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically) +as soon as the merge request is merged.  - -### Close an issue by merging a merge request - -To [close an issue when a merge request is merged](closing_issues.md#via-merge-request), use the [automatic issue closing pattern](automatic_issue_closing.md). diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 56b94585672..27ce3a814f9 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,4 +1,4 @@ -# Export Issues to CSV **[STARTER]** +# 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). @@ -48,7 +48,6 @@ Exported issues are always sorted by `Issue ID`. 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` | @@ -71,7 +70,6 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot | 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. +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 15MB 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/csv_import.md b/doc/user/project/issues/csv_import.md index b0b1cfcfdf7..cc0d5ac9028 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -7,7 +7,8 @@ Issues can be imported to a project by uploading a CSV file with the columns The user uploading the CSV file will be set as the author of the imported issues. -> **Note:** A permission level of `Developer` or higher is required to import issues. +NOTE: **Note:** A permission level of [Developer](../../permissions.md), or higher, is required +to import issues. ## Prepare for the import @@ -24,42 +25,26 @@ To import issues: 1. Select the file and click the **Import issues** button. The file is processed in the background and a notification email is sent -to you once the import is completed. +to you once the import is complete. ## CSV file format -### Header row +When importing issues from a CSV file, it must be formatted in a certain way: -CSV files must contain a header row where the first column header is `title` and the second is `description`. -If additional columns are present, they will be ignored. +- **header row:** CSV files must contain a header row where the first column header + is `title` and the second is `description`. If additional columns are present, they + will be ignored. +- **separators:** The column separator is automatically detected from the header row. + Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`). + The row separator can be either `CRLF` or `LF`. +- **double-quote character:** The double-quote (`"`) character is used to quote fields, + enabling the use of the column separator within a field (see the third line in the + sample CSV data below). To insert a double-quote (`"`) within a quoted + field, use two double-quote characters in succession, i.e. `""`. +- **data rows:** After the header row, succeeding rows must follow the same column + order. The issue title is required while the description is optional. -### Column separator - -The column separator is automatically detected from the header row. - -Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`). - -### Row separator - -Lines ending in either `CRLF` or `LF` are supported. - -### Quote character - -The double-quote (`"`) character is used to quote fields so you can use the column separator within a field. To insert -a double-quote (`"`) within a quoted field, use two double-quote characters in succession, i.e. `""`. - -### Data rows - -After the header row, succeeding rows must follow the same column order. The issue title is required while the -description is optional. - -### File size - -The limit depends on the configuration value of Max Attachment Size for the GitLab instance. - -For GitLab.com, it is set to 10 MB. - -## Sample data +Sample CSV data: ```csv title,description @@ -67,3 +52,9 @@ My Issue Title,My Issue Description Another Title,"A description, with a comma" "One More Title","One More Description" ``` + +### File size + +The limit depends on the configuration value of Max Attachment Size for the GitLab instance. + +For GitLab.com, it is set to 10 MB. diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md index 536a0de8974..e50259e0dcf 100644 --- a/doc/user/project/issues/deleting_issues.md +++ b/doc/user/project/issues/deleting_issues.md @@ -1,13 +1,5 @@ -# Deleting Issues +--- +redirect_to: 'managing_issues.md#deleting-issues' +--- -> [Introduced][ce-2982] in GitLab 8.6 - -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -You can delete an issue by editing it and clicking on the delete button. - - - ->**Note:** Only [project owners](../../permissions.md) can delete issues. - -[ce-2982]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2982
\ No newline at end of file +This document was moved to [another location](managing_issues.md#deleting-issues). diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md new file mode 100644 index 00000000000..1324a90e00b --- /dev/null +++ b/doc/user/project/issues/design_management.md @@ -0,0 +1,79 @@ +# Design Management **(PREMIUM)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +CAUTION: **Warning:** +This an **alpha** feature and is subject to change at any time without +prior notice. + +## Overview + +Design Management allows you to upload design assets (wireframes, mockups, etc.) +to GitLab issues and keep them stored in one single place, accessed by the Design +Management's page within an issue, giving product designers, product managers, and engineers a +way to collaborate on designs over one single source of truth. + +You can easily share mock-ups of designs with your team, or visual regressions can be easily +viewed and addressed. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see the video [Design Management (GitLab 12.2)](https://www.youtube.com/watch?v=CCMtCqdK_aM). + +## Requirements + +Design Management requires +[Large File Storage (LFS)](../../../workflow/lfs/manage_large_binaries_with_git_lfs.md) +to be enabled: + +- For GitLab.com, LFS is already enabled. +- For self-managed instances, a GitLab administrator must have + [enabled LFS globally](../../../workflow/lfs/lfs_administration.md). +- For both GitLab.com and self-managed instances: LFS must be enabled for the project itself. + If enabled globally, LFS will be enabled by default to all projects. To enable LFS on the + project level, navigate to your project's **Settings > General**, expand **Visibility, project features, permissions** + and enable **Git Large File Storage**. + +## Limitations + +- Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`. + The [`svg` extension is not yet supported](https://gitlab.com/gitlab-org/gitlab-ee/issues/12771). +- Design uploads are limited to 10 files at a time. +- [Designs cannot yet be deleted](https://gitlab.com/gitlab-org/gitlab-ee/issues/11089). +- Design Management is + [not yet supported in the project export](https://gitlab.com/gitlab-org/gitlab-ee/issues/11090). +- Design Management data + [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab-ee/issues/13429) yet. +- Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab-ee/issues/13426) + when an issue is moved, nor [deleted](https://gitlab.com/gitlab-org/gitlab-ee/issues/13427) + when an issue is deleted. +- Design Management + [isn't supported by Geo](https://gitlab.com/groups/gitlab-org/-/epics/1633) yet. + +## The Design Management page + +Navigate to the **Design Management** page from any issue by clicking the **Designs** tab: + + + +## Adding designs + +To upload design images, click the **Upload Designs** button and select images to upload. + +Designs with the same filename as an existing uploaded design will create a new version +of the design, and will replace the previous version. + +## Viewing designs + +Images on the Design Management page can be enlarged by clicking on them. + +## Adding annotations to designs + +When a design image is displayed, you can add annotations to it by clicking on +the image. A badge is added to the image and a form is displayed to start a new +discussion. For example: + + + +When submitted, the form saves a badge linked to the discussion on the image. Different discussions have different badge numbers. For example: + + diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 987c16dfab6..bd3298497d2 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -4,30 +4,32 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. -Due dates can be used in issues to keep track of deadlines and make sure -features are shipped on time. Due dates require at least [Reporter permissions](../../permissions.md#project-members-permissions) -to be able to edit them. On the contrary, they can be seen by everybody. +Due dates can be used in issues to keep track of deadlines and make sure features are +shipped on time. Users must have at least [Reporter permissions](../../permissions.md) +to be able to edit them, but they can be seen by everybody with permission to view +the issue. ## Setting a due date -When creating or editing an issue, you can see the due date field from where -a calendar will appear to help you choose the date you want. To remove it, -select the date text and delete it. +When creating or editing an issue, you can click in the **due date** field and a calendar +will appear to help you choose the date you want. To remove the date, select the date +text and delete it. The date is related to the server's timezone, not the timezone of +the user setting the due date.  -A quicker way to set a due date is via the issue sidebar. Simply expand the -sidebar and select **Edit** to pick a due date or remove the existing one. +You can also set a due date via the issue sidebar. Expand the +sidebar and click **Edit** to pick a due date or remove the existing one. Changes are saved immediately.  ## Making use of due dates -Issues that have a due date can be distinctively seen in the issue tracker +Issues that have a due date can be easily seen in the issue tracker, displaying a date next to them. Issues where the date is overdue will have the icon and the date colored red. You can sort issues by those that are -_Due soon_ or _Due later_ from the dropdown menu in the right. +`Due soon` or `Due later` from the dropdown menu on the right.  @@ -36,14 +38,13 @@ Due dates also appear in your [todos list](../../../workflow/todos.md).  The day before an open issue is due, an email will be sent to all participants -of the issue. Both the due date and the day before are calculated using the +of the issue. Like the due date, the "day before the due date" is determined by the server's timezone. Issues with due dates can also be exported as an iCalendar feed. The URL of the feed can be added to calendar applications. The feed is accessible by clicking -on the _Subscribe to calendar_ button on the following pages: +on the **Subscribe to calendar** button on the following pages: -- on the **Assigned Issues** page that is linked on the right-hand side of the - GitLab header +- on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header - on the **Project Issues** page - on the **Group Issues** page diff --git a/doc/user/project/issues/img/adding_note_to_design_1.png b/doc/user/project/issues/img/adding_note_to_design_1.png Binary files differnew file mode 100644 index 00000000000..aa50bbb69ce --- /dev/null +++ b/doc/user/project/issues/img/adding_note_to_design_1.png diff --git a/doc/user/project/issues/img/adding_note_to_design_2.png b/doc/user/project/issues/img/adding_note_to_design_2.png Binary files differnew file mode 100644 index 00000000000..37cefeb1a15 --- /dev/null +++ b/doc/user/project/issues/img/adding_note_to_design_2.png diff --git a/doc/user/project/issues/img/comment-or-discussion.png b/doc/user/project/issues/img/comment-or-discussion.png Binary files differindex ccecc9fa39f..a29014c984c 100644 --- a/doc/user/project/issues/img/comment-or-discussion.png +++ b/doc/user/project/issues/img/comment-or-discussion.png diff --git a/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png b/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png Binary files differnew file mode 100644 index 00000000000..1f4ad5c42bb --- /dev/null +++ b/doc/user/project/issues/img/confidential_mr_branch_dropdown_v12_1.png diff --git a/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png b/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png Binary files differnew file mode 100644 index 00000000000..7b7bd599a71 --- /dev/null +++ b/doc/user/project/issues/img/confidential_mr_dropdown_v12_1.png diff --git a/doc/user/project/issues/img/create_mr_from_issue.png b/doc/user/project/issues/img/create_mr_from_issue.png Binary files differindex 680c42b5df0..d05a678cd17 100644 --- a/doc/user/project/issues/img/create_mr_from_issue.png +++ b/doc/user/project/issues/img/create_mr_from_issue.png diff --git a/doc/user/project/issues/img/design_management_v12_2.png b/doc/user/project/issues/img/design_management_v12_2.png Binary files differnew file mode 100644 index 00000000000..ad803df4e63 --- /dev/null +++ b/doc/user/project/issues/img/design_management_v12_2.png diff --git a/doc/user/project/issues/img/issues_main_view_numbered.png b/doc/user/project/issues/img/issues_main_view_numbered.png Binary files differindex 16cb6b497b0..92b9df44972 100644 --- a/doc/user/project/issues/img/issues_main_view_numbered.png +++ b/doc/user/project/issues/img/issues_main_view_numbered.png diff --git a/doc/user/project/issues/img/link_zoom_call_in_issue.png b/doc/user/project/issues/img/link_zoom_call_in_issue.png Binary files differnew file mode 100644 index 00000000000..3153a0a9b07 --- /dev/null +++ b/doc/user/project/issues/img/link_zoom_call_in_issue.png diff --git a/doc/user/project/issues/img/reopen-issue.png b/doc/user/project/issues/img/reopen-issue.png Binary files differindex 1749be31239..fc48742afe0 100644 --- a/doc/user/project/issues/img/reopen-issue.png +++ b/doc/user/project/issues/img/reopen-issue.png diff --git a/doc/user/project/issues/img/report-abuse.png b/doc/user/project/issues/img/report-abuse.png Binary files differindex f189cbf1d36..f8cef22da03 100644 --- a/doc/user/project/issues/img/report-abuse.png +++ b/doc/user/project/issues/img/report-abuse.png diff --git a/doc/user/project/issues/img/show-all-activity.png b/doc/user/project/issues/img/show-all-activity.png Binary files differindex c43ba75ce25..55c6f5ab5db 100644 --- a/doc/user/project/issues/img/show-all-activity.png +++ b/doc/user/project/issues/img/show-all-activity.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 76dc6e49bce..bf04ed2d2d0 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -6,8 +6,9 @@ Issues are the fundamental medium for collaborating on ideas and planning work i The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, and planning work. -Issues can allow you, your team, and your collaborators to share and discuss proposals before and during their implementation. -However, they can be used for a variety of other purposes, customized to your needs and workflow. +Issues can allow you, your team, and your collaborators to share and discuss proposals +before, and during, their implementation. However, they can be used for a variety of +other purposes, customized to your needs and workflow. Issues are always associated with a specific project, but if you have multiple projects in a group, you can also view all the issues collectively at the group level. @@ -17,13 +18,15 @@ you can also view all the issues collectively at the group level. - Discussing the implementation of a new idea - Tracking tasks and work status - Accepting feature proposals, questions, support requests, or bug reports -- Elaborating new code implementations +- Elaborating on new code implementations -See also the blog post "[Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/)". +See also [Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/). ## Parts of an issue -Issues contain a variety of content and metadata, enabling a large range of flexibility in how they are used. Each issue can contain the following attributes, though some items may remain unset. +Issues contain a variety of content and metadata, enabling a large range of flexibility +in how they are used. Each issue can contain the following attributes, though not all items +must be set. <table class="borderless-table fixed-table"> <tr> @@ -70,68 +73,99 @@ Issues contain a variety of content and metadata, enabling a large range of flex ## Viewing and managing issues -While you can view and manage the full detail of an issue at its URL, you can also work with multiple issues at a time using the Issues List, Issue Boards, Epics **[ULTIMATE]**, and issue references. +While you can view and manage the full details of an issue on the [issue page](#issue-page), +you can also work with multiple issues at a time using the [Issues List](#issues-list), +[Issue Boards](#issue-boards), Issue references, and [Epics](#epics-ultimate)**(ULTIMATE)**. + +Key actions for Issues include: + +- [Creating issues](managing_issues.md#create-a-new-issue) +- [Moving issues](managing_issues.md#moving-issues) +- [Closing issues](managing_issues.md#closing-issues) +- [Deleting issues](managing_issues.md#deleting-issues) ### Issue page  -On an issue’s page, you can view all aspects of the issue, and you can also modify them if you you have the necessary [permissions](../../permissions.md). - -For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page. +On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md), +and modify them if you have the necessary [permissions](../../permissions.md). ### Issues list  -On the Issues List, you can view all issues in the current project, or from multiple projects when opening the Issues List from the higher-level group context. Filter the issue list by [any search query](../../search/index.md#issues-and-merge-requests-per-project) and/or specific metadata, such as label(s), assignees(s), status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. +On the Issues List, you can view all issues in the current project, or from multiple +projects when opening the Issues List from the higher-level group context. Filter the +issue list with a [search query](../../search/index.md#issues-and-merge-requests-per-project), +including specific metadata, such as label(s), assignees(s), status, and more. From this +view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. -For more information on interacting with Issues, see the [Issue Data and Actions](issue_data_and_actions.md) page. +For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page +for a rundown of all the fields and information in an issue. -For sorting by issue priority, see [Label Priority](../labels.md#label-priority). +You can sort a list of issues several ways, including by issue creation date, milestone due date, +etc. For more information, see the [Sorting and Ordering Issue Lists](sorting_issue_lists.md) page. ### Issue boards  -Issue boards are Kanban boards with columns that display issues based on their labels or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using highly customizable workflows. - -You can reorder issues within a column, or drag an issue card to another column; its associated label or assignee will change to match that of the new column. The entire board can also be filtered to only include issues from a certain milestone or an overarching label. +[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their labels +or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using +highly customizable workflows. -For more information, see the [Issue Boards](../issue_board.md) page. +You can reorder issues within a column. If you drag an issue card to another column, its +associated label or assignee will change to match that of the new column. The entire +board can also be filtered to only include issues from a certain milestone or an overarching +label. -### Epics **[ULTIMATE]** +### Design Management **(PREMIUM)** -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. +With [Design Management](design_management.md), you can upload design +assets to issues and view them all together to easily share and +collaborate with your team. -For more information, see the [Epics](../../group/epics/index.md) page. +### Epics **(ULTIMATE)** -### Related issues **[STARTER]** +[Epics](../../group/epics/index.md) 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. -You can mark two issues as related, so that when viewing each one, the other is always listed in its Related Issues section. This can help display important context, such as past work, dependencies, or duplicates. +### Related issues **(STARTER)** -For more information, see [Related Issues](related_issues.md). +You can mark two issues as related, so that when viewing one, the other is always +listed in its [Related Issues](related_issues.md) section. This can help display important +context, such as past work, dependencies, or duplicates. ### Crosslinking issues -When you reference an issue from another issue or merge request by including its URL or ID, the referenced issue displays a message in the Activity stream about the reference, with a link to the other issue or MR. +You can [crosslink issues](crosslinking_issues.md) by referencing an issue from another +issue or merge request by including its URL or ID. The referenced issue displays a +message in the Activity stream about the reference, with a link to the other issue or MR. -For more information, see [Crosslinking issues](crosslinking_issues.md). +### Similar issues -## Issue actions +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866) in GitLab 11.6. -- [Create an issue](create_new_issue.md) -- [Create an issue from a template](../../project/description_templates.md#using-the-templates) -- [Close an issue](closing_issues.md) -- [Move an issue](moving_issues.md) -- [Delete an issue](deleting_issues.md) -- [Create a merge request from an issue](issue_data_and_actions.md#22-create-merge-request) +To prevent duplication of issues for the same topic, GitLab searches for similar issues +when new issues are being created. + +When typing in the title in the **New Issue** page, GitLab searches titles and descriptions +across all issues the user has access to in the current project. Up 5 similar issues, +sorted by most recently updated, are displayed below the title box. Note that this feature +requires [GraphQL](../../../api/graphql/index.md) to be enabled. -## Advanced issue management + -- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues in order to change their status, assignee, milestone, or labels in bulk. +## Other Issue actions + +- [Create an issue from a template](../../project/description_templates.md#using-the-templates) +- [Set a due date](due_dates.md) +- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues + in order to change their status, assignee, milestone, or labels in bulk. - [Import issues](csv_import.md) -- [Export issues](csv_export.md) **[STARTER]** +- [Export issues](csv_export.md) **(STARTER)** - [Issues API](../../../api/issues.md) -- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, -or Bugzilla. +- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) + such as Jira, Redmine, or Bugzilla. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index da585022263..d7d168710ef 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -39,16 +39,24 @@ after it is closed.  -#### 2. Todos +#### 2. To Do -You can click **add todo** to add the issue to your [GitLab Todo](../../../workflow/todos.md) -list. If it is already on your todo list, the buttom will show **mark todo as done**, -which you can click to mark that issue as done (which will be reflected in the Todo list). +You can add issues to and remove issues from your [GitLab To-Do List](../../../workflow/todos.md). + +The button to do this has a different label depending on whether the issue is already on your To-Do List or not. If the issue is: + +- Already on your To-Do List: The button is labeled **Mark as done**. Click the button to remove the issue from your To-Do List. +- Not on your To-Do List: The button is labelled **Add a To Do**. Click the button to add the issue to your To-Do List. #### 3. Assignee -An issue can be assigned to yourself, another person, or [many people](#31-multiple-assignees-STARTER). -The assignee(s) can be changed as much as needed. The idea is that the assignees are +An issue can be assigned to: + +- Yourself. +- Another person. +- [Many people](#31-multiple-assignees-STARTER). **(STARTER)** + +The assignee(s) can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. When assigned to someone, it will appear in their assigned issues list. @@ -56,7 +64,7 @@ TIP: **Tip:** If a user is not member of that project, it can only be assigned to them if they created the issue themselves. -##### 3.1. Multiple Assignees **[STARTER]** +##### 3.1. Multiple Assignees **(STARTER)** Often multiple people work on the same issue together, which can be especially difficult to track in large teams where there is shared ownership of an issue. @@ -64,7 +72,7 @@ to track in large teams where there is shared ownership of an issue. In [GitLab Starter](https://about.gitlab.com/pricing/), you can [assign multiple people](multiple_assignees_for_issues.md) to an issue. -#### 4. Epic **[ULTIMATE]** +#### 4. Epic **(ULTIMATE)** You can assign issues to an [Epic](../../group/epics/index.md), which allows better management of groups of related issues. @@ -99,7 +107,7 @@ TIP: **Tip:** If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu from which you can select **Create new label**. -#### 9. Weight **[STARTER]** +#### 9. Weight **(STARTER)** [Assign a weight](../../../workflow/issue_weight.md) to an issue. Larger values are used to indicate more effort is required to complete the issue. Only @@ -113,13 +121,13 @@ issue boards or the issue list. #### 11. Lock issue -You can [lock the discussions](../../discussions/index.md#lock-discussions) in the issue, +You can [lock the threads](../../discussions/index.md#lock-discussions) in the issue, to prevent further comments from being added. #### 12. Participants -All the users involved in that issue. Either they participated in the [discussion](../../discussions/index.md), -or were mentioned in the description or discussions. +All the users involved in that issue. Either they participated in the [thread](../../discussions/index.md), +or were mentioned in the description or threads. #### 13. Notifications @@ -149,6 +157,19 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. +##### Zoom call links + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/62966) in GitLab 12.0. + +Including a link to a [Zoom](https://zoom.us) call in the description of an issue +results in a **Join Zoom meeting** button at the top of the issue, just under the header. + +For example: + + + +To remove the button, edit the description and remove the Zoom call link. + #### 17. Mentions You can mention a user or a group present in your GitLab instance with `@username` or @@ -164,15 +185,15 @@ TIP: **Tip:** Avoid mentioning `@all` in issues and merge requests, as it sends an email notification to all the members of that project's group, which can be interpreted as spam. -#### 18. Related Issues **[STARTER]** +#### 18. Related Issues **(STARTER)** Issues that were mentioned as [related issues](related_issues.md) are listed here. You can also click the `+` to add more related issues. #### 19. Related Merge Requests -Merge requests that were mentioned in that issue's description or in the issue discussion -thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. +Merge requests that were mentioned in that issue's description or in the issue thread +are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. Also, if the current issue was mentioned as related in another merge request, that merge request will be listed here. @@ -184,14 +205,22 @@ dropdown list of available [GitLab Flavored Markdown Emoji](../../markdown.md#em TIP: **Tip:** Posting "+1" as a comment in a thread spams all subscribed participants of that issue, -clutters the discussion threads, and is not recommended. Awarding an emoji is a way +clutters the threads, and is not recommended. Awarding an emoji is a way to let them know your reaction without spamming them. #### 21. Show all activity You can filter what is displayed in the issue history by clicking on **Show all activity** -and selecting either **Show comments only**, which only shows discussions and hides -updates to the issue, or **Show history only**, which hides discussions and only shows updates. +and selecting either **Show comments only**, which only shows threads and hides +updates to the issue, or **Show history only**, which hides threads and only shows updates. + +- You can mention a user or a group present in your GitLab instance with + `@username` or `@groupname` and they will be notified via To-Do items + and email, unless they have [disabled all notifications](#13-notifications) + in their profile settings. +- Mentions for yourself (the current logged in user), will be highlighted + in a different color, allowing you to easily see which comments involve you, + helping you focus on them quickly.  @@ -218,15 +247,15 @@ filtered, as shown above. Collaborate in the issue by posting comments in its thread. This text field also fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). -#### 25. Submit Comment, start a discussion, or comment and close +#### 25. Submit Comment, start a thread, or comment and close Once you write a comment, you can: - Click **Comment** and your comment will be published. -- Choose **Start discussion** from the dropdown list and start a new [discussion thread](../../discussions/index.md#threaded-discussions) +- Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) within that issue's main thread to discuss specific points. This invites other participants - to reply directly to your discussion, keeping related comments grouped together. + to reply directly to your thread, keeping related comments grouped together. - + You can also close the issue from here, so you don't need to scroll to the top of the issue page. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md new file mode 100644 index 00000000000..e9b4e591384 --- /dev/null +++ b/doc/user/project/issues/managing_issues.md @@ -0,0 +1,227 @@ +# Managing Issues + +[GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and +planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues), +[closing](#closing-issues), and [deleting](#deleting-issues) are key actions that +you can do with issues. + +## Create a new Issue + +When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md#parts-of-an-issue), as illustrated below. If you know +the values you want to assign to an issue, you can use the [Quick actions](../quick_actions.md) +feature to input values, instead of selecting them from lists. + + + +### Accessing the new Issue form + +There are many ways to get to the new Issue form from within a project: + +- Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: + +  + +- From an **opened issue** in your project, click **New Issue** to create a new + issue in the same project: + +  + +- From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown + menu with a few options. Select **New Issue** to create an issue in that project: + +  + +- From an **Issue Board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. + It opens a new issue for that project, pre-labeled with its respective list. + +  + +### New issue from the group-level Issue Tracker + +Go 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 Service Desk **(PREMIUM)** + +Enable [Service Desk](../service_desk.md) for 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 via email + +A link to **Email a new issue to this project** is displayed at the bottom of a project's +**Issues List** page, if your GitLab instance has [incoming email](../../../administration/incoming_email.md) +configured. + + + +When you click this link, an email address is generated and displayed, which should be used +by **you only**, to create issues in this project. You can save this address as a +contact in your email client for easy acceess. + +CAUTION: **Caution:** +This is a private email address, generated just for you. **Keep it to yourself**, +as anyone who knows it can create issues or merge requests as if they +were you. If the address is compromised, or you'd like it to be regenerated for +any reason, click **Email a new issue to this project** again and click the reset link. + +Sending an email to this address will create a new issue in your name for +this project, where: + +- The email subject becomes the issue title. +- The email body becomes the issue description. +- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. + +NOTE: **Note:** +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 URL with prefilled fields + +You can link directly to the new issue page for a given project, with prefilled +field values using query string parameters in a URL. This is useful for embedding +a URL in an external HTML page, and also certain scenarios where you want the user to +create an issue with certain fields prefilled. + +The title, description, and description template fields can be prefilled using +this method. You cannot pre-fill both the description and description template fields +in the same URL (since a description template also populates the description field). + +Follow these examples to form your new issue URL with prefilled fields. + +- For a new issue in the GitLab Community Edition project with a pre-filled title + and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` +- For a new issue in the GitLab Community Edition project with a pre-filled title + and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` + +## Moving Issues + +Moving an issue will copy it to a new location (project), and close it in the old project, +but it will not be deleted. There will also be a system note added to both issues +indicating where it came from and went to. + +The "Move issue" button is at the bottom of the right-sidebar when viewing the issue. + + + +### Moving Issues in Bulk + +If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. + +To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change **project**, **admin_user** and **target_project** to your values. We do also recommend [creating a backup](../../../raketasks/backup_restore.md#creating-a-backup-of-the-gitlab-system) before attempting any changes in the console. + +```ruby +project = Project.find_by_full_path('full path of the project where issues are moved from') +issues = project.issues +admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues +target_project = Project.find_by_full_path('full path of target project where issues moved to') + +issues.each do |issue| + if issue.state != "closed" && issue.moved_to.nil? + Issues::MoveService.new(project, admin_user).execute(issue, target_project) + else + puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" + end +end; nil +``` + +## Closing Issues + +When you decide that an issue is resolved, or no longer needed, you can close the issue +using the close button: + + + +You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card +from its list and dropping it into the **Closed** list. + + + +### Closing issues automatically + +NOTE: **Note:** +For performance reasons, automatic issue closing is disabled for the very first +push from an existing repository. + +When a commit or merge request resolves one or more issues, it is possible to have +these issues closed automatically when the commit or merge request reaches the project's +default branch. + +If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), +all issues referenced in the matched text will be closed. This happens when the commit +is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch), +or when a commit or merge request is merged into it. + +For example, if `Closes #4, #6, Related to #5` is included in a Merge Request +description, issues `#4` and `#6` will close automatically when the MR is merged, but not `#5`. +Using `Related to` flags `#5` as a [related issue](related_issues.md), +but it will not close automatically. + + + +If the issue is in a different repository than the MR, add the full URL for the issue(s): + +```md +Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> +``` + +#### Default closing pattern + +When not specified, the default issue closing pattern as shown below will be used: + +```bash +((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+) +``` + +This translates to the following keywords: + +- Close, Closes, Closed, Closing, close, closes, closed, closing +- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing +- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving +- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing + +Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's +source code that can match references to: + +- A local issue (`#123`). +- A cross-project issue (`group/project#123`). +- A link to an issue (`https://gitlab.example.com/group/project/issues/123`). + +For example the following commit message: + +``` +Awesome commit message + +Fix #20, Fixes #21 and Closes group/otherproject#22. +This commit is also related to #17 and fixes #18, #19 +and https://gitlab.example.com/group/otherproject/issues/23. +``` + +will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, +as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as it does +not match the pattern. It works with multi-line commit messages as well as one-liners +when used from the command line with `git commit -m`. + +#### Customizing the issue closing pattern **(CORE ONLY)** + +In order to change the default issue closing pattern, GitLab administrators must edit the +[`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) +of your installation. + +## Deleting Issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2982) in GitLab 8.6 + +Users with [project owner permission](../../permissions.md) can delete an issue by +editing it and clicking on the delete button. + + diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md index 8aac2c01444..8331f865b83 100644 --- a/doc/user/project/issues/moving_issues.md +++ b/doc/user/project/issues/moving_issues.md @@ -1,35 +1,5 @@ -# Moving Issues - -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -Moving an issue will close it and duplicate it on the specified project. -There will also be a system note added to both issues indicating where it came from or went to. - -You can move an issue with the "Move issue" button at the bottom of the right-sidebar when viewing the issue. - - - -## Troubleshooting - -### Moving Issues in Bulk - -If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. - -To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change **project**, **admin_user** and **target_project** to your values. We do also recommend [creating a backup](https://docs.gitlab.com/ee/raketasks/backup_restore.html#creating-a-backup-of-the-gitlab-system) before attempting any changes in the console. - -```ruby -project = Project.find_by_full_path('full path of the project where issues are moved from') -issues = project.issues -admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues -target_project = Project.find_by_full_path('full path of target project where issues moved to') - -issues.each do |issue| - if issue.state != "closed" && issue.moved_to.nil? - Issues::MoveService.new(project, admin_user).execute(issue, target_project) - else - puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" - end -end; nil - -``` +--- +redirect_to: 'managing_issues.md#moving-issues' +--- +This document was moved to [another location](managing_issues.md#moving-issues). diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index d1db0790d69..c9efe9f5031 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -1,4 +1,4 @@ -# Multiple Assignees for Issues **[STARTER]** +# Multiple Assignees for Issues **(STARTER)** > **Note:** [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1904) diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index e679ebf86e6..d7178506b64 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -1,4 +1,4 @@ -# Related issues **[STARTER]** +# Related issues **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. @@ -19,7 +19,7 @@ Issues from a different project require additional information like the group and the project name. For example: - same project: `#44` -- same group: `project#44 ` +- same group: `project#44` - different group: `group/project#44` Valid references will be added to a temporary list that you can review. diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md index e90ecd88ec6..9cbac53ee41 100644 --- a/doc/user/project/issues/similar_issues.md +++ b/doc/user/project/issues/similar_issues.md @@ -1,16 +1,5 @@ -# Similar issues +--- +redirect_to: 'index.md#similar-issues' +--- -> [Introduced][ce-22866] in GitLab 11.6. - -Similar issues suggests issues that are similar when new issues are being created. -This features requires [GraphQL] to be enabled. - - - -You can see the similar issues when typing in the title in the new issue form. -This searches both titles and descriptions across all issues the user has access -to in the current project. It then displays the first 5 issues sorted by most -recently updated. - -[GraphQL]: ../../../api/graphql/index.md -[ce-22866]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866 +This document was moved to [another location](index.md#similar-issues). diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md new file mode 100644 index 00000000000..0fe86e6f410 --- /dev/null +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -0,0 +1,30 @@ +# Sorting and Ordering Issue Lists + +You can sort a list of issues several ways, including by issue creation date, milestone due date, +etc. The available sorting options can change based on the context of the list. +For sorting by issue priority, see [Label Priority](../labels.md#label-priority). + +In group and project issue lists, it is also possible to order issues manually, +similar to [issue boards](../issue_board.md#issue-ordering-in-a-list). + +## Manual sorting + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/62178) in GitLab 12.2. + +When you select **Manual** sorting, you can change +the order by dragging and dropping the issues. The changed order will persist. Everyone who visits the same list will see the reordered list, with some exceptions. + +Each issue is assigned a relative order value, representing its relative +order with respect to the other issues in the list. When you drag-and-drop reorder +an issue, its relative order value changes accordingly. + +In addition, any time that issue appears in a manually sorted list, +the updated relative order value will be used for the ordering. This means that +if issue `A` is drag-and-drop reordered to be above issue `B` by any user in +a given list inside your GitLab instance, any time those two issues are subsequently +loaded in any list in the same instance (could be a different project issue list or a +different group issue list, for example), that ordering will be maintained. + +This ordering also affects [issue boards](../issue_board.md#issue-ordering-in-a-list). +Changing the order in an issue list changes the ordering in an issue board, +and vice versa. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 3eca1313a18..cc1274faa2c 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -2,43 +2,52 @@ ## Overview -Labels allow you to categorize issues or merge requests using descriptive titles like `bug`, `feature request`, or `docs`. Each label also has a customizable color. They allow you to quickly and dynamically filter and manage issues or merge requests you care about, and are visible throughout GitLab in most places where issues and merge requests are located. +Labels allow you to categorize issues or merge requests using descriptive titles like +`bug`, `feature request`, or `docs`. Each label also has a customizable color. They +allow you to quickly and dynamically filter and manage issues or merge requests you +care about, and are visible throughout GitLab in most places where issues and merge +requests are located. ## Project labels and group labels In GitLab, you can create project and group labels: - **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. +- **Group labels** can be assigned to any issue or merge request in any project in + that group, or any subgroups of the group. -## Scoped labels **[PREMIUM]** +## 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 +Scoped labels allow teams to use the simple and familiar label feature 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 +A scoped label is a kind of label defined by a special double-colon syntax in the label’s title, using the format `key::value`. For example: - + 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. +For example, if an issue is already labeled `priority::3`, and then you apply the +`priority::2` label to it, `priority::3` is automatically removed. This functionality is demonstrated in a video titled [Use scoped labels in GitLab 11.10 for custom fields and custom workflows](https://www.youtube.com/watch?v=4BCBby6du3c). ### Labels with multiple colon pairs -If labels have multiple instances of `::`, the longest path from left to right, until the last `::`, is considered the "key" or the "scope". +If labels have multiple instances of `::`, the longest path from left to right, until +the last `::`, is considered the "key" or the "scope". -For example, `nested::key1::value1` and `nested::key1::value2` cannot both exist on the same issue. Adding the latter label will automatically remove the former due to the shared scope of `nested::key1`. +For example, `nested::key1::value1` and `nested::key1::value2` cannot both exist on +the same issue. Adding the latter label will automatically remove the former due to +the shared scope of `nested::key1`. -`nested::key1::value1` and `nested::key2::value1` can both exist on the same issue, as these are considered to use two different label scopes, `nested::key1` and `nested::key2`. +`nested::key1::value1` and `nested::key2::value1` can both exist on the same issue, +as these are considered to use two different label scopes, `nested::key1` and `nested::key2`. -### Workflows with scoped labels **[PREMIUM]** +### Workflows with scoped labels 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 @@ -58,101 +67,156 @@ be able to advance workflow states consistently in issues themselves. ## Creating labels ->**Note:** +NOTE: **Note:** A permission level of Reporter or higher is required to create labels. ### New project label To create a **project label**, navigate to **Issues > Labels** in the project. -This page only shows project labels in this project and group labels of this project's parent group. +This page only shows the project labels in this project, and the group labels of the +project's parent group. -Click the **New label** button. Enter the title, an optional description, and the background color. Click **Create label** to create the label. +Click the **New label** button. Enter the title, an optional description, and the +background color. Click **Create label** to create the label. -If a project has no labels, you can generate a default set of project labels from its empty label list page: +If a project has no labels, you can generate a default set of project labels from +its empty label list page: - + GitLab will add the following default labels to the project: - + ### New group label -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. +To create a **group label**, 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 from the Epic sidebar. **(ULTIMATE)** - +Please note that the created label will belong to the immediate group to which the +epic belongs. + + 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 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 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. +To update a label, navigate to **Issues > Labels** in the project or group +and click the pencil icon. The title, description and color can be changed. + +To delete a label, click the three dots next to the `Subscribe` button, and select +**Delete**. -You can delete a label by clicking the trash icon. + ### Promoting project labels to group labels -If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same label among multiple projects in the same group. If you previously created a project label and now want to make it available for other projects, you can promote it to a group label. +If you are expanding from a few projects to a larger number of projects within the +same group, you may want to share the same label among multiple projects in the same +group. If you previously created a project label and now want to make it available +for other projects, you can promote it to a group label. -From the project label list page, you can promote a project label to a group label. This will merge all project labels across all projects in this group with the same name into a single group label. All issues and merge requests that previously were assigned one of these project labels will now be assigned the new group label. This action cannot be reversed and the changes are permanent. +From the project label list page, you can promote a project label to a group label. +This will merge all project labels with the same name into a single group label, across +all projects in this group. All issues and merge requests that were previously +assigned one of these project labels will now be assigned the new group label. This +action cannot be reversed and the changes are permanent. - + ## Assigning labels from the sidebar -Every issue and merge request can be assigned any number of labels. The labels are visible on every issue and merge request page, in the sidebar. They are also visible in the issue board. From the sidebar, you can assign or unassign a label to the object (i.e. label or unlabel it). You can also perform this as a [quick action](quick_actions.md) in a comment. +Every issue and merge request can be assigned any number of labels. The labels are +visible on every issue and merge request page, in the sidebar. They are also visible on: + +- Every issue and merge request page in the sidebar. +- The issue board. + +From the sidebar, you can assign or unassign a label to the object (i.e. label or +unlabel it). You can also perform this as a [quick action](quick_actions.md), +in a comment. | View labels in sidebar | Assign labels from sidebar | -|:---:|:---:| +|:----------------------:|:--------------------------:| |  |  | ## Searching for project labels -You can search for project labels by navigating from the left sidebar to your -project's **Issues > Labels** and entering your query to the search bar on the -top-right: +To search for project labels, go to **Issues > Labels** in the left sidebar, and enter +your search query in the **Filter** field.  -GitLab will consider the label title and description for the search. +GitLab will check both the label titles and descriptions for the search. + +## Filtering by label -## Filtering issues, merge requests and epics by label +The following can be filtered labels: + +- Issue lists +- Merge Request lists +- Epic lists **(ULTIMATE)** +- Issue Boards ### Filtering in list pages -From the project issue list page and the project merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group (including subgroup ancestors) labels and project labels. +- From the project issue list page and the project merge request list page, you can + [filter](../search/index.md#issues-and-merge-requests) by: + - Group labels (including subgroup ancestors) + - Project labels -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 issue list page and the group merge request list page, you can + [filter](../search/index.md#issues-and-merge-requests) by: + - Group labels (including subgroup ancestors and subgroup descendants) + - 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 descendant group labels. +- You can [filter](../search/index.md#issues-and-merge-requests) the group epic list + page by: **(ULTIMATE)** + - Current group labels + - Descendant 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]** +- From [project boards](issue_board.md), you can use the [search and filter bar](../search/index.md#issue-boards) + to filter by: + - Group labels + - Project labels + +- From [group issue boards](issue_board.md#group-issue-boards-premium), you can use the + [search and filter bar](../search/index.md#issue-boards) to filter by group labels only. **(PREMIUM)** + +- From [project boards](issue_board.md), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter), + you can filter by: **(STARTER)** + - Group labels + - Project labels + +- From [group issue boards](issue_board.md#group-issue-boards-premium), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter), + you can filter by group labels only. **(STARTER)** ## Subscribing to labels -From the project label list page and the group label list page, you can subscribe to [notifications](../../workflow/notifications.md) of a given label, to alert you that the label has been assigned to an issue or merge request. +From the project label list page and the group label list page, you can subscribe +to [notifications](../../workflow/notifications.md) of a given label, to alert you +that the label has been assigned to an issue or merge request. - + ## Label priority @@ -161,26 +225,43 @@ From the project label list page and the group label list page, you can subscrib > - Introduced in GitLab 8.9. > - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this. -Labels can have relative priorities, which are used in the "Label priority" and "Priority" sort orders of the issue and merge request list pages. +Labels can have relative priorities, which are used in the "Label priority" and +"Priority" sort orders of the issue and merge request list pages. + +From the project label list page, star a label to indicate that it has a priority. + + + +Drag starred labels up and down the list to change their priority. Higher in the list +means higher priority. Prioritization happens at the project level, only on the project +label list page, and not on the group label list page. -From the project label list page, star a label to indicate that it has a priority. Drag starred labels up and down to change their priority. Higher means higher priority. Prioritization happens at the project level, only on the project label list page, and not on the group label list page. However, both project and group labels can be prioritized on the project label list page since both types are displayed on the project label list page. +However, both project and group +labels can be prioritized on the project label list page since both types are displayed +on the project label list page. - + -On the project and group issue and merge request list pages, you can sort by `Label priority` and `Priority`, which account for objects (issues and merge requests) that have prioritized labels assigned to them. +On the merge request and issue pages, for both groups and projects, you can sort by `Label priority` +and `Priority`, which account for objects (issues and merge requests) that have prioritized +labels assigned to them. If you sort by `Label priority`, GitLab considers this sort comparison order: - Object with a higher priority prioritized label. - Object without a prioritized label. -Ties are broken arbitrarily. (Note that we _only_ consider the highest prioritized label in an object, and not any of the lower prioritized labels. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this.) +Ties are broken arbitrarily. Note that we _only_ consider the highest prioritized label +in an object, and not any of the lower prioritized labels. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) +considers changing this.  If you sort by `Priority`, GitLab considers this sort comparison order: -- Object's assigned [milestone](milestones/index.md)'s due date is sooner, provided the object has a milestone and the milestone has a due date. If this isn't the case, consider the object having a due date in the infinite future. +- Due date of the assigned [milestone](milestones/index.md) is sooner, provided + the object has a milestone and the milestone has a due date. If this isn't the case, + consider the object having a due date in the infinite future. - Object with a higher priority prioritized label. - Object without a prioritized label. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 2a490e3fd7f..e343fd45488 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -10,8 +10,6 @@ or import a new user to your project. To view, edit, add, and remove project's members, go to your project's **Settings > Members**. ---- - ## Add a user Right next to **People**, start typing the name or username of the user you @@ -19,22 +17,16 @@ want to add.  ---- - Select the user and the [permission level](../../permissions.md) that you'd like to give the user. Note that you can select more than one user.  ---- - Once done, hit **Add users to project** and they will be immediately added to your project with the permissions you gave them above.  ---- - From there on, you can either remove an existing user or change their access level to the project. @@ -47,8 +39,6 @@ In the dropdown menu, you can see only the projects you are Maintainer on.  ---- - Select the one you want and hit **Import project members**. A flash message notifying you that the import was successful will appear, and the new members are now in the project's members list. Notice that the permissions that they @@ -56,8 +46,6 @@ had on the project you imported from are retained.  ---- - ## Invite people using their e-mail address If a user you want to give access to doesn't have an account on your GitLab @@ -66,23 +54,17 @@ user search field.  ---- - As you can imagine, you can mix inviting multiple people and adding existing GitLab users to the project.  ---- - Once done, hit **Add users to project** and watch that there is a new member with the e-mail address we used above. From there on, you can resend the invitation, change their access level, or even delete them.  ---- - Once the user accepts the invitation, they will be prompted to create a new GitLab account using the same e-mail address the invitation was sent to. @@ -97,15 +79,11 @@ side of your screen.  ---- - Project owners & maintainers will be notified of your request and will be able to approve or decline it on the members page.  ---- - If you change your mind before your request is approved, just click the **Withdraw Access Request** button. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 611ff0e6bfb..9340d239677 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -20,18 +20,18 @@ To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Settings > Members** -  +  1. Select the 'Share with group' tab 1. Add the 'Engineering' group with the maximum access level of your choice 1. Click **Share** to share it -  +  1. After sharing 'Project Acme' with 'Engineering', the project will be listed on the group dashboard -  +  Note that you can only share a project with: diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index f6c4f767e3c..49b9826a52a 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -2,7 +2,7 @@ type: reference, howto --- -# Browser Performance Testing **[PREMIUM]** +# 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. @@ -19,7 +19,7 @@ tool for measuring the performance of web sites, and has built a simple 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) +The [Sitespeed.io performance score](https://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. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index c3c2bdd94b3..3a409bab19d 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,16 +1,27 @@ --- type: reference, howto +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html' --- -# Code Quality **[STARTER]** +# Code Quality **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. With the help of [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. + +Code Quality: + +- Uses [Code Climate Engines](https://codeclimate.com), which are + free and open source. Code Quality doesn't require a Code Climate + subscription. +- Runs in [pipelines](../../../ci/pipelines.md) using an Docker image built in + [GitLab Code + Quality](https://gitlab.com/gitlab-org/security-products/codequality) project. +- Can make use of a [template](#template-and-examples). +- Is available with [Auto + DevOps](../../../topics/autodevops/index.md#auto-code-quality-starter). Going a step further, GitLab can show the Code Quality report right in the merge request widget area: @@ -21,22 +32,48 @@ in the merge request widget area: For instance, consider the following workflow: -1. Your backend team member starts a new implementation for making a 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 +1. Your backend team member starts a new implementation for making a 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. + +## Template and examples + +For most GitLab instances, the supplied template is the preferred method of +implementing Code Quality. See +[Analyze your project's Code Quality](../../../ci/examples/code_quality.md) for: + +- Information on the builtin GitLab Code Quality template. +- Examples of manual GitLab configuration for earlier GitLab versions. -## How it works +## Configuring jobs using variables -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 job supports environment variables that users can set to +configure job execution at runtime. -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: +For a list of available environment variables, see +[Environment variables](https://gitlab.com/gitlab-org/security-products/codequality/blob/master/README.md#environment-variables). + +## Implementing a custom tool + +It's possible to have a custom tool provide Code Quality reports in GitLab. To +do this: + +1. Define a job in your `.gitlab-ci.yml` file that generates the + [Code Quality report + artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter). +1. Configure your tool to generate the Code Quality report artifact as a JSON + file that implements subset of the [Code Climate + spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types). + +The Code Quality report artifact JSON file must contain an array of objects +with the following properties: | Name | Description | | ---------------------- | -------------------------------------------------------------------------------------- | @@ -63,13 +100,16 @@ Example: ``` NOTE: **Note:** -Although the Code Climate spec supports more properties, those are ignored by GitLab. +Although the Code Climate spec supports more properties, those are ignored by +GitLab. + +## Code Quality reports -For more information on what the Code Quality job should look like, check the -example on [analyzing a project's code quality](../../../ci/examples/code_quality.md). +Once the Code Quality job has completed, GitLab: -GitLab then checks this report, compares the metrics between the source and target -branches, and shows the information right on the merge request. +- Checks the generated report. +- Compares the metrics between the source and target branches. +- Shows the information right on the merge request. 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, diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md index ccc694672a6..0aa108a2e73 100644 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ b/doc/user/project/merge_requests/code_quality_diff.md @@ -1,5 +1,4 @@ --- -redirect_from: 'code_quality_diff.md' redirect_to: 'code_quality.md' --- diff --git a/doc/user/project/merge_requests/img/allow_collaboration.png b/doc/user/project/merge_requests/img/allow_collaboration.png Binary files differindex e40e8a6b11c..cc13493646d 100644 --- a/doc/user/project/merge_requests/img/allow_collaboration.png +++ b/doc/user/project/merge_requests/img/allow_collaboration.png diff --git a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png Binary files differindex 4ba4c84c8c5..bc7678b21ec 100644 --- a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png +++ b/doc/user/project/merge_requests/img/allow_collaboration_after_save.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 differindex b6dc86f312e..2598cc71c33 100644 --- a/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png +++ 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 differindex b6f6188b9cd..6a09412533f 100644 --- a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png +++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit.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 differindex 868b9d58740..4c554d846cc 100644 --- a/doc/user/project/merge_requests/img/approvals_starter_project_edit.png +++ 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 differindex 7375820224c..fc88a59a745 100644 --- a/doc/user/project/merge_requests/img/approvals_starter_project_empty.png +++ 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 differindex e68259ac5c2..e2641f48c7a 100644 --- a/doc/user/project/merge_requests/img/approve.png +++ 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 differindex 3db5a9159e5..bab0cd4e041 100644 --- a/doc/user/project/merge_requests/img/approve_additionally.png +++ b/doc/user/project/merge_requests/img/approve_additionally.png diff --git a/doc/user/project/merge_requests/img/create_from_email.png b/doc/user/project/merge_requests/img/create_from_email.png Binary files differindex 5cb2afaf976..14eef473e27 100644 --- a/doc/user/project/merge_requests/img/create_from_email.png +++ b/doc/user/project/merge_requests/img/create_from_email.png diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png Binary files differnew file mode 100644 index 00000000000..2dc02634fd8 --- /dev/null +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_inaccessible_v12_2.png diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png Binary files differnew file mode 100644 index 00000000000..362e7e0ead2 --- /dev/null +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_edit_v12_2.png diff --git a/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png b/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.png Binary files differnew file mode 100644 index 00000000000..e00231c839b --- /dev/null +++ b/doc/user/project/merge_requests/img/cross_project_dependencies_view_v12_2.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 differindex 9c386391a4f..4c28ee17f47 100644 --- a/doc/user/project/merge_requests/img/filter_approver_merge_requests.png +++ b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png Binary files differindex 8df6a3c9a29..0989b41e2a4 100644 --- a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png +++ b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png diff --git a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png Binary files differnew file mode 100644 index 00000000000..ee94dbdea5c --- /dev/null +++ b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png Binary files differindex ea3aff59aa1..ed374b11fbd 100644 --- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png +++ b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png diff --git a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png b/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png Binary files differindex 9ae6e350798..dde2680ed74 100644 --- a/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.png +++ b/doc/user/project/merge_requests/img/multiple_assignees_for_merge_requests_sidebar.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 differindex 6083e1745ef..b178d26cf85 100644 --- a/doc/user/project/merge_requests/img/remove_approval.png +++ b/doc/user/project/merge_requests/img/remove_approval.png diff --git a/doc/user/project/merge_requests/img/squash_mr_message.png b/doc/user/project/merge_requests/img/squash_mr_message.png Binary files differindex 8734cab29aa..8c7dc7886f7 100644 --- a/doc/user/project/merge_requests/img/squash_mr_message.png +++ b/doc/user/project/merge_requests/img/squash_mr_message.png diff --git a/doc/user/project/merge_requests/img/wip_blocked_accept_button.png b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png Binary files differindex b6d38d85165..ab2c8425b83 100644 --- a/doc/user/project/merge_requests/img/wip_blocked_accept_button.png +++ b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 447b338928c..2794cbc0f39 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -18,12 +18,12 @@ It is as simple as the name implies: a _request_ to _merge_ one branch into anot With GitLab merge requests, you can: - Compare the changes between two [branches](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching) -- [Review and discuss](../../discussions/index.md#discussions) the proposed modifications inline +- [Review and discuss](../../discussions/index.md#threads) the proposed modifications inline - Live preview the changes when [Review Apps](../../../ci/review_apps/index.md) is configured for your project - Build, test, and deploy your code in a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md) - Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests) - View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines) -- [Automatically close the issue(s)](../../project/issues/closing_issues.md#via-merge-request) that originated the implementation proposed in the merge request +- [Automatically close the issue(s)](../../project/issues/managing_issues.md#closing-issues-automatically) that originated the implementation proposed in the merge request - 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) @@ -37,16 +37,17 @@ With GitLab merge requests, you can: With **[GitLab Enterprise Edition][ee]**, you can also: -- Prepare a full review and submit it once it's ready with [Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) **[PREMIUM]** -- View the deployment process across projects with [Multi-Project Pipelines](../../../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](../../application_security/license_management/index.md) **[ULTIMATE]** -- Analyze your source code for vulnerabilities with [Static Application Security Testing](../../application_security/sast/index.md) **[ULTIMATE]** -- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](../../application_security/dast/index.md) **[ULTIMATE]** -- Analyze your dependencies for vulnerabilities with [Dependency Scanning](../../application_security/dependency_scanning/index.md) **[ULTIMATE]** -- Analyze your Docker images for vulnerabilities with [Container Scanning](../../application_security/container_scanning/index.md) **[ULTIMATE]** -- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **[PREMIUM]** +- Prepare a full review and submit it once it's ready with [Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) **(PREMIUM)** +- View the deployment process across projects with [Multi-Project Pipelines](../../../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](../../application_security/license_management/index.md) **(ULTIMATE)** +- Analyze your source code for vulnerabilities with [Static Application Security Testing](../../application_security/sast/index.md) **(ULTIMATE)** +- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](../../application_security/dast/index.md) **(ULTIMATE)** +- Analyze your dependencies for vulnerabilities with [Dependency Scanning](../../application_security/dependency_scanning/index.md) **(ULTIMATE)** +- Analyze your Docker images for vulnerabilities with [Container Scanning](../../application_security/container_scanning/index.md) **(ULTIMATE)** +- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **(PREMIUM)** +- Specify merge order dependencies with [Cross-project Merge Request Dependencies](#cross-project-merge-request-dependencies-premium) **(PREMIUM)** ## Use cases @@ -54,9 +55,9 @@ 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 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 avoid using dependencies whose license is not compatible with your project with [License Management reports](license_management.md) **[ULTIMATE]** +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 @@ -68,7 +69,7 @@ B. Consider you're a web developer writing a webpage for your company's website: 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](merge_request_approvals.md) 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 @@ -155,13 +156,13 @@ and remember to merge the request manually. [Learn more about merging when pipeline succeeds.](merge_when_pipeline_succeeds.md) -## Resolve discussion comments in merge requests reviews +## Resolve threads in merge requests reviews Keep track of the progress during a code review with resolving comments. Resolving comments prevents you from forgetting to address feedback and lets -you hide discussions that are no longer relevant. +you hide threads that are no longer relevant. -[Read more about resolving discussion comments in merge requests reviews.](../../discussions/index.md) +[Read more about resolving threads in merge requests reviews.](../../discussions/index.md) ## Commenting on any file line in merge requests @@ -172,7 +173,7 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg  -## Perform a Review **[PREMIUM]** +## 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 @@ -192,12 +193,12 @@ commit when merging, to allow for a neater commit history. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. As a reviewer, you can add suggestions to change the content in -merge request discussions, and users with appropriate [permission](../../permissions.md) +merge request threads, and users with appropriate [permission](../../permissions.md) can easily apply them to the codebase directly from the UI. Read through the documentation on [Suggest changes](../../discussions/index.md#suggest-changes) to learn more. -## Multiple assignees **[STARTER]** +## Multiple assignees **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing). @@ -274,7 +275,8 @@ branch already exists, the patches will be applied on top of it. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26752) in GitLab 11.10. NOTE: **Note:** -Git push options are only available with Git 2.10 or newer. +Git push options are only available with Git 2.10 or newer. With Git older than 2.18 +`git push --push-option=...` should be used instead of `git push -o ...`. GitLab supports using [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) @@ -284,6 +286,9 @@ as pushing changes: - Create a new merge request for the pushed branch. - Set the target of the merge request to a particular branch. - Set the merge request to merge when its pipeline succeeds. +- Set the merge request to remove the source branch when it's merged. +- Set the title of the merge request to a particular title. +- Set the description of the merge request to a particular description. ### Create a new merge request using git push options @@ -327,6 +332,49 @@ pipeline succeeds at the same time using a `-o` flag per push option: git push -o merge_request.create -o merge_request.merge_when_pipeline_succeeds ``` +### Set removing the source branch using git push options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2. + +To set an existing merge request to remove the source branch when the +merge request is merged, the +`merge_request.remove_source_branch` push option can be used: + +```sh +git push -o merge_request.remove_source_branch +``` + +You can also use this push option in addition to the +`merge_request.create` push option. + +### Set merge request title using git push options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2. + +To set the title of an existing merge request, use +the `merge_request.title` push option: + +```sh +git push -o merge_request.title="The title I want" +``` + +You can also use this push option in addition to the +`merge_request.create` push option. + +### Set merge request description using git push options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/64320) in GitLab 12.2. + +To set the description of an existing merge request, use +the `merge_request.description` push option: + +```sh +git push -o merge_request.description="The description I want" +``` + +You can also use this push option in addition to the +`merge_request.create` push option. + ## Find the merge request that introduced a change > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2383) in GitLab 10.5. @@ -364,7 +412,12 @@ 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]** +## Merge Requests for Confidential Issues + +Create [merge requests to resolve confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) +for preventing leakage or early release of sentive data through regular merge requests. + +## Merge request approvals **(STARTER)** > Included in [GitLab Starter][products]. @@ -375,7 +428,7 @@ 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]** +## Code Quality **(STARTER)** > Introduced in [GitLab Starter][products] 9.3. @@ -385,7 +438,18 @@ 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]** +## Metrics Reports **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9788) in [GitLab Premium][products] 11.10. +Requires GitLab Runner 11.10 and above. + +If you are using [GitLab CI][ci], you can configure your job to output custom +metrics and GitLab will display the Metrics Report on the merge request so +that it's fast and easy to identify changes to important metrics. + +[Read more about Metrics Report](../../../ci/metrics_reports.md). + +## Browser Performance Testing **(PREMIUM)** > Introduced in [GitLab Premium][products] 10.3. @@ -395,7 +459,22 @@ GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the d [Read more about Browser Performance Testing.](browser_performance_testing.md) -## Security reports **[ULTIMATE]** +## Cross-project Merge Request Dependencies **(PREMIUM)** + +> Introduced in [GitLab Premium][products] 12.2. + +A single logical change may be split across several merge requests, across +several projects. When this happens, the order in which MRs are merged is +important. + +GitLab allows you to specify that a merge request depends on other MRs. With +this relationship in place, the merge request cannot be merged until all of its +dependencies have also been merged, helping to maintain the consistency of a +single logical change. + +[Read more about cross-project merge request dependencies.](merge_request_dependencies.md) + +## Security reports **(ULTIMATE)** GitLab can scan and report any vulnerabilities found in your project. @@ -409,15 +488,6 @@ without having to check the entire job log. [Read more about JUnit test reports](../../../ci/junit_test_reports.md). -## 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 @@ -427,6 +497,15 @@ list.  +### Incrementally expand merge request diffs + +By default, the diff shows only the parts of a file which are changed. +To view more unchanged lines above or below a change click on the +**Expand up** or **Expand down** icons. You can also click on **Show all lines** +to expand the entire file. + + + ## Ignore whitespace changes in Merge Request diff view If you click the **Hide whitespace changes** button, you can see the diff diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index fd151a6df45..5161b25de99 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -2,7 +2,7 @@ type: reference, concepts --- -# Merge request approvals **[STARTER]** +# 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). @@ -12,9 +12,9 @@ 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. +1. Specifying code maintainers for an entire repository. +1. Specifying reviewers for a given proposed code change. +1. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes. ## Enabling the new approvals interface @@ -44,7 +44,7 @@ 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) @@ -54,7 +54,7 @@ To edit the merge request approvals: 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 @@ -64,7 +64,7 @@ suitable to your workflow: [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]** +## Editing approvals **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. @@ -83,9 +83,9 @@ request approval rules: 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]** +## Multiple approval rules **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. @@ -144,14 +144,17 @@ the following is possible: - 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 @@ -159,13 +162,13 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei 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 +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) +[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved) or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). -## Code Owners approvals **[PREMIUM]** +## Code Owners approvals **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. @@ -203,7 +206,7 @@ First, you have to enable this option in the project's settings: 1. Tick the "Can override approvers and approvals required per merge request" checkbox -  +  1. Click **Save changes** @@ -226,27 +229,16 @@ The default approval settings can now be overridden when creating a 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]** +## 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. +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, +approval rules can be added to an MR with no restriction. ## Resetting approvals on push @@ -259,7 +251,7 @@ new commits are pushed to the source branch of the merge request: 1. Tick the "Remove all approvals in a merge request when new commits are pushed to its source branch" checkbox -  +  1. Click **Save changes** @@ -295,7 +287,7 @@ enabling [**Prevent approval of merge requests by their committers**](#prevent-a 1. Tick the checkbox **Prevent approval of merge requests by their committers**. 1. Click **Save changes**. -## Require authentication when approving a merge request **[STARTER]** +## Require authentication when approving a merge request **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. @@ -331,6 +323,16 @@ the dropdown) `approver` and select the user.  +## Security approvals in merge requests **(ULTIMATE)** + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 12.2. + +Merge Request Approvals can be configured to require approval from a member +of your security team when a vulnerability would be introduced by a merge request. + +For more information, see +[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests-ultimate). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md new file mode 100644 index 00000000000..b30e24b2386 --- /dev/null +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -0,0 +1,142 @@ +--- +type: reference, concepts +--- + +# Cross-project Merge Request dependencies **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +Cross-project merge request dependencies allows a required order of merging +between merge requests in different projects to be expressed. If a +merge request "depends on" another, then it cannot be merged until its +dependency is itself merged. + +NOTE: **Note:** +Merge requests dependencies are a **PREMIUM** feature, but this restriction is +only enforced for the dependent merge request. A merge request in a **CORE** or +**STARTER** project can be a dependency of a **PREMIUM** merge request, but not +vice-versa. + +NOTE: **Note:** +A merge request can only depend on merge requests in a different project. Two +merge requests in the same project cannot depend on each other. + +## Use cases + +- Ensure changes to a library are merged before changes to a project that + imports the library. +- Prevent a documentation-only merge request from being merged before the merge request + implementing the feature to be documented. +- Require an merge request updating a permissions matrix to be merged before merging an + merge request from someone who hasn't yet been granted permissions. + +It is common for a single logical change to span several merge requests, spread +out across multiple projects, and the order in which they are merged can be +significant. + +For example, given a project `mycorp/awesome-project` that imports a library +at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also** +require changes to `awesome-lib`, and so necessitate two merge requests. Merging +the `awesome-project` merge request before the `awesome-lib` one would +break the `master`branch. + +The `awesome-project` merge request could be [marked as +WIP](work_in_progress_merge_requests.md), +and the reason for the WIP stated included in the comments. However, this +requires the state of the `awesome-lib` merge request to be manually +tracked, and doesn't scale well if the `awesome-project` merge request +depends on changes to **several** other projects. + +By making the `awesome-project` merge request depend on the +`awesome-lib` merge request instead, this relationship is +automatically tracked by GitLab, and the WIP state can be used to +communicate the readiness of the code in each individual merge request +instead. + +## Configuration + +To continue the above example, you can configure a dependency when creating the +new merge request in `awesome-project` (or by editing it, if it already exists). +The dependency needs to be configured on the **dependent** merge +request. There is a "Cross-project dependencies" section in the form: + + + +Anyone who can edit a merge request can change the list of dependencies. + +New dependencies can be added by reference, or by URL. To remove a dependency, +press the **X** by its reference. + +As dependencies are specified across projects, it's possible that someone else +has added a dependency for a merge request in a project you don't have access to. +These are shown as a simple count: + + + +If necessary, you can remove all the dependencies like this by pressing the +**X**, just as you would for a single, visible dependency. + +Once you're finished, press the **Save changes** button to submit the request, +or **Cancel** to return without making any changes. + +The list of configured dependencies, and the status of each one, is shown in the +merge request widget: + + + +Until all dependencies have, themselves, been merged, the **Merge** +button will be disabled for the dependent merge request. In +particular, note that **closed merge requests** still prevent their +dependents from being merged - it is impossible to automatically +determine whether the dependency expressed by a closed merge request +has been satisfied in some other way or not. + +If a merge request has been closed **and** the dependency is no longer relevant, +it must be removed as a dependency, following the instructions above, before +merge. + +## Limitations + +- API support: [gitlab-ee#12551](https://gitlab.com/gitlab-org/gitlab-ee/issues/12551) +- Dependencies are not preserved across project export/import: [gitlab-ee#12549](https://gitlab.com/gitlab-org/gitlab-ee/issues/12549) +- Complex merge order dependencies are not supported: [gitlab-ee#11393](https://gitlab.com/gitlab-org/gitlab-ee/issues/11393) + +The last item merits a little more explanation. Dependencies between merge +requests can be described as a graph of relationships. The simplest possible +graph has one merge request that depends upon another: + +```mermaid +graph LR; + myfriend/awesome-lib!10-->mycorp/awesome-project!100; +``` + +A more complex (and still supported) graph might have one merge request that +directly depends upon several others: + +```mermaid +graph LR; + myfriend/awesome-lib!10-->mycorp/awesome-project!100; + herfriend/another-lib!1-->mycorp/awesome-project!100; +``` + +Several different merge requests can also directly depend upon the +same merge request: + +```mermaid +graph LR; + herfriend/another-lib!1-->myfriend/awesome-lib!10; + herfriend/another-lib!1-->mycorp/awesome-project!100; +``` + +What is **not** supported is a "deep", or "nested" graph of dependencies, e.g.: + +```mermaid +graph LR; + herfriend/another-lib!1-->myfriend/awesome-lib!10; + myfriend/awesome-lib!10-->mycorp/awesome-project!100; +``` + +In this example, `myfriend/awesome-lib!10` depends on `herfriend/another-lib!1`, +and is itself a dependent of `mycorp/awesome-project!100`. This means that +`myfriend/awesome-lib!10` becomes an **indirect** dependency of +`mycorp/awesome-project!100`, which is not yet supported. diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index c93c7a5fe08..50a4e514d49 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -36,12 +36,14 @@ changes to be reviewed. ## Only allow merge requests to be merged if the pipeline succeeds You can prevent merge requests from being merged if their pipeline did not succeed -or if there are discussions to be resolved. +or if there are threads to be resolved. Navigate to your project's settings page and expand the **Merge requests** section. In the **Merge checks** subsection, select the **Pipelines must succeed** check box and hit **Save** for the changes to take effect. +NOTE: **Note:** This setting also prevents merge requests from being merged if there is no pipeline. +  From now on, every time the pipeline fails you will not be able to merge the @@ -49,6 +51,21 @@ merge request from the UI, until you make all relevant jobs pass.  +### Limitations + +When this setting is enabled, a merge request is prevented from being merged if there is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#onlyexcept-advanced) rules are used and they don't generate any pipelines. + +Users that expect to be able to merge a merge request in this scenario should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-ce/issues/54226) and that it's succesful. + +For example, to that on merge requests there is always a passing job even though `only/except` rules may not generate any other jobs: + +```yaml +enable_merge: + only: merge_requests + script: + - echo true +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 39fd2588811..38459584eed 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -50,7 +50,10 @@ all you have to do is enable squashing before you press merge to join the commits in the merge request into a single commit. This way, the history of your base branch remains clean with -meaningful commit messages and is simpler to [revert](revert_changes.md) if necessary. +meaningful commit messages and: + +- It's simpler to [revert](revert_changes.md) if necessary. +- The merged branch will retain the full commit history. ## Enabling squash for a merge request diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 9cd868067bc..ea59644fce6 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -5,7 +5,7 @@ type: reference, concepts # "Work In Progress" merge requests If a merge request is not yet ready to be merged, perhaps due to continued development -or open discussions, you can prevent it from being accepted before it's ready by flagging +or open threads, you can prevent it from being accepted before it's ready by flagging it as a **Work In Progress**. This will disable the "Merge" button, preventing it from being merged, and it will stay disabled until the "WIP" flag has been removed. @@ -15,11 +15,11 @@ being merged, and it will stay disabled until the "WIP" flag has been removed. There are several ways to flag a merge request as a Work In Progress: -- Add "[WIP]" or "WIP:" to the start of the merge request's title. Clicking on +- Add `[WIP]` or `WIP:` to the start of the merge request's title. Clicking on **Start the title with WIP:**, under the title box, when editing the merge request's description will have the same effect. - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-and-merge-requests) - in a discussion comment in the merge request. This is a toggle, and can be repeated + in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. - Add "wip" or "WIP" to the start of a commit message targeting the merge request's source branch. This is not a toggle, and doing it again in another commit will have @@ -30,11 +30,11 @@ There are several ways to flag a merge request as a Work In Progress: Similar to above, when a Merge Request is ready to be merged, you can remove the "Work in Progress" flag in several ways: -- Remove "[WIP]" or "WIP:" from the start of the merge request's title. Clicking on +- Remove `[WIP]` or `WIP:` from the start of the merge request's title. Clicking on **Remove the WIP: prefix from the title**, under the title box, when editing the merge request's description, will have the same effect. - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-and-merge-requests) - in a discussion comment in the merge request. This is a toggle, and can be repeated + in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. - Click on the **Resolve WIP status** button near the bottom of the merge request description, next to the "Merge" button (see [image above](#work-in-progress-merge-requests)). diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index 7ffeb032d7f..d4dd9c7d4c3 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,6 +1,9 @@ -# Burndown Charts **[STARTER]** +--- +type: reference +--- + +# 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. @@ -20,7 +23,8 @@ 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/). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, check the video demonstration on [Mapping work versus time with Burndown Charts](https://www.youtube.com/watch?v=zJU2MuRChzs). ## Use cases @@ -68,3 +72,15 @@ 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. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 6cd866b5c0d..453983fa882 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -1,3 +1,7 @@ +--- +type: index, reference +--- + # Milestones ## Overview @@ -14,12 +18,12 @@ the start and end of your Agile sprint. Set the milestone title to the name of your Agile sprint, such as `November 2018 sprint`. Add an issue to your Agile sprint by associating -the milestone to the issue. +the milestone to the issue. ## Milestones as releases Milestones can be used as releases. -Set the milestone due date to represent the release date of your release. +Set the milestone due date to represent the release date of your release. (And leave the milestone start date blank.) Set the milestone title to the version of your release, such as `Version 9.4`. @@ -84,9 +88,9 @@ 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 [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]** +- 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 @@ -124,13 +128,13 @@ These features are only available for project milestones and not group milestone - 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]** +### 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]** +### 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. @@ -145,3 +149,15 @@ The milestone sidebar on the milestone view shows the following: For project milestones only, the milestone sidebar shows the total issue weight of all issues that have the milestone assigned.  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index c07c4099f22..8606d92f20c 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -6,8 +6,6 @@ GitLab 8.12 has a completely redesigned [job permissions] system. You can find all discussion and all our concerns when choosing the current approach in issue [#18994](https://gitlab.com/gitlab-org/gitlab-ce/issues/18994). ---- - Jobs permissions should be tightly integrated with the permissions of a user who is triggering a job. @@ -30,13 +28,13 @@ The reasons to do it like that are: With the new behavior, any job that is triggered by the user, is also marked with their read permissions. When a user does a `git push` or changes files through the web UI, a new pipeline will be usually created. This pipeline will be marked -as created be the pusher (local push or via the UI) and any job created in this +as created by the pusher (local push or via the UI) and any job created in this pipeline will have the read permissions of the pusher but not write permissions. This allows us to make it really easy to evaluate the access for all projects that have [Git submodules][gitsub] or are using container images that the pusher -would have access too. **The permission is granted only for time that job is -running. The access is revoked after the job is finished.** +would have access too. **The permission is granted only for the time that the job +is running. The access is revoked after the job is finished.** ## Types of users @@ -76,7 +74,7 @@ We try to make sure that this token doesn't leak by: 1. Securing all API endpoints to not expose the job token. 1. Masking the job token from job logs. -1. Allowing to use the job token **only** when job is running. +1. Granting permissions to the job token **only** when the job is running. However, this brings a question about the Runners security. To make sure that this token doesn't leak, you should also make sure that you configure @@ -88,13 +86,6 @@ your Runners in the most possible secure way, by avoiding the following: By using an insecure GitLab Runner configuration, you allow the rogue developers to steal the tokens of other jobs. -## Pipeline triggers - -Since 9.0 [pipeline triggers][triggers] do support the new permission model. -The new triggers do impersonate their associated user including their access -to projects and their project permissions. To migrate trigger to use new permission -model use **Take ownership**. - ## Before GitLab 8.12 In versions before GitLab 8.12, all CI jobs would use the CI Runner's token @@ -108,8 +99,6 @@ and to checkout project sources. It could also be used with the GitLab Container Registry for that project, allowing pulling and pushing Docker images from within the CI job. ---- - GitLab would create a special checkout URL like: ``` @@ -185,7 +174,7 @@ The [Job environment variable][jobenv] `CI_JOB_TOKEN` can be used to authenticate any clones of dependent repositories. For example: ``` -git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/myuser/mydependentrepo +git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependentrepo>.git ``` It can also be used for system-wide authentication @@ -208,7 +197,7 @@ Container Registries for private projects. > **Notes:** > > - GitLab Runner versions prior to 1.8 don't incorporate the introduced changes -> for permissions. This makes the `image:` directive to not work with private +> for permissions. This makes the `image:` directive not work with private > projects automatically and it needs to be configured manually on Runner's host > with a predefined account (for example administrator's personal account with > access token created explicitly for this purpose). This issue is resolved with @@ -232,11 +221,22 @@ test: - docker run $CI_REGISTRY/group/other-project:latest ``` +### Pipeline triggers + +Since 9.0 [pipeline triggers][triggers] do support the new permission model. +The new triggers do impersonate their associated user including their access +to projects and their project permissions. + +### API + +GitLab API cannot be used via `CI_JOB_TOKEN` but there is a [proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/29566) +to support it. + [job permissions]: ../permissions.md#job-permissions [comment]: https://gitlab.com/gitlab-org/gitlab-ce/issues/22484#note_16648302 [gitsub]: ../../ci/git_submodules.md [https]: ../admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols -[triggers]: ../../ci/triggers/README.md +[triggers]: ../../ci/triggers/README.md#ci-job-token [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update [workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse [jobenv]: ../../ci/variables/README.md#predefined-environment-variables diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index a5db3d70bb9..75b0623e6b0 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -1,4 +1,4 @@ -# Feature Flags **[PREMIUM]** +# Feature Flags **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 11.4. @@ -74,9 +74,9 @@ 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. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) (`*`). Choose a rollout strategy. This status and rollout strategy combination 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. Set the status and rollout strategy of the additional spec. This status and rollout strategy combination takes precedence over the default spec since we always use the most specific match available. 1. Click **Create feature flag** or **Update feature flag**.  @@ -85,6 +85,46 @@ 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. +## Rollout Strategy + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8240) in GitLab 12.2. + +The selected rollout strategy affects which users will experience the feature enabled. + +The status of an environment spec ultimately determines whether or not a feature is enabled at all. +For instance, a feature will always be disabled for every user if the matching environment spec has a disabled status, regardless of the chosen rollout strategy. +However, a feature will be enabled for 50% of logged-in users if the matching environment spec has an enabled status along with a **Percent rollout (logged in users)** strategy set to 50%. + +### All users + +Enables the feature for all users. + +**All users** is implemented using the Unleash [default](https://unleash.github.io/docs/activation_strategy#default) activation strategy. + +### Percent rollout (logged in users) + +**Percent rollout (logged in users)** enables the feature for a percentage of authenticated users. Set a value of 15%, for example, to enable the feature for 15% of authenticated users. + +A rollout percentage may be between 0% and 100%. + +CAUTION: **Caution:** +If this strategy is selected, then the Unleash client **must** be given a user id for the feature to be enabled. See the [Ruby example](#ruby-application-example) below. + +**Percent rollout (logged in users)** is implemented using the Unleash [gradualRolloutUserId](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid) activation strategy. + +## Target Users + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8240) in GitLab 12.2. + +A feature flag may be enabled for a list of target users. + + + +CAUTION: **Caution:** +The Unleash client **must** be given a user id for the feature to be enabled for target users. See the [Ruby example](#ruby-application-example) below. + +**Target users** is implemented using the Unleash [userWithId](https://unleash.github.io/docs/activation_strategy#userwithid) activation strategy. + ## Integrating with your application In order to use Feature Flags, you need to first @@ -175,3 +215,34 @@ func main() { log.Fatal(http.ListenAndServe(":8080", nil)) } ``` + +### Ruby application example + +Here's an example of how to integrate the feature flags in a Ruby application. + +The Unleash client is given a user id for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**. + +```ruby +#!/usr/bin/env ruby + +require 'unleash' +require 'unleash/context' + +unleash = Unleash::Client.new({ + url: 'http://gitlab.com/api/v4/feature_flags/unleash/42', + app_name: 'production', + instance_id: '29QmjsW6KngPR5JNPMWx' +}) + +unleash_context = Unleash::Context.new +# Replace "123" with the id of an authenticated user. +# Note that the context's user id must be a string: +# https://unleash.github.io/docs/unleash_context +unleash_context.user_id = "123" + +if unleash.is_enabled?("my_feature_name", unleash_context) + puts "Feature enabled" +else + puts "hello, world!" +end +``` diff --git a/doc/user/project/operations/img/error_tracking_list.png b/doc/user/project/operations/img/error_tracking_list.png Binary files differindex aa0f9867fdb..194c7b440a4 100644 --- a/doc/user/project/operations/img/error_tracking_list.png +++ b/doc/user/project/operations/img/error_tracking_list.png diff --git a/doc/user/project/operations/img/external_dashboard_link.png b/doc/user/project/operations/img/external_dashboard_link.png Binary files differindex 4fb8bce7cd0..82c5e05e467 100644 --- a/doc/user/project/operations/img/external_dashboard_link.png +++ b/doc/user/project/operations/img/external_dashboard_link.png diff --git a/doc/user/project/operations/img/external_dashboard_settings.png b/doc/user/project/operations/img/external_dashboard_settings.png Binary files differindex 8dc380f01e2..e1b7fa56a1c 100644 --- a/doc/user/project/operations/img/external_dashboard_settings.png +++ b/doc/user/project/operations/img/external_dashboard_settings.png diff --git a/doc/user/project/operations/img/feature_flags_list.png b/doc/user/project/operations/img/feature_flags_list.png Binary files differindex 5313a163fec..f3e85b9ce44 100644 --- a/doc/user/project/operations/img/feature_flags_list.png +++ 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 differindex 9630c907cfc..43d069c09ce 100644 --- a/doc/user/project/operations/img/specs_list.png +++ b/doc/user/project/operations/img/specs_list.png diff --git a/doc/user/project/operations/img/target_users_v12_2.png b/doc/user/project/operations/img/target_users_v12_2.png Binary files differnew file mode 100644 index 00000000000..c88d2b7be97 --- /dev/null +++ b/doc/user/project/operations/img/target_users_v12_2.png diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index 84711d1146f..2da9c3e70cf 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -7,6 +7,6 @@ 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](feature_flags.md). **[PREMIUM]** -- [Trace](tracing.md) 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)** - Add a [button to the Monitoring dashboard](linking_to_an_external_dashboard.md) linking directly to your existing external dashboards. diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md index 0416e096cf2..b92d2e49839 100644 --- a/doc/user/project/operations/tracing.md +++ b/doc/user/project/operations/tracing.md @@ -1,4 +1,4 @@ -# Tracing **[ULTIMATE]** +# Tracing **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7903) in GitLab Ultimate 11.5. @@ -17,8 +17,8 @@ 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), +[Getting Started documentation](https://www.jaegertracing.io/docs/1.13/getting-started/). +There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/1.13/getting-started/#AllinoneDockerimage), as well as deployment options for [Kubernetes](https://github.com/jaegertracing/jaeger-kubernetes) and [OpenShift](https://github.com/jaegertracing/jaeger-openshift). @@ -27,8 +27,8 @@ and [OpenShift](https://github.com/jaegertracing/jaeger-openshift). 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/). + [client libraries](https://www.jaegertracing.io/docs/1.13/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 + GitLab will redirect you to the configured Jaeger URL. diff --git a/doc/user/project/packages/img/npm_package_view.png b/doc/user/project/packages/img/npm_package_view.png Binary files differindex 8baf7d0ef9f..e0634718c02 100644 --- a/doc/user/project/packages/img/npm_package_view.png +++ b/doc/user/project/packages/img/npm_package_view.png diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md index 9b7af738696..c61402afb2c 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -1,4 +1,4 @@ -# GitLab Maven Repository **[PREMIUM]** +# GitLab Maven Repository **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. @@ -12,7 +12,7 @@ project can have its own space to store its Maven artifacts. NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the Maven repository](../../../administration/packages.md).**[PREMIUM ONLY]** +[enabled support for the Maven repository](../../../administration/packages.md).**(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 @@ -198,7 +198,7 @@ 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`). +(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`). ### Instance level Maven endpoint @@ -279,59 +279,59 @@ shows how to create a new package each time the `master` branch is updated: 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> - ``` + ```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. + ```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 - ``` + ```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. diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md index 2e274573434..e01bac6b26f 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -1,4 +1,4 @@ -# GitLab NPM Registry **[PREMIUM]** +# GitLab NPM Registry **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. @@ -11,16 +11,11 @@ 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](../../../administration/packages.md).**[PREMIUM ONLY]** +[enabled support for the NPM registry](../../../administration/packages.md).**(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: @@ -36,12 +31,15 @@ get familiar with the package naming convention. ## Package naming convention -**Only packages that have the same path as the project** are supported. For - example: +**Packages must be scoped in the root namespace of the project**. The package +name may be anything but it is preferred that the project name be used unless +it is not possible due to a naming collision. For example: | Project | Package | Supported | | ---------------------- | ----------------------- | --------- | | `foo/bar` | `@foo/bar` | Yes | +| `foo/bar/baz` | `@foo/baz` | Yes | +| `foo/bar/buz` | `@foo/anything` | Yes | | `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes | | `gitlab-org/gitlab-ce` | `@foo/bar` | No | @@ -51,41 +49,42 @@ 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). +credentials will need to be provided for authentication. Support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow) or [personal access tokens](../../profile/personal_access_tokens.md). -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. +CAUTION: **2FA is only supported with personal access tokens:** +If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers. Standard OAuth tokens 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: +To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow) +or [personal access token](../../profile/personal_access_tokens.md), 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 +; Add the 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> +//gitlab.com/api/v4/packages/npm/:_authToken=<your_token> -; Add OAuth token for uploading to the registry. Replace <your_project_id> +; Add 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> +//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_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. +of your project and `<your_token>` with your OAuth or personal access 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. +NOTE: **Note:** +If you encounter an error message with [Yarn](https://yarnpkg.com/en/), see the +[troubleshooting section](#troubleshooting). + ## Uploading packages Before you will be able to upload a package, you need to specify the registry @@ -113,8 +112,37 @@ npm publish You can then navigate to your project's **Packages** page and see the uploaded packages or even delete them. +If you attempt to publish a package with a name that already exists within +a given scope, you will receive a `403 Forbidden!` error. + ## 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`. + +## Troubleshooting + +### Error running yarn with NPM registry + +If you are using [yarn](https://yarnpkg.com/en/) with the NPM registry, you may get +an error message like: + +```sh +yarn install v1.15.2 +warning package.json: No license field +info No lockfile found. +warning XXX: No license field +[1/4] 🔍 Resolving packages... +[2/4] 🚚 Fetching packages... +error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"". +info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log". +info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command +``` + +In this case, try adding this to your `.npmrc` file (and replace `<your_oauth_token>` +with your with your OAuth or personal access token): + +```text +//gitlab.com/api/v4/projects/:_authToken=<your_oauth_token> +``` diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md new file mode 100644 index 00000000000..3b80370d4a9 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -0,0 +1,95 @@ +--- +type: concepts +--- + +# DNS records overview + +_Read this document for a brief overview of DNS records in the scope +of GitLab Pages, for beginners in web development._ + +A Domain Name System (DNS) web service routes visitors to websites +by translating domain names (such as `www.example.com`) into the +numeric IP addresses (such as `192.0.2.1`) that computers use to +connect to each other. + +A DNS record is created to point a (sub)domain to a certain location, +which can be an IP address or another domain. In case you want to use +GitLab Pages with your own (sub)domain, you need to access your domain's +registrar control panel to add a DNS record pointing it back to your +GitLab Pages site. + +Note that **how to** add DNS records depends on which server your domain +is hosted on. Every control panel has its own place to do it. If you are +not an admin of your domain, and don't have access to your registrar, +you'll need to ask for the technical support of your hosting service +to do it for you. + +To help you out, we've gathered some instructions on how to do that +for the most popular hosting services: + +- [Amazon](http://docs.aws.amazon.com/gettingstarted/latest/swh/getting-started-configure-route53.html) +- [Bluehost](https://my.bluehost.com/cgi/help/559) +- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200169096-How-do-I-add-A-records-) +- [cPanel](https://documentation.cpanel.net/display/ALD/Edit+DNS+Zone) +- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) +- [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) +- [Hostgator](http://support.hostgator.com/articles/changing-dns-records) +- [Inmotion hosting](https://my.bluehost.com/cgi/help/559) +- [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) +- [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx) + +If your hosting service is not listed above, you can just try to +search the web for `how to add dns record on <my hosting service>`. + +## `A` record + +A DNS A record maps a host to an IPv4 IP address. +It points a root domain as `example.com` to the host's IP address as +`192.192.192.192`. + +Example: + +- `example.com` => `A` => `192.192.192.192` + +## CNAME record + +CNAME records define an alias for canonical name for your server (one defined +by an A record). It points a subdomain to another domain. + +Example: + +- `www` => `CNAME` => `example.com` + +This way, visitors visiting `www.example.com` will be redirected to +`example.com`. + +## MX record + +MX records are used to define the mail exchanges that are used for the domain. +This helps email messages arrive at your mail server correctly. + +Example: + +- `MX` => `mail.example.com` + +Then you can register emails for `users@mail.example.com`. + +## TXT record + +A `TXT` record can associate arbitrary text with a host or other name. A common +use is for site verification. + +Example: + +- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"` + +This way, you can verify the ownership for that domain name. + +## All combined + +You can have one DNS record or more than one combined: + +- `example.com` => `A` => `192.192.192.192` +- `www` => `CNAME` => `example.com` +- `MX` => `mail.example.com` +- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"`
\ No newline at end of file diff --git a/doc/user/project/pages/img/add_certificate_to_pages.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png Binary files differindex d92a981dc60..d92a981dc60 100644 --- a/doc/user/project/pages/img/add_certificate_to_pages.png +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png diff --git a/doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png Binary files differindex 0150329d4b2..0150329d4b2 100644 --- a/doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png diff --git a/doc/user/project/pages/img/dns_cname_record_example.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png Binary files differindex 43d1a838544..43d1a838544 100644 --- a/doc/user/project/pages/img/dns_cname_record_example.png +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png Binary files differnew file mode 100644 index 00000000000..3b93572a8f1 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png Binary files differnew file mode 100644 index 00000000000..5eab04a61a9 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png Binary files differnew file mode 100644 index 00000000000..5f2f100e883 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md new file mode 100644 index 00000000000..1821d954af3 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -0,0 +1,276 @@ +--- +last_updated: 2019-07-04 +type: reference, howto +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' +--- + +# Custom domains and SSL/TLS Certificates + +Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. + +To use one or more custom domain names with your Pages site, you can: + +- Add a [custom **root domain** or a **subdomain**](#set-up-pages-with-a-custom-domain). +- Add [SSL/TLS certification](#adding-an-ssltls-certificate-to-pages). + +## Set up Pages with a custom domain + +To set up Pages with a custom domain name, read the requirements +and steps below. + +### Requirements + +- A GitLab Pages website up and running, served under the default Pages domain + (`*.gitlab.io`, for GitLab.com). +- A custom domain name `example.com` or subdomain `subdomain.example.com`. +- Access to your domain's server control panel to set up DNS records: + - A DNS A or CNAME record poiting your domain to GitLab Pages server. + - A DNS TXT record to verify your domain's ownership. + +### Steps + +Follow the steps below to add your custom domain to Pages. See also +this document for an [overview on DNS records](dns_concepts.md). + +#### 1. Add a custom domain to Pages + +Navigate to your project's **Setting > Pages** and click **+ New domain** +to add your custom domain to GitLab Pages. You can choose whether to: + +- Add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). +- Leave it blank (it can be added later). + +Click **Create New Domain**. + + + +#### 2. Get the verification code + +Once you have added a new domain to Pages, the verification code will be prompted to you. Copy the values from GitLab and paste them in your domain's control panel as a TXT record on the next step. + + + +#### 3. Set up DNS records for Pages + +Read this document for an [overview of DNS records for Pages](dns_concepts.md). +If you're familiar with the subject, follow the instructions below +according to the type of domain you want to use with your Pages site: + +- [For root domains](#for-root-domains), `example.com`. +- [For subdomains](#for-subdomains), `subdomain.example.com`. +- [For both](#for-both-root-and-subdomains). + +##### For root domains + +Root domains (`example.com`) require: + +- A [DNS A record](dns_concepts.md#a-record) pointing your domain to the Pages server. +- A [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership. + +| From | DNS Record | To | +| ---- | ---------- | -- | +| example.com | A | 35.185.44.232 | +| _gitlab-pages-verification-code.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | + +For projects on GitLab.com, this IP is `35.185.44.232`. +For projects living in other GitLab instances (CE or EE), please contact +your sysadmin asking for this information (which IP address is Pages +server running on your instance). + + + +CAUTION: **Caution:** +Note that if you use your root domain for your GitLab Pages website +**only**, and if your domain registrar supports this feature, you can +add a DNS apex `CNAME` record instead of an `A` record. The main +advantage of doing so is that when GitLab Pages IP on GitLab.com +changes for whatever reason, you don't need to update your `A` record. +There may be a few exceptions, but **this method is not recommended** +as it most likely won't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain. + +##### For subdomains + +Subdomains (`subdomain.example.com`) require: + +- A DNS [CNAME record](dns_concepts.md#cname-record) record pointing your subdomain to the Pages server. +- A DNS [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership. + +| From | DNS Record | To | +| ---- | ---------- | -- | +| subdomain.example.com | CNAME | namespace.gitlab.io | +| _gitlab-pages-verification-code.subdomain.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | + +Note that, whether it's a user or a project website, the `CNAME` +should point to your Pages domain (`namespace.gitlab.io`), +without any `/project-name`. + + + +##### For both root and subdomains + +There are a few cases where you need point both subdomain and root +domain to the same website, for instance, `example.com` and `www.example.com`. + +They require: + +- A DNS A record for the domain. +- A DNS CNAME record for the subdomain. +- A DNS TXT record for each. + +| From | DNS Record | To | +| ---- | ---------- | -- | +| example.com | A | 35.185.44.232 | +| _gitlab-pages-verification-code.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | +|---+---| +| www.example.com | CNAME | namespace.gitlab.io | +| _gitlab-pages-verification-code.www.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | + +If you're using CloudFlare, check +[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare). + +> **Notes**: +> +> - **Do not** use a CNAME record if you want to point your + `domain.com` to your GitLab Pages site. Use an `A` record instead. +> - **Do not** add any special chars after the default Pages + domain. E.g., don't point `subdomain.domain.com` to + or `namespace.gitlab.io/`. Some domain hosting providers may request a trailling dot (`namespace.gitlab.io.`), though. +> - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017. +> - GitLab Pages IP on GitLab.com [has changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains) + from `52.167.214.135` to `35.185.44.232` in 2018. + +#### 4. Verify the domain's ownership + +Once you have added all the DNS records: + +1. Go back at your project's **Settings > Pages**. +1. Locate your domain name and click **Details**. +1. Click the **Retry verification** button to activate your new domain. + + + +As soon as your domain becomes active, your website will be available +through your domain name. + +CAUTION: **Caution:** +Considering GitLab instances with domain verification enabled, +if the domain cannot be verified for 7 days, it will be removed +from the GitLab project. + +> **Notes:** +> +> - Domain verification is **required for GitLab.com users**; + for GitLab self-managed instances, your GitLab administrator has the option + to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). +> - [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), + although it's usually a matter of minutes to complete. Until it does, verification + will fail and attempts to visit your domain will respond with a 404. +> - Once your domain has been verified, leave the verification record + in place: your domain will be periodically reverified, and may be + disabled if the record is removed. + +### Adding more domain aliases + +You can add more than one alias (custom domains and subdomains) to the same project. +An alias can be understood as having many doors leading to the same room. + +All the aliases you've set to your site will be listed on **Setting > Pages**. +From that page, you can view, add, and remove them. + +### Redirecting `www.domain.com` to `domain.com` with Cloudflare + +If you use Cloudflare, you can redirect `www` to `domain.com` +without adding both `www.domain.com` and `domain.com` to GitLab. + +To do so, you can use Cloudflare's page rules associated to a +CNAME record to redirect `www.domain.com` to `domain.com`. You +can use the following setup: + +1. In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232`. +1. In GitLab, add the domain to GitLab Pages and get the verification code. +1. In Cloudflare, create a DNS `TXT` record to verify your domain. +1. In GitLab, verify your domain. +1. In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com`. +1. In Cloudflare, add a Page Rule pointing `www.domain.com` to `domain.com`: + - Navigate to your domain's dashboard and click **Page Rules** + on the top nav. + - Click **Create Page Rule**. + - Enter the domain `www.domain.com` and click **+ Add a Setting**. + - From the dropdown menu, choose **Forwarding URL**, then select the + status code **301 - Permanent Redirect**. + - Enter the destination URL `https://domain.com`. + +## Adding an SSL/TLS certificate to Pages + +Read this document for an [overview on SSL/TLS certification](ssl_tls_concepts.md). + +To secure your custom domain with GitLab Pages you can opt by: + +- Using the [Let's Encrypt integration with GitLab Pages](lets_encrypt_integration.md), + which automatically obtains and renews SSL certificates + for your Pages domains. +- Manually adding SSL/TLS certificates to GitLab Pages websites + by following the steps below. + +### Requirements + +- A GitLab Pages website up and running accessible via a custom domain. +- **A PEM certificate**: it is the certificate generated by the CA, + which needs to be added to the field **Certificate (PEM)**. +- **An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority)**: (aka "root certificate"), it is + the part of the encryption keychain that identifies the CA. + Usually it's combined with the PEM certificate, but there are + some cases in which you need to add them manually. + [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) + are one of these cases. +- **A private key**, it's an encrypted key which validates + your PEM against your domain. + +### Steps + +- To add the certificate at the time you add a new domain, go to your + project's **Settings > Pages > New Domain**, add the domain name and the certificate. +- To add the certificate to a domain previously added, go to your + project's **Settings > Pages**, locate your domain name, click **Details** and **Edit** to add the certificate. + + + +1. Add the PEM certificate to its corresponding field. +1. If your certificate is missing its intermediate, copy + and paste the root certificate (usually available from your CA website) + and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), + just jumping a line between them. +1. Copy your private key and paste it in the last field. + +NOTE: **Note:** +**Do not** open certificates or encryption keys in +regular text editors. Always use code editors (such as +Sublime Text, Atom, Dreamweaver, Brackets, etc). + +## Force HTTPS for GitLab Pages websites + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28857) in GitLab 10.7. + +To make your website's visitors even more secure, you can choose to +force HTTPS for GitLab Pages. By doing so, all attempts to visit your +website via HTTP will be automatically redirected to HTTPS via 301. + +It works with both GitLab's default domain and with your custom +domain (as long as you've set a valid certificate for it). + +To enable this setting: + +1. Navigate to your project's **Settings > Pages**. +1. Tick the checkbox **Force HTTPS (requires valid certificates)**. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md new file mode 100644 index 00000000000..255d535645d --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -0,0 +1,87 @@ +--- +type: reference +description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." +--- + +# GitLab Pages integration with Let's Encrypt + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) in GitLab 12.1. + +The GitLab Pages integration with Let's Encrypt (LE) allows you +to use LE certificates for your Pages website with custom domains +without the hassle of having to issue and update them yourself; +GitLab does it for you, out-of-the-box. + +[Let's Encrypt](https://letsencrypt.org) is a free, automated, and +open source Certificate Authority. + +CAUTION: **Caution:** +This feature is in **beta** and might present bugs and UX issues +such as [#64870](https://gitlab.com/gitlab-org/gitlab-ce/issues/64870). +See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) +for more information. + +## Requirements + +Before you can enable automatic provisioning of a SSL certificate for your domain, make sure you have: + +- Created a [project](../getting_started_part_two.md) in GitLab + containing your website's source code. +- Acquired a domain (`example.com`) and added a [DNS entry](index.md) + pointing it to your Pages website. +- [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) + and verified your ownership. +- Have your website up and running, accessible through your custom domain. + +NOTE: **Note:** +GitLab's Let's Encrypt integration is enabled and available on GitLab.com. +For **self-managed** GitLab instances, make sure your administrator has +[enabled it](../../../../administration/pages/index.md#lets-encrypt-integration). + +## Enabling Let's Encrypt integration for your custom domain + +Once you've met the requirements, to enable Let's Encrypt integration: + +1. Navigate to your project's **Settings > Pages**. +1. Find your domain and click **Details**. +1. Click **Edit** in the top-right corner. +1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**: + +  + +1. Click **Save changes**. + +Once enabled, GitLab will obtain a LE certificate and add it to the +associated Pages domain. It will be also renewed automatically by GitLab. + +> **Notes:** +> +> - Issuing the certificate and updating Pages configuration +> **can take up to an hour**. +> - If you already have SSL certificate in domain settings it +> will continue to work until it will be replaced by Let's Encrypt's certificate. + +## Troubleshooting + +### Error "Certificate misses intermediates" + +If you get an error **Certificate misses intermediates** while trying to enable Let's Encrypt integration for your domain, follow the steps below: + +1. Go to your project's **Settings > Pages**. +1. Turn off **Force HTTPS** if it's turned on. +1. Click **Details** on your domain. +1. Click the **Edit** button in the top right corner of domain details page. +1. Enable Let's Encrypt integration. +1. Click **Save**. +1. Go to your project's **Settings > Pages**. +1. Turn on **Force HTTPS**. + +<!-- Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md new file mode 100644 index 00000000000..ee0550bfca2 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -0,0 +1,75 @@ +--- +type: concepts +--- + +# SSL/TLS Certificates + +_Read this document for a brief overview of SSL/TLS certificates in +the scope of GitLab Pages, for beginners in web development._ + +Every GitLab Pages project on GitLab.com will be available under +HTTPS for the default Pages domain (`*.gitlab.io`). Once you set +up your Pages project with your custom (sub)domain, if you want +it secured by HTTPS, you will have to issue a certificate for that +(sub)domain and install it on your project. + +NOTE: **Note:** +Certificates are NOT required to add to your custom +(sub)domain on your GitLab Pages project, though they are +highly recommendable. + +Let's start with an introduction to the importance of HTTPS. + +## Why should I care about HTTPS? + +This might be your first question. If our sites are hosted by GitLab Pages, +they are static, hence we are not dealing with server-side scripts +nor credit card transactions, then why do we need secure connections? + +Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" +security measure, necessary just for big companies, like banks and shoppings sites +with financial transactions. +Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): + +> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ + +Therefore, the reason why certificates are so important is that they encrypt +the connection between the **client** (you, me, your visitors) +and the **server** (where you site lives), through a keychain of +authentications and validations. + +How about taking Josh's advice and protecting our sites too? We will be +well supported, and we'll contribute to a safer internet. + +## Organizations supporting HTTPS + +There is a huge movement in favor of securing all the web. W3C fully +[supports the cause](https://w3ctag.github.io/web-https/) and explains very well +the reasons for that. Richard Barnes, a writer for Mozilla Security Blog, +suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/), +and would no longer accept unsecured connections. Recently, Mozilla published a +[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/) +reiterating the importance of HTTPS. + +## Issuing Certificates + +GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by +[Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as +[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://securingtomorrow.mcafee.com/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) +for public websites for security reasons and to ensure that browsers trust your site's certificate. + +There are various kinds of certificates, each one +with a certain security level. A static personal website will +not require the same security level as an online banking web app, +for instance. + +There are some certificate authorities that +offer free certificates, aiming to make the internet more secure +to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/), +which issues certificates trusted by most of browsers, it's open +source, and free to use. See [GitLab Pages integration with Let's Encrypt](../custom_domains_ssl_tls_certification/lets_encrypt_integration.md) to enable HTTPS on your custom domain. + +Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/), +which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/). +Their certs are valid up to 15 years. See the tutorial on +[how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/). diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index 8baf41dba78..d844d4222b1 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -380,7 +380,7 @@ What you can do with GitLab CI is pretty much up to your creativity. Once you get used to it, you start creating awesome scripts that automate most of tasks you'd do manually in the past. Read through the -[documentation of GitLab CI](https://docs.gitlab.com/ce/ci/yaml/README.html) +[documentation of GitLab CI](../../../ci/yaml/README.md) to understand how to go even further on your scripts. - On this blog post, understand the concept of diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index d585c19fc5c..9bc9fe97fd3 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,303 +1 @@ ---- -last_updated: 2019-06-04 -type: concepts, reference, howto ---- - -# GitLab Pages custom domains and SSL/TLS Certificates - -Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. - -These steps assume you've already [set your site up](getting_started_part_two.md) and it's served under the default Pages domain `namespace.gitlab.io`, or `namespace.gitlab.io/project-name`. - -## Adding your custom domain to GitLab Pages - -To use one or more custom domain with your Pages site, there are two things -you should consider first, which we'll cover in this guide: - -1. Either if you're adding a **root domain** or a **subdomain**, for which - you'll need to set up [DNS records](#dns-records) -1. Whether you want to add an [SSL/TLS certificate](#ssltls-certificates) or not - -To finish the association, you need to [add your domain to your project's Pages settings](#add-your-custom-domain-to-gitlab-pages-settings). - -Let's start from the beginning with [DNS records](#dns-records). -If you already know how they work and want to skip the introduction to DNS, -you may be interested in skipping it until the [TL;DR](#tldr) section below. - -### DNS Records - -A Domain Name System (DNS) web service routes visitors to websites -by translating domain names (such as `www.example.com`) into the -numeric IP addresses (such as `192.0.2.1`) that computers use to -connect to each other. - -A DNS record is created to point a (sub)domain to a certain location, -which can be an IP address or another domain. In case you want to use -GitLab Pages with your own (sub)domain, you need to access your domain's -registrar control panel to add a DNS record pointing it back to your -GitLab Pages site. - -Note that **how to** add DNS records depends on which server your domain -is hosted on. Every control panel has its own place to do it. If you are -not an admin of your domain, and don't have access to your registrar, -you'll need to ask for the technical support of your hosting service -to do it for you. - -To help you out, we've gathered some instructions on how to do that -for the most popular hosting services: - -- [Amazon](http://docs.aws.amazon.com/gettingstarted/latest/swh/getting-started-configure-route53.html) -- [Bluehost](https://my.bluehost.com/cgi/help/559) -- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200169096-How-do-I-add-A-records-) -- [cPanel](https://documentation.cpanel.net/display/ALD/Edit+DNS+Zone) -- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) -- [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) -- [Hostgator](http://support.hostgator.com/articles/changing-dns-records) -- [Inmotion hosting](https://my.bluehost.com/cgi/help/559) -- [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) -- [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx) - -If your hosting service is not listed above, you can just try to -search the web for `how to add dns record on <my hosting service>`. - -#### DNS A record - -In case you want to point a root domain (`example.com`) to your -GitLab Pages site, deployed to `namespace.gitlab.io`, you need to -log into your domain's admin control panel and add a DNS `A` record -pointing your domain to Pages' server IP address. For projects on -GitLab.com, this IP is `35.185.44.232`. For projects living in -other GitLab instances (CE or EE), please contact your sysadmin -asking for this information (which IP address is Pages server -running on your instance). - -**Practical Example:** - - - -CAUTION: **Caution:** -Note that if you use your root domain for your GitLab Pages website -**only**, and if your domain registrar supports this feature, you can -add a DNS apex `CNAME` record instead of an `A` record. The main -advantage of doing so is that when GitLab Pages IP on GitLab.com -changes for whatever reason, you don't need to update your `A` record. -There may be a few exceptions, but **this method is not recommended** -as it most likely won't work if you set an `MX` record for your root domain. - -#### DNS CNAME record - -In case you want to point a subdomain (`hello-world.example.com`) -to your GitLab Pages site initially deployed to `namespace.gitlab.io`, -you need to log into your domain's admin control panel and add a DNS -`CNAME` record pointing your subdomain to your website URL -(`namespace.gitlab.io`) address. - -Note that, whether it's a user or a project website, the `CNAME` -should point to your Pages domain (`namespace.gitlab.io`), -without any `/project-name`. - -**Practical Example:** - - - -#### DNS TXT record - -Unless your GitLab administrator has [disabled custom domain verification](../../../administration/pages/index.md#custom-domain-verification), -you'll have to prove that you own the domain by creating a `TXT` record -containing a verification code. The code will be displayed after you -[add your custom domain to GitLab Pages settings](#add-your-custom-domain-to-gitlab-pages-settings). - -If using a [DNS A record](#dns-a-record), you can place the TXT record directly -under the domain. If using a [DNS CNAME record](#dns-cname-record), the two record types won't -co-exist, so you need to place the TXT record in a special subdomain of its own. - -If the domain cannot be verified for 7 days, it will be removed from the GitLab project. - -#### TL;DR - -For root domains (`domain.com`), set a DNS `A` record and verify your -domain's ownership with a TXT record: - -| From | DNS Record | To | -| ---- | ---------- | -- | -| domain.com | A | 35.185.44.232 | -| domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | - -For subdomains (`subdomain.domain.com`), set a DNS `CNAME` record and -verify your domain's ownership with a TXT record: - -| From | DNS Record | To | -| ---- | ---------- | -- | -| subdomain.domain.com | CNAME | namespace.gitlab.io | -| _gitlab-pages-verification-code.subdomain.domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | - -> **Notes**: -> -> - **Do not** use a CNAME record if you want to point your - `domain.com` to your GitLab Pages site. Use an `A` record instead. -> - **Do not** add any special chars after the default Pages - domain. E.g., **do not** point your `subdomain.domain.com` to - `namespace.gitlab.io.` or `namespace.gitlab.io/`. -> - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017 -> - GitLab Pages IP on GitLab.com [has been changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains) - from `52.167.214.135` to `35.185.44.232` in 2018 - -### Add your custom domain to GitLab Pages settings - -Once you've set the DNS record, you'll need navigate to your project's -**Setting > Pages** and click **+ New domain** to add your custom domain to -GitLab Pages. You can choose whether to add an [SSL/TLS certificate](#ssltls-certificates) -to make your website accessible under HTTPS or leave it blank. If you don't add a certificate, -your site will be accessible only via HTTP: - - - -Once you have added a new domain, you will need to **verify your ownership** -(unless the GitLab administrator has disabled this feature). A verification code -will be shown to you; add it as a [DNS TXT record](#dns-txt-record), then press -the "Verify ownership" button to activate your new domain: - - - -Once your domain has been verified, leave the verification record in place - -your domain will be periodically reverified, and may be disabled if the record -is removed. - -You can add more than one alias (custom domains and subdomains) to the same project. -An alias can be understood as having many doors leading to the same room. - -All the aliases you've set to your site will be listed on **Setting > Pages**. -From that page, you can view, add, and remove them. - -Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), -although it's usually a matter of minutes to complete. Until it does, verification -will fail and attempts to visit your domain will respond with a 404. - -### Redirecting `www.domain.com` to `domain.com` with Cloudflare - -If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both -`www.domain.com` and `domain.com` to GitLab. This happens due to a [Cloudflare feature that creates -a 301 redirect as a "page rule"](https://gitlab.com/gitlab-org/gitlab-ce/issues/48848#note_87314849) for redirecting `www.domain.com` to `domain.com`. In this case, -you can use the following setup: - -- In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232` -- In GitLab, add the domain to GitLab Pages -- In Cloudflare, create a DNS `TXT` record to verify your domain -- In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com` - -## SSL/TLS Certificates - -Every GitLab Pages project on GitLab.com will be available under -HTTPS for the default Pages domain (`*.gitlab.io`). Once you set -up your Pages project with your custom (sub)domain, if you want -it secured by HTTPS, you will have to issue a certificate for that -(sub)domain and install it on your project. - ->**Note:** -Certificates are NOT required to add to your custom -(sub)domain on your GitLab Pages project, though they are -highly recommendable. - -Let's start with an introduction to the importance of HTTPS. -Alternatively, jump ahead to [adding certificates to your project](#adding-certificates-to-your-project). - -### Why should I care about HTTPS? - -This might be your first question. If our sites are hosted by GitLab Pages, -they are static, hence we are not dealing with server-side scripts -nor credit card transactions, then why do we need secure connections? - -Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" -security measure, necessary just for big companies, like banks and shoppings sites -with financial transactions. -Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): - -> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ - -Therefore, the reason why certificates are so important is that they encrypt -the connection between the **client** (you, me, your visitors) -and the **server** (where you site lives), through a keychain of -authentications and validations. - -How about taking Josh's advice and protecting our sites too? We will be -well supported, and we'll contribute to a safer internet. - -### Organizations supporting HTTPS - -There is a huge movement in favor of securing all the web. W3C fully -[supports the cause](https://w3ctag.github.io/web-https/) and explains very well -the reasons for that. Richard Barnes, a writer for Mozilla Security Blog, -suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/), -and would no longer accept unsecured connections. Recently, Mozilla published a -[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/) -reiterating the importance of HTTPS. - -## Issuing Certificates - -GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by -[Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as -[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://securingtomorrow.mcafee.com/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) -for public websites for security reasons and to ensure that browsers trust your site's certificate. - -There are various kinds of certificates, each one -with a certain security level. A static personal website will -not require the same security level as an online banking web app, -for instance. - -There are some certificate authorities that -offer free certificates, aiming to make the internet more secure -to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/), -which issues certificates trusted by most of browsers, it's open -source, and free to use. See our tutorial on [how to secure your GitLab Pages website with Let's Encrypt](lets_encrypt_for_gitlab_pages.md). - -Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/), -which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/). -Their certs are valid up to 15 years. See the tutorial on -[how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/). - -### Adding certificates to your project - -Regardless the CA you choose, the steps to add your certificate to -your Pages project are the same. - -### What do you need - -1. A PEM certificate -1. An intermediate certificate -1. A private key - - - -These fields are found under your **Project**'s **Settings** > **Pages** > **New Domain**. - -### What's what? - -- A PEM certificate is the certificate generated by the CA, - which needs to be added to the field **Certificate (PEM)**. -- An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority) (aka "root certificate") is - the part of the encryption keychain that identifies the CA. - Usually it's combined with the PEM certificate, but there are - some cases in which you need to add them manually. - [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) - are one of these cases. -- A private key is an encrypted key which validates - your PEM against your domain. - -### Now what? - -Now that you hopefully understand why you need all -of this, it's simple: - -- Your PEM certificate needs to be added to the first field -- If your certificate is missing its intermediate, copy - and paste the root certificate (usually available from your CA website) - and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), - just jumping a line between them. -- Copy your private key and paste it in the last field - ->**Note:** -**Do not** open certificates or encryption keys in -regular text editors. Always use code editors (such as -Sublime Text, Atom, Dreamweaver, Brackets, etc). - -_Read on about [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md)_ +This document was moved to [another location](custom_domains_ssl_tls_certification/index.md). diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 3e50cd4887c..3bab652ca39 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -22,7 +22,7 @@ Optional Features: 1. **Optional**: an SSL/TLS certificate so your custom domain is accessible under HTTPS. -The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [Part 3](getting_started_part_three.md)). +The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md)). ## Project @@ -77,23 +77,23 @@ containing the most popular SSGs templates to get you started. 1. [Fork](../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. 1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** -and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your -site to the server. + and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + site to the server. 1. Once the pipeline has finished successfully, find the link to visit your -website from your project's **Settings > Pages**. + website from your project's **Settings > Pages**. You can also take some **optional** further steps: - _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: -  +  - _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`: go to your project's + from the Pages group into a **user/group** website, you'll need to: + - 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 + - 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 config file. @@ -107,12 +107,12 @@ from the Pages group into a **user/group** website, you'll need to: files to your project, add, commit and push to GitLab. 1. From the your **Project**'s page, click **Set up CI/CD**: -  +  1. Choose one of the templates from the dropbox menu. Pick up the template corresponding to the SSG you're using (or plain HTML). -  +  Once you have both site files and `.gitlab-ci.yml` in your project's root, GitLab CI/CD will build your site and deploy it with Pages. @@ -123,20 +123,20 @@ where you'll find its default URL. > **Notes:** > > - GitLab Pages [supports any SSG](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/), but, - if you don't find yours among the templates, you'll need - to configure your own `.gitlab-ci.yml`. To do that, please - read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among - the [example projects](https://gitlab.com/pages). If you set - up a new one, please - [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md) - to our examples. +> if you don't find yours among the templates, you'll need +> to configure your own `.gitlab-ci.yml`. To do that, please +> read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among +> the [example projects](https://gitlab.com/pages). If you set +> up a new one, please +> [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md) +> to our examples. > > - The second step _"Clone it to your local computer"_, can be done - differently, achieving the same results: instead of cloning the bare - repository to you local computer and moving your site files into it, - you can run `git init` in your local website directory, add the - remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, - then add, commit, and push to GitLab. +> differently, achieving the same results: instead of cloning the bare +> repository to you local computer and moving your site files into it, +> you can run `git init` in your local website directory, add the +> remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, +> then add, commit, and push to GitLab. ## URLs and Baseurls @@ -169,4 +169,4 @@ baseurl: "" ## Custom Domains GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. -See [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md) for more information. +See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information. diff --git a/doc/user/project/pages/img/pages_project_templates_11-8.png b/doc/user/project/pages/img/pages_project_templates_11-8.png Binary files differdeleted file mode 100644 index a645d28260b..00000000000 --- a/doc/user/project/pages/img/pages_project_templates_11-8.png +++ /dev/null diff --git a/doc/user/project/pages/img/pages_project_templates_v11_8.png b/doc/user/project/pages/img/pages_project_templates_v11_8.png Binary files differnew file mode 100644 index 00000000000..61cae88b5a8 --- /dev/null +++ b/doc/user/project/pages/img/pages_project_templates_v11_8.png diff --git a/doc/user/project/pages/img/remove_pages.png b/doc/user/project/pages/img/remove_pages.png Binary files differindex 60f76f15f93..d6c37ef30cd 100644 --- a/doc/user/project/pages/img/remove_pages.png +++ b/doc/user/project/pages/img/remove_pages.png diff --git a/doc/user/project/pages/img/verify_your_domain.png b/doc/user/project/pages/img/verify_your_domain.png Binary files differdeleted file mode 100644 index d870f9e6505..00000000000 --- a/doc/user/project/pages/img/verify_your_domain.png +++ /dev/null diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 04bda212128..a0bc10b0ed7 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -12,7 +12,6 @@ type: index, reference > - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8. > - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/47857) in GitLab 11.8. - **GitLab Pages is a feature that allows you to publish static websites directly from a repository in GitLab.** @@ -102,13 +101,13 @@ To get started with GitLab Pages, you can either: 1. Select **Create from Template**. 1. Choose one of the templates starting with **Pages**: -  +  1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** -and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your -site to the server. + and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + site to the server. 1. Once the pipeline has finished successfully, find the link to visit your -website from your project's **Settings > Pages**. + website from your project's **Settings > Pages**. Your website is then visible on your domain, and you can modify yourfiles as you wish. For every modification pushed to your repository, GitLab CI/CD @@ -116,8 +115,8 @@ will run a new pipeline to publish your changes to the server. _Advanced options:_ -- [Use a custom domain](getting_started_part_three.md#adding-your-custom-domain-to-gitlab-pages) -- Apply [SSL/TLS certification](getting_started_part_three.md#ssltls-certificates) to your custom domain +- [Use a custom domain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) +- Apply [SSL/TLS certification](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages) to your custom domain ## Availability @@ -141,11 +140,11 @@ To learn more about configuration options for GitLab Pages, read the following: | [Static websites and Pages domains](getting_started_part_one.md) | Understand what is a static website, and how GitLab Pages default domains work. | | [Projects and URL structure](getting_started_part_two.md) | Forking projects and creating new ones from scratch, understanding URLs structure and baseurls. | | [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. | -| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, custom 404 pages, limitations, FAQ. | +| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, Access Control, custom 404 pages, limitations, FAQ. | |---+---| -| [Custom domains and SSL/TLS Certificates](getting_started_part_three.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. | +| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. | +| [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates automatically obtained and renewed by GitLab. | | [CloudFlare certificates](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. | -| [Let's Encrypt certificates](lets_encrypt_for_gitlab_pages.md) | Secure your Pages site with Let's Encrypt certificates. | |---+---| | [Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | A conceptual overview on static versus dynamic sites. | | [Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) | A conceptual overview on SSGs. | diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 4fab7f79e0c..e8984cb8b9f 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -13,17 +13,17 @@ To familiarize yourself with GitLab Pages first: - Read an [introduction to GitLab Pages](index.md#overview). - Learn [how to get started with Pages](index.md#getting-started). - Learn how to enable GitLab Pages -across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md). + across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md). ## GitLab Pages requirements In brief, this is what you need to upload your website in GitLab Pages: 1. Domain of the instance: domain name that is used for GitLab Pages -(ask your administrator). + (ask your administrator). 1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`][pages] in the root directory of your repository. 1. A directory called `public` in your site's repo containing the content -to be published. + to be published. 1. GitLab Runner enabled for the project. ## GitLab Pages on GitLab.com @@ -67,7 +67,7 @@ Some static site generators provide plugins for that functionality so that you don't have to create and edit HTML files manually. For example, Jekyll has the [redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from). -## GitLab Pages Access Control **[CORE ONLY]** +## GitLab Pages Access Control **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. @@ -83,23 +83,23 @@ You can enable Pages access control on your project, so that only 1. Navigate to your project's **Settings > General > Permissions**. 1. Toggle the **Pages** button to enable the access control. - NOTE: **Note:** - If you don't see the toggle button, that means that it's not enabled. - Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). + NOTE: **Note:** + If you don't see the toggle button, that means that it's not enabled. + Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). 1. The Pages access control dropdown allows you to set who can view pages hosted with GitLab Pages, depending on your project's visibility: - - If your project is private: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. - - If your project is internal: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. - - If your project is public: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is private: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is internal: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. + - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is public: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. 1. Click **Save changes**. diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 91a660c0f7a..1338c7e58f5 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,10 +1,15 @@ --- -description: "How to secure GitLab Pages websites with Let's Encrypt." +description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." type: howto -last_updated: 2019-06-04 +last_updated: 2019-07-15 --- -# Let's Encrypt for GitLab Pages +# Let's Encrypt for GitLab Pages (manual process, deprecated) + +CAUTION: **Warning:** +This method is still valid but was **deprecated** in favor of the +[Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) +introduced in GitLab 12.1. If you have a GitLab Pages website served under your own domain, you might want to secure it with a SSL/TSL certificate. @@ -18,9 +23,9 @@ To follow along with this tutorial, we assume you already have: - Created a [project](getting_started_part_two.md) in GitLab which contains your website's source code. -- Acquired a domain (`example.com`) and added a [DNS entry](getting_started_part_three.md#dns-records) +- Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) pointing it to your Pages website. -- [Added your domain to your Pages project](getting_started_part_three.md#add-your-custom-domain-to-gitlab-pages-settings) +- [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps) and verified your ownership. - Cloned your project into your computer. - Your website up and running, served under HTTP protocol at `http://example.com`. @@ -36,111 +41,111 @@ operating systems the steps might be slightly different. Follow the [CertBot instructions](https://certbot.eff.org/) according to your OS. 1. On your computer, open a terminal and navigate to your repository's - root directory: + root directory: - ```bash - cd path/to/dir - ``` + ```bash + cd path/to/dir + ``` 1. Install CertBot (the tool Let's Encrypt uses to issue certificates): - ```bash - brew install certbot - ``` + ```bash + brew install certbot + ``` 1. Request a certificate for your domain (`example.com`) and - provide an email account (`your@email.com`) to receive notifications: + provide an email account (`your@email.com`) to receive notifications: - ```bash - sudo certbot certonly -a manual -d example.com --email your@email.com - ``` + ```bash + sudo certbot certonly -a manual -d example.com --email your@email.com + ``` - Alternatively, you can register without adding an e-mail account, - but you won't be notified about the certificate expiration's date: + Alternatively, you can register without adding an e-mail account, + but you won't be notified about the certificate expiration's date: - ```bash - sudo certbot certonly -a manual -d example.com --register-unsafely-without-email - ``` + ```bash + sudo certbot certonly -a manual -d example.com --register-unsafely-without-email + ``` - TIP: **Tip:** - Read through CertBot's documentation on their - [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). + TIP: **Tip:** + Read through CertBot's documentation on their + [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). 1. You'll be prompted with a message to agree with their terms. - Press `A` to agree and `Y` to let they log your IP. + Press `A` to agree and `Y` to let they log your IP. - CertBot will then prompt you with the following message: + CertBot will then prompt you with the following message: - ```bash - Create a file containing just this data: + ```bash + Create a file containing just this data: - Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb + Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb - And make it available on your web server at this URL: + And make it available on your web server at this URL: - http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP + http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP - Press Enter to Continue - ``` + Press Enter to Continue + ``` 1. **Do not press Enter yet.** Let's Encrypt will need to verify your - domain ownership before issuing the certificate. To do so, create 3 - consecutive directories under your website's root: - `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` - and add to the last folder an `index.html` file containing the content - referred on the previous prompt message: - - ```bash - Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb - ``` - - Note that this file needs to be accessed under - `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` - to allow Let's Encrypt to verify the ownership of your domain, - therefore, it needs to be part of the website content under the - repo's [`public`](index.md#how-it-works) folder. + domain ownership before issuing the certificate. To do so, create 3 + consecutive directories under your website's root: + `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` + and add to the last folder an `index.html` file containing the content + referred on the previous prompt message: + + ```bash + Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb + ``` + + Note that this file needs to be accessed under + `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` + to allow Let's Encrypt to verify the ownership of your domain, + therefore, it needs to be part of the website content under the + repo's [`public`](index.md#how-it-works) folder. 1. Add, commit, and push the file into your repo in GitLab. Once the pipeline - passes, press **Enter** on your terminal to continue issuing your - certificate. CertBot will then prompt you with the following message: - - ```bash - Waiting for verification... - Cleaning up challenges - - IMPORTANT NOTES: - - Congratulations! Your certificate and chain have been saved at: - /etc/letsencrypt/live/example.com/fullchain.pem - Your key file has been saved at: - /etc/letsencrypt/live/example.com/privkey.pem - Your cert will expire on 2019-03-12. To obtain a new or tweaked - version of this certificate in the future, simply run certbot - again. To non-interactively renew *all* of your certificates, run - "certbot renew" - - If you like Certbot, please consider supporting our work by: - - Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate - Donating to EFF: https://eff.org/donate-le - ``` + passes, press **Enter** on your terminal to continue issuing your + certificate. CertBot will then prompt you with the following message: + + ```bash + Waiting for verification... + Cleaning up challenges + + IMPORTANT NOTES: + - Congratulations! Your certificate and chain have been saved at: + /etc/letsencrypt/live/example.com/fullchain.pem + Your key file has been saved at: + /etc/letsencrypt/live/example.com/privkey.pem + Your cert will expire on 2019-03-12. To obtain a new or tweaked + version of this certificate in the future, simply run certbot + again. To non-interactively renew *all* of your certificates, run + "certbot renew" + - If you like Certbot, please consider supporting our work by: + + Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate + Donating to EFF: https://eff.org/donate-le + ``` ## Add your certificate to GitLab Pages Now that your certificate has been issued, let's add it to your Pages site: 1. Back at GitLab, navigate to your project's **Settings > Pages**, - find your domain and click **Details** and **Edit** to add your certificate. + find your domain and click **Details** and **Edit** to add your certificate. 1. From your terminal, copy and paste the certificate into the first field - **Certificate (PEM)**: + **Certificate (PEM)**: - ```bash - sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy - ``` + ```bash + sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy + ``` 1. Copy and paste the private key into the second field **Key (PEM)**: - ```bash - sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy - ``` + ```bash + sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy + ``` 1. Click **Save changes** to apply them to your website. 1. Wait a few minutes for the configuration changes to take effect. 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 29846206491..ce3c3dc6af1 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 e135dd51070..993fbf8ca00 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/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 002addfc043..ef90899c512 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -1,24 +1,24 @@ +--- +type: reference, howto +--- + # Introduction to job artifacts -> **Notes:** -> -> - Since GitLab 8.2 and GitLab Runner 0.7.0, job artifacts that are created by -> GitLab Runner are uploaded to GitLab and are downloadable as a single archive -> (`tar.gz`) using the GitLab UI. -> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format -> changed to `ZIP`, and it is now possible to browse its contents, with the added -> ability of downloading the files separately. -> - Starting with GitLab 8.17, builds are renamed to jobs. -> - The artifacts browser will be available only for new artifacts that are sent -> to GitLab using GitLab Runner version 1.0 and up. It will not be possible to -> browse old artifacts already uploaded to GitLab. ->- This is the user documentation. For the administration guide see -> [administration/job_artifacts](../../../administration/job_artifacts.md). - -Artifacts is a list of files and directories which are attached to a job -after it finishes. This feature is enabled by default in all +> - Introduced in GitLab 8.2 and GitLab Runner 0.7.0. +> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format changed to `ZIP`, and it is now possible to browse its contents, with the added ability of downloading the files separately. +> - In GitLab 8.17, builds were renamed to jobs. +> - The artifacts browser will be available only for new artifacts that are sent to GitLab using GitLab Runner version 1.0 and up. It will not be possible to browse old artifacts already uploaded to GitLab. + +Artifacts are a list of files and directories which created by a job +once it finishes. This feature is [enabled by default](../../../administration/job_artifacts.md) in all GitLab installations. +Job artifacts that are created by GitLab Runner are uploaded to GitLab and are downloadable as a single archive using the GitLab UI. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s). +Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII). + ## Defining artifacts in `.gitlab-ci.yml` A simple example of using the artifacts definition in `.gitlab-ci.yml` would be @@ -50,11 +50,8 @@ For more examples on artifacts, follow the [artifacts reference in ## Browsing artifacts -> **Note:** > With GitLab 9.2, PDFs, images, videos and other formats can be previewed > directly in the job artifacts browser without the need to download them. -> -> **Note:** > With [GitLab 10.1][ce-14399], HTML files in a public project can be previewed > directly in a new tab without the need to download them when > [GitLab Pages](../../../administration/pages/index.md) is enabled. @@ -67,8 +64,6 @@ artifacts in case you changed your mind and want to keep them.  ---- - The archive browser shows the name and the actual file size of each file in the archive. If your artifacts contained directories, then you are also able to browse inside them. @@ -80,8 +75,6 @@ one HTML file that you can view directly online when  ---- - ## Downloading artifacts If you need to download the whole archive, there are buttons in various places @@ -90,29 +83,29 @@ inside GitLab that make that possible. 1. While on the pipelines page, you can see the download icon for each job's artifacts archive in the right corner: -  +  1. While on the **Jobs** page, you can see the download icon for each job's artifacts archive in the right corner: -  +  1. While inside a specific job, you are presented with a download button along with the one that browses the archive: -  +  1. And finally, when browsing an archive you can see the download button at the top right corner: -  +  ## Downloading the latest artifacts It is possible to download the latest artifacts of a job via a well known URL so you can use it for scripting purposes. ->**Note:** +NOTE: **Note:** The latest artifacts are considered as the artifacts created by jobs in the latest pipeline that succeeded for the specific ref. Artifacts for other pipelines can be accessed with direct access to them. @@ -173,9 +166,9 @@ https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/file/htmlcov/ind The latest builds are also exposed in the UI in various places. Specifically, look for the download button in: -- the main project's page -- the branches page -- the tags page +- The main project's page +- The branches page +- The tags page If the latest job has failed to upload the artifacts, you can see that information in the UI. @@ -187,9 +180,13 @@ information in the UI. DANGER: **Warning:** This is a destructive action that leads to data loss. Use with caution. -If you have at least Developer [permissions](../../permissions.md#gitlab-cicd-permissions) -on the project, you can erase a single job via the UI which will also remove the -artifacts and the job's trace. +You can erase a single job via the UI, which will also remove the job's +artifacts and trace, if you are: + +- The owner of the job. +- A [Maintainer](../../permissions.md#gitlab-cicd-permissions) of the project. + +To erase a job: 1. Navigate to a job's page. 1. Click the trash icon at the top right of the job's trace. @@ -201,3 +198,15 @@ In order to retrieve a job artifact of a different project, you might need to us [expiry date]: ../../../ci/yaml/README.md#artifactsexpire_in [ce-14399]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14399 + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index dd5427ab35a..f3e9c950efd 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -1,10 +1,14 @@ +--- +type: reference, howto +--- + # Pipeline schedules -> **Notes**: -> > - Introduced in GitLab 9.1 as [Trigger Schedule](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10533). > - [Renamed to Pipeline Schedule](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10853) in GitLab 9.2. -> - Cron notation is parsed by [Fugit](https://github.com/floraison/fugit). + +NOTE: **Note:** +Cron notation is parsed by [Fugit](https://github.com/floraison/fugit). Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository. @@ -118,3 +122,15 @@ on the target branch, the schedule will stop creating new pipelines. This can happen if, for example, the owner is blocked or removed from the project, or the target branch or tag is protected. In this case, someone with sufficient privileges must take ownership of the schedule. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 16f48c462eb..456209c2180 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Pipelines settings To reach the pipelines settings navigate to your project's @@ -5,6 +9,10 @@ To reach the pipelines settings navigate to your project's The following settings can be configured per project. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s). +Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII). + ## Git strategy With Git strategy, you can choose the default way your repository is fetched @@ -24,10 +32,11 @@ in `.gitlab-ci.yml`. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28919) in GitLab 12.0. -NOTE: **Note**: As of GitLab 12.0, newly created projects will automaticallyl have a default +NOTE: **Note**: +As of GitLab 12.0, newly created projects will automatically have a default `git depth` value of `50`. -It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning +It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning a repository. Setting a limit to `git depth` can speed up Pipelines execution. Maximum allowed value is `1000`. @@ -67,6 +76,13 @@ Here are some valid examples: - `my/path/.gitlab-ci.yml` - `my/path/.my-custom-file.yml` +The path can be customized at a project level. To customize the path: + +1. Go to the project's **Settings > CI / CD**. +1. Expand the **General pipelines** section. +1. Provide a value in the **Custom CI config path** field. +1. Click **Save changes**. + ## Test coverage parsing If you use test coverage in your code, GitLab can capture its output in the @@ -88,6 +104,22 @@ in the jobs table. A few examples of known coverage tools for a variety of languages can be found in the pipelines settings page. +### Removing color codes + +Some test coverage tools output with ANSI color codes that won't be +parsed correctly by the regular expression and will cause coverage +parsing to fail. + +If your coverage tool doesn't provide an option to disable color +codes in the output, you can pipe the output of the coverage tool through a +small one line script that will strip the color codes off. + +For example: + +```bash +lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' +``` + ## Visibility of pipelines Access to pipelines and job details (including output of logs and artifacts) @@ -199,3 +231,15 @@ https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?st ## Environment Variables [Environment variables](../../../ci/variables/README.html#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 56e8f1731ae..7a79cdbcaee 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Protected Branches [Permissions](../permissions.md) in GitLab are fundamentally defined around the @@ -9,13 +13,13 @@ created protected branches. By default, a protected branch does four simple things: -- it prevents its creation, if not already created, from everybody except users - with Maintainer permission -- it prevents pushes from everybody except users with Maintainer permission -- it prevents **anyone** from force pushing to the branch -- it prevents **anyone** from deleting the branch +- It prevents its creation, if not already created, from everybody except users + with Maintainer permission. +- It prevents pushes from everybody except users with Maintainer permission. +- It prevents **anyone** from force pushing to the branch. +- It prevents **anyone** from deleting the branch. ->**Note**: +NOTE: **Note:** A GitLab admin is allowed to push to the protected branches. See the [Changelog](#changelog) section for changes over time. @@ -30,11 +34,11 @@ that the `master` branch is protected by default. 1. From the **Branch** dropdown menu, select the branch you want to protect and click **Protect**. In the screenshot below, we chose the `develop` branch. -  +  1. Once done, the protected branch will appear in the "Protected branches" list. -  +  ## Using the Allowed to merge and Allowed to push settings @@ -66,9 +70,9 @@ 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]** +## Restricting push and merge access to certain users **(STARTER)** -> This feature was [introduced][ce-5081] in [GitLab Starter][ee] 8.11. +> [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 @@ -141,7 +145,7 @@ branches via GitLab's web interface: 1. In order to prevent accidental deletion, an additional confirmation is required -  +  Deleting a protected branch is only allowed via the web interface, not via Git. This means that you can't accidentally delete a protected branch from your @@ -174,12 +178,21 @@ for details about the pipelines security model. - Allow developers to merge into a protected branch without having push access [gitlab-org/gitlab-ce!4892][ce-4892] - Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!4665][ce-4665] ---- - [ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665 "Allow specifying protected branches using wildcards" [ce-4892]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4892 "Allow developers to merge into a protected branch without having push access" [ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081 "Allow creating protected branches that can't be pushed to" [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/ + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 26bec323f02..5cc3b8a7fc3 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Protected Tags > [Introduced][ce-10356] in GitLab 9.1. @@ -14,21 +18,21 @@ Protected tags will prevent anyone from updating or deleting the tag, as and wil To protect a tag, you need to have at least Maintainer permission level. -1. Navigate to the project's Settings -> Repository page +1. Navigate to the project's **Settings > Repository**: -  +  -1. From the **Tag** dropdown menu, select the tag you want to protect or type and click `Create wildcard`. In the screenshot below, we chose to protect all tags matching `v*`. +1. From the **Tag** dropdown menu, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`: -  +  -1. From the `Allowed to create` dropdown, select who will have permission to create matching tags and then click `Protect`. +1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**: -  +  -1. Once done, the protected tag will appear in the "Protected tags" list. +1. Once done, the protected tag will appear in the **Protected tags** list: -  +  ## Wildcard protected tags @@ -45,13 +49,23 @@ matching the wildcard. For example: Two different wildcards can potentially match the same tag. For example, `*-stable` and `production-*` would both match a `production-stable` tag. In that case, if _any_ of these protected tags have a setting like -"Allowed to create", then `production-stable` will also inherit this setting. +**Allowed to create**, then `production-stable` will also inherit this setting. If you click on a protected tag's name, you will be presented with a list of all matching tags:  ---- +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> [ce-10356]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10356 "Protected Tags" diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 1d640966013..647250bd02a 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -1,13 +1,18 @@ -# GitLab quick actions +--- +type: reference +--- + +# GitLab Quick Actions Quick actions are textual shortcuts for common actions on issues, epics, merge requests, and commits that are usually done by clicking buttons or dropdowns in GitLab's UI. You can enter these commands while creating a new issue or merge request, or in comments of issues, epics, merge requests, and commits. Each command should be on a separate line in order to be properly detected and executed. Once executed, -the commands are removed from the text body and not visible to anyone else. -## Quick actions for issues and merge requests +> From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26672), an alert is displayed when a quick action is successfully applied. + +## Quick Actions for issues and merge requests The following quick actions are applicable to both issues and merge requests threads, discussions, and descriptions: @@ -16,8 +21,8 @@ discussions, and descriptions: |:---------------------------|:------------------------------ |:------|:--------------| | `/tableflip <Comment>` | Append the comment with `(╯°□°)╯︵ ┻━┻` | ✓ | ✓ | | `/shrug <Comment>` | Append the comment with `¯\＿(ツ)＿/¯` | ✓ | ✓ | -| `/todo` | Add a todo | ✓ | ✓ | -| `/done` | Mark todo as done | ✓ | ✓ | +| `/todo` | Add a To Do | ✓ | ✓ | +| `/done` | Mark To Do as done | ✓ | ✓ | | `/subscribe` | Subscribe | ✓ | ✓ | | `/unsubscribe` | Unsubscribe | ✓ | ✓ | | `/close` | Close | ✓ | ✓ | @@ -26,37 +31,59 @@ discussions, and descriptions: | `/award :emoji:` | Toggle emoji award | ✓ | ✓ | | `/assign me` | Assign yourself | ✓ | ✓ | | `/assign @user` | Assign one user | ✓ | ✓ | -| `/assign @user1 @user2` | Assign multiple users **[STARTER]** | ✓ | ✓ | -| `/unassign @user1 @user2` | Remove assignee(s) **[STARTER]** | ✓ | ✓ | -| `/reassign @user1 @user2` | Change assignee **[STARTER]** | ✓ | ✓ | +| `/assign @user1 @user2` | Assign multiple users **(STARTER)** | ✓ | ✓ | +| `/unassign @user1 @user2` | Remove assignee(s) **(STARTER)** | ✓ | ✓ | +| `/reassign @user1 @user2` | Change assignee **(STARTER)** | ✓ | ✓ | | `/unassign` | Remove current assignee | ✓ | ✓ | | `/milestone %milestone` | Set milestone | ✓ | ✓ | | `/remove_milestone` | Remove milestone | ✓ | ✓ | | `/label ~label1 ~label2` | Add label(s). Label names can also start without ~ but mixed syntax is not supported. | ✓ | ✓ | | `/unlabel ~label1 ~label2` | Remove all or specific label(s)| ✓ | ✓ | -| `/relabel ~label1 ~label2` | Replace label | ✓ | ✓ | -| <code>/copy_metadata #issue | !merge_request</code> | Copy labels and milestone from other issue or merge request in the project | ✓ | ✓ | -| <code>/estimate <1w 3d 2h 14m></code> | Set time estimate | ✓ | ✓ | +| `/relabel ~label1 ~label2` | Replace existing label(s) with those specified | ✓ | ✓ | +| `/copy_metadata <#issue>` | Copy labels and milestone from another issue in the project | ✓ | ✓ | +| `/copy_metadata <!merge_request>` | Copy labels and milestone from another merge request in the project | ✓ | ✓ | +| `/estimate <1w 3d 2h 14m>` | Set time estimate | ✓ | ✓ | | `/remove_estimate` | Remove time estimate | ✓ | ✓ | -| <code>/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)></code> | Add or subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | +| `/spend <time(1h 30m)> <date(YYYY-MM-DD)>` | Add spent time; optionally, specify the date that time was spent on | ✓ | ✓ | +| `/spend <time(-1h 5m)> <date(YYYY-MM-DD)>` | Subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | | `/remove_time_spent` | Remove time spent | ✓ | ✓ | -| `/lock` | Lock the discussion | ✓ | ✓ | -| `/unlock` | Unlock the discussion | ✓ | ✓ | -| <code>/due <in 2 days | this Friday | December 31st></code>| Set due date | ✓ | | +| `/lock` | Lock the thread | ✓ | ✓ | +| `/unlock` | Unlock the thread | ✓ | ✓ | +| `/due <date>` | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | ✓ | | | `/remove_due_date` | Remove due date | ✓ | | -| `/weight 0,1,2, ...` | Set weight **[STARTER]** | ✓ | | -| `/clear_weight` | Clears weight **[STARTER]** | ✓ | | -| `/epic <&epic | group&epic | Epic URL>` | Add to epic **[ULTIMATE]** | ✓ | | -| `/remove_epic` | Removes from epic **[ULTIMATE]** | ✓ | | -| `/promote` | Promote issue to epic **[ULTIMATE]** | ✓ | | +| `/weight <value>` | Set weight. Valid options for `<value>` include `0`, `1`, `2`, etc. **(STARTER)** | ✓ | | +| `/clear_weight` | Clears weight **(STARTER)** | ✓ | | +| `/epic <epic>` | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. **(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 | ✓ | | +| `/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 | ✓ | | +| `/relate #issue1 #issue2` | Mark issues as related **(STARTER)** | ✓ | | + +## Autocomplete characters + +Many quick actions require a parameter, for example: username, milestone, and +label. [Autocomplete characters](autocomplete_characters.md) can make it easier +to enter a parameter, compared to selecting items from a list. + +## Quick actions parameters + +The easiest way to set parameters for quick actions is to use autocomplete. If +you manually enter a parameter, it must be enclosed in double quotation marks +(`"`), unless it contains only: + +1. ASCII letters. +1. Numerals. +1. Underscore, hyphen, question mark, dot, and ampersand. + +Parameters are also case-sensitive. Autocomplete handles this, and the insertion +of quotation marks, automatically. ## Quick actions for commit messages @@ -66,7 +93,7 @@ The following quick actions are applicable for commit messages: |:------------------------|:------------------------------------------| | `/tag v1.2.3 <message>` | Tags this commit with an optional message | -## Quick actions for Epics **[ULTIMATE]** +## Quick actions for Epics **(ULTIMATE)** The following quick actions are applicable for epics threads and description: @@ -74,8 +101,8 @@ The following quick actions are applicable for epics threads and description: |:---------------------------|:----------------------------------------| | `/tableflip <Comment>` | Append the comment with `(╯°□°)╯︵ ┻━┻` | | `/shrug <Comment>` | Append the comment with `¯\＿(ツ)＿/¯` | -| `/todo` | Add a todo | -| `/done` | Mark todo as done | +| `/todo` | Add a To Do | +| `/done` | Mark To Do as done | | `/subscribe` | Subscribe | | `/unsubscribe` | Unsubscribe | | `/close` | Close | @@ -84,4 +111,20 @@ The following quick actions are applicable for epics threads and description: | `/award :emoji:` | Toggle emoji award | | `/label ~label1 ~label2` | Add label(s) | | `/unlabel ~label1 ~label2` | Remove all or specific label(s) | -| `/relabel ~label1 ~label2` | Replace label | +| `/relabel ~label1 ~label2` | Replace existing label(s) with those specified | +| `/child_epic <epic>` | Adds child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) **(ULTIMATE)**| +| `/remove_child_epic <epic>` | Removes child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) **(ULTIMATE)** | +| `/parent_epic <epic>` | Sets parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic` or `epic-URL`. ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) **(ULTIMATE)** | +| `/remove_parent_epic` | Removes parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) | + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/releases/img/releases.png b/doc/user/project/releases/img/releases.png Binary files differindex f8b1b7305ad..da5bcd9d913 100644 --- a/doc/user/project/releases/img/releases.png +++ b/doc/user/project/releases/img/releases.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 00a4f6c6a6b..aae253467f0 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Releases > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. @@ -60,3 +64,15 @@ Navigate to **Project > Releases** in order to see the list of releases for a gi project.  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/repository/img/compare_branches.png b/doc/user/project/repository/branches/img/compare_branches.png Binary files differindex 52d5c518c45..52d5c518c45 100644 --- a/doc/user/project/repository/img/compare_branches.png +++ b/doc/user/project/repository/branches/img/compare_branches.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 13e4f2ce163..a864665602e 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,17 +1,41 @@ +--- +type: concepts, howto +--- + # Branches -Read through GiLab's branching documentation: +A branch is a version of a project's working tree. You create a branch for each +set of related changes you make. This keeps each set of changes separate from +each other, allowing changes to be made in parallel, without affecting each +other. + +After pushing your changes to a new branch, you can: + +- Create a [merge request](../../merge_requests/index.md) +- Perform inline code review +- [Discuss](../../../discussions/index.md) your implementation with your team +- Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). + +With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request +[approval](../../merge_requests/merge_request_approvals.md) from your managers. + +For more information on managing branches using the GitLab UI, see: + +- [Default branches](#default-branch) +- [Create a branch](../web_editor.md#create-a-new-branch) +- [Protected branches](../../protected_branches.md#protected-branches) +- [Delete merged branches](#delete-merged-branches) +- [Branch filter search box](#branch-filter-search-box) + +You can also manage branches using the +[command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). -- [Create a branch](../web_editor.md#create-a-new-branch). -- [Default branch](#default-branch). -- [Protected branches](../../protected_branches.md#protected-branches). -- [Delete merged branches](#delete-merged-branches). -- [Branch filter search box](#branch-filter-search-box). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Watch the video [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE). See also: - [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. -- [GitLab Flow](../../../../university/training/gitlab_flow.md). Use the best of GitLab for your branching strategies. +- [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation. - [Getting started with Git](../../../../topics/git/index.md) and GitLab. ## Default branch @@ -21,7 +45,7 @@ branch for your project. You can choose another branch to be your project's default under your project's **Settings > Repository**. The default branch is the branch affected by the -[issue closing pattern](../../issues/automatic_issue_closing.md), +[issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically), which means that _an issue will be closed when a merge request is merged to the **default branch**_. @@ -29,6 +53,17 @@ The default branch is also protected against accidental deletion. Read through the documentation on [protected branches](../../protected_branches.md#protected-branches) to learn more. +## Compare + +To compare branches in a repository: + +1. Navigate to your project's repository. +1. Select **Repository > Compare** in the sidebar. +1. Select branches to compare using the [branch filter search box](#branch-filter-search-box) +1. Click **Compare** to view the changes inline: + + + ## Delete merged branches > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449) in GitLab 8.14. @@ -57,3 +92,15 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi - `^feature` will only match branch names that begin with 'feature'. - `feature$` will only match branch names that end with 'feature'. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 3260a355fdc..b929c6a681a 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,38 +1,39 @@ -# Signing commits with GPG +--- +type: concepts, howto +--- -NOTE: **Note:** -The term GPG is used for all OpenPGP/PGP/GPG related material and -implementations. +# Signing commits with GPG > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546) in GitLab 9.5. > - Subkeys support was added in GitLab 10.1. -GitLab can show whether a commit is verified or not when signed with a GPG key. -All you need to do is upload the public GPG key in your profile settings. - -GPG verified tags are not supported yet. +You can use a GPG key to sign Git commits made in a GitLab repository. Signed +commits are labeled **Verified** if the identity of the committer can be +verified. To verify the identity of a committer, GitLab requires their public +GPG key. -## Getting started with GPG +NOTE: **Note:** +The term GPG is used for all OpenPGP/PGP/GPG related material and +implementations. -Here are a few guides to get you started with GPG: +GPG verified tags are not supported yet. -- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) -- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) -- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) -- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) +See the [further reading](#further-reading) section for more details on GPG. ## How GitLab handles GPG GitLab uses its own keyring to verify the GPG signature. It does not access any public key server. -In order to have a commit verified on GitLab the corresponding public key needs -to be uploaded to GitLab. For a signature to be verified three conditions need -to be met: +For a commit to be verified by GitLab: -1. The public key needs to be added your GitLab account -1. One of the emails in the GPG key matches a **verified** email address you use in GitLab -1. The committer's email matches the verified email from the gpg key +- The committer must have a GPG public/private key pair. +- The committer's public key must have been uploaded to their GitLab + account. +- One of the emails in the GPG key must match a **verified** email address + used by the committer in GitLab. +- The committer's email address must match the verified email address from the + GPG key. ## Generating a GPG key @@ -45,94 +46,94 @@ started: 1. Generate the private/public key pair with the following command, which will spawn a series of questions: - ```sh - gpg --full-gen-key - ``` + ```sh + gpg --full-gen-key + ``` - NOTE: **Note:** - In some cases like Gpg4win on Windows and other macOS versions, the command - here may be `gpg --gen-key`. + NOTE: **Note:** + In some cases like Gpg4win on Windows and other macOS versions, the command + here may be `gpg --gen-key`. 1. The first question is which algorithm can be used. Select the kind you want or press <kbd>Enter</kbd> to choose the default (RSA and RSA): - ``` - Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - Your selection? 1 - ``` - -1. The next question is key length. We recommend to choose the highest value - which is `4096`: - - ``` - RSA keys may be between 1024 and 4096 bits long. - What keysize do you want? (2048) 4096 - Requested keysize is 4096 bits - ``` -1. Next, you need to specify the validity period of your key. This is something - subjective, and you can use the default value which is to never expire: - - ``` - Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years - Key is valid for? (0) 0 - Key does not expire at all - ``` + ``` + Please select what kind of key you want: + (1) RSA and RSA (default) + (2) DSA and Elgamal + (3) DSA (sign only) + (4) RSA (sign only) + Your selection? 1 + ``` + +1. The next question is key length. We recommend you choose `4096`: + + ``` + RSA keys may be between 1024 and 4096 bits long. + What keysize do you want? (2048) 4096 + Requested keysize is 4096 bits + ``` + +1. Specify the validity period of your key. This is something + subjective, and you can use the default value, which is to never expire: + + ``` + Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + <n>w = key expires in n weeks + <n>m = key expires in n months + <n>y = key expires in n years + Key is valid for? (0) 0 + Key does not expire at all + ``` 1. Confirm that the answers you gave were correct by typing `y`: - ``` - Is this correct? (y/N) y - ``` + ``` + Is this correct? (y/N) y + ``` -1. Enter you real name, the email address to be associated with this key (should - match a verified email address you use in GitLab) and an optional comment - (press <kbd>Enter</kbd> to skip): +1. Enter your real name, the email address to be associated with this key + (should match a verified email address you use in GitLab) and an optional + comment (press <kbd>Enter</kbd> to skip): - ``` - GnuPG needs to construct a user ID to identify your key. + ``` + GnuPG needs to construct a user ID to identify your key. - Real name: Mr. Robot - Email address: <your_email> - Comment: - You selected this USER-ID: - "Mr. Robot <your_email>" + Real name: Mr. Robot + Email address: <your_email> + Comment: + You selected this USER-ID: + "Mr. Robot <your_email>" - Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O - ``` + Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O + ``` 1. Pick a strong password when asked and type it twice to confirm. 1. Use the following command to list the private GPG key you just created: - ``` - gpg --list-secret-keys --keyid-format LONG <your_email> - ``` + ``` + gpg --list-secret-keys --keyid-format LONG <your_email> + ``` - Replace `<your_email>` with the email address you entered above. + Replace `<your_email>` with the email address you entered above. 1. Copy the GPG key ID that starts with `sec`. In the following example, that's `30F2B65B9246B6CA`: - ``` - sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] - D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <your_email> - ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] - ``` + ``` + sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <your_email> + ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] + ``` 1. Export the public key of that ID (replace your key ID from the previous step): - ``` - gpg --armor --export 30F2B65B9246B6CA - ``` + ``` + gpg --armor --export 30F2B65B9246B6CA + ``` 1. Finally, copy the public key and [add it in your profile settings](#adding-a-gpg-key-to-your-account) @@ -146,17 +147,17 @@ You can add a GPG key in your profile's settings: 1. On the upper right corner, click on your avatar and go to your **Settings**. -  +  1. Navigate to the **GPG keys** tab and paste your _public_ key in the 'Key' box. -  +  1. Finally, click on **Add key** to add it to GitLab. You will be able to see its fingerprint, the corresponding email address and creation date. -  +  ## Associating your GPG key with Git @@ -166,29 +167,29 @@ key to use. 1. Use the following command to list the private GPG key you just created: - ```sh - gpg --list-secret-keys --keyid-format LONG <your_email> - ``` + ```sh + gpg --list-secret-keys --keyid-format LONG <your_email> + ``` - Replace `<your_email>` with the email address you entered above. + Replace `<your_email>` with the email address you entered above. 1. Copy the GPG key ID that starts with `sec`. In the following example, that's `30F2B65B9246B6CA`: - ``` - sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] - D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <your_email> - ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] - ``` + ``` + sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <your_email> + ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] + ``` 1. Tell Git to use that key to sign the commits: - ```sh - git config --global user.signingkey 30F2B65B9246B6CA - ``` + ```sh + git config --global user.signingkey 30F2B65B9246B6CA + ``` - Replace `30F2B65B9246B6CA` with your GPG key ID. + Replace `30F2B65B9246B6CA` with your GPG key ID. 1. (Optional) If Git is using `gpg` and you get errors like `secret key not available` or `gpg: signing failed: secret key not available`, run the following command to @@ -206,9 +207,9 @@ commits: 1. Commit like you used to, the only difference is the addition of the `-S` flag: - ``` - git commit -S -m "My commit msg" - ``` + ``` + git commit -S -m "My commit msg" + ``` 1. Enter the passphrase of your GPG key when asked. 1. Push to GitLab and check that your commits [are verified](#verifying-commits). @@ -227,13 +228,13 @@ git config --global commit.gpgsign true "Verified" or "Unverified", depending on the verification status of the GPG signature. -  +  1. By clicking on the GPG badge, details of the signature are displayed. -  +  -  +  ## Revoking a GPG key @@ -261,7 +262,7 @@ To remove a GPG key from your account: 1. Navigate to the **GPG keys** tab. 1. Click on the trash icon besides the GPG key you want to delete. -## Rejecting commits that are not signed **[PREMIUM]** +## Rejecting commits that are not signed **(PREMIUM)** You can configure your project to reject commits that aren't GPG-signed via [push rules](../../../../push_rules/push_rules.md). @@ -269,3 +270,24 @@ via [push rules](../../../../push_rules/push_rules.md). ## GPG signing API Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit). + +## Further reading + +For more details about GPG, see: + +- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) +- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) +- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) +- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/repository/img/download_source_code.png b/doc/user/project/repository/img/download_source_code.png Binary files differindex 17f2cb4b3e8..56808061980 100644 --- a/doc/user/project/repository/img/download_source_code.png +++ b/doc/user/project/repository/img/download_source_code.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 6fccfd40987..84d63d29929 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,3 +1,7 @@ +--- +type: concepts, howto +--- + # Repository A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) @@ -68,7 +72,7 @@ according to the markup language. | Plain text | `txt` | | [Markdown](../../markdown.md) | `mdown`, `mkd`, `mkdn`, `md`, `markdown` | | [reStructuredText](http://docutils.sourceforge.net/rst.html) | `rst` | -| [Asciidoc](https://asciidoctor.org/docs/what-is-asciidoc/) | `adoc`, `ad`, `asciidoc` | +| [AsciiDoc](../../asciidoc.md) | `adoc`, `ad`, `asciidoc` | | [Textile](https://txstyle.org/) | `textile` | | [rdoc](http://rdoc.sourceforge.net/doc/index.html) | `rdoc` | | [Orgmode](https://orgmode.org/) | `org` | @@ -111,33 +115,7 @@ GitLab. ## Branches -When you submit changes in a new [branch](branches/index.md), you create a new version -of that project's file tree. Your branch contains all the changes -you are presenting, which are detected by Git line by line. - -To continue your workflow, once you pushed your changes to a new branch, -you can create a [merge request](../merge_requests/index.md), perform -inline code review, and [discuss](../../discussions/index.md) -your implementation with your team. -You can live preview changes submitted to a new branch with -[Review Apps](../../../ci/review_apps/index.md). - -With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request -[approval](../merge_requests/merge_request_approvals.md) from your managers. - -To create, delete, and view [branches](branches/index.md) via GitLab's UI: - -- [Default branches](branches/index.md#default-branch) -- [Create a branch](web_editor.md#create-a-new-branch) -- [Protected branches](../protected_branches.md#protected-branches) -- [Delete merged branches](branches/index.md#delete-merged-branches) -- [Branch filter search box](branches/index.md#branch-filter-search-box) - -Alternatively, you can use the -[command line](../../../gitlab-basics/start-using-git.md#create-a-branch). - -To learn more about branching strategies read through the -[GitLab Flow](../../../university/training/gitlab_flow.md) documentation. +For details, see [Branches](branches/index.md). ## Commits @@ -171,17 +149,14 @@ Via command line, you can commit multiple times before pushing. - **Sign a commit:** Use GPG to [sign your commits](gpg_signed_commits/index.md). -## Repository size - -A project's repository size is reported on the project's **Details** page. The reported size is -updated every 15 minutes at most, so may not reflect recent activity. +## Project and repository size -The repository size for: +A project's size is reported on the project's **Details** page. The reported size is +updated every 15 minutes at most, so may not reflect recent activity. The displayed files size includes repository files, artifacts, and LFS. -- GitLab.com [is set by GitLab](../../gitlab_com/index.md#repository-size-limit). -- Self-managed instances is set by your GitLab administrators. +The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors. -You can [reduce a repository's size using Git](reducing_the_repo_size_using_git.md). +[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by admins. GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#repository-size-limit). ## Contributors @@ -216,15 +191,7 @@ detected, add the following to `.gitattributes` in the root of your repository. > *.proto linguist-detectable=true -## Compare - -Select branches to compare using the [branch filter search box](branches/index.md#branch-filter-search-box), then click the **Compare** button to view the changes inline: - - - -Find it under your project's **Repository > Compare**. - -## Locked files **[PREMIUM]** +## Locked files **(PREMIUM)** Use [File Locking](../file_lock.md) to lock your files to prevent any conflicting changes. @@ -259,3 +226,15 @@ By clicking the download icon, a dropdown will open with links to download the f `tar`, `tar.gz`, and `tar.bz2`. - **Artifacts:** allows users to download the artifacts of the latest CI build. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> 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 e3d771524ce..3adf66e4b6f 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 @@ -1,3 +1,7 @@ +--- +type: howto +--- + # Reducing the repository size using Git A GitLab Enterprise Edition administrator can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md) @@ -35,16 +39,16 @@ BFG Repo-Cleaner](#using-the-bfg-repo-cleaner). It's faster and simpler than `git filter-branch`, and GitLab can use its account of what has changed to clean up its own internal state, maximizing the space saved. -> **Warning:** -> Make sure to first make a copy of your repository since rewriting history will -> purge the files and information you are about to delete. Also make sure to -> inform any collaborators to not use `pull` after your changes, but use `rebase`. +CAUTION: **Caution:** +Make sure to first make a copy of your repository since rewriting history will +purge the files and information you are about to delete. Also make sure to +inform any collaborators to not use `pull` after your changes, but use `rebase`. -> **Warning:** -> This process is not suitable for removing sensitive data like password or keys -> from your repository. Information about commits, including file content, is -> cached in the database, and will remain visible even after they have been -> removed from the repository. +CAUTION: **Caution:** +This process is not suitable for removing sensitive data like password or keys +from your repository. Information about commits, including file content, is +cached in the database, and will remain visible even after they have been +removed from the repository. ## Using the BFG Repo-Cleaner @@ -54,87 +58,100 @@ up its own internal state, maximizing the space saved. 1. Navigate to your repository: - ``` - cd my_repository/ - ``` + ``` + cd my_repository/ + ``` 1. Change to the branch you want to remove the big file from: - ``` - git checkout master - ``` + ``` + git checkout master + ``` 1. Create a commit removing the large file from the branch, if it still exists: - ``` - git rm path/to/big_file.mpg - git commit -m 'Remove unneeded large file' - ``` + ``` + git rm path/to/big_file.mpg + git commit -m 'Remove unneeded large file' + ``` 1. Rewrite history: - ``` - bfg --delete-files path/to/big_file.mpg - ``` + ``` + bfg --delete-files path/to/big_file.mpg + ``` - An object map file will be written to `object-id-map.old-new.txt`. Keep it - around - you'll need it for the final step! + An object map file will be written to `object-id-map.old-new.txt`. Keep it + around - you'll need it for the final step! 1. Force-push the changes to GitLab: - ``` - git push --force-with-lease origin master - ``` + ``` + git push --force-with-lease origin master + ``` - If this step fails, someone has changed the `master` branch while you were - rewriting history. You could restore the branch and re-run BFG to preserve - their changes, or use `git push --force` to overwrite their changes. + If this step fails, someone has changed the `master` branch while you were + rewriting history. You could restore the branch and re-run BFG to preserve + their changes, or use `git push --force` to overwrite their changes. 1. Navigate to **Project > Settings > Repository > Repository Cleanup**: -  +  - Upload the `object-id-map.old-new.txt` file and press **Start cleanup**. - This will remove any internal git references to the old commits, and run - `git gc` against the repository. You will receive an email once it has - completed. + Upload the `object-id-map.old-new.txt` file and press **Start cleanup**. + This will remove any internal git references to the old commits, and run + `git gc` against the repository. You will receive an email once it has + completed. +NOTE: **Note:** 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! +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: - ``` - cd my_repository/ - ``` + ``` + cd my_repository/ + ``` 1. Change to the branch you want to remove the big file from: - ``` - git checkout master - ``` + ``` + git checkout master + ``` 1. Use `filter-branch` to remove the big file: - ``` - git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD - ``` + ``` + git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD + ``` 1. Instruct Git to purge the unwanted data: - ``` - git reflog expire --expire=now --all && git gc --prune=now --aggressive - ``` + ``` + git reflog expire --expire=now --all && git gc --prune=now --aggressive + ``` 1. Lastly, force push to the repository: - ``` - git push --force origin master - ``` + ``` + git push --force origin master + ``` Your repository should now be below the size limit. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index ce9d23bf911..b5299eaca27 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,3 +1,7 @@ +--- +type: howto +--- + # GitLab Web Editor Sometimes it's easier to make quick changes directly from the GitLab interface @@ -13,8 +17,6 @@ Choose **New file** from the dropdown.  ---- - Enter a file name in the **File name** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field will default to the branch you were viewing in the file browser. If you enter @@ -59,8 +61,6 @@ selector. Choose **Upload file** from the dropdown.  ---- - Once the upload dialog pops up there are two ways to upload your file. Either drag and drop a file on the pop up or use the **click to upload** link. A file preview will appear once you have selected a file to upload. @@ -80,8 +80,6 @@ Choose **New directory** from the dropdown.  ---- - In the new directory dialog enter a directory name, a commit message and choose the target branch. Click **Create directory** to finish. @@ -107,14 +105,14 @@ Once you click it, a new branch will be created that diverges from the default branch of your project, by default `master`. The branch name will be based on the title of the issue and as a prefix, it will have its internal ID. Thus, the example screenshot above will yield a branch named -`2-et-cum-et-sed-expedita-repellat-consequatur-ut-assumenda-numquam-rerum`. +`23177-add-support-for-rich-references-to-referables`. Since GitLab 9.0, when you click the `New branch` in an empty repository project, GitLab automatically creates the master branch, commits a blank `README.md` file to it and creates and redirects you to a new branch based on the issue title. If your [project is already configured with a deployment service][project-services-doc] (e.g. Kubernetes), GitLab takes one step further and prompts you to set up [auto deploy][auto-deploy-doc] by helping you create a `.gitlab-ci.yml` file. After the branch is created, you can edit files in the repository to fix the issue. When a merge request is created based on the newly created branch, -the description field will automatically display the [issue closing pattern] +the description field will automatically display the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) `Closes #ID`, where `ID` the ID of the issue. This will close the issue once the merge request is merged. @@ -129,8 +127,6 @@ choose **New branch** from the dropdown.  ---- - Enter a new **Branch name**. Optionally, change the **Create from** field to choose which branch, tag or commit SHA this new branch will originate from. This field will autocomplete if you start typing an existing branch or tag. @@ -139,8 +135,6 @@ branch.  ---- - You can now make changes to any files, as needed. When you're ready to merge the changes back to master you can use the widget at the top of the screen. This widget only appears for a period of time after you create the branch or @@ -156,8 +150,6 @@ SHA. From a project's files page, choose **New tag** from the dropdown.  ---- - Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you would like to create this new tag. You can optionally add a message and release notes. The release notes section supports markdown format and you can @@ -181,4 +173,15 @@ through the web editor, you can choose to use another of your linked email addresses from the **User Settings > Edit Profile** page. [ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808 -[issue closing pattern]: ../issues/automatic_issue_closing.md + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 1a582164d03..645b9bffcc1 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,4 +1,4 @@ -# Service Desk **[PREMIUM]** +# 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). @@ -53,36 +53,35 @@ 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: +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). +1. Navigate to your project's **Settings** and scroll down to the **Service Desk** + section. +1. 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. +1. 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. + **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._ + _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._ +1. Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**: -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 diff --git a/doc/user/project/settings/img/general_settings.png b/doc/user/project/settings/img/general_settings.png Binary files differindex 4ff6fff5ca3..f88a158d2be 100644 --- a/doc/user/project/settings/img/general_settings.png +++ b/doc/user/project/settings/img/general_settings.png diff --git a/doc/user/project/settings/img/import_export_download_export.png b/doc/user/project/settings/img/import_export_download_export.png Binary files differindex ab81c87bf5f..c7ab7565fc7 100644 --- a/doc/user/project/settings/img/import_export_download_export.png +++ b/doc/user/project/settings/img/import_export_download_export.png diff --git a/doc/user/project/settings/img/import_export_export_button.png b/doc/user/project/settings/img/import_export_export_button.png Binary files differindex 9e368739695..6933e3edfcc 100644 --- a/doc/user/project/settings/img/import_export_export_button.png +++ b/doc/user/project/settings/img/import_export_export_button.png diff --git a/doc/user/project/settings/img/import_export_mail_link.png b/doc/user/project/settings/img/import_export_mail_link.png Binary files differindex 985c37650d3..1bd9a071178 100644 --- a/doc/user/project/settings/img/import_export_mail_link.png +++ b/doc/user/project/settings/img/import_export_mail_link.png diff --git a/doc/user/project/settings/img/import_export_new_project.png b/doc/user/project/settings/img/import_export_new_project.png Binary files differindex fc1f73c5d6e..0e2365ecb68 100644 --- a/doc/user/project/settings/img/import_export_new_project.png +++ b/doc/user/project/settings/img/import_export_new_project.png diff --git a/doc/user/project/settings/img/import_export_select_file.png b/doc/user/project/settings/img/import_export_select_file.png Binary files differindex e3e1a5ef980..90a3e8d5c4e 100644 --- a/doc/user/project/settings/img/import_export_select_file.png +++ b/doc/user/project/settings/img/import_export_select_file.png diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 819515d7a4c..9c1a31fb7c3 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -2,33 +2,33 @@ >**Notes:** > -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/3050) in GitLab 8.9. -> - Importing will not be possible if the import instance version differs from -> that of the exporter. -> - For GitLab admins, please read through -> [Project import/export administration](../../../administration/raketasks/project_import_export.md). -> - For existing installations, the project import option has to be enabled in -> application settings (`/admin/application_settings`) under 'Import sources'. -> Ask your administrator if you don't see the **GitLab export** button when -> creating a new project. -> - Starting with GitLab 10.0, administrators can disable the project export option -> on the GitLab instance in application settings (`/admin/application_settings`) -> under 'Visibility and Access Controls'. -> - You can find some useful raketasks if you are an administrator in the -> [import_export](../../../administration/raketasks/project_import_export.md) raketask. -> - The exports are stored in a temporary [shared directory](../../../development/shared_files.md) -> and are deleted every 24 hours by a specific worker. -> - Group members will get exported as project members, as long as the user has -> maintainer or admin access to the group where the exported project lives. An admin -> in the import side is required to map the users, based on email or username. -> Otherwise, a supplementary comment is left to mention the original author and -> the MRs, notes or issues will be owned by the importer. -> - Project members with owner access will get imported as maintainers. -> - Control project Import/Export with the [API](../../../api/project_import_export.md). -> - If an imported project contains merge requests originated from forks, -> then new branches associated with such merge requests will be created -> within a project during the import/export. Thus, the number of branches -> in the exported project could be bigger than in the original project. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/3050) in GitLab 8.9. +> - Importing will not be possible if the import instance version differs from +> that of the exporter. +> - For GitLab admins, please read through +> [Project import/export administration](../../../administration/raketasks/project_import_export.md). +> - For existing installations, the project import option has to be enabled in +> application settings (`/admin/application_settings`) under 'Import sources'. +> Ask your administrator if you don't see the **GitLab export** button when +> creating a new project. +> - Starting with GitLab 10.0, administrators can disable the project export option +> on the GitLab instance in application settings (`/admin/application_settings`) +> under 'Visibility and Access Controls'. +> - You can find some useful raketasks if you are an administrator in the +> [import_export](../../../administration/raketasks/project_import_export.md) raketask. +> - The exports are stored in a temporary [shared directory](../../../development/shared_files.md) +> and are deleted every 24 hours by a specific worker. +> - Group members will get exported as project members, as long as the user has +> maintainer or admin access to the group where the exported project lives. An admin +> in the import side is required to map the users, based on email or username. +> Otherwise, a supplementary comment is left to mention the original author and +> the MRs, notes or issues will be owned by the importer. +> - Project members with owner access will get imported as maintainers. +> - Control project Import/Export with the [API](../../../api/project_import_export.md). +> - If an imported project contains merge requests originated from forks, +> then new branches associated with such merge requests will be created +> within a project during the import/export. Thus, the number of branches +> in the exported project could be bigger than in the original project. Existing projects running on any GitLab instance or GitLab.com can be exported with all their related data and be moved into a new GitLab instance. @@ -66,6 +66,7 @@ The following items will be exported: - Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, and other project entities - LFS objects +- Issue boards The following items will NOT be exported: @@ -74,6 +75,13 @@ The following items will NOT be exported: - CI variables - Webhooks - Any encrypted tokens +- Merge Request Approvers +- Push Rules +- Awards + +NOTE: **Note:** +For more details on the specific data persisted in a project export, see the +[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/import_export/import_export.yml) file. ## Exporting a project and its data @@ -83,29 +91,34 @@ The following items will NOT be exported: 1. Scroll down to find the **Export project** button: -  +  1. Once the export is generated, you should receive an e-mail with a link to download the file: -  +  1. Alternatively, you can come back to the project settings and download the file from there, or generate a new export. Once the file available, the page should show the **Download export** button: -  +  ## Importing the project -1. The GitLab project import feature is the first import option when creating a +1. The GitLab project import feature is the first import option when creating a new project. Click on **GitLab export**: -  +  1. Enter your project name and URL. Then select the file you exported previously: -  +  1. Click on **Import project** to begin importing. Your newly imported project page will appear soon. + +NOTE: **Note:** +If use of the `Internal` visibility level +[is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), +all imported projects are given the visibility of `Private`. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index ba890c5ac01..4e3db95b6d6 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -9,7 +9,7 @@ to your project's homepage and clicking **Settings**. ## General settings -Under a project's general settings you can find everything concerning the +Under a project's general settings, you can find everything concerning the functionality of a project. ### General project settings @@ -18,7 +18,7 @@ Adjust your project's name, description, avatar, [default branch](../repository/  -The project description also partially supports [standard markdown](../../markdown.md#standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +The project description also partially supports [standard markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. ### Sharing and permissions @@ -26,12 +26,18 @@ Set up your project's access, [visibility](../../../public_access/public_access.  -If Issues are disabled, or you can't access Issues because you're not a project member, then Lables and Milestones +If Issues are disabled, or you can't access Issues because you're not a project member, then Labels and Milestones links will be missing from the sidebar UI. -You can still access them with direct links if you can access Merge Requests. This is deliberate, if you can see +You can still access them with direct links if you can access Merge Requests. This is deliberate, if you can see Issues or Merge Requests, both of which use Labels and Milestones, then you shouldn't be denied access to Labels and Milestones pages. +#### Disabling email notifications + +You can disable all email notifications related to the project by selecting the +**Disable email notifications** checkbox. Only the project owner is allowed to change +this setting. + ### Issue settings Add an [issue description template](../description_templates.md#description-templates) to your project, so that every new issue will start with a custom template. @@ -42,13 +48,13 @@ Set up your project's merge request settings: - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.html)). - Merge request [description templates](../description_templates.md#description-templates). -- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **[STARTER]** +- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **(STARTER)** - Enable [merge only of pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all discussions are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved). +- Enable [merge only when all discussions are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved).  -### Service Desk **[PREMIUM]** +### Service Desk **(PREMIUM)** Enable [Service Desk](../service_desk.md) for your project to offer customer support. @@ -109,8 +115,8 @@ You can transfer an existing project into a [group](../../group/index.md) if: 1. You have at least **Maintainer** [permissions] to that group. 1. The project is in a subgroup you own. 1. You are at least a **Maintainer** of the project under your personal namespace. -Similarly, if you are an owner of a group, you can transfer any of its projects -under your own user. + Similarly, if you are an owner of a group, you can transfer any of its projects + under your own user. To transfer a project: @@ -135,6 +141,6 @@ namespace if needed. Configure Error Tracking to discover and view [Sentry errors within GitLab](../operations/error_tracking.md). -### Jaeger tracing **[ULTIMATE]** +### 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/img/terminal_status.png b/doc/user/project/web_ide/img/terminal_status.png Binary files differnew file mode 100644 index 00000000000..91c341a9854 --- /dev/null +++ b/doc/user/project/web_ide/img/terminal_status.png diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index a634a8b2f54..9bf400e7dff 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -67,8 +67,8 @@ shows you a preview of the merge request diff if you commit your changes. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19279) in [GitLab Core][ce] 11.0. -You can use the Web IDE to quickly fix failing tests by opening -the branch or merge request in the Web IDE and opening the logs of the failed +You can use the Web IDE to quickly fix failing tests by opening +the branch or merge request in the Web IDE and opening the logs of the failed job. You can access the status of all jobs for the most recent pipeline and job traces for the current commit by clicking the **Pipelines** button in the top right. @@ -80,8 +80,8 @@ left. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19318) in [GitLab Core][ce] 11.0. -To switch between your authored and assigned merge requests, click the -dropdown in the top of the sidebar to open a list of merge requests. You will +To switch between your authored and assigned merge requests, click the +dropdown in the top of the sidebar to open a list of merge requests. You will need to commit or discard all your changes before switching to a different merge request. @@ -89,9 +89,9 @@ request. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20850) in [GitLab Core][ce] 11.2. -To switch between branches of the current project repository, click the dropdown -in the top of the sidebar to open a list of branches. -You will need to commit or discard all your changes before switching to a +To switch between branches of the current project repository, click the dropdown +in the top of the sidebar to open a list of branches. +You will need to commit or discard all your changes before switching to a different branch. ## Client Side Evaluation @@ -117,7 +117,7 @@ GitLab.com  Once you have done that, you can preview projects with a `package.json` file and -a `main` entry point inside the Web IDE. An example `package.json` is shown +a `main` entry point inside the Web IDE. An example `package.json` is shown below. ```json @@ -129,33 +129,29 @@ below. } ``` -## Interactive Web Terminals for the Web IDE **[ULTIMATE ONLY]** +## 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**. +Shared Runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611), +so you would need to use your own private Runner(s) to make use of this feature. -[Interactive web terminals](../../../ci/interactive_web_terminal/index.md) -give the user access to a terminal to interact with the Runner directly from +[Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) +give the project [Maintainers](../../permissions.md#project-members-permissions) +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 +- 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]** + [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 @@ -175,13 +171,13 @@ 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. + `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`. + 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: @@ -204,7 +200,7 @@ 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 +### 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 @@ -212,7 +208,7 @@ 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** +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. @@ -231,9 +227,62 @@ 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. +### File syncing to web terminal + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. + +File changes in the Web IDE can be synced to a running web terminal. +This enables users to test their code changes in a preconfigured terminal +environment. + +NOTE: **Note:** +Only file changes in the Web IDE are synced to the terminal. +Changes made in the terminal are **not** synced to the Web IDE. +This feature is only available for Kubernetes Runners. + +To enable file syncing to the web terminal, the `.gitlab/.gitlab-webide.yml` +file needs to have a `webide-file-sync` service configured. Here is an example +configuration for a Node JS project which uses this service: + +```yaml +terminal: + # This can be any image that has the necessary runtime environment for your project. + image: + name: node:10-alpine + services: + - name: registry.gitlab.com/gitlab-org/webide-file-sync:latest + alias: webide-file-sync + entrypoint: ["/bin/sh"] + command: ["-c", "sleep 5 && ./webide-file-sync -project-dir $CI_PROJECT_DIR"] + ports: + # The `webide-file-sync` executable defaults to port 3000. + - number: 3000 +``` + +- The `webide-file-sync` executable must start **after** the project + directory is available. This is why we need to add `sleep 5` to the `command`. + See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/issues/7) for + more info. +- `$CI_PROJECT_DIR` is a + [predefined environment variable](../../../ci/variables/predefined_variables.md) + for GitLab Runners. This is where your project's repository will be. + +Once you have configured the web terminal for file syncing, then when the web +terminal is started, a **Terminal** status will be visible in the status bar. + + + +Changes made to your files via the Web IDE will sync to the running terminal +when: + +- <kbd>Ctrl</kbd> + <kbd>S</kbd> (or <kbd>Cmd</kbd> + <kbd>S</kbd> on Mac) + is pressed while editing a file. +- Anything outside the file editor is clicked after editing a file. +- A file or folder is created, deleted, or renamed. + ### Limitations -Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming +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. @@ -246,6 +295,5 @@ active terminal at a time. 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/reserved_names.md b/doc/user/reserved_names.md index 9e8475d8294..68532ccee65 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -40,19 +40,18 @@ It is currently not possible to create a project with the following names: Currently the following names are reserved as top level groups: -- 503.html - \- - .well-known - 404.html - 422.html - 500.html - 502.html +- 503.html - abuse_reports - admin - api - apple-touch-icon-precomposed.png - apple-touch-icon.png -- files - assets - autocomplete - ci @@ -61,12 +60,14 @@ Currently the following names are reserved as top level groups: - explore - favicon.ico - favicon.png +- files - groups - health_check - help - import - invites - jwt +- login - notification_settings - oauth - profile @@ -78,8 +79,6 @@ Currently the following names are reserved as top level groups: - sent_notifications - slash-command-logo.png - snippets -- u -- unicorn_test - unsubscribes - uploads - users @@ -88,22 +87,5 @@ Currently the following names are reserved as top level groups: These group names are unavailable as subgroup names: - \- -- activity -- analytics -- audit_events -- avatar -- edit -- group_members -- hooks -- issues -- labels -- ldap -- ldap_group_links -- merge_requests -- milestones -- notification_setting -- pipeline_quota -- projects -- subgroups [reserved]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/path_regex.rb diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md index f80f4183802..52da6d65000 100644 --- a/doc/user/search/advanced_global_search.md +++ b/doc/user/search/advanced_global_search.md @@ -1,4 +1,4 @@ -# Advanced Global Search **[STARTER ONLY]** +# Advanced Global Search **(STARTER ONLY)** > - [Introduced][ee-109] in GitLab [Starter][ee] 8.4. > - This is the user documentation. To install and configure Elasticsearch, diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index d302cb7a809..c3d22e4fd29 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -1,4 +1,4 @@ -# Advanced Syntax Search **[STARTER ONLY]** +# Advanced Syntax Search **(STARTER ONLY)** > **Notes:** > - Introduced in [GitLab Enterprise Starter][ee] 9.2 @@ -50,9 +50,9 @@ here's a quick guide: 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. +- 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. diff --git a/doc/user/search/index.md b/doc/user/search/index.md index bb6c48471c7..8d7b4a429aa 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -55,12 +55,12 @@ Selecting **Any** does the opposite. It returns results that have a non-empty va You can filter issues and merge requests by specific terms included in titles or descriptions. - Syntax - - 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 term, use double quotes: `"display bug"` + - 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 term, use double quotes: `"display bug"` - Limitation - - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching - issues for `included in titles` is same as `included titles` + - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching + issues for `included in titles` is same as `included titles`  @@ -97,10 +97,10 @@ quickly access issues and merge requests created or assigned to you within that  -## Todos +## To-Do List -Your [todos](../../workflow/todos.md#gitlab-todos) can be searched by "to do" and "done". -You can [filter](../../workflow/todos.md#filtering-your-todos) them per project, +Your [To-Do List](../../workflow/todos.md#gitlab-to-do-list) can be searched by "to do" and "done". +You can [filter](../../workflow/todos.md#filtering-your-to-do-list) them per project, author, type, and action. Also, you can sort them by [**Label priority**](../../user/project/labels.md#label-priority), **Last created** and **Oldest created**. @@ -143,14 +143,14 @@ and **Labels**, select multiple issues to add to a list of your choice:  -## Advanced Global Search **[STARTER]** +## 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]** +## Advanced Syntax Search **(STARTER)** Use advanced queries for more targeted search results. |
