diff options
Diffstat (limited to 'doc/user')
74 files changed, 1536 insertions, 584 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 427f3103cfc..02c2efaa4f3 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -1,26 +1,49 @@ +--- +type: reference +--- + # Custom instance-level project templates **(PREMIUM ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. -When you create a new [project](../project/index.md), creating it based on custom project templates is -a convenient bootstrap option. +GitLab administrators can configure the group where all the custom project +templates are sourced. -GitLab administrators can configure a GitLab group that serves as template -source for an entire GitLab instance under **Admin area > Settings > Custom project templates**. +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/settings/img/email_confirmation.png b/doc/user/admin_area/settings/img/email_confirmation.png Binary files differnew file mode 100644 index 00000000000..4d888da3416 --- /dev/null +++ b/doc/user/admin_area/settings/img/email_confirmation.png diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index d77e91156f8..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 -By implementing sign-up restrictions, you can blacklist or whitelist email addresses -belonging to specific domains. +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,7 +31,9 @@ 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 @@ -33,10 +42,10 @@ To access this feature: 1. Navigate to the **Settings > General** in the Admin area. 1. Expand the **Sign-up restrictions** section. -For the: +For the blacklist, you can enter the list manually or upload a `.txt` file that +contains list entries. -- Blacklist, you can enter the list manually, or upload a `.txt` file with it. -- Whitelist you must enter the list manually. +For the whitelist, you must enter the list manually. 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 diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index f698e0a1608..516600c9d99 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -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 diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index da75684a3fe..86491c7d74e 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Container Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672) @@ -47,7 +51,7 @@ To enable Container Scanning in your pipeline, you need: 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 ``` @@ -114,7 +118,7 @@ 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. ``` diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 4b98dd73d76..88e2d1ef22b 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Dynamic Application Security Testing (DAST) **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4348) @@ -199,3 +203,15 @@ Once a vulnerability is found, you can interact with it. Read more on how to 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_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 09bd306363c..6a810757a28 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Dependency Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105) @@ -142,6 +146,7 @@ using environment variables. | `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). | @@ -149,7 +154,7 @@ using environment variables. | `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_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 @@ -330,7 +335,7 @@ project's dependencies with their versions. This list can be generated only for [languages and package managers](#supported-languages-and-package-managers) supported by Gemnasium. -To see the generated dependency list, navigate to your project's **Project > Dependency List**. +To see the generated dependency list, navigate to your project's **Security & Compliance > Dependency List**. ## Versioning and release process @@ -341,3 +346,15 @@ Please check the [Release Process documentation](https://gitlab.com/gitlab-org/s 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). + +<!-- ## 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/index.md b/doc/user/application_security/index.md index 56a4cbd26d2..31f0b5a050c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,10 +1,22 @@ +--- +type: reference, howto +--- + # 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. +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 @@ -54,7 +66,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. @@ -124,7 +136,7 @@ generated by GitLab. To apply the fix: #### 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 @@ -135,3 +147,15 @@ 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.  + +<!-- ## 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/index.md b/doc/user/application_security/license_management/index.md index b0eb753938b..c324848c703 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # License Management **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) @@ -227,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..59835aeba01 --- /dev/null +++ b/doc/user/application_security/sast/analyzers.md @@ -0,0 +1,143 @@ +--- +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) +- [Brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) +- [ESLint (Javascript)](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) +- [SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) +- [Flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) +- [Gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) +- [NodeJsScan](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) +- [PHP CS security-audit](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) +- [Secrets (Gitleaks, TruffleHog & Diffence secret detectors)](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) +- [Security Code Scan (.NET)](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) +- [TSLint (Typescript)](https://gitlab.com/gitlab-org/security-products/analyzers/tslint) +- [Sobelow (Elixir Phoenix)](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) + +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 | 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 1f9fd9d4e18..aac881112ff 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Static Application Security Testing (SAST) **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3775) @@ -135,6 +139,58 @@ sast: CI_DEBUG_TRACE: "true" ``` +### Available variables + +SAST can be [configured](#customizing-the-sast-settings) using environment variables. + +#### Docker images + +The following are Docker image-related variables. + +| 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). | + +### Vulnerability filters + +Some analyzers make it possible to filter out vulnerabilities under a given threshold. + +| `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, 1=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:** @@ -282,3 +338,15 @@ Once a vulnerability is found, you can interact with it. Read more on how to 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..40689861e2a --- /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..89b310895d3 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 2a2385c00ae..ac8c1ac0354 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # GitLab Security Dashboard **(ULTIMATE)** The Security Dashboard is a good place to get an overview of all the security @@ -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 @@ -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/clusters/applications.md b/doc/user/clusters/applications.md index 6956086c382..e1a6f8fcf71 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -5,11 +5,12 @@ 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#add-new-gke-cluster). ## 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 +20,8 @@ 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, navigate to your project's **Operations > Kubernetes**. + - Group-level cluster, navigate to your group's **Kubernetes** page. Install Helm first as it's used to install other applications. @@ -232,8 +233,8 @@ 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, navigate to your project's **Operations > Kubernetes**. + - Group-level cluster, 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. @@ -259,8 +260,8 @@ The applications below can be uninstalled. 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, navigate to your project's **Operations > Kubernetes**. + - Group-level cluster, navigate to your group's **Kubernetes** page. 1. Select your cluster. 1. Click the **Uninstall** button for the application. diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index 117a46da0ea..5b5f75c2dd9 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -1,22 +1,26 @@ -# Bulk editing issue milestones **(PREMIUM)** +# Bulk editing issue and merge request milestones **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7249) in -[GitLab Ultimate](https://about.gitlab.com/pricing/) 12.1. +> - [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 [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: **Note:** -A permission level of `Reporter` or higher is required in order to manage issues. +> NOTE: **Note:** +> +> - 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. -Milestones can be updated simultaneously across multiple issues by using the bulk editing feature. +Milestones can be updated simultaneously across multiple issues or merge requests by using the bulk editing feature.  -To bulk update group issue milestones: +To bulk update group issue or merge request milestones: -1. Navigate to the issues list. -1. Click **Edit issues**. +1. Navigate to the issues or merge requests list. +1. Click the **Edit issues** or **Edit merge requests** button. - This will open a sidebar on the right-hand side of your screen where an editable field for milestones will be displayed. - - Checkboxes will also appear beside each issue. + - Checkboxes will also appear beside each issue or merge request. 1. Check the checkbox beside each issue to be edited. 1. Select the desired milestone from the sidebar. 1. Click **Update all**. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 0dffc216f8e..625c5440ec0 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 @@ -138,6 +137,13 @@ 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. +## Security of Runners + +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 Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 7597105f36f..14c831fe671 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -78,9 +78,9 @@ 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 +### Bulk editing issues and merge requests -For details, see [bulk editing issues](../group/bulk_editing/index.md). +For details, see [bulk editing issues and merge requests](../group/bulk_editing/index.md). ## Create a new group 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..8c5dbe36f98 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_attribute_mapping.png b/doc/user/group/saml_sso/img/scim_attribute_mapping.png Binary files differindex c9f6b71f5b0..dad459d8c28 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..85e5648816e --- /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..4b8887b5418 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_provisioning_status.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 54923ab69ff..e3f657af564 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -71,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 094f4130d0c..ab48c9080a9 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -45,7 +45,7 @@ The following identity providers are supported: Feature.enable(:group_scim, group) ``` -### GitLab configuration +## GitLab configuration Once [Single sign-on](index.md) has been configured, we can: @@ -55,41 +55,48 @@ Once [Single sign-on](index.md) has been configured, we can:  -## 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. +First, double check the [Single sign-on](index.md) configuration for your group and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab. -The GitLab app in Azure needs to be configured following -[Azure's SCIM setup](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#getting-started). + -Note the following: +#### Set up admin credentials + +Next, configure your GitLab application in Azure 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). - Should there be any problems with the availability of GitLab or similar 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`. See below for [troubleshooting](#troubleshooting). +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). -### Synchronize Azure Active Directory users +#### Configure attribute mapping -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`. +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`. - Example configuration: + Save your changes and you should have the following configuration:  -1. Click on **Show advanced options > Edit attribute list for AppName**. + 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. Leave the `id` as the primary and only required field. NOTE: **Note:** @@ -99,12 +106,14 @@ You can then test the connection clicking on `Test Connection`. See below for [t  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. + the application (`Users and groups`), otherwise, it will sync the whole Active Directory. Once enabled, the synchronization details and any errors will appear on the bottom of the **Provisioning** screen, together with a link to the audit logs. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 1c6cca049c5..2eb3fae1a85 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -28,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 --- @@ -74,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/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 37f3f21f539..9380dcf2a32 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -136,26 +136,26 @@ Supported formats (named colors are not supported): Color written inside backticks will be followed by a color "chip": ```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)` -``` - -`#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)` +`#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)` +``` + +`#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)` ### Diagrams and flowcharts using Mermaid @@ -397,6 +397,7 @@ unordered or ordered lists: - [ ] Sub-task 1 - [x] Sub-task 2 - [ ] Sub-task 3 + 1. [x] Completed task 1. [ ] Incomplete task 1. [ ] Sub-task 1 @@ -408,6 +409,7 @@ unordered or ordered lists: - [ ] Sub-task 1 - [x] Sub-task 2 - [ ] Sub-task 3 + 1. [x] Completed task 1. [ ] Incomplete task 1. [ ] Sub-task 1 @@ -976,7 +978,7 @@ after the `</summary>` tag and before the `</details>` tag, as shown in the exam These details _will_ remain **hidden** until expanded. - PASTE LOGS HERE +PASTE LOGS HERE </details> ``` @@ -988,7 +990,7 @@ These details _will_ remain **hidden** until expanded. These details <em>will</em> remain <b>hidden</b> until expanded. - PASTE LOGS HERE +PASTE LOGS HERE </details> @@ -1047,14 +1049,14 @@ A new line due to the previous backslash. First paragraph. Another line in the same paragraph. -A third line in the same paragraph, but this time ending with two spaces. +A third line in the same paragraph, but this time ending with two spaces. A new line directly under the first paragraph. <!-- (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) --> Second paragraph. -Another line, this time ending with a backslash. +Another line, this time ending with a backslash. A new line due to the previous backslash. ### Links @@ -1135,13 +1137,13 @@ GFM will autolink almost any URL you put into your text: ### Lists Ordered and unordered lists can be easily created. Add the number you want the list -to start with, like `1. ` (with a space) at the start of each line for ordered lists. +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 +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. -Add a `* `, `- ` or `+ ` (with a space) at the start of each line for unordered lists, but +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. Examples: @@ -1156,7 +1158,9 @@ Examples: 4. And another item. * Unordered lists can use asterisks + - Or minuses + + Or pluses ``` @@ -1170,9 +1174,11 @@ Examples: 1. Next ordered sub-list item 1. And another item. -* Unordered lists can use asterisks +- Unordered lists can use asterisks + - Or minuses -+ Or pluses + +- Or pluses --- diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 619cf34b5c3..e6822f0c52c 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -47,6 +47,7 @@ The following table depicts the various user permission levels in a project. | View approved/blacklisted licenses **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View license management reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View Security reports **(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) | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -74,6 +75,7 @@ The following table depicts the various user permission levels in a project. | 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)** | | | ✓ | ✓ | ✓ || +| Upload [Design Management](project/issues/design_management.md) files **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Create new branches | | | ✓ | ✓ | ✓ | | Push to non-protected branches | | | ✓ | ✓ | ✓ | | Force push to non-protected branches | | | ✓ | ✓ | ✓ | @@ -209,13 +211,16 @@ group. | Create project in group | | | ✓ | ✓ | ✓ | | Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | | Enable/disable a dependency proxy **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Create subgroup | | | | ✓ (1) | ✓ | | Edit group | | | | | ✓ | -| Create subgroup | | | | | ✓ | | Manage group members | | | | | ✓ | | Remove group | | | | | ✓ | | Delete group epic **(ULTIMATE)** | | | | | ✓ | | View group Audit Events | | | | | ✓ | +- (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 When you add a member to a subgroup, they inherit the membership and diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 304a7984191..cbee79de493 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,37 +1,71 @@ -# Deleting a User Account +# 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. - -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 -deleting users from the [API](../../../api/users.md#user-deletion) or the -admin area. - -[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 +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 records are not ghosted and will be removed, along +with any groups the user 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. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 61a30a775b0..fc5eb8c7b56 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -147,39 +147,40 @@ 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 on your avatar at the top-right corner of the navigation bar. +1. From the menu that appears, click **Settings**. +1. In the **Main settings** section, locate **Commit email** dropdown. 1. Select any of the verified emails. -1. Hit **Update profile settings**. +1. Press **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, +GitLab provides users with an automatically generated private commit email option, which allows the user to not make their email information public. 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. Select **Use a private email** option. -1. Hit **Update profile settings**. +1. Click on your avatar at the top-right corner of the navigation bar. +1. From the menu that appears, click **Settings**. +1. In the **Main settings** section, locate **Commit email** dropdown. +1. Select the "Use a private email" option. +1. Press **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 +In order 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_PRIVATE_COMMIT_EMAIL> ``` ## Troubleshooting 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 1783f81df3a..f4733620640 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -13,8 +13,8 @@ by using the bulk editing feature.  NOTE: **Note:** -Bulk editing of merge requests is only available at the project level. -For more details, see [bulk editing group issues](../group/bulk_editing/index.md). +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: diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 55a9fbabf98..28f3420de35 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -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/index.md b/doc/user/project/clusters/index.md index 4c247691757..670dde6bb00 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,33 +1,111 @@ -# 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) for +> projects in GitLab 10.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) for +> [groups](../../group/clusters/index.md) in GitLab 11.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/39840) for +> [instances](../../instance/clusters/index.md) in GitLab 11.11. -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) + +### 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: -## Adding and creating a new GKE cluster via GitLab +- `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` +- `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` + +`$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), @@ -39,7 +117,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: @@ -49,7 +127,7 @@ 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: @@ -57,7 +135,7 @@ 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. + 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**. @@ -91,14 +169,14 @@ client certificate is enabled. 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. -## Adding an existing Kubernetes cluster +### Add existing Kubernetes cluster 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. + 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: @@ -216,7 +294,36 @@ To add an existing Kubernetes cluster to your project: 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) @@ -227,7 +334,7 @@ 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. @@ -246,7 +353,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. @@ -264,7 +371,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: @@ -294,12 +401,12 @@ 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. @@ -312,7 +419,7 @@ GitLab creates the following resources for ABAC clusters. | Project namespace | `ServiceAccount` | Uses namespace of Project | Deploying to a cluster | | Project namespace | `Secret` | Token for project ServiceAccount | Deploying to a cluster | -### RBAC cluster resources +#### RBAC cluster resources GitLab creates the following resources for RBAC clusters. @@ -330,11 +437,12 @@ GitLab creates the following resources for RBAC clusters. NOTE: **Note:** Project-specific resources are only created if your cluster is [managed by GitLab](#gitlab-managed-clusters). -### Security of GitLab Runners +#### 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. @@ -343,10 +451,78 @@ 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-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. + +For example, let's say the following Kubernetes clusters exist in a project: + +| Cluster | Environment scope | +| ----------- | ----------------- | +| Development | `*` | +| Staging | `staging` | +| 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 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. + +### 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 @@ -355,7 +531,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 @@ -366,7 +542,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. @@ -381,7 +557,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 @@ -420,7 +596,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, @@ -430,79 +606,19 @@ 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. - ---- - -For example, let's say the following Kubernetes clusters exist in a project: - -| Cluster | Environment scope | -| ----------- | ----------------- | -| Development | `*` | -| Staging | `staging` | -| Production | `production` | +## Deploying to a Kubernetes cluster -And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md): +A Kubernetes cluster can be the destination for a deployment job, using +special [deployment variables](#deployment-variables). -```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 @@ -522,7 +638,7 @@ 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 +### Troubleshooting Before the deployment jobs starts, GitLab creates the following specifically for the deployment job: @@ -554,105 +670,8 @@ 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 864cd75823c..163f3befeee 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -5,6 +5,10 @@ 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): diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index c021d059d30..8df27976662 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -35,7 +35,7 @@ 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). + 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. @@ -60,7 +60,7 @@ 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 diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index a32759c7bdc..92ad49e9448 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -28,7 +28,7 @@ To run Knative on Gitlab, you will need: - 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 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. @@ -96,7 +96,8 @@ cluster which already has Knative installed. You must do the following: 1. Follow the steps to - [add an existing Kubernetes cluster](../index.md#adding-an-existing-kubernetes-cluster). + [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 diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 9368c56004d..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.md). -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. @@ -173,9 +173,9 @@ curl localhost:5001/debug/vars 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 +- 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 @@ -183,7 +183,8 @@ 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 @@ -195,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 @@ -218,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? diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index 5d36e1d4be3..6707b88c317 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -21,19 +21,19 @@ 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) + - Time to schedule an issue (by milestone or by adding it to an issue board) - **Plan** (Board) - - Time to first commit + - Time to first commit - **Code** (IDE) - - Time to create a merge request + - Time to create a merge request - **Test** (CI) - - Time it takes GitLab CI/CD to test your code + - Time it takes GitLab CI/CD to test your code - **Review** (Merge Request/MR) - - Time spent on code review + - Time spent on code review - **Staging** (Continuous Deployment) - - Time between merging and deploying to production + - Time between merging and deploying to production - **Production** (Total) - - Total lifecycle time; i.e. the velocity of the project or team + - Total lifecycle time; i.e. the velocity of the project or team ## How the data is measured 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/import/svn.md b/doc/user/project/import/svn.md index 7359487e1bf..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 diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 7307c5b8991..45e96437517 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -66,15 +66,15 @@ 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 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/prometheus.md b/doc/user/project/integrations/prometheus.md index 61c30e0b0ef..e609fe43507 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -323,8 +323,11 @@ Once enabled, an issue will be opened automatically when an alert is triggered w - `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. +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. diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 6be8fc82431..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. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 30940b65454..84adb9637fc 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -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 diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 422e4b71424..eaca5f8cfb8 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -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 diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md new file mode 100644 index 00000000000..2327fa84998 --- /dev/null +++ b/doc/user/project/issues/design_management.md @@ -0,0 +1,58 @@ +# 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). +- [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). + +## 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. + 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..6da747a3f21 --- /dev/null +++ b/doc/user/project/issues/img/design_management_v12_2.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 6706e1c2e2b..bf04ed2d2d0 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -120,6 +120,12 @@ associated label or assignee will change to match that of the new column. The en board can also be filtered to only include issues from a certain milestone or an overarching label. +### Design Management **(PREMIUM)** + +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. + ### Epics **(ULTIMATE)** [Epics](../../group/epics/index.md) let you manage your portfolio of projects more diff --git a/doc/user/project/merge_requests/blocking_merge_requests.md b/doc/user/project/merge_requests/blocking_merge_requests.md new file mode 100644 index 00000000000..0506a7cb4a5 --- /dev/null +++ b/doc/user/project/merge_requests/blocking_merge_requests.md @@ -0,0 +1,133 @@ +--- +type: reference, concepts +--- + +# Blocking merge requests **(PREMIUM)** + +> Introduced in GitLab Premium 12.2 + +Blocking merge requests allow dependencies between MRs to be expressed. If a +merge request is blocked by another MR, it cannot be merged until that blocking +MR is itself merged. + +NOTE: **Note:** +Blocking merge requests are a **PREMIUM** feature, but this restriction is only +enforced for the blocked merge request. A merge request in a **CORE** or +**STARTER** project can block a **PREMIUM** merge request, but not vice-versa. + +## 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 MR + implementing the feature to be documented +* Require an MR updating a permissions matrix to be merged before merging an + MR from someone who hasn't yet been granted permissions + +It is common for a single logical change to span several merge requests. These +MRs may all be in a single project, or they may be 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` MR before the `awesome-lib` one would break the `master` +branch. + +The `awesome-project` MR 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` MR to be manually tracked, and doesn't +scale well if the `awesome-project` MR depends on changes to **several** other +projects. + +By marking the `awesome-project` MR as blocked on the `awesome-lib` MR instead, +the status of the dependency is automatically tracked by GitLab, and the WIP +state can be used to communicate the readiness of the code in each individual +MR instead. + +## Configuration + +To continue the above example, you can configure a block when creating the +new MR in `awesome-project` (or by editing it, if it already exists). The block +needs to be configured on the MR that will be **blocked**, rather than on the +**blocking** MR. There is a "Blocking merge requests" section in the form: + + + +Anyone who can edit a merge request can change the list of blocking merge +requests. + +New blocks can be added by reference, by URL, or by using autcompletion. To +remove a block, press the "X" by its reference. + +As blocks can be specified across projects, it's possible that someone else has +added a block 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 blocks like this by pressing the "X", just +as you would for a single, visible block. + +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 blocks, and the status of each one, is shown in the merge +request widget: + + + +Until all blocking merge requests have, themselves, been merged, the "Merge" +button will be disabled. In particular, note that **closed** merge requests +still block their dependents - it is impossible to automatically determine if +merge requests that were blocked by that MR when it was open, are still blocked +when it is closed. + +If a merge request has been closed **and** the block is no longer relevant, it +must be removed as a blocking MR, following the instructions above, before +merge. + +## Limitations + +* API support: [gitlab-ee#12551](https://gitlab.com/gitlab-org/gitlab-ee/issues/12551) +* Blocking relationships 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. Blocking merge requests can be +described as a graph of dependencies. The simplest possible graph has one +merge request blocking another: + +```mermaid +graph LR; + myfriend/awesome-lib!10-->mycorp/awesome-project!100; +``` + +A more complex (and still supported) graph might have several MRs blocking +another from being merged: + +```mermaid +graph LR; + myfriend/awesome-lib!10-->mycorp/awesome-project!100; + herfriend/another-lib!1-->mycorp/awesome-project!100; +``` + +We also support one MR blocking several others from being merged: + +```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` would be blocked from being merged by +`herfriend/another-lib!1`, and would also block `mycorp/awesome-project!100` +from being merged. This is **not** yet supported. + diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index ad1d79ae5b1..eb6e454062a 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -9,8 +9,18 @@ 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 +31,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 +99,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/img/edit_blocking_merge_requests.png b/doc/user/project/merge_requests/img/edit_blocking_merge_requests.png Binary files differnew file mode 100644 index 00000000000..0fe26d602e3 --- /dev/null +++ b/doc/user/project/merge_requests/img/edit_blocking_merge_requests.png diff --git a/doc/user/project/merge_requests/img/edit_blocking_merge_requests_inaccessible.png b/doc/user/project/merge_requests/img/edit_blocking_merge_requests_inaccessible.png Binary files differnew file mode 100644 index 00000000000..a1003c41c22 --- /dev/null +++ b/doc/user/project/merge_requests/img/edit_blocking_merge_requests_inaccessible.png diff --git a/doc/user/project/merge_requests/img/show_blocking_merge_requests_in_mr_widget.png b/doc/user/project/merge_requests/img/show_blocking_merge_requests_in_mr_widget.png Binary files differnew file mode 100644 index 00000000000..a1241f9e38c --- /dev/null +++ b/doc/user/project/merge_requests/img/show_blocking_merge_requests_in_mr_widget.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 8c28e24683f..f78ec9d96e6 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -47,6 +47,7 @@ With **[GitLab Enterprise Edition][ee]**, you can also: - 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 [Blocking Merge Requests](#blocking-merge-requests-premium) **(PREMIUM)** ## Use cases @@ -285,6 +286,7 @@ 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. ### Create a new merge request using git push options @@ -328,6 +330,43 @@ 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 + +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 + +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 + +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. @@ -412,6 +451,21 @@ GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the d [Read more about Browser Performance Testing.](browser_performance_testing.md) +## Blocking Merge Requests **(PREMIUM)** + +> Introduced in [GitLab Premium][products] 12.2. + +A single logical change may be split across several merge requests, and perhaps +even across several projects. When this happens, the order in which MRs are +merged is important. + +GitLab allows you to specify that a merge request is blocked by other MRs. With +this relationship in place, the merge request cannot be merged until all of its +blockers have also been merged, helping to maintain the consistency of a single +logical change. + +[Read more about Blocking Merge Requests.](blocking_merge_requests.md) + ## Security reports **(ULTIMATE)** GitLab can scan and report any vulnerabilities found in your project. diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index 84e08b4eeb8..d4dd9c7d4c3 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,6 +1,9 @@ +--- +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 142462e1879..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 @@ -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/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md index 481b1ce0337..ca0aa9965ef 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -49,35 +49,32 @@ 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. 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 index 7675a5dd9d4..4588375738e 100644 --- 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 @@ -15,6 +15,12 @@ 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: @@ -55,9 +61,22 @@ associated Pages domain. It will be also renewed automatically by GitLab. > - 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 +## 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 +<!-- 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 diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 9451b5349c0..e8984cb8b9f 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -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/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 2411744c874..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. @@ -108,7 +105,7 @@ inside GitLab that make that possible. 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. @@ -169,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. @@ -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..4e25d8545e9 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -1,7 +1,9 @@ +--- +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). @@ -118,3 +120,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 df82daa3da3..45f27b3c811 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 @@ -216,3 +224,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 20a03dff2da..e3515711f17 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. @@ -68,7 +72,7 @@ they are set to "Maintainers" by default. ## Restricting push and merge access to certain users **(STARTER)** -> This feature was [introduced][ce-5081] in [GitLab Starter][ee] 8.11. +> [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 @@ -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]: https://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..687c4e1ea6f 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,19 +18,19 @@ 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:  @@ -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 f81669a41c9..40fba8fb111 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -1,4 +1,8 @@ -# 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. @@ -7,7 +11,7 @@ in comments of issues, epics, merge requests, and commits. Each command should b 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 +## Quick Actions for issues and merge requests The following quick actions are applicable to both issues and merge requests threads, discussions, and descriptions: @@ -96,3 +100,15 @@ The following quick actions are applicable for epics threads and description: | `/remove_child_epic <&epic | group&epic | Epic URL>` | Removes child epic from epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) | | `/parent_epic <&epic | group&epic | Epic URL>` | Sets parent epic to epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) | | `/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/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/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index ad9f065b19b..c3d22e4fd29 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -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 c34b9ae3d7e..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`  |
