diff options
Diffstat (limited to 'doc/user')
174 files changed, 4624 insertions, 2029 deletions
diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md new file mode 100644 index 00000000000..78a07f4a04e --- /dev/null +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -0,0 +1,66 @@ +--- +type: howto +--- + +# Activating and deactivating users + +GitLab administrators can deactivate and activate users. + +## Deactivating a user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/63921) in GitLab 12.4. + +In order to temporarily prevent access by a GitLab user that has no recent activity, administrators +can choose to deactivate the user. + +Deactivating a user is functionally identical to [blocking a user](blocking_unblocking_users.md), +with the following differences: + +- It does not prohibit the user from logging back in via the UI. +- Once a deactivated user logs back into the GitLab UI, their account is set to active. + +A deactivated user: + +- Cannot access Git repositories or the API. +- Will not receive any notifications from GitLab. +- Will not be able to use [slash commands](../../integration/slash_commands.md). + +Personal projects, and group and user history of the deactivated user will be left intact. + +A user can be deactivated from the Admin Area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Select a user. +1. Under the **Account** tab, click **Deactivate user**. + +Please note that for the deactivation option to be visible to an admin, the user: + +- Must be currently active. +- Should not have any activity in the last 180 days. + +Users can also be deactivated using the [GitLab API](../../api/users.html#deactivate-user). + +NOTE: **Note:** +A deactivated user does not consume a [seat](../../subscriptions/index.md#managing-subscriptions). + +## Activating a user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/63921) in GitLab 12.4. + +A deactivated user can be activated from the Admin Area. + +To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Click on the **Deactivated** tab. +1. Select a user. +1. Under the **Account** tab, click **Activate user**. + +Users can also be activated using the [GitLab API](../../api/users.html#activate-user). + +NOTE: **Note:** +Activating a user will change the user's state to active and it consumes a +[seat](../../subscriptions/index.md#managing-subscriptions). + +TIP: **Tip:** +A deactivated user can also activate their account by themselves by simply logging back via the UI. diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md new file mode 100644 index 00000000000..8868170169e --- /dev/null +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -0,0 +1,48 @@ +--- +type: howto +--- + +# Blocking and unblocking users + +GitLab administrators block and unblock users. + +## Blocking a user + +In order to completely prevent access of a user to the GitLab instance, administrators can choose to +block the user. + +Users can be blocked [via an abuse report](abuse_reports.md#blocking-users), +or directly from the Admin Area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Select a user. +1. Under the **Account** tab, click **Block user**. + +A blocked user: + +- Will not be able to login. +- Cannot access Git repositories or the API. +- Will not receive any notifications from GitLab. +- Will not be able to use [slash commands](../../integration/slash_commands.md). + +Personal projects, and group and user history of the blocked user will be left intact. + +Users can also be blocked using the [GitLab API](../../api/users.html#block-user). + +NOTE: **Note:** +A blocked user does not consume a [seat](../../subscriptions/index.md#managing-subscriptions). + +## Unblocking a user + +A blocked user can be unblocked from the Admin Area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Click on the **Blocked** tab. +1. Select a user. +1. Under the **Account** tab, click **Unblock user**. + +Users can also be unblocked using the [GitLab API](../../api/users.html#unblock-user). + +NOTE: **Note:** +Unblocking a user will change the user's state to active and it consumes a +[seat](../../subscriptions/index.md#managing-subscriptions). diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 5117b5f476f..4e24c25de8f 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -6,7 +6,7 @@ type: reference You can set a maximum size for display of diff files (patches). -For details about diff files, [View changes between files](../project/merge_requests/index.md#view-changes-between-file-versions). +For details about diff files, [View changes between files](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-changes-between-file-versions). ## Maximum diff patch size diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index c75a8bcac79..35cb2b42c56 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -112,8 +112,8 @@ To list users matching a specific criteria, click on one of the following tabs o - **2FA Enabled** - **2FA Disabled** - **External** -- **Blocked** -- **Deactivated** +- **[Blocked](blocking_unblocking_users.md)** +- **[Deactivated](activating_deactivating_users.md)** - **Without projects** For each user, their username, email address, are listed, also the date their account was diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 6439607de33..103d7ecc573 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -13,7 +13,7 @@ type: concepts, howto GitLab provides liveness and readiness probes to indicate service health and reachability to required services. These probes report on the status of the database connection, Redis connection, and access to the filesystem. These -endpoints [can be provided to schedulers like Kubernetes][kubernetes] to hold +endpoints [can be provided to schedulers like Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) to hold traffic until the system is ready or restart the container as needed. ## IP whitelist @@ -39,7 +39,11 @@ GET http://localhost/-/liveness ## Health -Checks whether the application server is running. It does not verify the database or other services are running. +Checks whether the application server is running. +It does not verify the database or other services +are running. This endpoint circumvents Rails Controllers +and is implemented as additional middleware `BasicHealthCheck` +very early into the request processing lifecycle. ```text GET /-/health @@ -59,10 +63,17 @@ GitLab OK ## Readiness -The readiness probe checks whether the GitLab instance is ready to use. It checks the dependent services (Database, Redis, Gitaly etc.) and gives a status for each. +The readiness probe checks whether the GitLab instance is ready +to accept traffic via Rails Controllers. The check by default +does validate only instance-checks. + +If the `all=1` parameter is specified, the check will also validate +the dependent services (Database, Redis, Gitaly etc.) +and gives a status for each. ```text GET /-/readiness +GET /-/readiness?all=1 ``` Example request: @@ -75,37 +86,30 @@ Example response: ```json { - "db_check":{ + "master_check":[{ "status":"failed", - "message": "unexpected Db check result: 0" - }, - "redis_check":{ - "status":"ok" - }, - "cache_check":{ - "status":"ok" - }, - "queues_check":{ - "status":"ok" - }, - "shared_state_check":{ - "status":"ok" - }, - "gitaly_check":{ - "status":"ok", - "labels":{ - "shard":"default" - } - } - } + "message": "unexpected Master check result: false" + }], + ... +} ``` +On failure, the endpoint will return a `503` HTTP status code. + +This check does hit the database and Redis if authenticated via `token`. + +This check is being exempt from Rack Attack. + ## Liveness DANGER: **Warning:** -In Gitlab [12.4](https://about.gitlab.com/upcoming-releases/) the response body of the Liveness check will change to match the example below. +In Gitlab [12.4](https://about.gitlab.com/upcoming-releases/) +the response body of the Liveness check was changed +to match the example below. -The liveness probe checks whether the application server is alive. Unlike the [`health`](#health) check, this check hits the database. +Checks whether the application server is running. +This probe is used to know if Rails Controllers +are not deadlocked due to a multi-threading. ```text GET /-/liveness @@ -127,7 +131,9 @@ On success, the endpoint will return a `200` HTTP status code, and a response li } ``` -On failure, the endpoint will return a `500` HTTP status code. +On failure, the endpoint will return a `503` HTTP status code. + +This check is being exempt from Rack Attack. ## Access token (Deprecated) @@ -163,4 +169,3 @@ but commented out to help encourage others to add to it in the future. --> [pingdom]: https://www.pingdom.com [nagios-health]: https://nagios-plugins.org/doc/man/check_http.html [newrelic-health]: https://docs.newrelic.com/docs/alerts/alert-policies/downtime-alerts/availability-monitoring -[kubernetes]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/ diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index a1beee404eb..e443127a8a0 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -32,7 +32,7 @@ For instance, consider the following workflow: 1. Your team develops apps which require large files to be stored in the application repository. -1. Although you have enabled [Git LFS](../../../workflow/lfs/manage_large_binaries_with_git_lfs.md#git-lfs) +1. Although you have enabled [Git LFS](../../../administration/lfs/manage_large_binaries_with_git_lfs.md#git-lfs) to your project, your storage has grown significantly. 1. Before you exceed available storage, you set up a limit of 10 GB per repository. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index c60b3323105..f775dd8bbb4 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -134,6 +134,19 @@ Once that time passes, the jobs will be archived and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. +## Default CI configuration path + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/18073) in GitLab 12.5. + +The default CI configuration file path for new projects can be set in the Admin +area of your GitLab instance (`.gitlab-ci.yml` if not set): + +1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Input the new path in the **Default CI configuration path** field. +1. Hit **Save changes** for the changes to take effect. + +It is also possible to specify a [custom CI configuration path for a specific project](../../project/pipelines/settings.md#custom-ci-configuration-path). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 6026f9dc735..4611d5f5c77 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -8,7 +8,7 @@ You can customize some of the content in emails sent from your GitLab instance. ## Custom logo -The logo in the header of some emails can be customized, see the [logo customization section](../../../customization/branded_page_and_email_header.md). +The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#navigation-bar). ## Custom additional text **(PREMIUM ONLY)** diff --git a/doc/user/admin_area/settings/img/two_factor_grace_period.png b/doc/user/admin_area/settings/img/two_factor_grace_period.png Binary files differnew file mode 100644 index 00000000000..e7fb52969aa --- /dev/null +++ b/doc/user/admin_area/settings/img/two_factor_grace_period.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 4ca91ae5339..42f496bfbfa 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -14,6 +14,7 @@ include: - [Continuous Integration and Deployment](continuous_integration.md) - [Email](email.md) - [Sign up restrictions](sign_up_restrictions.md) +- [Sign in restrictions](sign_in_restrictions.md) - [Terms](terms.md) - [Third party offers](third_party_offers.md) - [Usage statistics](usage_statistics.md) diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md new file mode 100644 index 00000000000..0975766400f --- /dev/null +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -0,0 +1,56 @@ +--- +type: reference +--- + +# Sign-in restrictions **(CORE ONLY)** + +You can use sign-in restrictions to limit the authentication with password +for web interface and Git over HTTP(S), two-factor authentication enforcing, as well as +as configuring the home page URL and after sign-out path. + +## Password authentication enabled + +You can restrict the password authentication for web interface and Git over HTTP(S): + +- **Web interface**: When this feature is disabled, an [external authentication provider](../../../administration/auth/README.md) must be used. +- **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) must be used to authenticate. + +## Two-factor authentication + +When this feature enabled, all users will have to use the [two-factor authentication](../../profile/account/two_factor_authentication.md). + +Once the two-factor authentication is configured as mandatory, the users will be allowed +to skip forced configuration of two-factor authentication for the configurable grace +period in hours. + + + +## Sign-in information + +All users that are not logged-in will be redirected to the page represented by the configured +"Home page URL" if value is not empty. + +All users will be redirect to the page represented by the configured "After sign out path" +after sign out if value is not empty. + +If a "Sign in text" in Markdown format is provided, then every user will be presented with +this message after logging-in. + +## Settings + +To access this feature: + +1. Navigate to the **Settings > General** in the Admin area. +1. Expand the **Sign-in restrictions** section. + +<!-- ## 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/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 98126f72a78..81edd9eac34 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -31,7 +31,7 @@ patches will need to be backported, making sure active GitLab instances remain secure. If you disable version check, this information will not be collected. Enable or -disable the version check at **Admin area > Settings > Usage statistics**. +disable the version check at **Admin area > Settings > Metrics and profiling > Usage statistics**. ## Usage ping **(CORE ONLY)** @@ -85,7 +85,7 @@ will be able to show [usage statistics](../../instance_statistics/index.md) of your instance to your users. This can be restricted to admins by selecting "Only admins" in the Instance -Statistics visibility section under **Admin area > Settings > Usage statistics**. +Statistics visibility section under **Admin area > Settings > Metrics and profiling > Usage statistics**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index f718e31e8bd..73406fd5037 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -177,7 +177,7 @@ For more details, see [SSH key restrictions](../../../security/ssh_keys_restrict > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3586) in GitLab 10.3. -This option is enabled by default. By disabling it, both [pull and push mirroring](../../../workflow/repository_mirroring.md) will no longer +This option is enabled by default. By disabling it, both [pull and push mirroring](../../project/repository/repository_mirroring.md) will no longer work in every repository and can only be re-enabled by an admin on a per-project basis.  diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md index e17202645d3..c75f101b0e1 100644 --- a/doc/user/analytics/cycle_analytics.md +++ b/doc/user/analytics/cycle_analytics.md @@ -3,9 +3,10 @@ > - Introduced prior to GitLab 12.3 at the project level. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 at the group level. -Cycle Analytics measures the time spent to go from an [idea to production] - also known -as cycle time - for each of your projects. Cycle Analytics displays the median time for an idea to -reach production, along with the time typically spent in each DevOps stage along the way. +Cycle Analytics measures the time spent to go from an +[idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) +(also known as cycle time) for each of your projects. Cycle Analytics displays the median time +spent in each stage defined in the process. NOTE: **Note:** Use the `cycle_analytics` feature flag to enable at the group level. @@ -14,8 +15,8 @@ Cycle Analytics is useful in order to quickly determine the velocity of a given project. It points to bottlenecks in the development process, enabling management to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. -Cycle Analytics is tightly coupled with the [GitLab flow] and calculates a separate median for each -stage. +Cycle Analytics is tightly coupled with the [GitLab flow](../../topics/gitlab_flow.md) and +calculates a separate median for each stage. ## Overview @@ -46,6 +47,16 @@ There are seven stages that are tracked as part of the Cycle Analytics calculati - **Production** (Total) - Total lifecycle time; i.e. the velocity of the project or team +## Date ranges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13216) in GitLab 12.4. + +GitLab provides the ability to filter analytics based on a date range. To filter results: + +1. Select a group. +1. Optionally select a project. +1. Select a date range using the available date pickers. + ## How the data is measured Cycle Analytics records cycle time and data based on the project issues with the @@ -53,7 +64,8 @@ exception of the staging and production stages, where only data deployed to production are measured. Specifically, if your CI is not set up and you have not defined a `production` -or `production/*` [environment], then you will not have any data for those stages. +or `production/*` [environment](../../ci/yaml/README.md#environment), then you will not have any +data for those stages. Each stage of Cycle Analytics is further described in the table below. @@ -64,11 +76,9 @@ Each stage of Cycle Analytics is further described in the table below. | Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the issue closing pattern is not present in the merge request description, the MR is not considered to the measurement time of the stage. | | Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | | Review | Measures the median time taken to review the merge request that has closing issue pattern, between its creation and until it's merged. | -| Staging | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the [environment] set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. | +| Staging | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the environment set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. | | Production| The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. | ---- - How this works, behind the scenes: 1. Issues and merge requests are grouped together in pairs, such that for each @@ -81,12 +91,12 @@ How this works, behind the scenes: we need for the stages, like issue creation date, merge request merge time, etc. -To sum up, anything that doesn't follow [GitLab flow] will not be tracked and the +To sum up, anything that doesn't follow [GitLab flow](../../workflow/gitlab_flow.md) will not be tracked and the Cycle Analytics dashboard will not present any data for: -- merge requests that do not close an issue. -- issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. -- staging and production stages, if the project has no `production` or `production/*` +- Merge requests that do not close an issue. +- Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. +- Staging and production stages, if the project has no `production` or `production/*` environment. ## Example workflow @@ -107,7 +117,7 @@ environments is configured. 1. Push branch and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in its description at 14:00 (stop of **Code** stage / start of **Test** and **Review** stages). -1. The CI starts running your scripts defined in [`.gitlab-ci.yml`][yml] and +1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/README.md) and takes 5min (stop of **Test** stage). 1. Review merge request, ensure that everything is OK and merge the merge request at 19:00. (stop of **Review** stage / start of **Staging** stage). @@ -151,7 +161,7 @@ The current permissions on the Project Cycle Analytics dashboard are: - Internal projects - any authenticated user can access. - Private projects - any member Guest and above can access. -You can [read more about permissions][permissions] in general. +You can [read more about permissions](../../ci/yaml/README.md) in general. NOTE: **Note:** As of GitLab 12.3, the project-level page is deprecated. You should access @@ -169,14 +179,6 @@ For Cycle Analytics functionality introduced in GitLab 12.3 and later: Learn more about Cycle Analytics in the following resources: -- [Cycle Analytics feature page](https://about.gitlab.com/product/cycle-analytics/) -- [Cycle Analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/) -- [Cycle Analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/) - -[ce-5986]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/5986 -[ce-20975]: https://gitlab.com/gitlab-org/gitlab-foss/issues/20975 -[environment]: ../../ci/yaml/README.md#environment -[GitLab flow]: ../../workflow/gitlab_flow.md -[idea to production]: https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab -[permissions]: ../permissions.md -[yml]: ../../ci/yaml/README.md +- [Cycle Analytics feature page](https://about.gitlab.com/product/cycle-analytics/). +- [Cycle Analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). +- [Cycle Analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index aecbac15c98..40295e47e89 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -42,10 +42,19 @@ The following metrics and visualizations are available on a project or group lev - Number of lines of code per commit. - Number of files touched. - Scatterplot showing all MRs merged on a certain date, together with the days it took to complete the action and a 30 day rolling median. - - Users can zoom in and out on specific days of interest. - Table showing the list of merge requests with their respective time duration metrics. - Users can sort by any of the above metrics. +## Date ranges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13188) in GitLab 12.4. + +GitLab has the ability to filter analytics based on a date range. To filter results: + +1. Select a group. +1. Optionally select a project. +1. Select a date range using the available date pickers. + ## Permissions The **Productivity Analytics** dashboard can be accessed only: diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 14dae56f087..931755c6305 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -40,10 +40,9 @@ to perform audits for your Docker-based apps. To enable Container Scanning in your pipeline, you need: - A GitLab Runner with the - [`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or - [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) - executor running in privileged mode. If you're using the shared Runners on GitLab.com, - this is enabled by default. + [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or + [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) + executor. - Docker `18.09.03` or higher installed on the machine where the Runners are running. If you're using the shared Runners on GitLab.com, this is already the case. @@ -150,17 +149,18 @@ container_scanning: Container Scanning can be [configured](#overriding-the-container-scanning-template) using environment variables. -| Environment Variable | Description | Default | -| ------ | ------ | ------ | -| `KLAR_TRACE` | Set to true to enable more verbose output from klar. | `"false"` | -| `DOCKER_USER` | Username for accessing a Docker registry requiring authentication. | `$CI_REGISTRY_USER` | -| `DOCKER_PASSWORD` | Password for accessing a Docker registry requiring authentication. | `$CI_REGISTRY_PASSWORD` | -| `CLAIR_OUTPUT` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold will be outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | `Unknown` | -| `REGISTRY_INSECURE` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | `"false"` | -| `CLAIR_VULNERABILITIES_DB_URL` | This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/blob/30522ca8b901223ac8c32b633d8d67f340b159c1/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L17-19) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [postgres server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/klar/#running-the-scanning-tool) section of the [klar readme](https://gitlab.com/gitlab-org/security-products/analyzers/klar). | `clair-vulnerabilities-db` | -| `CI_APPLICATION_REPOSITORY` | Docker repository URL for the image to be scanned. | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | -| `CI_APPLICATION_TAG` | Docker respository tag for the image to be scanned. | `$CI_COMMIT_SHA` | -| `CLAIR_DB_IMAGE_TAG` | The Docker image tag for the [postgres server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | `latest` | +| Environment Variable | Description | Default | +| ------ | ------ | ------ | +| `KLAR_TRACE` | Set to true to enable more verbose output from klar. | `"false"` | +| `DOCKER_USER` | Username for accessing a Docker registry requiring authentication. | `$CI_REGISTRY_USER` | +| `DOCKER_PASSWORD` | Password for accessing a Docker registry requiring authentication. | `$CI_REGISTRY_PASSWORD` | +| `CLAIR_OUTPUT` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold will be outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | `Unknown` | +| `REGISTRY_INSECURE` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | `"false"` | +| `CLAIR_VULNERABILITIES_DB_URL` | This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/blob/30522ca8b901223ac8c32b633d8d67f340b159c1/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L17-19) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [postgres server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/klar/#running-the-scanning-tool) section of the [GitLab klar analyzer readme](https://gitlab.com/gitlab-org/security-products/analyzers/klar). | `clair-vulnerabilities-db` | +| `CI_APPLICATION_REPOSITORY` | Docker repository URL for the image to be scanned. | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | +| `CI_APPLICATION_TAG` | Docker respository tag for the image to be scanned. | `$CI_COMMIT_SHA` | +| `CLAIR_DB_IMAGE` | The Docker image name and tag for the [postgres server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise air-gapped installation. | `arminc/clair-db:latest` | +| `CLAIR_DB_IMAGE_TAG` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [postgres server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | `latest` | ## Security Dashboard @@ -178,6 +178,47 @@ 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). +## Running Container Scanning in an offline air-gapped installation + +Container Scanning can be executed on an offline air-gapped GitLab Ultimate installation using the following process: + +1. Host the following Docker images on a [local Docker container registry](../../packages/container_registry/index.md): + - [arminc/clair-db vulnerabilities database](https://hub.docker.com/r/arminc/clair-db) + - [GitLab klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) +1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry: + + ```yaml + include: + - template: Container-Scanning.gitlab-ci.yml + + container_scanning: + image: $CI_REGISTRY/namespace/gitlab-klar-analyzer + variables: + CLAIR_DB_IMAGE: $CI_REGISTRY/namespace/clair-vulnerabilities-db + ``` + +It may be worthwhile to set up a [scheduled pipeline](../../project/pipelines/schedules.md) to automatically build a new version of the vulnerabilities database on a preset schedule. You can use the following `.gitlab-yml.ci` as a template: + +```yaml +image: docker:stable + +services: + - docker:stable-dind + +stages: + - build + +build_latest_vulnerabilities: + stage: build + script: + - docker pull arminc/clair-db:latest + - docker tag arminc/clair-db:latest $CI_REGISTRY/namespace/clair-vulnerabilities-db + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db +``` + +The above template will work for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. + ## Troubleshooting ### docker: Error response from daemon: failed to copy xattrs diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 951c4b9dd73..d285b5ff585 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -339,3 +339,33 @@ 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. --> + +## Troubleshooting + +### Running out of memory + +By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25% +of the total memory on the host. +Since it keeps most of its information in memory during a scan, +it is possible for DAST to run out of memory while scanning large applications. +This results in the following error: + +``` +[zap.out] java.lang.OutOfMemoryError: Java heap space +``` + +Fortunately, it is straightforward to increase the amount of memory available +for DAST by overwriting the `script` key in the DAST template: + +```yaml +include: + template: DAST.gitlab-ci.yml + +dast: + script: + - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} + - /analyze -t $DAST_WEBSITE -z"-Xmx3072m" +``` + +Here, DAST is being allocated 3072 MB. +Change the number after `-Xmx` to the required memory amount. diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png Binary files differnew file mode 100644 index 00000000000..4687987b763 --- /dev/null +++ b/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 8366e943ccc..2828d487153 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -17,7 +17,7 @@ sidebar. ## Viewing dependencies - + Dependencies are displayed with the following information: diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 9f87d79025e..0e46052b0bd 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -37,7 +37,7 @@ The results are sorted by the severity of the vulnerability: ## Requirements -To run a Dependency Scanning job, you need GitLab Runner with the +To run a Dependency Scanning job, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) executor running in privileged mode. If you're using the shared Runners on GitLab.com, @@ -47,6 +47,8 @@ CAUTION: **Caution:** If you use your own Runners, make sure that the Docker version you have installed is **not** `19.03.00`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. +Privileged mode is not necessary if you've [disabled Docker in Docker for Dependency Scanning](#disabling-docker-in-docker-for-dependency-scanning) + ## Supported languages and package managers The following languages and dependency managers are supported. @@ -59,27 +61,10 @@ The following languages and dependency managers are supported. | Go ([Golang](https://golang.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/7132 "Dependency Scanning for Go")) | not available | | PHP ([Composer](https://getcomposer.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | Python ([pip](https://pip.pypa.io/en/stable/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| Python ([Pipfile](https://docs.pipenv.org/en/latest/basics/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available | +| Python ([Pipfile](https://pipenv.kennethreitz.org/en/latest/basics/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available | | Python ([poetry](https://poetry.eustace.io/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/7006 "Support Poetry in Dependency Scanning")) | not available | | Ruby ([gem](https://rubygems.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | -## Remote checks - -While some tools pull a local database to check vulnerabilities, some others -like Gemnasium require sending data to GitLab central servers to analyze them: - -1. Gemnasium scans the dependencies of your project locally and sends a list of - packages to GitLab central servers. -1. The servers return the list of known vulnerabilities for all versions of - these packages. -1. The client picks up the relevant vulnerabilities by comparing with the versions - of the packages that are used by the project. - -The Gemnasium client does **NOT** send the exact package versions your project relies on. - -You can disable the remote checks by [using](#customizing-the-dependency-scanning-settings) -the `DS_DISABLE_REMOTE_CHECKS` environment variable and setting it to `"true"`. - ## Configuration For GitLab 11.9 and later, to enable Dependency Scanning, you must @@ -116,7 +101,7 @@ include: template: Dependency-Scanning.gitlab-ci.yml variables: - DS_DISABLE_REMOTE_CHECKS: "true" + DS_PYTHON_VERSION: 2 ``` Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline @@ -150,7 +135,7 @@ using environment variables. | `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/issues/12296) in GitLab 12.1)| | | `DS_PIP_DEPENDENCY_PATH` | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/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_DISABLE_DIND` | Disable Docker in Docker and run analyzers [individually](#disabling-docker-in-docker-for-dependency-scanning).| | | `DS_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to `0` to disable). | | | `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | `DS_EXCLUDED_PATHS=doc,spec` | | `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`. | | @@ -158,6 +143,50 @@ using environment variables. | `DS_RUN_ANALYZER_TIMEOUT` | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | | | `PIP_INDEX_URL` | Base URL of Python Package Index (default `https://pypi.org/simple`). | | | `PIP_EXTRA_INDEX_URL` | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. | | +| `MAVEN_CLI_OPTS` | List of command line arguments that will be passed to the maven analyzer during the project's build phase (see example for [using private repos](#using-private-maven-repos)). | | + +### Using private Maven repos + +If you have a private Maven repository which requires login credentials, +you can use the `MAVEN_CLI_OPTS` environment variable to pass variables +specified in your settings (e.g., username, password, etc.). + +For example, if you have a settings file in your project source (e.g., `mysettings.xml`) +that looks like the following, you can specify the variables +[by adding an entry under your project's settings](../../../ci/variables/README.md#via-the-ui), +so that you don't have to expose your private data in `.gitlab-ci.yml` (e.g., adding +`MAVEN_CLI_OPTS` with value `--settings mysettings.xml -Dprivate.username=foo -Dprivate.password=bar`). + +```xml +<!-- mysettings.xml --> +<settings> + ... + <servers> + <server> + <id>private_server</id> + <username>${private.username}</username> + <password>${private.password}</password> + </server> + </servers> +</settings> +``` + +### Disabling Docker in Docker for Dependency Scanning + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12487) in GitLab Ultimate 12.5. + +You can avoid the need for Docker in Docker by running the individual analyzers. +This does not require running the executor in privileged mode. For example: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DISABLE_DIND: "true" +``` + +This will create individual `<analyzer-name>-dependency_scanning` jobs for each analyzer that runs in your CI/CD pipeline. ## Interacting with the vulnerabilities diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index e9f5898950e..dbbcb606ac7 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -203,14 +203,34 @@ An approval will be optional when a license report: - Contains no software license violations. - Contains only new licenses that are `approved` or unknown. -<!-- ## Troubleshooting +## 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. +### Getting error message `sast job: stage parameter should be [some stage name here]` -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. --> +When including a security job template like [`SAST`](sast/index.md#configuration), +the following error can be raised, depending on your GitLab CI/CD configuration: + +``` +Found errors in your .gitlab-ci.yml: + +* sast job: stage parameter should be unit-tests +``` + +This error appears when the stage (nammed `test`) of the included job isn't declared +in `.gitlab-ci.yml`. +To fix this issue, you can either: + +- Add a `test` stage in your `.gitlab-ci.yml`. +- Change the default stage of the included security jobs. For example, with `SAST`: + + ```yaml + include: + template: SAST.gitlab-ci.yml + + sast: + stage: unit-tests + ``` + +[Learn more on overriding the SAST template](sast/index.md#overriding-the-sast-template). +All the security scanning tools define their stage, so this error can occur with +all of them. diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md index 75a3b33e32e..3cf8301adca 100644 --- a/doc/user/application_security/license_compliance/index.md +++ b/doc/user/application_security/license_compliance/index.md @@ -94,8 +94,20 @@ always take the latest License Compliance artifact available. Behind the scenes, [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/license-management) is used to detect the languages/frameworks and in turn analyzes the licenses. -The License Compliance settings can be changed through environment variables by using the -[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in the [License Compliance documentation](https://gitlab.com/gitlab-org/security-products/license-management#settings). +The License Compliance settings can be changed through [environment variables](#available-variables) by using the +[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. + +### Available variables + +License Compliance can be configured using environment variables. + +| Environment variable | Required | Description | +|-----------------------|----------|-------------| +| `MAVEN_CLI_OPTS` | no | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. | +| `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if your project has both Golang and Ruby code stored in different directories and you want to only scan the Ruby code, you can update your `.gitlab-ci-yml` template to specify which project directories to scan, like `LICENSE_FINDER_CLI_OPTS: '--debug --aggregate-paths=. ruby'`. | +| `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | +| `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | +| `SETUP_CMD` | no | Custom setup for the dependency installation. (experimental) | ### Installing custom dependencies diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 76a566f7514..6eb2ca71e71 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -25,7 +25,7 @@ SAST supports the following official analyzers: - [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET)) - [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) - [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) -- [`tslint`](https://gitlab.com/gitlab-org/security-products/analyzers/tslint) (TSLint (Typescript)) +- [`tslint`](https://gitlab.com/gitlab-org/security-products/analyzers/tslint) (TSLint (TypeScript)) The analyzers are published as Docker images that SAST will use to launch dedicated containers for each analysis. @@ -111,6 +111,9 @@ 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. +CAUTION: **Caution:** +Custom analyzers are not spawned automatically when [Docker In Docker](index.md#disabling-docker-in-docker-for-sast) is disabled. + ## Analyzers Data | Property \ Tool | Apex | Bandit | Brakeman | ESLint security | Find Sec Bugs | Flawfinder | Go AST Scanner | NodeJsScan | Php CS Security Audit | Security code Scan (.NET) | TSLint Security | Sobelow | diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index cb54d9f3853..615eb072ea7 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -78,7 +78,7 @@ The following table shows which languages, package managers and frameworks are s | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | | Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | -| Typescript | [TSLint config security](https://github.com/webschik/tslint-config-security/) | 11.9 | +| TypeScript | [TSLint config security](https://github.com/webschik/tslint-config-security/) | 11.9 | NOTE: **Note:** The Java analyzers can also be used for variants like the @@ -146,7 +146,15 @@ sast: CI_DEBUG_TRACE: "true" ``` -### Using a variable to pass username and password to a private Maven repository +### Using environment variables to pass credentials for private repositories + +Some analyzers require downloading the project's dependencies in order to +perform the analysis. In turn, such dependencies may live in private Git +repositories and thus require credentials like username and password to download them. +Depending on the analyzer, such credentials can be provided to +it via [custom environment variables](#custom-environment-variables). + +#### Using a variable to pass username and password to a private Maven repository If you have a private Apache Maven repository that requires login credentials, you can use the `MAVEN_CLI_OPTS` [environment variable](#available-variables) @@ -184,14 +192,14 @@ SAST can be [configured](#customizing-the-sast-settings) using environment varia 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_DISABLE_DIND` | Disable Docker in Docker and run analyzers [individually](#disabling-docker-in-docker-for-sast). | -| `SAST_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | +| Environment variable | Description | +|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SAST_ANALYZER_IMAGES` | Comma separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). Not available when [Docker in Docker is disabled](#disabling-docker-in-docker-for-sast). | +| `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_DISABLE_DIND` | Disable Docker in Docker and run analyzers [individually](#disabling-docker-in-docker-for-sast). | +| `SAST_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). Not available when [Docker in Docker is disabled](#disabling-docker-in-docker-for-sast). | #### Vulnerability filters @@ -216,6 +224,9 @@ The following variables configure timeouts. | `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".| +NOTE: **Note:** +Timeout variables are not applicable for setups with [disabled Docker In Docker](index.md#disabling-docker-in-docker-for-sast). + #### Analyzer settings Some analyzers can be customized with environment variables. @@ -234,6 +245,19 @@ Some analyzers can be customized with environment variables. | `SBT_PATH` | spotbugs | Path to the `sbt` executable. | | `FAIL_NEVER` | spotbugs | Set to `1` to ignore compilation failure. | +#### Custom environment variables + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/18193) in GitLab Ultimate 12.5. + +In addition to the aforementioned SAST configuration variables, +all [custom environment variables](../../../ci/variables/README.md#creating-a-custom-environment-variable) are propagated +to the underlying SAST analyzer images if +[the SAST vendored template](#configuration) is used. + +CAUTION: **Caution:** +Variables having names starting with these prefixes will **not** be propagated to the SAST Docker container and/or +analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. + ## Reports JSON format CAUTION: **Caution:** diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_3.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_3.png Binary files differdeleted file mode 100644 index 1fe76a9e08f..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_3.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_4.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_4.png Binary files differnew file mode 100644 index 00000000000..682dcbec63f --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v12_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 0e26206f070..688d231d568 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -71,12 +71,12 @@ Once you're on the dashboard, at the top you should see a series of filters for: - Report type - Project -To the right of the filters, you should see a **Hide dismissed** toggle button. +To the right of the filters, you should see a **Hide dismissed** toggle button ([available in GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/issues/9102)). NOTE: **Note:** The dashboard only shows projects with [security reports](#supported-reports) enabled in a group. - + Selecting one or more filters will filter the results in this page. Disabling the **Hide dismissed** toggle button will let you also see vulnerabilities that have been dismissed. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index dc6f859e881..c3e2e6bca5b 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -7,7 +7,7 @@ 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-removing-clusters). +[create a cluster](../project/clusters/add_remove_clusters.md). ## Installing applications @@ -40,6 +40,7 @@ The following applications can be installed: - [GitLab Runner](#gitlab-runner) - [JupyterHub](#jupyterhub) - [Knative](#knative) +- [Crossplane](#crossplane) With the exception of Knative, the applications will be installed in a dedicated namespace called `gitlab-managed-apps`. @@ -82,19 +83,21 @@ certificates. Installing Cert-Manager on your cluster will issue a certificate by [Let's Encrypt](https://letsencrypt.org/) and ensure that certificates are valid and up-to-date. -NOTE: **Note:** -The -[jetstack/cert-manager](https://github.com/jetstack/cert-manager) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) -file. Prior to GitLab 12.3, -the [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager) -chart was used. +The chart used to install this application depends on the version of GitLab used. In: -NOTE: **Note:** -If you have installed cert-manager prior to GitLab 12.3, Let's Encrypt will -[block requests from older versions of cert-manager](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753). -To resolve this, uninstall cert-manager (consider [backing up any additional configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html)), then install cert-manager again. +- GitLab 12.3 and newer, the [jetstack/cert-manager](https://github.com/jetstack/cert-manager) + chart is used with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) + file. +- GitLab 12.2 and older, the [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager) + chart was used. + +If you have installed Cert-Manager prior to GitLab 12.3, Let's Encrypt will +[block requests from older versions of Cert-Manager](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753). + +To resolve this: + +1. Uninstall Cert-Manager (consider [backing up any additional configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html)). +1. Install Cert-Manager again. ### GitLab Runner @@ -105,10 +108,20 @@ To resolve this, uninstall cert-manager (consider [backing up any additional con project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous integration -service included with GitLab that coordinates the jobs. When installing -the GitLab Runner via the applications, it will run in **privileged -mode** by default. Make sure you read the [security -implications](../project/clusters/index.md#security-implications) before doing so. +service included with GitLab that coordinates the jobs. + +If the project is on GitLab.com, shared Runners are available +(the first 2000 minutes are free, you can +[buy more later](../../subscriptions/index.md#extra-shared-runners-pipeline-minutes)) +and you do not have to deploy one if they are enough for your needs. If a +project-specific Runner is desired, or there are no shared Runners, it is easy +to deploy one. + +Note that the deployed Runner will be set as **privileged**, which means it will essentially +have root access to the underlying machine. This is required to build Docker images, +so it is the default. Make sure you read the +[security implications](../project/clusters/index.md#security-implications) +before deploying one. NOTE: **Note:** The [`runner/gitlab-runner`](https://gitlab.com/gitlab-org/charts/gitlab-runner) @@ -127,11 +140,112 @@ web proxy for your applications and is useful if you want to use [Auto DevOps](../../topics/autodevops/index.md) or deploy your own web apps. NOTE: **Note:** +With the following procedure, a load balancer must be installed in your cluster +to obtain the endpoint. You can use either +Ingress, or Knative's own load balancer ([Istio](https://istio.io)) if using Knative. + +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. + +To install it, click on the **Install** button for Ingress. GitLab will attempt +to determine the external endpoint and it should be available within a few minutes. + +#### Determining the external endpoint automatically + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/17052) in GitLab 10.6. + +After you install Ingress, the external endpoint should be available within a few minutes. + +TIP: **Tip:** +This endpoint can be used for the +[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) +using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. + +If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: + +1. Check your [Kubernetes cluster on Google Kubernetes Engine](https://console.cloud.google.com/kubernetes) to ensure there are no errors on its nodes. +1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) on Google Kubernetes Engine. For more information, see [Resource Quotas](https://cloud.google.com/compute/quotas). +1. Check [Google Cloud's Status](https://status.cloud.google.com/) to ensure they are not having any disruptions. + +Once installed, you may see a `?` for "Ingress IP Address" depending on the +cloud provider. For EKS specifically, this is because the ELB is created +with a DNS name, not an IP address. If GitLab is still unable to +determine the endpoint of your Ingress or Knative application, you can +[determine it manually](#determining-the-external-endpoint-manually). + +NOTE: **Note:** The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) file. +#### Determining the external endpoint manually + +If the cluster is on GKE, click the **Google Kubernetes Engine** link in the +**Advanced settings**, or go directly to the +[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) +and select the proper project and cluster. Then click **Connect** and execute +the `gcloud` command in a local terminal or using the **Cloud Shell**. + +If the cluster is not on GKE, follow the specific instructions for your +Kubernetes provider to configure `kubectl` with the right credentials. +The output of the following examples will show the external endpoint of your +cluster. This information can then be used to set up DNS entries and forwarding +rules that allow external access to your deployed applications. + +If you installed Ingress via the **Applications**, run the following command: + +```bash +kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' +``` + +Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: + +```bash +kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' +``` + +For Istio/Knative, the command will be different: + +```bash +kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' +``` + +Otherwise, you can list the IP addresses of all load balancers: + +```bash +kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' +``` + +NOTE: **Note:** +If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) +will also be created, which will incur additional AWS costs. + +NOTE: **Note:** +You may see a trailing `%` on some Kubernetes versions, **do not include it**. + +The Ingress is now available at this address and will route incoming requests to +the proper service based on the DNS name in the request. To support this, a +wildcard DNS CNAME record should be created for the desired domain name. For example, +`*.myekscluster.com` would point to the Ingress hostname obtained earlier. + +#### 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, +your apps will not be able to be reached, and you'd have to change the DNS +record again. In order to avoid that, you should change it into a static +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 + +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. + #### Web Application Firewall (ModSecurity) > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/65192) in GitLab 12.3 (enabled using `ingress_modsecurity` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-in-development)). @@ -150,7 +264,7 @@ This feature: For example: ```sh - kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- tail -f /var/log/modsec_audit.log + kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- tail -f /var/log/modsec/audit.log ``` There is a small performance overhead by enabling `modsecurity`. However, if this is @@ -242,7 +356,7 @@ server to use the external IP address for that domain. For any application created and installed, they will be accessible as `<program_name>.<kubernetes_namespace>.<domain_name>`. This will require your Kubernetes cluster to have [RBAC -enabled](../project/clusters/index.md#rbac-cluster-resources). +enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). NOTE: **Note:** The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) @@ -257,12 +371,52 @@ chart is used to install this application. open-source monitoring and alerting system useful to supervise your deployed applications. +GitLab is able to monitor applications automatically, using the +[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and +memory metrics are automatically collected, and response metrics are retrieved +from NGINX Ingress as well. + +To enable monitoring, simply install Prometheus into the cluster with the +**Install** button. + NOTE: **Note:** The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus) chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/prometheus/values.yaml) file. +### Crossplane + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34702) in GitLab 12.5 for project-level clusters. + +[Crossplane](https://crossplane.io/docs) is a multi-cloud control plane useful for +managing applications and infrastructure across multiple clouds. It extends the +Kubernetes API using: + +- Custom resources. +- Controllers that watch those custom resources. + +Crossplane allows provisioning and lifecycle management of infrastructure components +across cloud providers in a uniform manner by abstracting cloud provider-specific +configurations. + +The Crossplane GitLab-managed application: + +- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the + project repository. +- Can then be used to provision infrastructure or managed applications such as + PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services + required by the application via the Auto DevOps pipeline. + +For information on configuring Crossplane installed on the cluster, see +[Crossplane configuration](crossplane.md). + +NOTE: **Note:** +[`alpha/crossplane`](https://charts.crossplane.io/alpha/) chart v0.4.1 is used to +install Crossplane using the +[`values.yaml`](https://github.com/crossplaneio/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) +file. + ## Upgrading applications > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/24789) in GitLab 11.8. @@ -296,13 +450,14 @@ The applications below can be uninstalled. | Application | GitLab version | Notes | | ----------- | -------------- | ----- | -| Cert-Manager | 12.2+ | The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish to [back up your configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html) or [revoke your certificates](https://letsencrypt.org/docs/revoking/) | +| Cert-Manager | 12.2+ | The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish to [back up your configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html) or [revoke your certificates](https://letsencrypt.org/docs/revoking/). | | GitLab Runner | 12.2+ | Any running pipelines will be canceled. | | Helm | 12.2+ | The associated Tiller pod, the `gitlab-managed-apps` namespace, and all of its resources will be deleted and cannot be restored. | | Ingress | 12.1+ | The associated load balancer and IP will be deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. | | JupyterHub | 12.1+ | All data not committed to GitLab will be deleted and cannot be restored. | | Knative | 12.1+ | The associated IP will be deleted and cannot be restored. | | Prometheus | 11.11+ | All data will be deleted and cannot be restored. | +| Crossplane | 12.5+ | All data will be deleted and cannot be restored. | To uninstall an application: diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md new file mode 100644 index 00000000000..37210b22f6f --- /dev/null +++ b/doc/user/clusters/crossplane.md @@ -0,0 +1,292 @@ +# Crossplane configuration + +Once Crossplane [is installed](applications.md#crossplane), it must be configured for +use. + +The process of configuring Crossplane includes: + +1. Configuring RBAC permissions. +1. Configuring Crossplane with a cloud provider. +1. Configure managed service access. +1. Setting up Resource classes. +1. Using Auto DevOps configuration options. +1. Connect to the PostgreSQL instance. + +To allow Crossplane to provision cloud services such as PostgreSQL, the cloud provider +stack must be configured with a user account. For example: + +- A service account for GCP. +- An IAM user for AWS. + +Important notes: + +- This guide uses GCP as an example. However, the process for AWS and Azure will be +similar. +- Crossplane requires the Kubernetes cluster to be VPC native with Alias IPs enabled so +that the IP address of the pods are routable within the GCP network. + +First, we need to declare some environment variables with configuration that will be used throughout this guide: + +```sh +export PROJECT_ID=crossplane-playground # the GCP project where all resources reside. +export NETWORK_NAME=default # the GCP network where your GKE is provisioned. +export REGION=us-central1 # the GCP region where the GKE cluster is provisioned. +``` + +## Configure RBAC permissions + +- For a non-GitLab managed cluster(s), ensure that the service account for the token provided can manage resources in the `database.crossplane.io` API group. +Manually grant GitLab's service account the ability to manage resources in the +`database.crossplane.io` API group. The Aggregated ClusterRole allows us to do that. + +NOTE: **Note:** +For a non-GitLab managed cluster, ensure that the service account for the token provided can manage resources in the `database.crossplane.io` API group. +1. Save the following YAML as `crossplane-database-role.yaml`: + +```sh +cat > crossplane-database-role.yaml <<EOF +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: crossplane-database-role + labels: + rbac.authorization.k8s.io/aggregate-to-edit: "true" +rules: +- apiGroups: + - database.crossplane.io + resources: + - postgresqlinstances + verbs: + - get + - list + - create + - update + - delete + - patch + - watch +EOF +``` + +Once the file is created, apply it with the following command in order to create the necessary role: + +```sh +kubectl apply -f crossplane-database-role.yaml +``` + +## Configure Crossplane with a cloud provider + +See [Configure Your Cloud Provider Account](https://crossplane.io/docs/v0.4/cloud-providers.html) +to configure the installed cloud provider stack with a user account. + +Note that the Secret and the Provider resource referencing the Secret needs to be +applied to the `gitlab-managed-apps` namespace in the guide. Make sure you change that +while following the process. + +[Configure Providers](https://crossplane.io/docs/v0.4/cloud-providers.html) + +## Configure Managed Service Access + +We need to configure connectivity between the PostgreSQL database and the GKE cluster. +This can done by either: + +- Using Crossplane as demonstrated below. +- Directly in the GCP console by +[configuring private services access](https://cloud.google.com/vpc/docs/configure-private-services-access). +Create a GlobalAddress and Connection resources: + +```sh +cat > network.yaml <<EOF +--- +# gitlab-ad-globaladdress defines the IP range that will be allocated for cloud services connecting to the instances in the given Network. + +apiVersion: compute.gcp.crossplane.io/v1alpha3 +kind: GlobalAddress +metadata: + name: gitlab-ad-globaladdress +spec: + providerRef: + name: gcp-provider + reclaimPolicy: Delete + name: gitlab-ad-globaladdress + purpose: VPC_PEERING + addressType: INTERNAL + prefixLength: 16 + network: projects/$PROJECT_ID/global/networks/$NETWORK_NAME +--- +# gitlab-ad-connection is what allows cloud services to use the allocated GlobalAddress for communication. Behind +# the scenes, it creates a VPC peering to the network that those service instances actually live. + +apiVersion: servicenetworking.gcp.crossplane.io/v1alpha3 +kind: Connection +metadata: + name: gitlab-ad-connection +spec: + providerRef: + name: gcp-provider + reclaimPolicy: Delete + parent: services/servicenetworking.googleapis.com + network: projects/$PROJECT_ID/global/networks/$NETWORK_NAME + reservedPeeringRangeRefs: + - name: gitlab-ad-globaladdress +EOF +``` + +Apply the settings specified in the file with the following command: + +```sh +kubectl apply -f network.yaml +``` + +You can verify creation of the network resources with the following commands. +Verify that the status of both of these resources is ready and is synced. + +```sh +kubectl describe connection.servicenetworking.gcp.crossplane.io gitlab-ad-connection +kubectl describe globaladdress.compute.gcp.crossplane.io gitlab-ad-globaladdress +``` + +## Setting up Resource classes + +Resource classes are a way of defining a configuration for the required managed service. We will define the Postgres Resource class + +- Define a gcp-postgres-standard.yaml resourceclass which contains + +1. A default CloudSQLInstanceClass. +1. A CloudSQLInstanceClass with labels. + +```sh +cat > gcp-postgres-standard.yaml <<EOF +apiVersion: database.gcp.crossplane.io/v1beta1 +kind: CloudSQLInstanceClass +metadata: + name: cloudsqlinstancepostgresql-standard + labels: + gitlab-ad-demo: "true" +specTemplate: + writeConnectionSecretsToNamespace: gitlab-managed-apps + forProvider: + databaseVersion: POSTGRES_9_6 + region: $REGION + settings: + tier: db-custom-1-3840 + dataDiskType: PD_SSD + dataDiskSizeGb: 10 + ipConfiguration: + privateNetwork: projects/$PROJECT_ID/global/networks/$NETWORK_NAME + # this should match the name of the provider created in the above step + providerRef: + name: gcp-provider + reclaimPolicy: Delete +--- +apiVersion: database.gcp.crossplane.io/v1beta1 +kind: CloudSQLInstanceClass +metadata: + name: cloudsqlinstancepostgresql-standard-default + annotations: + resourceclass.crossplane.io/is-default-class: "true" +specTemplate: + writeConnectionSecretsToNamespace: gitlab-managed-apps + forProvider: + databaseVersion: POSTGRES_9_6 + region: $REGION + settings: + tier: db-custom-1-3840 + dataDiskType: PD_SSD + dataDiskSizeGb: 10 + ipConfiguration: + privateNetwork: projects/$PROJECT_ID/global/networks/$NETWORK_NAME + # this should match the name of the provider created in the above step + providerRef: + name: gcp-provider + reclaimPolicy: Delete +EOF +``` + +Apply the resource class configuration with the following command: + +```sh +kubectl apply -f gcp-postgres-standard.yaml +``` + +Verify creation of the Resource class with the following command: + +```sh +kubectl get cloudsqlinstanceclasses +``` + +The Resource Classes allow you to define classes of service for a managed service. We could create another `CloudSQLInstanceClass` which requests for a larger or a faster disk. It could also request for a specific version of the database. + +## Auto DevOps Configuration Options + +The Auto DevOps pipeline can be run with the following options: + +The Environment variables, `AUTO_DEVOPS_POSTGRES_MANAGED` and `AUTO_DEVOPS_POSTGRES_MANAGED_CLASS_SELECTOR` need to be set to provision PostgresQL using Crossplane + +Alertnatively, the following options can be overridden from the values for the helm chart. + +- `postgres.managed` set to true which will select a default resource class. + The resource class needs to be marked with the annotation + `resourceclass.crossplane.io/is-default-class: "true"`. The CloudSQLInstanceClass + `cloudsqlinstancepostgresql-standard-default` will be used to satisfy the claim. + +- `postgres.managed` set to `true` with `postgres.managedClassSelector` + providing the resource class to choose based on labels. In this case, the + value of `postgres.managedClassSelector.matchLabels.gitlab-ad-demo="true"` + will select the CloudSQLInstance class `cloudsqlinstancepostgresql-standard` + to satisfy the claim request. + +The Auto DevOps pipeline should provision a PostgresqlInstance when it runs succesfully. + +Verify creation of the PostgresQL Instance. + +```sh +kubectl get postgresqlinstance +``` + +Sample Output: The `STATUS` field of the PostgresqlInstance transitions to `BOUND` when it is successfully provisioned. + +``` +NAME STATUS CLASS-KIND CLASS-NAME RESOURCE-KIND RESOURCE-NAME AGE +staging-test8 Bound CloudSQLInstanceClass cloudsqlinstancepostgresql-standard CloudSQLInstance xp-ad-demo-24-staging-staging-test8-jj55c 9m +``` + +The endpoint of the PostgreSQL instance, and the user credentials, are present in a secret called `app-postgres` within the same project namespace. + +Verify the secret with the database information is created with the following command: + +```sh +kubectl describe secret app-postgres +``` + +Sample Output: + +``` +Name: app-postgres +Namespace: xp-ad-demo-24-staging +Labels: <none> +Annotations: crossplane.io/propagate-from-name: 108e460e-06c7-11ea-b907-42010a8000bd + crossplane.io/propagate-from-namespace: gitlab-managed-apps + crossplane.io/propagate-from-uid: 10c79605-06c7-11ea-b907-42010a8000bd + +Type: Opaque + +Data +==== +privateIP: 8 bytes +publicIP: 13 bytes +serverCACertificateCert: 1272 bytes +serverCACertificateCertSerialNumber: 1 bytes +serverCACertificateCreateTime: 24 bytes +serverCACertificateExpirationTime: 24 bytes +username: 8 bytes +endpoint: 8 bytes +password: 27 bytes +serverCACertificateCommonName: 98 bytes +serverCACertificateInstance: 41 bytes +serverCACertificateSha1Fingerprint: 40 bytes +``` + +## Connect to the PostgresQL instance + +Follow this [GCP guide](https://cloud.google.com/sql/docs/postgres/connect-kubernetes-engine) if you +would like to connect to the newly provisioned Postgres database instance on CloudSQL. diff --git a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png b/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png Binary files differnew file mode 100644 index 00000000000..63e2d1cd4e8 --- /dev/null +++ b/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 37308ad7175..83b6f6fe300 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -4,7 +4,7 @@ CAUTION: **Warning:** This is an _alpha_ feature, and it is subject to change at any time without prior notice. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/17866) in GitLab 12.4 +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/32810) in GitLab 12.5 A project can be designated as the management project for a cluster. A management project can be used to run deployment jobs with @@ -20,14 +20,37 @@ This can be useful for: ## Permissions Only the management project will receive `cluster-admin` privileges. All -other projects will continue to receive [namespace scoped `edit` level privileges](../project/clusters/index.md#rbac-cluster-resources). +other projects will continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). + +Management projects are restricted to the following: + +- For project-level clusters, the management project must in the same + namespace (or descendants) as the cluster's project. +- For group-level clusters, the management project must in the same + group (or descendants) as as the cluster's group. +- For instance-level clusters, there are no such restrictions. ## Usage +To use a cluster management project for a cluster: + +1. Select the project. +1. Configure your pipelines. +1. Set an environment scope. + ### Selecting a cluster management project -This will be implemented as part of [this -issue](https://gitlab.com/gitlab-org/gitlab/issues/32810). +To select a cluster management project to use: + +1. Navigate to the appropriate configuration page. For a: + - [Project-level cluster](../project/clusters/index.md), navigate to your project's + **Operations > Kubernetes** page. + - [Group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** + page. +1. Select the project using **Cluster management project field** in the **Advanced settings** + section. + + ### Configuring your pipeline @@ -60,7 +83,7 @@ to a management project: | Staging | `staging` | | Production | `production` | -The the following environments set in +The following environments set in [`.gitlab-ci.yml`](../../ci/yaml/README.md) will deploy to the Development, Staging, and Production cluster respectively. @@ -86,16 +109,3 @@ configure production cluster: environment: name: production ``` - -## Disabling this feature - -This feature is enabled by default. To disable this feature, disable the -feature flag `:cluster_management_project`. - -To check if the feature flag is enabled on your GitLab instance, -please ask an administrator to execute the following in a Rails console: - -```ruby -Feature.enabled?(:cluster_management_project) # Check if it's enabled or not. -Feature.disable(:cluster_management_project) # Disable the feature flag. -``` diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 4742e7189b7..1fe456902a2 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -58,13 +58,18 @@ differentiate the new cluster from the rest. You can choose to allow GitLab to manage your cluster for you. If your cluster is managed by GitLab, resources for your projects will be automatically created. See the -[Access controls](../../project/clusters/index.md#access-controls) section for details on which resources will +[Access controls](../../project/clusters/add_remove_clusters.md#access-controls) section for details on which resources will be created. -If you choose to manage your own cluster, project-specific resources will not be created -automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will -need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](../../project/clusters/index.md#deployment-variables) -that will be used by your deployment jobs. +For clusters not managed by GitLab, project-specific resources will not be created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md) +for deployments with a cluster not managed by GitLab, you must ensure: + +- The project's deployment service account has permissions to deploy to + [`KUBE_NAMESPACE`](../../project/clusters/index.md#deployment-variables). +- `KUBECONFIG` correctly reflects any changes to `KUBE_NAMESPACE` + (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/issues/31519)). Editing + `KUBE_NAMESPACE` directly is discouraged. NOTE: **Note:** If you [install applications](#installing-applications) on your cluster, GitLab will create @@ -147,7 +152,7 @@ are deployed to the Kubernetes cluster, see the documentation for For important information about securely configuring GitLab Runners, see [Security of -Runners](../../project/clusters/index.md#security-of-gitlab-runners) +Runners](../../project/clusters/add_remove_clusters.md#security-of-gitlab-runners) documentation for project-level clusters. <!-- ## Troubleshooting diff --git a/doc/user/group/epics/img/epic_view_roadmap_v12.3.png b/doc/user/group/epics/img/epic_view_roadmap_v12.3.png Binary files differindex a17c56c618b..a17c56c618b 100755..100644 --- a/doc/user/group/epics/img/epic_view_roadmap_v12.3.png +++ b/doc/user/group/epics/img/epic_view_roadmap_v12.3.png diff --git a/doc/user/group/epics/img/epic_view_v12.3.png b/doc/user/group/epics/img/epic_view_v12.3.png Binary files differindex 79758cf3d52..79758cf3d52 100755..100644 --- a/doc/user/group/epics/img/epic_view_v12.3.png +++ b/doc/user/group/epics/img/epic_view_v12.3.png diff --git a/doc/user/group/epics/img/epics_list_view_v12.3.png b/doc/user/group/epics/img/epics_list_view_v12.3.png Binary files differdeleted file mode 100755 index c6817a503e7..00000000000 --- a/doc/user/group/epics/img/epics_list_view_v12.3.png +++ /dev/null diff --git a/doc/user/group/epics/img/epics_list_view_v12.5.png b/doc/user/group/epics/img/epics_list_view_v12.5.png Binary files differnew file mode 100644 index 00000000000..2520ee67abc --- /dev/null +++ b/doc/user/group/epics/img/epics_list_view_v12.5.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index f9690d4edfe..0753df70bc2 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -10,7 +10,7 @@ Epics let you manage your portfolio of projects more efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones. - + ## Use cases @@ -92,24 +92,44 @@ To remove a child epic from a parent epic: ## Start date and due date -To set a **Start date** and **Due date** for an epic, you can choose either of the following: +To set a **Start date** and **Due date** for an epic, select one of the following: - **Fixed**: Enter a fixed value. -- **From milestones:** Inherit a dynamic value from the issues added to the epic. +- **From milestones**: Inherit a dynamic value from the issues added to the epic. +- **Inherited**: Inherit a dynamic value from the issues added to the epic. ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7332) in GitLab 12.5 to replace **From milestones**). -If you select **From milestones** for the start date, GitLab will automatically set the -date to be earliest start date across all milestones that are currently assigned -to the issues that are added to the epic. Similarly, if you select "From milestones" -for the due date, GitLab will set it to be the latest due date across all -milestones that are currently assigned to those issues. +### Milestones -These are dynamic dates which are recalculated immediately if any of the following occur: +If you select **From milestones** for the start date, GitLab will automatically set the date to be earliest +start date across all milestones that are currently assigned to the issues that are added to the epic. +Similarly, if you select **From milestones** for the due date, GitLab will set it to be the latest due date across +all milestones that are currently assigned to those issues. + +These are dynamic dates which are recalculated if any of the following occur: - Milestones are re-assigned to the issues. - Milestone dates change. - Issues are added or removed from the epic. -## Roadmap +### Inherited + +If you select **Inherited** for the start date, GitLab will scan all child epics and issues assigned to the epic, +and will set the start date to match the earliest found start date or milestone. Similarly, if you select +**Inherited** for the due date, GitLab will set the due date to match the latest due date or milestone +found among its child epics and issues. + +These are dynamic dates and recalculated if any of the following occur: + +- A child epic's dates change. +- Milestones are reassigned to an issue. +- A milestone's dates change. +- Issues are added to, or removed from, the epic. + +Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top. +If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic, +then the parent epic's start date will reflect the change and this will propagate upwards to the top epic. + +## Roadmap in epics > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10. @@ -121,6 +141,8 @@ have a [start or due date](#start-date-and-due-date), a ## Reordering issues and child epics +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5. + New issues and child epics are added to the top of their respective lists in the **Epics and Issues** tab. You can reorder the list of issues and the list of child epics. Issues and child epics cannot be intermingled. To reorder issues assigned to an epic: @@ -267,7 +289,7 @@ Once you wrote your comment, you can either: ## Notifications -- [Receive notifications](../../../workflow/notifications.md) for epic events. +- [Receive notifications](../../profile/notifications.md) for epic events. <!-- ## Troubleshooting diff --git a/doc/user/group/index.md b/doc/user/group/index.md index c4be08c842b..5f45a462f94 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -75,7 +75,7 @@ By doing so: ## Issues and merge requests within a group Issues and merge requests are part of projects. For a given group, you can view all of the -[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, +[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) across all projects in that group, together in a single list view. ### Bulk editing issues and merge requests @@ -123,7 +123,7 @@ For more details on creating groups, watch the video [GitLab Namespaces (users, ## Add users to a group A benefit of putting multiple projects in one group is that you can -give a user to access to all projects in the group with one action. +give a user access to all projects in the group with one action. Add members to a group by navigating to the group's dashboard and clicking **Members**. @@ -135,14 +135,14 @@ Consider a group with two projects: - On the **Group Members** page, you can now add a new user to the group. - Now, because this user is a **Developer** member of the group, they automatically - gets **Developer** access to **all projects** within that group. + get **Developer** access to **all projects** within that group. To increase the access level of an existing user for a specific project, add them again as a new member to the project with the desired permission level. ## Request access to a group -As a group owner, you can enable or disable the ability for non members to request access to +As a group owner, you can enable or disable the ability for non-members to request access to your group. Go to the group settings, and click **Allow users to request access**. As a user, you can request to be a member of a group, if that setting is enabled. Go to the group for which you'd like to be a member, and click the **Request Access** button on the right @@ -353,10 +353,10 @@ content. Restriction currently applies to: - UI. -- API access. +- [From GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/issues/12874), API access. - [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/32113), Git actions via SSH. -To avoid accidental lock-out, admins and group owners are are able to access +To avoid accidental lock-out, admins and group owners are able to access the group regardless of the IP restriction. #### Allowed domain restriction **(PREMIUM)** @@ -385,7 +385,7 @@ Some domains cannot be restricted. These are the most popular public email domai To enable this feature: 1. Navigate to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section, and enter domain name into **Restrict membership by email** field. +1. Expand the **Permissions, LFS, 2FA** section, and enter the domain name into **Restrict membership by email** field. 1. Click **Save changes**. This will enable the domain-checking for all new users added to the group from this moment on. @@ -421,8 +421,9 @@ Define project templates at a group level by setting a group as the template sou #### Disabling email notifications -You can disable all email notifications related to the group, which also includes -it's subgroups and projects. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/23585) in GitLab 12.2. + +You can disable all email notifications related to the group, which includes its subgroups and projects. To enable this feature: @@ -444,7 +445,7 @@ To enable this feature: > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. -A group owner can check the aggregated storage usage for all the project in a group, sub-groups included, in the **Storage** tab of the **Usage Quotas** page available to the group page settings list. +A group owner can check the aggregated storage usage for all the projects in a group, sub-groups included, in the **Storage** tab of the **Usage Quotas** page available to the group page settings list.  diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index bcd79bd04bf..a72cd990706 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -26,7 +26,7 @@ Epics in the view can be sorted by: Each option contains a button that toggles the sort order between **ascending** and **descending**. The sort option and order will be persisted when browsing Epics, including the [epics list view](../epics/index.md). -Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap). +Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). ## Timeline duration diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index ecf2934b877..6fd56414796 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -26,6 +26,23 @@ SAML SSO for GitLab.com groups does not sync users between providers without usi  +### NameID + +GitLab.com uses the SAML NameID to identify users. The NameID element: + +- Is a required field in the SAML response. +- Must be unique to each user. +- Must be a persistent value that will never change, such as a randomly generated unique user ID. +- Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case. +- Should not be an email address or username. We strongly recommend against these as it is hard to guarantee they will never change, for example when a person's name changes. Email addresses are also case-insensitive, which can result in users being unable to sign in. + +CAUTION: **Warning:** +Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` will break the configuration and potentially lock users out of the GitLab group. + +#### NameID Format + +We recommend setting the NameID format to `Persistent` unless using a field (such as email) that requires a different format. + ### SSO enforcement SSO enforcement was: @@ -58,25 +75,16 @@ Since use of the group managed account requires the use of SSO, users of group m - The user will be unable to access the group (their credentials will no longer work on the identity provider when prompted to SSO). - Contributions in the group (e.g. issues, merge requests) will remain intact. -### NameID +#### Assertions -GitLab.com uses the SAML NameID to identify users. The NameID element: +When using Group Manged Accounts, the following user details need to be passed to GitLab as SAML Assertions in order for us to be able to create a user: -- Is a required field in the SAML response. -- Must be unique to each user. -- Must be a persistent value that will never change, such as a randomly generated unique user ID. -- Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case. - -We strongly recommend against using Email as the NameID as it is hard to guarantee it will never change, for example when a person's name changes. Similarly usernames should be avoided if possible. - -### Assertions - -| Field | Supported keys | -|-------|----------------| +| Field | Supported keys | +|-----------------|----------------| | Email (required)| `email`, `mail` | -| Full Name | `name` | -| First Name | `first_name`, `firstname`, `firstName` | -| Last Name | `last_name`, `lastname`, `lastName` | +| Full Name | `name` | +| First Name | `first_name`, `firstname`, `firstName` | +| Last Name | `last_name`, `lastname`, `lastName` | ## Metadata configuration @@ -108,17 +116,28 @@ NOTE: **Note:** GitLab is unable to provide support for IdPs that are not listed | Azure | [Configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications) | | Auth0 | [Auth0 as Identity Provider](https://auth0.com/docs/protocols/saml/saml-idp-generic) | | G Suite | [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en) | -| JumpCloud | [Single Sign On (SSO) with GitLab](https://support.jumpcloud.com/customer/en/portal/articles/2810701-single-sign-on-sso-with-gitlab) | +| JumpCloud | [Single Sign On (SSO) with GitLab](https://support.jumpcloud.com/support/s/article/single-sign-on-sso-with-gitlab-2019-08-21-10-36-47) | | Okta | [Setting up a SAML application in Okta](https://developer.okta.com/docs/guides/saml-application-setup/overview/) | | OneLogin | [Use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) | | Ping Identity | [Add and configure a new SAML application](https://support.pingidentity.com/s/document-item?bundleId=pingone&topicId=xsh1564020480660-1.html) | When [configuring your identify provider](#configuring-your-identity-provider), please consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. +### Okta setup notes + +| GitLab Setting | Okta Field | +|--------------|----------------| +| Identifier | Audience URI | +| Assertion consumer service URL | Single sign on URL | + +Under Okta's **Single sign on URL** field, check the option **Use this for Recipient URL and Destination URL**. + +Set attribute statements according to the [assertions table](#assertions). + ### OneLogin setup notes -NOTE: **Note:** -The GitLab app listed in the directory is for self-managed GitLab instances. Please use a generic SAML Test Connector. +The GitLab app listed in the OneLogin app catalog is for self-managed GitLab instances. +For GitLab.com, use a generic SAML Test Connector such as the SAML Test Connector (Advanced). | GitLab Setting | OneLogin Field | |--------------|----------------| diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 60b779b3f70..392b27bb42f 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -25,25 +25,6 @@ The following identity providers are supported: ## Requirements - [Group SSO](index.md) needs to be configured. -- The `scim_group` feature flag must be enabled: - - Run the following commands in a Rails console: - - ```sh - # Omnibus GitLab - gitlab-rails console - - # Installation from source - cd /home/git/gitlab - sudo -u git -H bin/rails console RAILS_ENV=production - ``` - - To enable SCIM for a group named `group_name`: - - ```ruby - group = Group.find_by_full_path('group_name') - Feature.enable(:group_scim, group) - ``` ## GitLab configuration @@ -85,8 +66,13 @@ You can then test the connection by clicking on **Test Connection**. If the conn 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. Determine how GitLab will uniquely identify users. + + - Use `objectId` unless users already have SAML linked for your group. + - If you already have users with SAML linked then use the `Name ID` value from the [SAML configuration](#azure). Using a different value will likely cause duplicate users and prevent users from accessing the GitLab group. + +1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to the unique identifier determined above, **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 the unique identifier determined above, and **Target attribute** to `externalId`. 1. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`. Save your changes and you should have the following configuration: @@ -118,6 +104,9 @@ You can then test the connection by clicking on **Test Connection**. If the conn 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. +CAUTION: **Warning:** +Once synchronized, changing the field mapped to `id` and `externalId` will likely cause provisioning errors, duplicate users, and prevent existing users from accessing the GitLab group. + ## Troubleshooting ### Testing Azure connection: invalid credentials diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index a3606fadb89..52b7035389a 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -176,7 +176,7 @@ Here's a list of what you can't do with subgroups: - [GitLab Pages](../../project/pages/index.md) supports projects hosted under a subgroup, but not subgroup websites. That means that only the highest-level group supports - [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-domain-names), + [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names), although you can have project websites under a subgroup. - It is not possible to share a project with a group that's an ancestor of the group the project is in. That means you can only share as you walk down diff --git a/doc/user/img/todos_add_todo_sidebar.png b/doc/user/img/todos_add_todo_sidebar.png Binary files differnew file mode 100644 index 00000000000..aefec7a2d9c --- /dev/null +++ b/doc/user/img/todos_add_todo_sidebar.png diff --git a/doc/user/img/todos_icon.png b/doc/user/img/todos_icon.png Binary files differnew file mode 100644 index 00000000000..9fee4337a75 --- /dev/null +++ b/doc/user/img/todos_icon.png diff --git a/doc/user/img/todos_index.png b/doc/user/img/todos_index.png Binary files differnew file mode 100644 index 00000000000..99c1575d157 --- /dev/null +++ b/doc/user/img/todos_index.png diff --git a/doc/user/img/todos_mark_done_sidebar.png b/doc/user/img/todos_mark_done_sidebar.png Binary files differnew file mode 100644 index 00000000000..2badd880b40 --- /dev/null +++ b/doc/user/img/todos_mark_done_sidebar.png diff --git a/doc/user/img/todos_todo_list_item.png b/doc/user/img/todos_todo_list_item.png Binary files differnew file mode 100644 index 00000000000..91bbf9e5373 --- /dev/null +++ b/doc/user/img/todos_todo_list_item.png diff --git a/doc/user/incident_management/img/incident_management_settings.png b/doc/user/incident_management/img/incident_management_settings.png Binary files differnew file mode 100644 index 00000000000..25ad4fd08b7 --- /dev/null +++ b/doc/user/incident_management/img/incident_management_settings.png diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md new file mode 100644 index 00000000000..5ac27d227a1 --- /dev/null +++ b/doc/user/incident_management/index.md @@ -0,0 +1,131 @@ +--- +description: "GitLab - Incident Management. GitLab offers solutions for handling incidents in your applications and services" +--- + +# Incident Management + +GitLab offers solutions for handling incidents in your applications and services, +from setting up an alert with Prometheus, to receiving a notification via a +monitoring tool like Slack, and automatically setting up Zoom calls with your +support team. + +## Configuring incidents **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in GitLab Ultimate 11.11. + +The Incident Management features can be enabled and disabled via your project's +**Settings > Operations > Incidents**. + + + +### Automatically create issues from alerts + +GitLab issues can automatically be created as a result of an alert notification. +An issue created this way will contain the error information to help you further +debug it. + +### Issue templates + +You can create your own [issue templates](../project/description_templates.md#creating-issue-templates) +that can be [used within Incident Management](../project/integrations/prometheus.md#taking-action-on-incidents-ultimate). + +To select your issue template for use within Incident Management: + +1. Visit your project's **Settings > Operations > Incidents**. +1. Select the template from the **Issue Template** dropdown. + +## Alerting + +GitLab can react to the alerts that your applications and services may be +triggering by automatically creating issues, and alerting developers via email. + +### Prometheus alerts + +Prometheus alerts can be set up in both: + +- [GitLab-managed Prometheus](../project/integrations/prometheus.md#setting-up-alerts-for-prometheus-metrics-ultimate) and +- [Self-managed Prometheus](../project/integrations/prometheus.md#external-prometheus-instances) installations. + +### Alert endpoint + +GitLab can accept alerts from any source via a generic webhook receiver. When +you set up the generic alerts integration, a unique endpoint will +be created which can receive a payload in JSON format. + +[Read more on setting this up, including how to customize the payload](../project/integrations/generic_alerts.md). + +### Recovery alerts + +GitLab can [automatically close issues](../project/integrations/prometheus.md#taking-action-on-incidents-ultimate) +that have been automatically created when you receive notification that the +alert is resolved. + +## Embedded metrics + +Metrics can be embedded anywhere where GitLab Markdown is used, for example, +descriptions and comments on issues and merge requests. + +TIP: **Tip:** +Both GitLab-hosted and Grafana metrics can also be +[embedded in issue templates](../project/integrations/prometheus.md#embedding-metrics-in-issue-templates). + +### GitLab-hosted metrics + +Learn how to embed [GitLab hosted metric charts](../project/integrations/prometheus.md#embedding-metric-charts-within-gitlab-flavored-markdown). + +### Grafana metrics + +Learn how to embed [Grafana hosted metric charts](../project/integrations/prometheus.md#embedding-grafana-charts). + +## Slack integration + +Slack slash commands allow you to control GitLab and view content right inside +Slack, without having to leave it. + +Learn how to [set up Slack slash commands](../project/integrations/slack_slash_commands.md) +and how to [use them](../../integration/slash_commands.md). + +### Slash commands + +Please refer to a list of [available slash commands](../../integration/slash_commands.md) and associated descriptions. + +## Zoom in issues + +In order to communicate synchronously for incidents management, GitLab allows to +associate a Zoom meeting with an issue. Once you start a Zoom call for a fire-fight, +you need a way to associate the conference call with an issue, so that your team +members can join swiftly without requesting a link. + +Read more how to [add or remove a zoom meeting](../project/issues/associate_zoom_meeting.md). + +### Alerting + +You can let GitLab know of alerts that may be triggering in your applications and services. GitLab can react to these by automatically creating Issues, and alerting developers via Email. + +#### Prometheus Alerts + +Prometheus alerts can be setup in both GitLab-managed Prometheus installs and self-managed Prometheus installs. + +Documentation for each method can be found here: + +- [GitLab-managed Prometheus](../project/integrations/prometheus.md#setting-up-alerts-for-prometheus-metrics-ultimate) +- [Self-managed Prometheus](../project/integrations/prometheus.md#external-prometheus-instances) + +#### Alert Endpoint + +GitLab can accept alerts from any source via a generic webhook receiver. When you set up the generic alerts integration, a unique endpoint will +be created which can receive a payload in JSON format. + +More information on setting this up, including how to customize the payload [can be found here](../project/integrations/generic_alerts.md). + +#### Recovery Alerts + +Coming soon: GitLab can automatically close Issues that have been automatically created when we receive notification that the alert is resolved. + +### Configuring Incidents + +Incident Management features can be easily enabled & disabled via the Project settings page. Head to Project -> Settings -> Operations -> Incidents. + +#### Auto-creation + +GitLab Issues can automatically be created as a result of an Alert notification. An Issue created this way will contain error information to help you further debug the error. diff --git a/doc/user/index.md b/doc/user/index.md index ee5d4a0a07b..ab953b6d8bf 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -50,15 +50,15 @@ GitLab is a Git-based platform that integrates a great number of essential tools With GitLab Enterprise Edition, you can also: - Provide support with [Service Desk](project/service_desk.md). -- Improve collaboration with - [Merge Request Approvals](project/merge_requests/index.md#merge-request-approvals-starter), - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md), - and [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). +- Improve collaboration with: + - [Merge Request Approvals](project/merge_requests/merge_request_approvals.md). **(STARTER)** + - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). **(STARTER)** + - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [Related Issues](project/issues/related_issues.md). - Use [Burndown Charts](project/milestones/burndown_charts.md) to track progress during a sprint or while working on a new version of their software. - Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Global Search](search/advanced_global_search.md) and [Advanced Syntax Search](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance. - [Authenticate users with Kerberos](../integration/kerberos.md). -- [Mirror a repository](../workflow/repository_mirroring.md) from elsewhere on your local server. +- [Mirror a repository](project/repository/repository_mirroring.md) from elsewhere on your local server. - [Export issues as CSV](project/issues/csv_export.md). - View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](../ci/multi_project_pipeline_graphs.md). - [Lock files](project/file_lock.md) to prevent conflicts. @@ -130,12 +130,12 @@ gather feedback through [resolvable threads](discussions/index.md#resolvable-com Read through the [GFM documentation](markdown.md) to learn how to apply the best of GitLab Flavored Markdown in your threads, comments, -issues and merge requests descriptions, and everywhere else GMF is +issues and merge requests descriptions, and everywhere else GFM is supported. ## Todos -Never forget to reply to your collaborators. [GitLab Todos](../workflow/todos.md) +Never forget to reply to your collaborators. [GitLab Todos](todos.md) are a tool for working faster and more effectively with your team, by listing all user or group mentions, as well as issues and merge requests you're assigned to. @@ -150,6 +150,11 @@ requests you're assigned to. you have quick access to. You can also gather feedback on them through [Discussions](#Discussions). +## Keyboard shortcuts + +There are many [keyboard shortcuts](shortcuts.md) in GitLab to help you navigate between +pages and accomplish tasks faster. + ## Integrations [Integrate GitLab](../integration/README.md) with your preferred tool, diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 0b4bb43b4bf..3bd0dcafc19 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -405,6 +405,7 @@ GFM will recognize the following: | label by ID | `~123` | `namespace/project~123` | `project~123` | | one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | | multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | | project milestone by ID | `%123` | `namespace/project%123` | `project%123` | | one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | | multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | @@ -417,9 +418,10 @@ GFM will recognize the following: > If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). -You can add task lists anywhere markdown is supported, but you can only "click" to -toggle the boxes if they are in issues, merge requests, or comments. In other places -you must edit the markdown manually to change the status by adding or removing the `x`. +You can add task lists anywhere Markdown is supported, but you can only "click" +to toggle the boxes if they are in issues, merge requests, or comments. In other +places you must edit the Markdown manually to change the status by adding or +removing an `x` within the square brackets. To create a task list, add a specially-formatted Markdown list. You can use either unordered or ordered lists: diff --git a/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png b/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png Binary files differdeleted file mode 100644 index d4db5e88672..00000000000 --- a/doc/user/operations_dashboard/img/index_operations_dashboard_top_bar_icon.png +++ /dev/null diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 649a95a5f3a..cdb80cca6f7 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -5,10 +5,7 @@ The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. -The dashboard can be accessed via the top bar, by clicking on the new -dashboard icon: - - +The dashboard can be accessed via the top bar, by clicking **More > Operations**. ## Adding a project to the dashboard @@ -28,6 +25,10 @@ last commit, pipeline status, and when it was last deployed.  +## Arranging projects on a dashboard + +You can drag project cards to change their order. The card order is currently only saved to your browser, so will not change the dashboard for other people. + ## Making it the default dashboard when you sign in The Operations Dashboard can also be made the default GitLab dashboard shown when diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index f81756f7979..953c7472f4d 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -1,6 +1,6 @@ # GitLab Conan Repository **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. With the GitLab Conan Repository, every project can have its own space to store Conan packages. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index d6358d72348..60f4dbc0abb 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -1,4 +1,4 @@ -# Dependency Proxy **(PREMIUM)** +# Dependency Proxy **(PREMIUM ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 5f5d86ab17e..d8b59ae63d0 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -42,6 +42,9 @@ it is not possible due to a naming collision. For example: | `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes | | `gitlab-org/gitlab` | `@foo/bar` | No | +CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:** +If you update the root namespace of a project with NPM packages, your changes will be rejected. To be allowed to do that, make sure to remove any NPM package first. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. + Now, you can configure your project to authenticate with the GitLab NPM Registry. @@ -105,6 +108,21 @@ Then, you could run `npm publish` either locally or via GitLab CI/CD: - **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) under your project's **Settings > CI/CD > Variables**. + +### Authenticating with a CI job token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9104) in GitLab Premium 12.5. + +If you’re using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token. +The token will inherit the permissions of the user that generates the pipeline. + +Add a corresponding section to your `.npmrc` file: + +```ini +@foo:registry=https://gitlab.com/api/v4/packages/npm/ +//gitlab.com/api/v4/packages/npm/:_authToken=${env.CI_JOB_TOKEN} +//gitlab.com/api/v4/projects/{env.CI_PROJECT_ID>/packages/npm/:_authToken=${env.CI_JOB_TOKEN} +``` ## Uploading packages diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 90874eca2eb..70660e5e22f 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -51,11 +51,11 @@ The following table depicts the various user permission levels in a project. | View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | View Dependency list **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View licenses in Dependency list **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View [Design Management](project/issues/design_management.md) pages **(PREMIUM)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View [Design Management](project/issues/design_management.md) pages **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control-core) | ✓ | ✓ | ✓ | ✓ | ✓ | -| View wiki pages | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| View wiki pages | ✓ | ✓ | ✓ | ✓ | ✓ | | See a list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | See a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | @@ -83,7 +83,7 @@ The following table depicts the various user permission levels in a project. | Push to non-protected branches | | | ✓ | ✓ | ✓ | | Force push to non-protected branches | | | ✓ | ✓ | ✓ | | Remove non-protected branches | | | ✓ | ✓ | ✓ | -| Create new merge request | | | ✓ | ✓ | ✓ | +| Create new merge request | | ✓ | ✓ | ✓ | ✓ | | Assign merge requests | | | ✓ | ✓ | ✓ | | Label merge requests | | | ✓ | ✓ | ✓ | | Lock merge request threads | | | ✓ | ✓ | ✓ | @@ -103,6 +103,7 @@ The following table depicts the various user permission levels in a project. | Apply code change suggestions | | | ✓ | ✓ | ✓ | | Create and edit wiki pages | | | ✓ | ✓ | ✓ | | Rewrite/remove Git tags | | | ✓ | ✓ | ✓ | +| Manage Feature Flags **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | | Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | @@ -120,6 +121,7 @@ The following table depicts the various user permission levels in a project. | Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | | Remove GitLab Pages | | | | ✓ | ✓ | | Manage clusters | | | | ✓ | ✓ | +| View Pods logs **(ULTIMATE)** | | | | ✓ | ✓ | | Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | | Manage Error Tracking | | | | ✓ | ✓ | @@ -168,7 +170,7 @@ the [documentation on Cycle Analytics permissions](analytics/cycle_analytics.md# Developers and users with higher permission level can use all the functionality of the Issue Board, that is create/delete lists -and drag issues around. Read though the +and drag issues around. Read through the [documentation on Issue Boards permissions](project/issue_board.md#permissions) to learn more. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index be761ca7558..beea063672e 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -32,63 +32,6 @@ As an administrator, you can delete a user account by: - **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**. - -### Deactivating a user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/63921) in GitLab 12.4. - -A user can be deactivated from the Admin area. Deactivating a user is functionally identical to blocking a user, with the following differences: - -- It does not prohibit the user from logging back in via the UI. -- Once a deactivated user logs back into the GitLab UI, their account is set to active. - -A deactivated user: - -- Cannot access Git repositories or the API. -- Will not receive any notifications from GitLab. -- Will not be able to use [slash commands](../../../integration/slash_commands.md). - -Personal projects, group and user history of the deactivated user will be left intact. - -NOTE: **Note:** -A deactivated user does not consume a [seat](../../../subscriptions/index.md#managing-subscriptions). - -To do this: - -1. Navigate to **Admin Area > Overview > Users**. -1. Select a user. -1. Under the **Account** tab, click **Deactivate user**. - -Please note that for the deactivation option to be visible to an admin, the user: - -- Must be currently active. -- Should not have any activity in the last 180 days. - -### Activating a user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/63921) in GitLab 12.4. - -A deactivated user can be activated from the Admin area. Activating a user sets their account to active state. - -To do this: - -1. Navigate to **Admin Area > Overview > Users**. -1. Click on the **Deactivated** tab. -1. Select a user. -1. Under the **Account** tab, click **Activate user**. - -TIP: **Tip:** -A deactivated user can also activate their account by themselves by simply logging back via the UI. - ## Associated Records > - Introduced for issues in diff --git a/doc/user/profile/img/notification_global_settings.png b/doc/user/profile/img/notification_global_settings.png Binary files differnew file mode 100644 index 00000000000..699f726c442 --- /dev/null +++ b/doc/user/profile/img/notification_global_settings.png diff --git a/doc/user/profile/img/notification_group_settings.png b/doc/user/profile/img/notification_group_settings.png Binary files differnew file mode 100644 index 00000000000..ed5e9459216 --- /dev/null +++ b/doc/user/profile/img/notification_group_settings.png diff --git a/doc/user/profile/img/notification_project_settings.png b/doc/user/profile/img/notification_project_settings.png Binary files differnew file mode 100644 index 00000000000..e2db2037d94 --- /dev/null +++ b/doc/user/profile/img/notification_project_settings.png diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 9c4001f0a79..06e4eac6623 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -53,7 +53,7 @@ From there, you can: [use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth) - Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications - Add and delete emails linked to your account -- Choose which email to use for notifications, web-based commits, and display on your public profile +- Choose which email to use for [notifications](notifications.md), web-based commits, and display on your public profile - Manage [SSH keys](../../ssh/README.md) to access your account via SSH - Manage your [preferences](preferences.md#syntax-highlighting-theme) to customize your own GitLab experience diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md new file mode 100644 index 00000000000..388576a48db --- /dev/null +++ b/doc/user/profile/notifications.md @@ -0,0 +1,231 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/notifications.html' +--- + +# GitLab Notification Emails + +GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications enabled, you can receive updates about activity in issues, merge requests, and epics. Notifications are sent via email. + +## Receiving notifications + +You will receive notifications for one of the following reasons: + +- You participate in an issue, merge request, or epic. In this context, _participate_ means comment, or edit. +- You enable notifications in an issue, merge request, or epic. To enable notifications, click the **Notifications** toggle in the sidebar to _on_. + +While notifications are enabled, you will receive notification of actions occurring in that issue, merge request, or epic. + +NOTE: **Note:** +Notifications can be blocked by an admin, preventing them from being sent. + +## Tuning your notifications + +The quantity of notifications can be overwhelming. GitLab allows you to tune the notifications you receive. For example, you may want to be notified about all activity in a specific project, but for others, only be notified when you are mentioned by name. + +You can tune the notifications you receive by combining your notification settings: + +- [Global notification settings](#global-notification-settings) +- [Notification scope](#notification-scope) +- [Notification levels](#notification-levels) + +### Editing notification settings + +To edit your notification settings: + +1. Click on your profile picture and select **Settings**. +1. Click **Notifications** in the left sidebar. +1. Edit the desired notification settings. Edited settings are automatically saved and enabled. + +These notification settings apply only to you. They do not affect the notifications received by anyone else in the same project or group. + + + +## Global notification settings + +Your **Global notification settings** are the default settings unless you select different values for a project or a group. + +- Notification email + - This is the email address your notifications will be sent to. +- Global notification level + - This is the default [notification level](#notification-levels) which applies to all your notifications. +- Receive notifications about your own activity. + - Check this checkbox if you want to receive notification about your own activity. Default: Not checked. + +### Notification scope + +You can tune the scope of your notifications by selecting different notification levels for each project and group. + +Notification scope is applied in order of precedence (highest to lowest): + +- Project + - For each project, you can select a notification level. Your project setting overrides the group setting. +- Group + - For each group, you can select a notification level. Your group setting overrides your default setting. +- Global (default) + - Your global, or _default_, notification level applies if you have not selected a notification level for the project or group in which the activity occurred. + +#### Project notifications + +You can select a notification level for each project. This can be useful if you need to closely monitor activity in select projects. + + + +To select a notification level for a project, use either of these methods: + +1. Click on your profile picture and select **Settings**. +1. Click **Notifications** in the left sidebar. +1. Locate the project in the **Projects** section. +1. Select the desired [notification level](#notification-levels). + +Or: + +1. Navigate to the project's page. +1. Click the notification dropdown, marked with a bell icon. +1. Select the desired [notification level](#notification-levels). + +#### Group notifications + +You can select a notification level and email address for each group. + + + +##### Group notification level + +To select a notification level for a group, use either of these methods: + +1. Click on your profile picture and select **Settings**. +1. Click **Notifications** in the left sidebar. +1. Locate the project in the **Groups** section. +1. Select the desired [notification level](#notification-levels). + +--- + +1. Navigate to the group's page. +1. Click the notification dropdown, marked with a bell icon. +1. Select the desired [notification level](#notification-levels). + +##### Group notification email address + +> Introduced in GitLab 12.0 + +You can select an email address to receive notifications for each group you belong to. This could be useful, for example, if you work freelance, and want to keep email about clients' projects separate. + +1. Click on your profile picture and select **Settings**. +1. Click **Notifications** in the left sidebar. +1. Locate the project in the **Groups** section. +1. Select the desired email address. + +### Notification levels + +For each project and group you can select one of the following levels: + +| Level | Description | +|:------------|:------------| +| Global | Your global settings apply. | +| Watch | Receive notifications for any activity. | +| On mention | Receive notifications when `@mentioned` in comments. | +| Participate | Receive notifications for threads you have participated in. | +| Disabled | Turns off notifications. | +| Custom | Receive notifications for custom selected events. | + +## Notification events + +Users will be notified of the following events: + +| Event | Sent to | Settings level | +|------------------------------|---------------------|------------------------------| +| New SSH key added | User | Security email, always sent. | +| New email added | User | Security email, always sent. | +| Email changed | User | Security email, always sent. | +| Password changed | User | Security email, always sent. | +| New user created | User | Sent on user creation, except for OmniAuth (LDAP)| +| User added to project | User | Sent when user is added to project | +| Project access level changed | User | Sent when user project access level is changed | +| User added to group | User | Sent when user is added to group | +| Group access level changed | User | Sent when user group access level is changed | +| Project moved | Project members (1) | (1) not disabled | +| New release | Project members | Custom notification | + +## Issue / Epics / Merge request events + +In most of the below cases, the notification will be sent to: + +- Participants: + - the author and assignee of the issue/merge request + - authors of comments on the issue/merge request + - anyone mentioned by `@username` in the title or description of the issue, merge request or epic **(ULTIMATE)** + - anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic **(ULTIMATE)** +- Watchers: users with notification level "Watch" +- Subscribers: anyone who manually subscribed to the issue, merge request, or epic **(ULTIMATE)** +- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below + +| Event | Sent to | +|------------------------|---------| +| New issue | | +| Close issue | | +| Reassign issue | The above, plus the old assignee | +| Reopen issue | | +| Due issue | Participants and Custom notification level with this event selected | +| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Remove milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | +| New merge request | | +| Push to merge request | Participants and Custom notification level with this event selected | +| Reassign merge request | The above, plus the old assignee | +| Close merge request | | +| Reopen merge request | | +| Merge merge request | | +| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Remove milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | +| Failed pipeline | The author of the pipeline | +| Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set | +| New epic **(ULTIMATE)** | | +| Close epic **(ULTIMATE)** | | +| Reopen epic **(ULTIMATE)** | | + +In addition, if the title or description of an Issue or Merge Request is +changed, notifications will be sent to any **new** mentions by `@username` as +if they had been mentioned in the original text. + +You won't receive notifications for Issues, Merge Requests or Milestones created +by yourself (except when an issue is due). You will only receive automatic +notifications when somebody else comments or adds changes to the ones that +you've created or mentions you. + +If an open merge request becomes unmergeable due to conflict, its author will be notified about the cause. +If a user has also set the merge request to automatically merge once pipeline succeeds, +then that user will also be notified. + +## Email Headers + +Notification emails include headers that provide extra content about the notification received: + +| Header | Description | +|-----------------------------|-------------------------------------------------------------------------| +| X-GitLab-Project | The name of the project the notification belongs to | +| X-GitLab-Project-Id | The ID of the project | +| X-GitLab-Project-Path | The path of the project | +| X-GitLab-(Resource)-ID | The ID of the resource the notification is for, where resource is `Issue`, `MergeRequest`, `Commit`, etc| +| X-GitLab-Discussion-ID | Only in comment emails, the ID of the thread the comment is from | +| X-GitLab-Pipeline-Id | Only in pipeline emails, the ID of the pipeline the notification is for | +| X-GitLab-Reply-Key | A unique token to support reply by email | +| X-GitLab-NotificationReason | The reason for being notified. "mentioned", "assigned", etc | +| List-Id | The path of the project in a RFC 2919 mailing list identifier useful for email organization, for example, with Gmail filters | + +### X-GitLab-NotificationReason + +This header holds the reason for the notification to have been sent out, +where reason can be `mentioned`, `assigned`, `own_activity`, etc. +Only one reason is sent out according to its priority: + +- `own_activity` +- `assigned` +- `mentioned` + +The reason in this header will also be shown in the footer of the notification email. For example an email with the +reason `assigned` will have this sentence in the footer: +`"You are receiving this email because you have been assigned an item on {configured GitLab hostname}"` + +NOTE: **Note:** +Only reasons listed above have been implemented so far. +Further implementation is [being discussed](https://gitlab.com/gitlab-org/gitlab/issues/20689). diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 82a6d2b3703..b299c74c8f4 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -82,7 +82,7 @@ You have 8 options here that you can use for your default dashboard view: - Your projects' activity - Starred projects' activity - Your groups -- Your [Todos](../../workflow/todos.md) +- Your [Todos](../todos.md) - Assigned Issues - Assigned Merge Requests - Operations Dashboard **(PREMIUM)** @@ -128,6 +128,19 @@ You can choose one of the following options as the first day of the week: If you select **System Default**, the system-wide default setting will be used. +## Integrations + +Configure your preferences with third-party services which provide enhancements to your GitLab experience. + +### Sourcegraph + +NOTE: **Note:** +This setting is only visible if Sourcegraph has been enabled by a GitLab administrator. + +Manage the availability of integrated code intelligence features powered by +Sourcegraph. View [the Sourcegraph feature documentation](../../integration/sourcegraph.md#enable-sourcegraph-in-user-preferences) +for more information. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md new file mode 100644 index 00000000000..150a451dfe5 --- /dev/null +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -0,0 +1,730 @@ +# Adding and removing Kubernetes clusters + +GitLab can integrate with the following Kubernetes providers: + +- Google Kubernetes Engine (GKE). +- Amazon Elastic Kubernetes Service (EKS). + +TIP: **Tip:** +Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial), +and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's +Google Kubernetes Engine Integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit. + +## Access controls + +When creating a cluster in GitLab, you will be asked if you would like to create either: + +- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) cluster. +- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. + +NOTE: **Note:** +[RBAC](#rbac-cluster-resources) is recommended and the GitLab default. + +GitLab creates the necessary service accounts and privileges to install and run +[GitLab managed applications](index.md#installing-applications). When GitLab creates the cluster, +a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace +to manage the newly created cluster. + +NOTE: **Note:** +Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/51716) in GitLab 11.5. + +When you install Helm into your cluster, the `tiller` service account +is created with `cluster-admin` privileges in the `gitlab-managed-apps` +namespace. + +This service account will be: + +- Added to the installed Helm Tiller +- Used by Helm to install and run [GitLab managed applications](index.md#installing-applications). + +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](add_remove_clusters.md#add-existing-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. + +### Important notes + +Note the following about access controls: + +- Environment-specific resources are only created if your cluster is + [managed by GitLab](index.md#gitlab-managed-clusters). +- If your cluster was created before GitLab 12.2, it will use a single namespace for all project + environments. + +### RBAC cluster resources + +GitLab creates the following resources for RBAC clusters. + +| Name | Type | Details | Created when | +|:----------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:-----------------------| +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new cluster | +| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | +| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | +| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | +| Environment namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | + +### ABAC cluster resources + +GitLab creates the following resources for ABAC clusters. + +| Name | Type | Details | Created when | +|:----------------------|:---------------------|:-------------------------------------|:---------------------------| +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | +| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | +| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | + +### 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](../../../topics/autodevops/index.md) +jobs. This implies the containers are running in privileged mode and you should, +therefore, be aware of some important details. + +The privileged flag gives all capabilities to the running container, which in +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, 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](index.md#installing-applications). + 1. Installing a Runner + [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). + +## Add new cluster + +### GKE cluster + +GitLab supports: + +- Creating a new GKE cluster using the GitLab UI. +- Providing credentials to add an [existing Kubernetes cluster](#add-existing-cluster). + +Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/25925), all the GKE clusters provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). + +NOTE: **Note:** +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. + +#### GKE Requirements + +Before creating your first cluster on Google Kubernetes Engine with GitLab's +integration, make sure the following requirements are met: + +- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) + is set up and you have permissions to access it. +- 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). + +Also note the following: + +- Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/issues/55902), all GKE clusters + created by GitLab are RBAC-enabled. Take a look at the [RBAC section](#rbac-cluster-resources) for + more information. +- Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/merge_requests/18341), the + cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR + notation. + +NOTE: **Note:** +GitLab requires basic authentication enabled and a client certificate issued for the cluster in +order to setup an [initial service account](#access-controls). Starting from [GitLab +11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster creation process will +explicitly request that basic authentication and client certificate is enabled. + +#### Creating the cluster on GKE + +If all of the above requirements are met, you can proceed to create and add a +new Kubernetes cluster to your project: + +1. Navigate to your project's **Operations > Kubernetes** page. + + NOTE: **Note:** + You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. + +1. Click **Add Kubernetes cluster**. +1. Click **Create with Google Kubernetes Engine**. +1. Connect your Google account if you haven't done already by clicking the + **Sign in with Google** button. +1. Choose your cluster's settings: + - **Kubernetes cluster name** - The name you wish to give the cluster. + - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **Google Cloud Platform project** - Choose the project you created in your GCP + console that will host the Kubernetes cluster. Learn more about + [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) + under which the cluster will be created. + - **Number of nodes** - Enter the number of nodes you wish the cluster to have. + - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) + of the Virtual Machine instance that the cluster will be based on. + - **Enable Cloud Run on GKE (beta)** - Check this if you want to use Cloud Run on GKE for this cluster. + See the [Cloud Run on GKE section](#cloud-run-on-gke) for more information. + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. + See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. +1. Finally, click the **Create Kubernetes cluster** button. + +After a couple of minutes, your cluster will be ready to go. You can now proceed +to install some [pre-defined applications](index.md#installing-applications). + +#### Cloud Run on GKE + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16566) in GitLab 12.4. + +You can choose to use Cloud Run on GKE in place of installing Knative and Istio +separately after the cluster has been created. This means that Cloud Run +(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at +create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. + +### EKS Cluster + +GitLab supports: + +- Creating a new EKS cluster using the GitLab UI + ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5). +- Providing credentials to add an [existing Kubernetes cluster](#add-existing-cluster). + +#### EKS Requirements + +Before creating your first cluster on Amazon EKS with GitLab's integration, +make sure the following requirements are met: + +- An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in. +- You have permissions to manage IAM resources. + +##### Additional requirements for self-managed instances + +If you are using a self-managed GitLab instance, GitLab must first +be configured with a set of Amazon credentials. These credentials +will be used to assume an Amazon IAM role provided by the user +creating the cluster. Create an IAM user and ensure it has permissions +to assume the role(s) that your users will use to create EKS clusters. + +For example, the following policy document allows assuming a role whose name starts with +`gitlab-eks-` in account `123456789012`: + +```json +{ + "Version": "2012-10-17", + "Statement": { + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "arn:aws:iam::123456789012:role/gitlab-eks-*" + } +} +``` + +Generate an access key for the IAM user, and configure GitLab with the credentials: + +1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section. +1. Check **Enable Amazon EKS integration**. +1. Enter the account ID and access key credentials into the respective + `Account ID`, `Access key ID` and `Secret access key` fields. +1. Click **Save changes**. + +#### Creating the cluster on EKS + +If all of the above requirements are met, you can proceed to create and add a +new Kubernetes cluster to your project: + +1. Navigate to your project's **Operations > Kubernetes** page. + + NOTE: **Note:** + You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. + +1. Click **Add Kubernetes cluster**. +1. Click **Amazon EKS**. You will be provided with an `Account ID` and `External ID` to use in the next step. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: + 1. From the left panel, select **Roles**. + 1. Click **Create role**. + 1. Under `Select type of trusted entity`, select **Another AWS account**. + 1. Enter the Account ID from GitLab into the `Account ID` field. + 1. Check **Require external ID**. + 1. Enter the External ID from GitLab into the `External ID` field. + 1. Click **Next: Permissions**. + 1. Click **Create Policy**, which will open a new window. + 1. Select the **JSON** tab, and paste in the following snippet in place of the existing content: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "autoscaling:CreateAutoScalingGroup", + "autoscaling:DescribeAutoScalingGroups", + "autoscaling:DescribeScalingActivities", + "autoscaling:UpdateAutoScalingGroup", + "autoscaling:CreateLaunchConfiguration", + "autoscaling:DescribeLaunchConfigurations", + "cloudformation:CreateStack", + "cloudformation:DescribeStacks", + "ec2:AuthorizeSecurityGroupEgress", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:RevokeSecurityGroupEgress", + "ec2:RevokeSecurityGroupIngress", + "ec2:CreateSecurityGroup", + "ec2:createTags", + "ec2:DescribeImages", + "ec2:DescribeKeyPairs", + "ec2:DescribeRegions", + "ec2:DescribeSecurityGroups", + "ec2:DescribeSubnets", + "ec2:DescribeVpcs", + "eks:CreateCluster", + "eks:DescribeCluster", + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:CreateRole", + "iam:CreateInstanceProfile", + "iam:GetRole", + "iam:ListRoles", + "iam:PassRole", + "ssm:GetParameters" + ], + "Resource": "*" + } + ] + } + ``` + + NOTE: **Note:** + These permissions give GitLab the ability to create resources, but not delete them. + This means that if an error is encountered during the creation process, changes will + not be rolled back and you must remove resources manually. You can do this by deleting + the relevant [CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html) + + 1. Click **Review policy**. + 1. Enter a suitable name for this policy, and click **Create Policy**. You can now close this window. + 1. Switch back to the "Create role" window, and select the policy you just created. + 1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. + 1. Click **Next: Review**. + 1. Enter a role name and optional description into the fields provided. + 1. Click **Create role**, the new role name will appear at the top. Click on its name and copy the `Role ARN` from the newly created role. +1. In GitLab, enter the copied role ARN into the `Role ARN` field. +1. Click **Authenticate with AWS**. +1. Choose your cluster's settings: + - **Kubernetes cluster name** - The name you wish to give the cluster. + - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **Kubernetes version** - The Kubernetes version to use. Currently the only version supported is 1.14. + - **Role name** - Select the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) + to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. + - **Region** - The [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) + in which the cluster will be created. + - **Key pair name** - Select the [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) + that you can use to connect to your worker nodes if required. + - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) + to use for your EKS Cluster resources. + - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) + in your VPC where your worker nodes will run. + - **Security group** - Choose the [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) + to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. + - **Instance type** - The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. + - **Node count** - The number of worker nodes. + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. + See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. +1. Finally, click the **Create Kubernetes cluster** button. + +After about 10 minutes, your cluster will be ready to go. You can now proceed +to install some [pre-defined applications](index.md#installing-applications). + +## Add existing cluster + +If you have either of the following types of clusters already, you can add them to a project: + +- [Google Kubernetes Engine cluster](#add-existing-gke-cluster). +- [Amazon Elastic Kubernetes Service](#add-existing-eks-cluster). + +NOTE: **Note:** +Kubernetes integration is not supported for arm64 clusters. See the issue +[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details. + +### Add existing GKE 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](../../permissions.md) and above to access the Kubernetes page. + +1. Click **Add Kubernetes cluster**. +1. Click **Add an existing Kubernetes cluster** and fill in the details: + - **Kubernetes cluster name** (required) - The name you wish to give the cluster. + - **Environment scope** (required) - The + [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **API URL** (required) - + It's the URL that GitLab uses to access the Kubernetes API. Kubernetes + exposes several APIs, we want the "base" URL that is common to all of them, + e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + + Get the API URL by running this command: + + ```sh + kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' + ``` + + - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate by running this command: + + ```sh + + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + + ``` + + NOTE: **Note:** + If the command returns the entire certificate chain, you need copy the *root ca* + certificate at the bottom of the chain. + + - **Token** - + GitLab authenticates against Kubernetes using service tokens, which are + scoped to a particular `namespace`. + **The token used should belong to a service account with + [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + privileges.** To create this service account: + + 1. Create a file called `gitlab-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab-admin + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` + + 1. Apply the service account and cluster role binding to your cluster: + + ```bash + kubectl apply -f gitlab-admin-service-account.yaml + ``` + + You will need the `container.clusterRoleBindings.create` permission + to create cluster-level roles. If you do not have this permission, + you can alternatively enable Basic Authentication and then run the + `kubectl apply` command as an admin: + + ```bash + kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> + ``` + + NOTE: **Note:** + Basic Authentication can be turned on and the password credentials + can be obtained using the Google Cloud Console. + + Output: + + ```bash + serviceaccount "gitlab-admin" created + clusterrolebinding "gitlab-admin" created + ``` + + 1. Retrieve the token for the `gitlab-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: gitlab-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + + NOTE: **Note:** + For GKE clusters, you will need the + `container.clusterRoleBindings.create` permission to create a cluster + role binding. You can follow the [Google Cloud + documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) + to grant access. + + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. + See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. + + - **Project namespace** (optional) - You don't have to fill it in; by leaving + it blank, GitLab will create one for you. Also: + - Each project should have a unique namespace. + - The project namespace is not necessarily the namespace of the secret, if + you're using a secret with broader permissions, like the secret from `default`. + - You should **not** use `default` as the project namespace. + - If you or someone created a secret specifically for the project, usually + with limited permissions, the secret's namespace and project namespace may + be the same. + +1. Finally, click the **Create Kubernetes cluster** button. + +After a couple of minutes, your cluster will be ready to go. You can now proceed +to install some [pre-defined applications](index.md#installing-applications). + +### Add existing EKS cluster + +In this section, we will show how to integrate an [Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab and begin +deploying applications. + +#### Requirements + +To integrate with with EKS, you will need: + +- An account on GitLab, like [GitLab.com](https://gitlab.com). +- An Amazon EKS cluster (with worker nodes properly configured). +- `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl). + +If you don't have an Amazon EKS cluster, one can be created by following the +[EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). + +#### Configuring and connecting the EKS cluster + +From the left side bar, hover over **Operations > Kubernetes > Add Kubernetes cluster**, +then click **Add an existing Kubernetes cluster**. + +A few details from the EKS cluster will be required to connect it to GitLab: + +1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to + authenticate to the EKS cluster. We will use the certificate created by default. + Open a shell and use `kubectl` to retrieve it: + + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate with: + + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` + +1. **Create admin token**: A `cluster-admin` token is required to install and + manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller + and creates limited service accounts for each application. To create the + token we will create an admin service account as follows: + + 1. Create a file called `eks-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: eks-admin + namespace: kube-system + ``` + + 1. Apply the service account to your cluster: + + ```bash + kubectl apply -f eks-admin-service-account.yaml + ``` + + Output: + + ```bash + serviceaccount "eks-admin" created + ``` + + 1. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: eks-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: eks-admin + namespace: kube-system + ``` + + 1. Apply the cluster role binding to your cluster: + + ```bash + kubectl apply -f eks-admin-cluster-role-binding.yaml + ``` + + Output: + + ```bash + clusterrolebinding "eks-admin" created + ``` + + 1. Retrieve the token for the `eks-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: eks-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=eks-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + +1. The API server endpoint is also required, so GitLab can connect to the cluster. + This is displayed on the AWS EKS console, when viewing the EKS cluster details. + +You now have all the information needed to connect the EKS cluster: + +- Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. +- Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. +- API URL: Paste in the API server endpoint retrieved above. +- CA Certificate: Paste the certificate data from the earlier step, as-is. +- Paste the admin token value. +- Project namespace: This can be left blank to accept the default namespace, based on the project name. + + + +Click on **Add Kubernetes cluster**, the cluster is now connected to GitLab. +At this point, [Kubernetes deployment variables](index.md#deployment-variables) will +automatically be available during CI/CD jobs, making it easy to interact with the cluster. + +If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. + +#### Disable Role-Based Access Control (RBAC) (optional) + +When connecting a cluster via GitLab integration, you may specify whether the +cluster is RBAC-enabled or not. This will affect how GitLab interacts with the +cluster for certain operations. If you **did not** check the "RBAC-enabled cluster" +checkbox at creation time, GitLab will assume RBAC is disabled for your cluster +when interacting with it. If so, you must disable RBAC on your cluster for the +integration to work properly. + + + +NOTE: **Note**: Disabling RBAC means that any application running in the cluster, +or user who can authenticate to the cluster, has full API access. This is a +[security concern](index.md#security-implications), and may not be desirable. + +To effectively disable RBAC, global permissions can be applied granting full access: + +```bash +kubectl create clusterrolebinding permissive-binding \ + --clusterrole=cluster-admin \ + --user=admin \ + --user=kubelet \ + --group=system:serviceaccounts +``` + +#### Create a default Storage Class + +Amazon EKS doesn't have a default Storage Class out of the box, which means +requests for persistent volumes will not be automatically fulfilled. As part +of Auto DevOps, the deployed Postgres instance requests persistent storage, +and without a default storage class it will fail to start. + +If a default Storage Class doesn't already exist and is desired, follow Amazon's +[guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) +to create one. + +Alternatively, disable Postgres by setting the project variable +[`POSTGRES_ENABLED`](../../../topics/autodevops/#environment-variables) to `false`. + +#### Deploy the app to EKS + +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#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. + + + +A new pipeline will automatically be created, which will begin to build, test, +and deploy the app. + +After the pipeline has finished, your app will be running in EKS and available +to users. Click on **CI/CD > Environments**. + + + +You will see a list of the environments and their deploy status, as well as +options to browse to the app, view monitoring metrics, and even access a shell +on the running pod. + +## 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 + +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. + +When removing the cluster integration, note: + +- You need Maintainer [permissions](../../permissions.md) and above to remove a Kubernetes cluster + integration. +- When you remove a cluster, you only remove its relationship to GitLab, not the cluster itself. To + remove the cluster, you can do so by visiting the GKE dashboard or using `kubectl`. + +## Learn more + +To learn more on automatically deploying your applications, +read about [Auto DevOps](../../../topics/autodevops/index.md). diff --git a/doc/user/project/clusters/eks_and_gitlab/img/create_dns.png b/doc/user/project/clusters/eks_and_gitlab/img/create_dns.png Binary files differdeleted file mode 100644 index 61ed85e5cd9..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/img/create_dns.png +++ /dev/null diff --git a/doc/user/project/clusters/eks_and_gitlab/img/create_project.png b/doc/user/project/clusters/eks_and_gitlab/img/create_project.png Binary files differdeleted file mode 100644 index b02ab4b9064..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/img/create_project.png +++ /dev/null diff --git a/doc/user/project/clusters/eks_and_gitlab/img/deploy_apps.png b/doc/user/project/clusters/eks_and_gitlab/img/deploy_apps.png Binary files differdeleted file mode 100644 index 0d9fcc838d9..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/img/deploy_apps.png +++ /dev/null diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 22576b84926..fda8cd6340e 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -1,278 +1,5 @@ -# Connecting and deploying to an Amazon EKS cluster +--- +redirect_to: '../add_remove_clusters.md#add-existing-eks-cluster' +--- -In this tutorial, we will show how to integrate an -[Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab and begin -deploying applications. - -## Introduction - -For an end-to-end walkthrough we will: - -1. Start with a new project based on the sample Ruby on Rails template. -1. Integrate an EKS cluster. -1. Utilize [Auto DevOps](../../../../topics/autodevops/) to build, test, and deploy our application. - -You will need: - -1. An account on GitLab, like [GitLab.com](https://gitlab.com). -1. An Amazon EKS cluster (with worker nodes properly configured). -1. `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl). - -If you don't have an Amazon EKS cluster, one can be created by following the -[EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). - -## Creating a new project - -On GitLab, create a new project by clicking on the `+` icon in the top navigation -bar and selecting **New project**. - -On the new project screen, click on the **Create from template** tab, and select -"Use template" for the Ruby on Rails sample project. - -Give the project a name, and then select **Create project**. - - - -## Configuring and connecting the EKS cluster - -From the left side bar, hover over **Operations > Kubernetes > Add Kubernetes cluster**, -then click **Add an existing Kubernetes cluster**. - -A few details from the EKS cluster will be required to connect it to GitLab: - -1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to - authenticate to the EKS cluster. We will use the certificate created by default. - Open a shell and use `kubectl` to retrieve it: - - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate with: - - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - -1. **Create admin token**: A `cluster-admin` token is required to install and - manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller - and creates limited service accounts for each application. To create the - token we will create an admin service account as follows: - - 2.1. Create a file called `eks-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: eks-admin - namespace: kube-system - ``` - - 2.2. Apply the service account to your cluster: - - ```bash - kubectl apply -f eks-admin-service-account.yaml - ``` - - Output: - - ```bash - serviceaccount "eks-admin" created - ``` - - 2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: eks-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: eks-admin - namespace: kube-system - ``` - - 2.4. Apply the cluster role binding to your cluster: - - ```bash - kubectl apply -f eks-admin-cluster-role-binding.yaml - ``` - - Output: - - ```bash - clusterrolebinding "eks-admin" created - ``` - - 2.5. Retrieve the token for the `eks-admin` service account: - - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: eks-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=eks-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - -1. The API server endpoint is also required, so GitLab can connect to the cluster. - This is displayed on the AWS EKS console, when viewing the EKS cluster details. - -You now have all the information needed to connect the EKS cluster: - -- Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. -- Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. -- API URL: Paste in the API server endpoint retrieved above. -- CA Certificate: Paste the certificate data from the earlier step, as-is. -- Paste the admin token value. -- Project namespace: This can be left blank to accept the default namespace, based on the project name. - - - -Click on **Add Kubernetes cluster**, the cluster is now connected to GitLab. -At this point, [Kubernetes deployment variables](../#deployment-variables) will -automatically be available during CI/CD jobs, making it easy to interact with the cluster. - -If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. - -## Disable Role-Based Access Control (RBAC) (optional) - -When connecting a cluster via GitLab integration, you may specify whether the -cluster is RBAC-enabled or not. This will affect how GitLab interacts with the -cluster for certain operations. If you **did not** check the "RBAC-enabled cluster" -checkbox at creation time, GitLab will assume RBAC is disabled for your cluster -when interacting with it. If so, you must disable RBAC on your cluster for the -integration to work properly. - - - -NOTE: **Note**: Disabling RBAC means that any application running in the cluster, -or user who can authenticate to the cluster, has full API access. This is a -[security concern](../index.md#security-implications), and may not be desirable. - -To effectively disable RBAC, global permissions can be applied granting full access: - -```bash -kubectl create clusterrolebinding permissive-binding \ - --clusterrole=cluster-admin \ - --user=admin \ - --user=kubelet \ - --group=system:serviceaccounts -``` - -## Deploy services to the cluster - -GitLab supports one-click deployment of helpful services to the cluster, many of -which support Auto DevOps. Back on the Kubernetes cluster screen in GitLab, a -list of applications is now available to deploy. - -First, install Helm Tiller, a package manager for Kubernetes. This enables -deployment of the other applications. - - - -### Deploying NGINX Ingress (optional) - -Next, if you would like the deployed app to be reachable on the internet, deploy -the Ingress. Note that this will also cause an -[Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) -to be created, which will incur additional AWS costs. - -Once installed, you may see a `?` for "Ingress IP Address". This is because the -created ELB is available at a DNS name, not an IP address. To get the DNS name, -run: - -```sh -kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}" -``` - -Note that you may see a trailing `%` on some Kubernetes versions, **do not include it**. - -The Ingress is now available at this address and will route incoming requests to -the proper service based on the DNS name in the request. To support this, a -wildcard DNS CNAME record should be created for the desired domain name. For example, -`*.myekscluster.com` would point to the Ingress hostname obtained earlier. - - - -### Deploying the GitLab Runner (optional) - -If the project is on GitLab.com, free shared Runners are available and you do -not have to deploy one. If a project specific Runner is desired, or there are no -shared Runners, it is easy to deploy one. - -Simply click on the **Install** button for the GitLab Runner. It is important to -note that the Runner deployed is set as **privileged**, which means it essentially -has root access to the underlying machine. This is required to build docker images, -and so is on by default. - -### Deploying Prometheus (optional) - -GitLab is able to monitor applications automatically, utilizing -[Prometheus](../../integrations/prometheus.html). Kubernetes container CPU and -memory metrics are automatically collected, and response metrics are retrieved -from NGINX Ingress as well. - -To enable monitoring, simply install Prometheus into the cluster with the -**Install** button. - -## Create a default Storage Class - -Amazon EKS doesn't have a default Storage Class out of the box, which means -requests for persistent volumes will not be automatically fulfilled. As part -of Auto DevOps, the deployed Postgres instance requests persistent storage, -and without a default storage class it will fail to start. - -If a default Storage Class doesn't already exist and is desired, follow Amazon's -[guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) -to create one. - -Alternatively, disable Postgres by setting the project variable -[`POSTGRES_ENABLED`](../../../../topics/autodevops/#environment-variables) to `false`. - -## Deploy the app to EKS - -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#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. - - - -A new pipeline will automatically be created, which will begin to build, test, -and deploy the app. - -After the pipeline has finished, your app will be running in EKS and available -to users. Click on **CI/CD > Environments**. - - - -You will see a list of the environments and their deploy status, as well as -options to browse to the app, view monitoring metrics, and even access a shell -on the running pod. - -## Learn more - -To learn more on automatically deploying your applications, -read about [Auto DevOps](../../../../topics/autodevops/index.md). +This document was moved to [another location](../add_remove_clusters.md#add-existing-eks-cluster). diff --git a/doc/user/project/clusters/eks_and_gitlab/img/add_cluster.png b/doc/user/project/clusters/img/add_cluster.png Binary files differindex 94ec83f1514..94ec83f1514 100644 --- a/doc/user/project/clusters/eks_and_gitlab/img/add_cluster.png +++ b/doc/user/project/clusters/img/add_cluster.png diff --git a/doc/user/project/clusters/eks_and_gitlab/img/environment.png b/doc/user/project/clusters/img/environment.png Binary files differindex 4714c447026..4714c447026 100644 --- a/doc/user/project/clusters/eks_and_gitlab/img/environment.png +++ b/doc/user/project/clusters/img/environment.png diff --git a/doc/user/project/clusters/img/kubernetes_pod_logs_v12_4.png b/doc/user/project/clusters/img/kubernetes_pod_logs_v12_4.png Binary files differdeleted file mode 100644 index 73c2ecd182a..00000000000 --- a/doc/user/project/clusters/img/kubernetes_pod_logs_v12_4.png +++ /dev/null diff --git a/doc/user/project/clusters/img/kubernetes_pod_logs_v12_5.png b/doc/user/project/clusters/img/kubernetes_pod_logs_v12_5.png Binary files differnew file mode 100644 index 00000000000..e54637e7218 --- /dev/null +++ b/doc/user/project/clusters/img/kubernetes_pod_logs_v12_5.png diff --git a/doc/user/project/clusters/eks_and_gitlab/img/pipeline.png b/doc/user/project/clusters/img/pipeline.png Binary files differindex 0eb00d0faa7..0eb00d0faa7 100644 --- a/doc/user/project/clusters/eks_and_gitlab/img/pipeline.png +++ b/doc/user/project/clusters/img/pipeline.png diff --git a/doc/user/project/clusters/eks_and_gitlab/img/rbac.png b/doc/user/project/clusters/img/rbac.png Binary files differindex 517e4f7ca44..517e4f7ca44 100644 --- a/doc/user/project/clusters/eks_and_gitlab/img/rbac.png +++ b/doc/user/project/clusters/img/rbac.png diff --git a/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_5.png b/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_5.png Binary files differnew file mode 100644 index 00000000000..f113b0353f2 --- /dev/null +++ b/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_5.png diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 9ecb785d6fe..c5c2c2c07e7 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -28,12 +28,11 @@ Using the GitLab project Kubernetes integration, you can: - 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). +See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to +set up integrations. + ### Deploy Boards **(PREMIUM)** GitLab's Deploy Boards offer a consolidated view of the current health and @@ -98,236 +97,10 @@ pods are annotated with: `$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), -and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's -Google Kubernetes Engine Integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit. - -NOTE: **Note:** -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 - -Before creating your first cluster on Google Kubernetes Engine with GitLab's -integration, make sure the following requirements are met: - -- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) - is set up and you have permissions to access it. -- 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 - -If all of the above requirements are met, you can proceed to create and add a -new Kubernetes cluster to your project: - -1. Navigate to your project's **Operations > Kubernetes** page. - - NOTE: **Note:** - You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. - -1. Click **Add Kubernetes cluster**. -1. Click **Create with Google Kubernetes Engine**. -1. Connect your Google account if you haven't done already by clicking the - **Sign in with Google** button. -1. From there on, choose your cluster's settings: - - **Kubernetes cluster name** - The name you wish to give the cluster. - - **Environment scope** - The [associated environment](#setting-the-environment-scope-premium) to this cluster. - - **Google Cloud Platform project** - Choose the project you created in your GCP - console that will host the Kubernetes cluster. Learn more about - [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) - under which the cluster will be created. - - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) - of the Virtual Machine instance that the cluster will be based on. - - **Enable Cloud Run on GKE (beta)** - Check this if you want to use Cloud Run on GKE for this cluster. See the [Cloud Run on GKE section](#cloud-run-on-gke) for more information. - - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. -1. Finally, click the **Create Kubernetes cluster** button. - -After a couple of minutes, your cluster will be ready to go. You can now proceed -to install some [pre-defined applications](#installing-applications). - -NOTE: **Note:** -GitLab requires basic authentication enabled and a client certificate issued for -the cluster in order to setup an [initial service -account](#access-controls). Starting from [GitLab -11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster -creation process will explicitly request that basic authentication and -client certificate is enabled. - -NOTE: **Note:** -Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/issues/55902), all GKE clusters created by GitLab are RBAC enabled. Take a look at the [RBAC section](#rbac-cluster-resources) for more information. - -### Add existing Kubernetes cluster - -NOTE: **Note:** -Kubernetes integration is not supported for arm64 clusters. See the issue [Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details. - -To add an existing Kubernetes cluster to your project: - -1. Navigate to your project's **Operations > Kubernetes** page. - - NOTE: **Note:** - You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. - -1. Click **Add Kubernetes cluster**. -1. Click **Add an existing Kubernetes cluster** and fill in the details: - - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - - **Environment scope** (required) - The - [associated environment](#setting-the-environment-scope-premium) to this cluster. - - **API URL** (required) - - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes - exposes several APIs, we want the "base" URL that is common to all of them, - e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. - - Get the API URL by running this command: - - ```sh - kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' - ``` - - - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate by running this command: - - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - - - **Token** - - GitLab authenticates against Kubernetes using service tokens, which are - scoped to a particular `namespace`. - **The token used should belong to a service account with - [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - privileges.** To create this service account: - - 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab-admin - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab-admin - namespace: kube-system - ``` - - 1. Apply the service account and cluster role binding to your cluster: - - ```bash - kubectl apply -f gitlab-admin-service-account.yaml - ``` - - Output: - - ```bash - serviceaccount "gitlab-admin" created - clusterrolebinding "gitlab-admin" created - ``` - - 1. Retrieve the token for the `gitlab-admin` service account: - - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: gitlab-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - NOTE: **Note:** - For GKE clusters, you will need the - `container.clusterRoleBindings.create` permission to create a cluster - role binding. You can follow the [Google Cloud - documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) - to grant access. - - - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. - - - **Project namespace** (optional) - You don't have to fill it in; by leaving - it blank, GitLab will create one for you. Also: - - Each project should have a unique namespace. - - The project namespace is not necessarily the namespace of the secret, if - you're using a secret with broader permissions, like the secret from `default`. - - You should **not** use `default` as the project namespace. - - If you or someone created a secret specifically for the project, usually - with limited permissions, the secret's namespace and project namespace may - be the same. - -1. Finally, click the **Create Kubernetes cluster** button. - -After a couple of minutes, your cluster will be ready to go. You can now proceed -to install some [pre-defined applications](#installing-applications). - -### 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. +After [adding a Kubernetes cluster](add_remove_clusters.md) to GitLab, read this section that covers +important considerations for configuring Kubernetes clusters with GitLab. ### Security implications @@ -340,15 +113,6 @@ 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. -### Cloud Run on GKE - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16566) in GitLab 12.4. - -You can choose to use Cloud Run on GKE in place of installing Knative and Istio -separately after the cluster has been created. This means that Cloud Run -(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at -create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. - ### GitLab-managed clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5. @@ -356,7 +120,7 @@ create time and cannot be [installed or uninstalled](../../clusters/applications You can choose to allow GitLab to manage your cluster for you. If your cluster is managed by GitLab, resources for your projects will be automatically created. See the -[Access controls](#access-controls) section for details on which resources will +[Access controls](add_remove_clusters.md#access-controls) section for details on which resources will be created. If you choose to manage your own cluster, project-specific resources will not be created @@ -386,97 +150,6 @@ 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 - -When creating a cluster in GitLab, you will be asked if you would like to create either: - -- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. -- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) cluster. - -NOTE: **Note:** -[RBAC](#rbac-cluster-resources) is recommended and the GitLab default. - -GitLab creates the necessary service accounts and privileges to install and run -[GitLab managed applications](#installing-applications). When GitLab creates the cluster, -a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace -to manage the newly created cluster. - - NOTE: **Note:** - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/51716) in GitLab 11.5. - -When you install Helm into your cluster, the `tiller` service account -is created with `cluster-admin` privileges in the `gitlab-managed-apps` -namespace. This service account will be added to the installed Helm Tiller and will -be used by Helm to install and run [GitLab managed applications](#installing-applications). -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](#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 - -GitLab creates the following resources for ABAC clusters. - -| Name | Type | Details | Created when | -|:----------------------|:---------------------|:-------------------------------------|:---------------------------| -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | -| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | -| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | -| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | -| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | - -#### RBAC cluster resources - -GitLab creates the following resources for RBAC clusters. - -| Name | Type | Details | Created when | -|:----------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:---------------------------| -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster | -| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | -| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | -| Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | -| Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | -| Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | -| Environment namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | - -NOTE: **Note:** -Environment-specific resources are only created if your cluster is [managed by GitLab](#gitlab-managed-clusters). - -NOTE: **Note:** -If your cluster was created before GitLab 12.2, it will use a single namespace for all project environments. - -#### Security of GitLab Runners - -GitLab Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode) -enabled by default, which allows them to execute special commands and running -Docker in Docker. This functionality is needed to run some of the -[Auto DevOps](../../../topics/autodevops/index.md) -jobs. This implies the containers are running in privileged mode and you should, -therefore, be aware of some important details. - -The privileged flag gives all capabilities to the running container, which in -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, 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 @@ -545,93 +218,12 @@ differentiate the new cluster with the rest. ## Installing applications -GitLab can install and manage some applications in your project-level -cluster. For more information on installing, upgrading, uninstalling, -and troubleshooting applications for your project cluster, see +GitLab can install and manage some applications like Helm, GitLab Runner, Ingress, +Prometheus, etc., in your project-level 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 - -NOTE: **Note:** -With the following procedure, a load balancer must be installed in your cluster -to obtain the endpoint. You can use either -[Ingress](#installing-applications), or Knative's own load balancer -([Istio](https://istio.io)) if using [Knative](#installing-applications). - -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 - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/17052) in GitLab 10.6. - -After you install [Ingress or Knative](#installing-applications), GitLab attempts to determine the external endpoint -and it should be available within a few minutes. If the endpoint doesn't appear -and your cluster runs on Google Kubernetes Engine: - -1. Check your [Kubernetes cluster on Google Kubernetes Engine](https://console.cloud.google.com/kubernetes) to ensure there are no errors on its nodes. -1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) on Google Kubernetes Engine. For more information, see [Resource Quotas](https://cloud.google.com/compute/quotas). -1. Check [Google Cloud's Status](https://status.cloud.google.com/) to ensure they are not having any disruptions. - -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 - -If the cluster is on GKE, click the **Google Kubernetes Engine** link in the -**Advanced settings**, or go directly to the -[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) -and select the proper project and cluster. Then click **Connect** and execute -the `gcloud` command in a local terminal or using the **Cloud Shell**. - -If the cluster is not on GKE, follow the specific instructions for your -Kubernetes provider to configure `kubectl` with the right credentials. -The output of the following examples will show the external endpoint of your -cluster. This information can then be used to set up DNS entries and forwarding -rules that allow external access to your deployed applications. - -If you installed the Ingress [via the **Applications**](#installing-applications), -run the following command: - -```bash -kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -``` - -Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: - -```bash -kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' -``` - -For Istio/Knative, the command will be different: - -```bash -kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' -``` - -Otherwise, you can list the IP addresses of all load balancers: - -```bash -kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].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, -your apps will not be able to be reached, and you'd have to change the DNS -record again. In order to avoid that, you should change it into a static -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 - -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. - ## Deploying to a Kubernetes cluster A Kubernetes cluster can be the destination for a deployment job. If @@ -654,8 +246,8 @@ GitLab CI/CD build environment. | Variable | Description | | -------- | ----------- | | `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](#access-controls). | -| `KUBE_NAMESPACE` | The Kubernetes namespace is auto-generated if not specified. The default value is `<project_name>-<project_id>-<environment>`. You can overwrite it to use different one if needed, otherwise the `KUBE_NAMESPACE` variable will receive the default value. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. | | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | @@ -668,6 +260,16 @@ service account of the cluster integration. NOTE: **Note:** If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be set to `<project_name>-<project_id>`. +When deploying a custom namespace: + +- The custom namespace must exist in your cluster. +- The project's deployment service account must have permission to deploy to the namespace. +- `KUBECONFIG` must be updated to use the custom namespace instead of the GitLab-provided default (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/issues/31519)). +- If deploying with Auto DevOps, you must *also* override `KUBE_NAMESPACE` with the custom namespace. + +CAUTION: **Caution:** +GitLab does not save custom namespaces in the database. So while deployments work with custom namespaces, GitLab's integration for already-deployed environments will not pick up the customized values. For example, [Deploy Boards](../deploy_boards.md) will not work as intended for those deployments. For more information, see the [related issue](https://gitlab.com/gitlab-org/gitlab/issues/27630). + ### Troubleshooting Before the deployment jobs starts, GitLab creates the following specifically for diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 4036eaf0bfb..797ddf784cc 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -11,7 +11,31 @@ Everything you need to build, test, deploy, and run your app at scale. ## 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): +[Kubernetes](https://kubernetes.io) pod logs can be viewed directly within GitLab. + + + +## Requirements + +[Deploying to a Kubernetes environment](../deploy_boards.md#enabling-deploy-boards) is required in order to be able to use Pod Logs. + +## Usage + +To access pod logs, you must have the right [permissions](../../permissions.md#project-members-permissions). + +You can access them in two ways. + +### From the project sidebar + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 12.5. + +Go to **Operations > Pod logs** on the sidebar menu. + + + +### From Deploy Boards + +Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md): 1. Go to **Operations > Environments** and find the environment which contains the desired pod, like `production`. 1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](../deploy_boards.md). @@ -23,9 +47,3 @@ Everything you need to build, test, deploy, and run your app at scale. - [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/5769), environments. Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab/issues/6502). - -  - -## Requirements - -[Enabling Deploy Boards](../deploy_boards.md#enabling-deploy-boards) is required in order to be able to use Pod Logs. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 7b17ec68234..bffae4c5069 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#add-new-gke-cluster). + The simplest way to get started is to add a cluster using one of [GitLab's integrations](../add_remove_clusters.md#add-new-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 [Add new GKE cluster](../index.md#add-new-gke-cluster) +Follow the steps outlined in [Add new cluster](../add_remove_clusters.md#add-new-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 9a9857bd5da..ffd7b0c0f2a 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -13,14 +13,16 @@ GitLab supports several ways deploy Serverless applications in both Kubernetes E Currently we support: -- [Knative](#knative): Build Knative applications with Knative and gitlabktl on GKE -- [AWS Lambda](aws.md): Create serverless applications via the Serverless Framework and GitLab CI +- [Knative](#knative): Build Knative applications with Knative and gitlabktl on GKE. +- [AWS Lambda](aws.md): Create serverless applications via the Serverless Framework and GitLab CI. ## Knative Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/knative/). -Knative extends Kubernetes to provide a set of middleware components that are useful to build modern, source-centric, container-based applications. Knative brings some significant benefits out of the box through its main components: +Knative extends Kubernetes to provide a set of middleware components that are useful to build +modern, source-centric, container-based applications. Knative brings some significant benefits out +of the box through its main components: - [Serving](https://github.com/knative/serving): Request-driven compute that can scale to zero. - [Eventing](https://github.com/knative/eventing): Management and delivery of events. @@ -39,7 +41,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#add-new-gke-cluster). + The simplest way to get started is to add a cluster using [GitLab's GKE integration](../add_remove_clusters.md#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. @@ -62,20 +64,22 @@ To run Knative on GitLab, you will need: using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). 1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. See [Installing Applications](../index.md#installing-applications) for more information. +1. **Logging** (optional): Configuring logging allows you to view and search request logs for your serverless function/application. + See [Configuring logging](#configuring-logging) for more information. ## Installing Knative via GitLab's Kubernetes integration NOTE: **Note:** The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** -1. [Add a Kubernetes cluster](../index.md) and [install Helm](../index.md#installing-applications). +1. [Add a Kubernetes cluster](../add_remove_clusters.md) and [install Helm](../index.md#installing-applications). 1. Once Helm has been successfully installed, scroll down to the Knative app section. Enter the domain to be used with your application/functions (e.g. `example.com`) and click **Install**.  1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the - **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../#manually-determining-the-external-endpoint). + **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../../../clusters/applications.md#determining-the-external-endpoint-manually). NOTE: **Note:** Running `kubectl` commands on your cluster requires setting up access to the cluster first. @@ -108,7 +112,7 @@ You must do the following: 1. Follow the steps to [add an existing Kubernetes - cluster](../index.md#add-existing-kubernetes-cluster). + cluster](../add_remove_clusters.md#add-existing-cluster). 1. Ensure GitLab can manage Knative: - For a non-GitLab managed cluster, ensure that the service account for the token @@ -164,13 +168,61 @@ You must do the following: or [serverless applications](#deploying-serverless-applications) onto your cluster. -## Deploying functions +## Configuring logging -> Introduced in GitLab 11.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33330) in GitLab 12.5. + +### Prerequisites + +- A GitLab-managed cluster. +- `kubectl` installed and working. + +Running `kubectl` commands on your cluster requires setting up access to the +cluster first. For clusters created on: + +- GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) +- Other platforms, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +### Enable request log template + +Run the following command to enable request logs: + +```shell +kubectl edit cm -n knative-serving config-observability +``` + +Copy the `logging.request-log-template` from the `data._example` field to the data field one level up in the hierarchy. + +### Enable request logs + +Run the following commands to install Elasticsearch, Kibana, and Filebeat into a `kube-logging` namespace and configure all nodes to forward logs using Filebeat: -Using functions is useful for dealing with independent events without needing -to maintain a complex unified infrastructure. This allows you to focus on a -single task that can be executed/scaled automatically and independently. +```shell +kubectl apply -f https://gitlab.com/gitlab-org/serverless/configurations/knative/raw/v0.7.0/kube-logging-filebeat.yaml +kubectl label nodes --all beta.kubernetes.io/filebeat-ready="true" +``` + +### Viewing request logs + +To view request logs: + +1. Run `kubectl proxy`. +1. Navigate to Kibana UI. + +Or: + +1. Open the Kibana UI. +1. Click on **Discover**, then select `filebeat-*` from the dropdown on the left. +1. Enter `kubernetes.container.name:"queue-proxy" AND message:/httpRequest/` into the search box. + +## Supported runtimes + +Serverless functions for GitLab can be written in 6 supported languages: + +- NodeJS and Ruby, with GitLab-managed and OpenFaas runtimes. +- C#, Go, PHP, and Python with OpenFaaS runtimes only. + +### GitLab managed runtimes Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are offered: @@ -180,6 +232,31 @@ Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runt `Dockerfile` presence is assumed when a runtime is not specified. +### OpenFaaS runtimes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29253) in GitLab 12.5. + +[OpenFaaS classic runtimes](https://github.com/openfaas/templates#templates-in-store) can be used with GitLab serverless. +Runtimes are specified using the pattern: `openfaas/classic/<template_name>`. The following +example shows how to define a function in `serverless.yml` using an OpenFaaS runtime: + +```yaml +hello: + source: ./hello + runtime: openfaas/classic/ruby + description: "Ruby function using OpenFaaS classic runtime" +``` + +`handler` is not needed for OpenFaaS functions. The location of the handler is defined +by the conventions of the runtime. + +See the [`ruby-openfaas-function`](https://gitlab.com/knative-examples/ruby-openfaas-function) +project for an example of a function using an OpenFaaS runtime. + +## Deploying functions + +> Introduced in GitLab 11.6. + You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**. @@ -311,10 +388,49 @@ The sample function can now be triggered from any HTTP client using a simple `PO  +### Running functions locally + +Running a function locally is a good way to quickly verify behavior during development. + +Running functions locally requires: + +- Go 1.12 or newer installed. +- Docker Engine installed and running. +- `gitlabktl` installed using the Go package manager: + + ```shell + GO111MODULE=on go get gitlab.com/gitlab-org/gitlabktl + ``` + +To run a function locally: + +1. Navigate to the root of your GitLab serverless project. +1. Build your function into a Docker image: + + ```shell + gitlabktl serverless build + ``` + +1. Run your function in Docker: + + ```shell + docker run -itp 8080:8080 <your_function_name> + ``` + +1. Invoke your function: + + ```shell + curl http://localhost:8080 + ``` + ## Deploying Serverless applications > Introduced in GitLab 11.5. +Serverless applications are the building block of serverless functions. They are useful in scenarios where an existing +runtime does not meet the needs of an application, such as one written in a language that has no runtime available. Note +though that serverless applications should be stateless! + NOTE: **Note:** You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png Binary files differindex f813b60dcd9..f813b60dcd9 100755..100644 --- a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png +++ b/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png diff --git a/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png Binary files differindex 59da6874d14..59da6874d14 100755..100644 --- a/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png +++ b/doc/user/project/img/code_owners_approval_protected_branch_v12_4.png diff --git a/doc/user/project/img/time_tracking_example_v12_2.png b/doc/user/project/img/time_tracking_example_v12_2.png Binary files differnew file mode 100644 index 00000000000..31d8c490ed1 --- /dev/null +++ b/doc/user/project/img/time_tracking_example_v12_2.png diff --git a/doc/user/project/img/time_tracking_sidebar_v8_16.png b/doc/user/project/img/time_tracking_sidebar_v8_16.png Binary files differnew file mode 100644 index 00000000000..22124afed6f --- /dev/null +++ b/doc/user/project/img/time_tracking_sidebar_v8_16.png diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index f883e4474e2..94ab9d9195b 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -75,7 +75,5 @@ You also can:  ---- - You can also choose a different name for the project and a different namespace, if you have the privileges to do so. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 0aeca7f73ad..9b98c52c4b8 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -125,7 +125,7 @@ your GitHub repositories are listed. ## Mirroring and pipeline status sharing -Depending your GitLab tier, [project mirroring](../../../workflow/repository_mirroring.md) can be set up to keep +Depending your GitLab tier, [project mirroring](../repository/repository_mirroring.md) can be set up to keep your imported project in sync with its GitHub copy. Additionally, you can configure GitLab to send pipeline status updates back GitHub with the diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 7ae288996da..c173d3d3e11 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -26,6 +26,7 @@ When you create a project in GitLab, you'll have access to a large number of from messing with history or pushing code without review - [Protected tags](protected_tags.md): Control over who has permission to create tags, and prevent accidental update or deletion + - [Repository mirroring](repository/repository_mirroring.md) - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. - [Web IDE](web_ide/index.md) @@ -44,7 +45,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Review Apps](../../ci/review_apps/index.md): Live preview the results of the changes proposed in a merge request in a per-branch basis - [Labels](labels.md): Organize issues and merge requests by labels -- [Time Tracking](../../workflow/time_tracking.md): Track estimate time +- [Time Tracking](time_tracking.md): Track estimate time and time spent on the conclusion of an issue or merge request - [Milestones](milestones/index.md): Work towards a target date diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index ec43696fdee..62310dd9177 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -1,6 +1,6 @@ # Generic alerts integration **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. GitLab can accept alerts from any source via a generic webhook receiver. When you set up the generic alerts integration, a unique endpoint will @@ -16,7 +16,7 @@ authored by the GitLab Alert Bot. To set up the generic alerts integration: 1. Navigate to **Settings > Integrations** in a project. -1. Click on **Alert endpoint**. +1. Click on **Alerts endpoint**. 1. Toggle the **Active** alert setting. The `URL` and `Authorization Key` for the webhook configuration can be found there. ## Customizing the payload @@ -37,12 +37,12 @@ Example request: ```sh curl --request POST \ --data '{"title": "Incident title"}' \ - --header "Authorization: Bearer <autorization_key>" \ + --header "Authorization: Bearer <authorization_key>" \ --header "Content-Type: application/json" \ <url> ``` -The `<autorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). +The `<authorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). Example payload: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 50adb5993e5..c1e6f93de30 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -31,7 +31,7 @@ integration settings. Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's -docs on [Adding an app to your team][slack-docs]. +docs on [Adding an app to your team](https://slack.com/help/articles/202035138). To enable GitLab's service for your Slack team: @@ -60,6 +60,5 @@ project, you would do: /gitlab gitlab-org/gitlab issue show 1001 ``` -[slack-docs]: https://get.slack.help/hc/en-us/articles/202035138-Adding-apps-to-your-team [slash commands]: ../../../integration/slash_commands.md [slack-manual]: slack_slash_commands.md diff --git a/doc/user/project/integrations/img/embed_metrics_issue_template.png b/doc/user/project/integrations/img/embed_metrics_issue_template.png Binary files differnew file mode 100644 index 00000000000..3c6a243e5c1 --- /dev/null +++ b/doc/user/project/integrations/img/embed_metrics_issue_template.png diff --git a/doc/user/project/integrations/img/grafana_panel_v12_5.png b/doc/user/project/integrations/img/grafana_panel_v12_5.png Binary files differnew file mode 100644 index 00000000000..18c17b910cd --- /dev/null +++ b/doc/user/project/integrations/img/grafana_panel_v12_5.png diff --git a/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png b/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png Binary files differnew file mode 100644 index 00000000000..fae62dd50df --- /dev/null +++ b/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png diff --git a/doc/user/project/integrations/img/heatmap_panel_type.png b/doc/user/project/integrations/img/heatmap_panel_type.png Binary files differnew file mode 100644 index 00000000000..a2b3911ec68 --- /dev/null +++ b/doc/user/project/integrations/img/heatmap_panel_type.png diff --git a/doc/user/project/integrations/img/http_proxy_access_v12_5.png b/doc/user/project/integrations/img/http_proxy_access_v12_5.png Binary files differnew file mode 100644 index 00000000000..0036a916a12 --- /dev/null +++ b/doc/user/project/integrations/img/http_proxy_access_v12_5.png diff --git a/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png Binary files differnew file mode 100644 index 00000000000..5cba6fa9038 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png diff --git a/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png b/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png Binary files differnew file mode 100644 index 00000000000..6cabe4193bd --- /dev/null +++ b/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png diff --git a/doc/user/project/integrations/img/select_query_variables_v12_5.png b/doc/user/project/integrations/img/select_query_variables_v12_5.png Binary files differnew file mode 100644 index 00000000000..23503577327 --- /dev/null +++ b/doc/user/project/integrations/img/select_query_variables_v12_5.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 6d2a0563ec1..874a1092b73 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -59,7 +59,7 @@ When connecting to **Jira Cloud**, which supports authentication via API token, > higher is required. > - GitLab 8.14 introduced a new way to integrate with Jira which greatly simplified > the configuration options you have to enter. If you are using an older version, -> [follow this documentation][jira-repo-old-docs]. +> [follow this documentation](https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable-ee/doc/project_services/jira.md). > - In order to support Oracle's Access Manager, GitLab will send additional cookies > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. @@ -205,4 +205,3 @@ authenticate with the Jira site. You will need to log in to your Jira instance and complete the CAPTCHA. [services-templates]: services_templates.md -[jira-repo-old-docs]: https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable/doc/project_services/jira.md diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index e385ee53636..315039f82b3 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -58,7 +58,7 @@ Click on the service links to see further configuration instructions and details ## Push hooks limit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31009) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/17874) in GitLab 12.4. If a single push includes changes to more than three branches or tags, services supported by `push_hooks` and `tag_push_hooks` events won't be executed. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index d7666d00e76..d3d4afefb59 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -117,7 +117,7 @@ You can view the performance dashboard for an environment by [clicking on the mo Custom metrics can be monitored by adding them on the monitoring dashboard page. Once saved, they will be displayed on the environment performance dashboard provided that either: -- A [connected Kubernetes cluster](../clusters/index.md#adding-and-removing-clusters) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration), or +- A [connected Kubernetes cluster](../clusters/add_remove_clusters.md) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration) - Prometheus is [manually configured](#manual-configuration-of-prometheus).  @@ -139,7 +139,7 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.htm - CI_ENVIRONMENT_SLUG - KUBE_NAMESPACE -To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`. +To specify a variable in a query, enclose it in quotation marks with curly braces with a leading percent. For example: `"%{ci_environment_slug}"`. ### Defining custom dashboards per project @@ -211,11 +211,11 @@ The following tables outline the details of expected properties. | Property | Type | Required | Description | | ------ | ------ | ------ | ------- | -| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use, can be `area-chart` or `line-chart` | +| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use, can be: `area-chart`, `line-chart` or `anomaly-chart`. | | `title` | string | yes | Heading for the panel. | | `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. | | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | -| `metrics` | array | yes | The metrics which should be displayed in the panel. | +| `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. | **Metrics (`metrics`) properties:** @@ -231,20 +231,20 @@ The following tables outline the details of expected properties. The below panel types are supported in monitoring dashboards. -##### Area +##### Area or Line Chart -To add an area panel type to a dashboard, look at the following sample dashboard file: +To add an area chart panel type to a dashboard, look at the following sample dashboard file: ```yaml dashboard: 'Dashboard Title' panel_groups: - group: 'Group Title' panels: - - type: area-chart - title: "Chart Title" + - type: area-chart # or line-chart + title: 'Area Chart Title' y_label: "Y-Axis" metrics: - - id: 10 + - id: area_http_requests_total query_range: 'http_requests_total' label: "Metric of Ages" unit: "count" @@ -255,10 +255,52 @@ Note the following properties: | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | | type | string | no | Type of panel to be rendered. Optional for area panel types | -| query_range | yes | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | +| query_range | string | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) |  +##### Anomaly chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16530) in GitLab 12.5. + +To add an anomaly chart panel type to a dashboard, add add a panel with *exactly* 3 metrics. + +The first metric represents the current state, and the second and third metrics represent the upper and lower limit respectively: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - type: anomaly-chart + title: "Chart Title" + y_label: "Y-Axis" + metrics: + - id: anomaly_requests_normal + query_range: 'http_requests_total' + label: "# of Requests" + unit: "count" + metrics: + - id: anomaly_requests_upper_limit + query_range: 10000 + label: "Max # of requests" + unit: "count" + metrics: + - id: anomaly_requests_lower_limit + query_range: 2000 + label: "Min # of requests" + unit: "count" +``` + +Note the following properties: + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| type | string | required | Must be `anomaly-chart` for anomaly panel types | +| query_range | yes | required | For anomaly panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) in every metric. | + + + ##### Single Stat To add a single stat panel type to a dashboard, look at the following sample dashboard file: @@ -286,6 +328,42 @@ Note the following properties:  +##### Heatmaps + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30581) in GitLab 12.5. + +To add a heatmap panel type to a dashboard, look at the following sample dashboard file: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - title: "Heatmap" + type: "heatmap" + metrics: + - id: 10 + query: 'sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[60m])) by (status_code)' + unit: req/sec + label: "Status code" +``` + +Note the following properties: + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| type | string | yes | Type of panel to be rendered. For heatmap panel types, set to `heatmap` | +| query_range | yes | yes | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | + + + +### View and edit the source file of a custom dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5. + +When viewing a custom dashboard of a project, you can view the original +`.yml` file by clicking on **Edit dashboard** button. + ### Downloading data as CSV Data from Prometheus charts on the metrics dashboard can be downloaded as CSV. @@ -332,9 +410,12 @@ receivers: ... ``` +In order for GitLab to associate your alerts with an [environment](../../../ci/environments.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. + ### Taking action on incidents **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +>- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. Alerts can be used to trigger actions, like open an issue automatically (enabled by default since `12.1`). To configure the actions: @@ -355,6 +436,8 @@ Once enabled, an issue will be opened automatically when an alert is triggered w - Optional list of attached annotations extracted from `annotations/*` - Alert [GFM](../../markdown.md): GitLab Flavored Markdown from `annotations/gitlab_incident_markdown` +When GitLab receives a **Recovery Alert**, it will automatically close the associated issue. This action will be recorded as a system message on the issue indicated that it was closed automatically by the GitLab Alert bot. + To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template, 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-foss/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. @@ -389,6 +472,8 @@ Prometheus server. ## Embedding metric charts within GitLab Flavored Markdown +### Embedding GitLab-managed Kubernetes metrics + > [Introduced][ce-29691] in GitLab 12.2. It is possible to display metrics charts within [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). @@ -414,9 +499,19 @@ The following requirements must be met for the metric to unfurl:  -### Embedding live Grafana charts +### Embedding metrics in issue templates + +It is also possible to embed either the default dashboard metrics or individual metrics in issue templates. For charts to render side-by-side, links to the entire metrics dashboard or individual metrics should be separated by either a comma or a space. + + + +### Embedding Grafana charts -It is also possible to embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) charts within issues, as a [Direct Linked Rendered Image](https://grafana.com/docs/reference/sharing/#direct-link-rendered-image). +Grafana metrics can be embedded in [GitLab Flavored Markdown](../../markdown.md). + +#### Embedding charts via Grafana Rendered Images + +It is possible to embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) charts in issues, as a [direct linked rendered image](https://grafana.com/docs/reference/sharing/#direct-link-rendered-image). The sharing dialog within Grafana provides the link, as highlighted below. @@ -435,6 +530,41 @@ This will render like so: <img src="https://dashboards.gitlab.com/render/d-solo/RZmbBr7mk/gitlab-triage?orgId=1&refresh=30s&var-env=gprd&var-environment=gprd&var-prometheus=prometheus-01-inf-gprd&var-prometheus_app=prometheus-app-01-inf-gprd&var-backend=All&var-type=All&var-stage=main&panelId=1247&width=1000&height=300"/> +#### Embedding charts via integration with Grafana HTTP API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31376) in GitLab 12.5. + +Each project can support integration with one Grafana instance. This configuration allows a user to copy a link to a panel in Grafana, then paste it into a GitLab markdown field. The chart will be rendered in the GitLab chart format. + +Prerequisites for embedding from a Grafana instance: + +1. The datasource must be a Prometheus instance. +1. The datasource must be proxyable, so the HTTP Access setting should be set to `Server`. + + + +##### Setting up the Grafana integration + +1. [Generate an Admin-level API Token in Grafana.](https://grafana.com/docs/http_api/auth/#create-api-token) +1. In your GitLab project, navigate to **Settings > Operations > Grafana Authentication**. +1. To enable the integration, check the "Active" checkbox. +1. For "Grafana URL", enter the base URL of the Grafana instance. +1. For "API Token", enter the Admin API Token you just generated. +1. Click **Save Changes**. + +##### Generating a link to a chart + +1. In Grafana, navigate to the dashboard you wish to embed a panel from. +  +1. In the upper-left corner of the page, select a specific value for each variable required for the queries in the chart. +  +1. In Grafana, click on a panel's title, then click **Share** to open the panel's sharing dialog to the **Link** tab. +1. If your Prometheus queries use Grafana's custom template variables, ensure that "Template variables" and "Current time range" options are toggled to **On**. Of Grafana global template variables, only `$__interval`, `$__from`, and `$__to` are currently supported. +  +1. Click **Copy** to copy the URL to the clipboard. +1. In GitLab, paste the URL into a markdown field and save. The chart will take a few moments to render. +  + ## Troubleshooting If the "No data found" screen continues to appear, it could be due to: diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index d630956c109..93f6dbb0302 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -30,7 +30,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../clusters/index.md#getting-the-external-endpoint). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 83eac44666c..a1dcb105196 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -30,7 +30,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../clusters/index.md#getting-the-external-endpoint). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 103d50a94e8..403972941b2 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -287,7 +287,7 @@ Different issue board features are available in different [GitLab tiers](https:/ | Tier | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists | |----------|--------------------------------|------------------------------|---------------------------|----------------| -| Core / Free | 1 | 1 | No | No | +| Core / Free | Multiple | 1 | No | No | | Starter / Bronze | Multiple | 1 | Yes | No | | Premium / Silver | Multiple | Multiple | Yes | Yes | | Ultimate / Gold | Multiple | Multiple | Yes | Yes | diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md new file mode 100644 index 00000000000..24775204c9f --- /dev/null +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -0,0 +1,42 @@ +# Associate a Zoom meeting with an issue + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16609) in GitLab 12.4. + +In order to communicate synchronously for incidents management, +GitLab allows to associate a Zoom meeting with an issue. +Once you start a Zoom call for a fire-fight, you need a way to +associate the conference call with an issue, so that your team +members can join swiftly without requesting a link. + +## Adding a zoom meeting to an issue + +To associate a zoom meeting with an issue, you can use GitLab's +[quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). + +In an issue, leave a comment using the `/zoom` quick action followed by a valid Zoom link: + +```sh +/zoom https://zoom.us/j/123456789 +``` + +If the Zoom meeting URL is valid and you have at least [Reporter permissions](../../permissions.md), +a system alert will notify you that the addition of the meeting URL was successful. +The issue's description will be automatically edited to include the Zoom link, and a button will +appear right under the issue's title. + + + +You are only allowed to attach a single Zoom meeting to an issue. If you attempt +to add a second Zoom meeting using the `/zoom` quick action, it won't work, you +need to [remove it](#removing-an-existing-zoom-meeting-from-an-issue) first. + +## Removing an existing Zoom meeting from an issue + +Similarly to adding a zoom meeting, you can remove it with a quick action: + +```sh +/remove_zoom +``` + +If you have at least [Reporter permissions](../../permissions.md), +a system alert will notify you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index fb7fdde7b94..b97bcd47f61 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -67,8 +67,8 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot | Milestone | Title of the issue milestone | | Weight | Issue weight | | Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../../../workflow/time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../../../workflow/time_tracking.md#time-spent) in seconds | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | ## Limitations diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 169da7049a6..594f73dbfbe 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -22,24 +22,26 @@ For an overview, see the video [Design Management (GitLab 12.2)](https://www.you ## Requirements Design Management requires -[Large File Storage (LFS)](../../../workflow/lfs/manage_large_binaries_with_git_lfs.md) +[Large File Storage (LFS)](../../../administration/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). + [enabled LFS globally](../../../administration/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**. +Design Management requires that projects are using +[hashed storage](../../../administration/repository_storage_types.html#hashed-storage) +(the default storage type since v10.0). + ## 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/issues/12771). - Design uploads are limited to 10 files at a time. -- Design Management is - [not yet supported in the project export](https://gitlab.com/gitlab-org/gitlab/issues/11090). - Design Management data [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/issues/13429) yet. - Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab/issues/13426) @@ -112,12 +114,16 @@ viewed by browsing previous versions. ## Adding annotations to designs -When a design image is displayed, you can add annotations to it by clicking on -the image. A badge is added to the image and a form is displayed to start a new -discussion. For example: +When a design is uploaded, you can add annotations by clicking on +the image on the exact location you'd like to add the note to. +A badge is added to the image identifying the annotation, from +which you can start a new discussion:  -When submitted, the form saves a badge linked to the discussion on the image. Different discussions have different badge numbers. For example: +Different discussions have different badge numbers:  + +From GitLab 12.5 on, new annotations will be outputted to the issue activity, +so that everyone involved can participate in the discussion. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 240859651e2..b19d5dc1650 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -33,7 +33,7 @@ the icon and the date colored red. You can sort issues by those that are  -Due dates also appear in your [todos list](../../../workflow/todos.md). +Due dates also appear in your [todos list](../../todos.md).  diff --git a/doc/user/project/issues/img/issue_weight.png b/doc/user/project/issues/img/issue_weight.png Binary files differnew file mode 100644 index 00000000000..3800b5940b8 --- /dev/null +++ b/doc/user/project/issues/img/issue_weight.png diff --git a/doc/user/project/issues/img/select_all_designs_v12_4.png b/doc/user/project/issues/img/select_all_designs_v12_4.png Binary files differdeleted file mode 100644 index b08b04c1214..00000000000 --- a/doc/user/project/issues/img/select_all_designs_v12_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/zoom-quickaction-button.png b/doc/user/project/issues/img/zoom-quickaction-button.png Binary files differindex d6d691b2267..c95a56b43e8 100644 --- a/doc/user/project/issues/img/zoom-quickaction-button.png +++ b/doc/user/project/issues/img/zoom-quickaction-button.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 01f4eb5b912..92da4235afa 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -41,7 +41,7 @@ after it is closed. #### 2. To Do -You can add issues to and remove issues from your [GitLab To-Do List](../../../workflow/todos.md). +You can add issues to and remove issues from your [GitLab To-Do List](../../todos.md). The button to do this has a different label depending on whether the issue is already on your To-Do List or not. If the issue is: @@ -83,9 +83,9 @@ Select a [milestone](../milestones/index.md) to attribute that issue to. #### 6. Time Tracking -Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../../../workflow/time_tracking.md). -You can add an [estimate of the time it will take](../../../workflow/time_tracking.md#estimates) -to resolve the issue, and also add [the time spent](../../../workflow/time_tracking.md#time-spent) +Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../time_tracking.md). +You can add an [estimate of the time it will take](../time_tracking.md#estimates) +to resolve the issue, and also add [the time spent](../time_tracking.md#time-spent) on the resolution of the issue. #### 7. Due date @@ -109,7 +109,7 @@ from which you can select **Create new label**. #### 9. Weight **(STARTER)** -[Assign a weight](../../../workflow/issue_weight.md) to an issue. +[Assign a weight](issue_weight.md) to an issue. Larger values are used to indicate more effort is required to complete the issue. Only positive values or zero are allowed. @@ -131,7 +131,7 @@ or were mentioned in the description or threads. #### 13. Notifications -Click on the icon to enable/disable [notifications](../../../workflow/notifications.md#issue--epics--merge-request-events) +Click on the icon to enable/disable [notifications](../../profile/notifications.md#issue--epics--merge-request-events) for the issue. This will automatically enable if you participate in the issue in any way. - **Enable**: If you are not a participant in the discussion on that issue, but @@ -162,7 +162,7 @@ allowing many formatting options. You can mention a user or a group present in your GitLab instance with `@username` or `@groupname` and they will be notified via todos and email, unless they have disabled all notifications in their profile settings. This is controlled in the -[notification settings](../../../workflow/notifications.md). +[notification settings](../../profile/notifications.md). Mentions for yourself (the current logged in user), will be highlighted in a different color, allowing you to easily see which comments involve you, helping you focus on @@ -257,4 +257,4 @@ You can attach and remove Zoom meetings to issues using the `/zoom` and `/remove Attaching a [Zoom](https://zoom.us) call an issue results in a **Join Zoom meeting** button at the top of the issue, just under the header. - +Read more how to [add or remove a zoom meeting](associate_zoom_meeting.md). diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md new file mode 100644 index 00000000000..4b8d2318e9b --- /dev/null +++ b/doc/user/project/issues/issue_weight.md @@ -0,0 +1,25 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' +--- + +# Issue weight **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/76) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. + +When you have a lot of issues, it can be hard to get an overview. +By adding a weight to each issue, you can get a better idea of how much time, +value or complexity a given issue has or will cost. + +You can set the weight of an issue during its creation, by simply changing the +value in the dropdown menu. You can set it to a non-negative integer +value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the +upper bound is essentially limitless). +You can remove weight from an issue +as well. + +This value will appear on the right sidebar of an individual issue, as well as +in the issues page next to a distinctive balance scale icon. + +As an added bonus, you can see the total sum of all issues on the milestone page. + + diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index cfd6d4eaf4b..d8356abdd1c 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -210,8 +210,8 @@ The following can be filtered by labels: ## Subscribing to labels From the project label list page and the group label list page, you can subscribe -to [notifications](../../workflow/notifications.md) of a given label, to alert you -that the label has been assigned to an epic, issue, and merge request. +to [notifications](../profile/notifications.md) of a given label, to alert you +that the label has been assigned to an epic, issue, or merge request.  diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 92681e741de..69bdfe10e3f 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -66,6 +66,18 @@ will scan your source code for code quality issues. The report will be saved as that you can later download and analyze. Due to implementation limitations we always take the latest Code Quality artifact available. +By default, report artifacts are not downloadable. If you need them downloadable on the +job details page, you can add `gl-code-quality-report.json` to the artifact paths like so: + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality: + artifacts: + paths: [gl-code-quality-report.json] +``` + The included `code_quality` job is running in the `test` stage, so it needs to be included in your CI config, like so: ```yaml @@ -91,7 +103,7 @@ old job definitions are still maintained they have been deprecated and may be re in the next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. -For GitLab 11.5 and earlier, the job should look like: +For GitLab 11.5 and later, the job should look like: ```yaml code_quality: diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md new file mode 100644 index 00000000000..084ebf32a92 --- /dev/null +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -0,0 +1,156 @@ +--- +type: index, reference +--- + +# Creating merge requests + +Merge requests are the primary method of making changes to files in a GitLab project. +Changes are proposed by creating and submitting a merge request, which is then +[reviewed, and accepted (or rejected)](reviewing_and_managing_merge_requests.md), +all within GitLab. + +## Creating new merge requests + +You can start creating a new merge request by clicking the **New merge request** button +on the **Merge Requests** page in a project. Then you must choose the source project and +branch that contain your changes, and the target project and branch where you want to merge +the changes into. Click on **Compare branches and continue** to go to the next step +and start filling in the merge request details. + +When viewing the commits on a branch other than master in **Repository > Commits**, you +can click on the **Create merge request** button, and a new merge request will be started +using the current branch as the source, and `master` in the current project as the target. + +If you have recently pushed changes to GitLab, the **Create merge request** button will +also appear in the top right of the: + +- **Project** page. +- **Repository > Files** page. +- **Merge Requests** page. + +In this case, the merge request will use the most recent branch you pushed changes +to as the source branch, and `master` in the current project as the target. + +## Workflow for new merge requests + +On the **New Merge Request** page, you can start by filling in the title and description +for the merge request. If there are are already commits on the branch, the title will +be pre-filled with the first line of the first commit message, and the description will +be pre-filled with any additional lines in the commit message. The title is the only +field that is mandatory in all cases. + +From here, you can also: + +- Set the merge request as a [work in progress](work_in_progress_merge_requests.md). +- Select the [assignee](#assignee), or [assignees](#multiple-assignees-starter). **(STARTER)** +- Select a [milestone](../milestones/index.md). +- Select [labels](../labels.md). +- Add any [merge request dependencies](merge_request_dependencies.md). **(PREMIUM)** +- Select [approval options](merge_request_approvals.md). **(STARTER)** +- Verify the source and target branches are correct. +- Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option. +- Enable the [squash commits when merge request is accepted](squash_and_merge.md) option. +- If the merge request is from a fork, enable [Allow collaboration on merge requests across forks](allow_collaboration.md). + +Many of these can be set when pushing changes from the command line, with +[Git push options](../push_options.md). + +### Merge requests to close issues + +If the merge request is being created to resolve an issue, you can add a note in the +description which will set it to [automatically close the issue](../issues/managing_issues.md#closing-issues-automatically) +when merged. + +If the issue is [confidential](../issues/confidential_issues.md), you may want to +use a different workflow for [merge requests for confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues), +to prevent confidential information from being exposed. + +## Assignee + +Choose an assignee to designate someone as the person responsible for the first +[review of the merge request](reviewing_and_managing_merge_requests.md). Open the +drop down box to search for the user you wish to assign, and the merge request will be +added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). + +### Multiple assignees **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). + +Multiple people often review merge requests at the same time. GitLab allows you to +have multiple assignees for merge requests to indicate everyone that is reviewing or +accountable for it. + + + +To assign multiple assignees to a merge request: + +1. From a merge request, expand the right sidebar and locate the **Assignees** section. +1. Click on **Edit** and from the dropdown menu, select as many users as you want + to assign the merge request to. + +Similarly, assignees are removed by deselecting them from the same dropdown menu. + +It's also possible to manage multiple assignees: + +- When creating a merge request. +- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). + +## Deleting the source branch + +When creating a merge request, select the "Delete source branch when merge +request accepted" option and the source branch will be deleted when the merge +request is merged. To make this option enabled by default for all new merge +requests, enable it in the [project's settings](../settings/index.md#merge-request-settings). + +This option is also visible in an existing merge request next to the merge +request button and can be selected/deselected before merging. It's only visible +to users with [Maintainer permissions](../../permissions.md) in the source project. + +If the user viewing the merge request does not have the correct permissions to +delete the source branch and the source branch is set for deletion, the merge +request widget will show the "Deletes source branch" text. + + + +## Create new merge requests by email + +_This feature needs [incoming email](../../../administration/incoming_email.md) +to be configured by a GitLab administrator to be available for CE/EE users, and +it's available on GitLab.com._ + +You can create a new merge request by sending an email to a user-specific email +address. The address can be obtained on the merge requests page by clicking on +a **Email a new merge request to this project** button. The subject will be +used as the source branch name for the new merge request and the target branch +will be the default branch for the project. The message body (if not empty) +will be used as the merge request description. You need +["Reply by email"](../../../administration/reply_by_email.md) enabled to use +this feature. If it's not enabled to your instance, you may ask your GitLab +administrator to do so. + +This is a private email address, generated just for you. **Keep it to yourself** +as anyone who gets ahold of it can create issues or merge requests as if they were you. +You can add this address to your contact list for easy access. + + + +_In GitLab 11.7, we updated the format of the generated email address. +However the older format is still supported, allowing existing aliases +or contacts to continue working._ + +### Adding patches when creating a merge request via e-mail + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22723) in GitLab 11.5. + +You can add commits to the merge request being created by adding +patches as attachments to the email. All attachments with a filename +ending in `.patch` will be considered patches and they will be processed +ordered by name. + +The combined size of the patches can be 2MB. + +If the source branch from the subject does not exist, it will be +created from the repository's HEAD or the specified target branch to +apply the patches. The target branch can be specified using the +[`/target_branch` quick action](../quick_actions.md). If the source +branch already exists, the patches will be applied on top of it. diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png Binary files differdeleted file mode 100644 index bbb131e86e9..00000000000 --- a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_3.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png Binary files differnew file mode 100644 index 00000000000..24c8c8f8c11 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit_v12_5.png diff --git a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_4.png b/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_4.png Binary files differindex c704129685f..c704129685f 100755..100644 --- a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_4.png +++ b/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_4.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 2ab7c3fb15b..1ca8c882ac7 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,5 +1,5 @@ --- -type: index, reference, concepts +type: index, reference --- # Merge requests @@ -9,45 +9,9 @@ to source code that exist as commits on a given Git branch.  -## Overview - -A Merge Request (**MR**) is the basis of GitLab as a code collaboration -and version control platform. -It is as simple as the name implies: a _request_ to _merge_ one branch into another. - -With GitLab merge requests, you can: - -- Compare the changes between two [branches](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching) -- [Review and discuss](../../discussions/index.md#threads) the proposed modifications inline -- Live preview the changes when [Review Apps](../../../ci/review_apps/index.md) is configured for your project -- Build, test, and deploy your code in a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md) -- Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests) -- View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines) -- [Automatically close the issue(s)](../../project/issues/managing_issues.md#closing-issues-automatically) that originated the implementation proposed in the merge request -- Assign it to any registered user, and change the assignee how many times you need -- Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation -- Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md) -- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.md#time-tracking) -- [Resolve merge conflicts from the UI](#resolve-conflicts) -- Enable [fast-forward merge requests](#fast-forward-merge-requests) -- Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch -- [Create new merge requests by email](#create-new-merge-requests-by-email) -- [Allow collaboration](allow_collaboration.md) so members of the target project can push directly to the fork -- [Squash and merge](squash_and_merge.md) for a cleaner commit history - -With **[GitLab Enterprise Edition][ee]**, you can also: - -- Prepare a full review and submit it once it's ready with [Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) **(PREMIUM)** -- View the deployment process across projects with [Multi-Project Pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** -- Request [approvals](merge_request_approvals.md) from your managers **(STARTER)** -- Analyze the impact of your changes with [Code Quality reports](code_quality.md) **(STARTER)** -- Manage the licenses of your dependencies with [License Compliance](../../application_security/license_compliance/index.md) **(ULTIMATE)** -- Analyze your source code for vulnerabilities with [Static Application Security Testing](../../application_security/sast/index.md) **(ULTIMATE)** -- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](../../application_security/dast/index.md) **(ULTIMATE)** -- Analyze your dependencies for vulnerabilities with [Dependency Scanning](../../application_security/dependency_scanning/index.md) **(ULTIMATE)** -- Analyze your Docker images for vulnerabilities with [Container Scanning](../../application_security/container_scanning/index.md) **(ULTIMATE)** -- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **(PREMIUM)** -- Specify merge order dependencies with [Merge Request Dependencies](#merge-request-dependencies-premium) **(PREMIUM)** +A Merge Request (**MR**) is the basis of GitLab as a code collaboration and version +control platform. It is as simple as the name implies: a _request_ to _merge_ one +branch into another. ## Use cases @@ -58,8 +22,11 @@ A. Consider you are a software developer working in a team: 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) **(STARTER)** 1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD 1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../application_security/license_compliance/index.md) **(ULTIMATE)** -1. You request the [approval](#merge-request-approvals-starter) from your manager -1. Your manager pushes a commit with their final review, [approves the merge request](merge_request_approvals.md), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter) +1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** +1. Your manager: + 1. Pushes a commit with their final review + 1. [Approves the merge request](merge_request_approvals.md) **(STARTER)** + 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md) 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD 1. Your implementations were successfully shipped to your customer @@ -71,547 +38,112 @@ B. Consider you're a web developer writing a webpage for your company's website: 1. You request your web designers for their implementation 1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/) -1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production - -## Merge requests per project - -View all the merge requests within a project by navigating to **Project > Merge Requests**. - -When you access your project's merge requests, GitLab will present them in a list, -and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#issues-and-merge-requests-per-project). - - - -## Merge requests per group - -View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. - -You can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group) from here. - - - -## Deleting the source branch - -When creating a merge request, select the "Delete source branch when merge -request accepted" option and the source branch will be deleted when the merge -request is merged. - -This option is also visible in an existing merge request next to the merge -request button and can be selected/deselected before merging. It's only visible -to users with [Maintainer permissions](../../permissions.md) in the source project. - -If the user viewing the merge request does not have the correct permissions to -delete the source branch and the source branch is set for deletion, the merge -request widget will show the "Deletes source branch" text. - - - -## Allow collaboration on merge requests across forks - -When a user opens a merge request from a fork, they are given the option to allow -upstream maintainers to collaborate with them on the source branch. This allows -the maintainers of the upstream project to make small fixes or rebase branches -before merging, reducing the back and forth of accepting community contributions. - -[Learn more about allowing upstream members to push to forks.](allow_collaboration.md) +1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production + +## Creating merge requests + +While making changes to files in the `master` branch of a repository is possible, it is not +the common workflow. In most cases, a user will make changes in a [branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching), +then [create a merge request](creating_merge_requests.md) to request that the changes +be merged into another branch (often the `master` branch). + +It is then [reviewed](#reviewing-and-managing-merge-requests), possibly updated after +discussions and suggestions, and finally approved and merged into the target branch. +Creating and reviewing merge requests is one of the most fundamental parts of working +with GitLab. + +When [creating merge requests](creating_merge_requests.md), there are a number of features +to be aware of: + +| Feature | Description | +|-----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Adding patches when creating a merge request via e-mail](creating_merge_requests.md#adding-patches-when-creating-a-merge-request-via-e-mail) | Add commits to a merge request created by e-mail, by adding patches as e-mail attachments. | +| [Allow collaboration on merge requests across forks](allow_collaboration.md) | Allows the maintainers of an upstream project to collaborate on a fork, to make fixes or rebase branches before merging, reducing the back and forth of accepting community contributions. | +| [Assignee](creating_merge_requests.md#assignee) | Add an assignee to indicate who is reviewing or accountable for it. | +| [Automatic issue closing](../../project/issues/managing_issues.md#closing-issues-automatically) | Set a merge request to close defined issues automatically as soon as it is merged. | +| [Create new merge requests by email](creating_merge_requests.md#create-new-merge-requests-by-email) | Create new merge requests by sending an email to a user-specific email address. | +| [Deleting the source branch](creating_merge_requests.md#deleting-the-source-branch) | Select the "Delete source branch when merge request accepted" option and the source branch will be deleted when the merge request is merged. | +| [Git push options](../push_options.md) | Use Git push options to create or update merge requests when pushing changes to GitLab with Git, without needing to use the GitLab interface. | +| [Labels](../../project/labels.md) | Organize your issues and merge requests consistently throughout the project. | +| [Merge request approvals](merge_request_approvals.md) **(STARTER)** | Set the number of necessary approvals and predefine a list of approvers that will need to approve every merge request in a project. | +| [Merge Request dependencies](merge_request_dependencies.md) **(PREMIUM)** | Specify that a merge request depends on other merge requests, enforcing a desired order of merging. | +| [Merge Requests for Confidential Issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) | Create merge requests to resolve confidential issues for preventing leakage or early release of sensitive data through regular merge requests. | +| [Milestones](../../project/milestones/index.md) | Track merge requests to achieve a broader goal in a certain period of time. | +| [Multiple assignees](creating_merge_requests.md#multiple-assignees-starter) **(STARTER)** | Have multiple assignees for merge requests to indicate everyone that is reviewing or accountable for it. | +| [Squash and merge](squash_and_merge.md) | Squash all changes present in a merge request into a single commit when merging, to allow for a neater commit history. | +| [Work In Progress merge requests](work_in_progress_merge_requests.md) | Prevent the merge request from being merged before it's ready | + +## Reviewing and managing merge requests + +Once a merge request has been [created](#creating-merge-requests) and submitted, there +are many powerful features that you can use during the review process to make sure only +the changes you want are merged into the repository. + +For managers and administrators, it is also important to be able to view and manage +all the merge requests in a group or project. When [reviewing or managing merge requests](reviewing_and_managing_merge_requests.md), +there are a number of features to be aware of: + +| Feature | Description | +|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Bulk editing merge requests](../../project/bulk_editing.md) | Update the attributes of multiple merge requests simultaneously. | +| [Cherry-pick changes](cherry_pick_changes.md) | Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button in a merged merge requests or a commit. | +| [Commenting on any file line in merge requests](reviewing_and_managing_merge_requests.md#commenting-on-any-file-line-in-merge-requests) | Make comments directly on the exact line of a file you want to talk about. | +| [Discuss changes in threads in merge requests reviews](../../discussions/index.md) | Keep track of the progress during a code review by making and resolving comments. | +| [Fast-forward merge requests](fast_forward_merge.md) | For a linear Git history and a way to accept merge requests without creating merge commits | +| [Find the merge request that introduced a change](versions.md) | When viewing the commit details page, GitLab will link to the merge request(s) containing that commit. | +| [Ignore whitespace changes in Merge Request diff view](reviewing_and_managing_merge_requests.md#ignore-whitespace-changes-in-Merge-Request-diff-view) | Hide whitespace changes from the diff view for a to focus on more important changes. | +| [Incrementally expand merge request diffs](reviewing_and_managing_merge_requests.md#incrementally-expand-merge-request-diffs) | View the content directly above or below a change, to better understand the context of that change. | +| [Live preview with Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps) | Live preview the changes when Review Apps are configured for your project | +| [Merge request diff file navigation](reviewing_and_managing_merge_requests.md#merge-request-diff-file-navigation) | Quickly jump to any changed file within the diff view. | +| [Merge requests versions](versions.md) | Select and compare the different versions of merge request diffs | +| [Merge when pipeline succeeds](merge_when_pipeline_succeeds.md) | Set a merge request that looks ready to merge to merge automatically when CI pipeline succeeds. | +| [Perform a Review](../../discussions/index.md#merge-request-reviews-premium) **(PREMIUM)** | Start a review in order to create multiple comments on a diff and publish them once you're ready. | +| [Pipeline status in merge requests](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests) | If using [GitLab CI/CD](../../../ci/README.md), see pre and post-merge pipelines information, and which deployments are in progress. | +| [Post-merge pipeline status](reviewing_and_managing_merge_requests.md#post-merge-pipeline-status) | When a merge request is merged, see the post-merge pipeline status of the branch the merge request was merged into. | +| [Resolve conflicts](resolve_conflicts.md) | GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. | +| [Revert changes](revert_changes.md) | Revert changes from any commit from within a merge request. | +| [Semi-linear history merge requests](reviewing_and_managing_merge_requests.md#semi-linear-history-merge-requests) | Enable semi-linear history merge requests as another security layer to guarantee the pipeline is passing in the target branch | +| [Suggest changes](../../discussions/index.md#suggest-changes) | Add suggestions to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. | +| [Time Tracking](../time_tracking.md#time-tracking) | Add a time estimation and the time spent with that merge request. | +| [View changes between file versions](reviewing_and_managing_merge_requests.md#view-changes-between-file-versions) | View what will be changed when a merge request is merged. | +| [View group merge requests](reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) | List and view the merge requests within a group. | +| [View project merge requests](reviewing_and_managing_merge_requests.md#view-project-merge-requests) | List and view the merge requests within a project. | + +## Testing and reports in merge requests + +GitLab has the ability to test the changes included in a merge request, and can display +or link to useful information directly in the merge request page: + +| Feature | Description | +|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. | +| [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | +| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../pipelines/job_artifacts.md) in merge requests. | +| [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | +| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | +| [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | +| [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | +| [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | +| [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines) | View the status of pipelines within the merge request, including the deployment process. | + +### Security Reports **(ULTIMATE)** + +In addition to the reports listed above, GitLab can do many types of [Security reports](../../application_security/index.md), +generated by scanning and reporting any vulnerabilities found in your project: + +| Feature | Description | +|-----------------------------------------------------------------------------------------|------------------------------------------------------------------| +| [Container Scanning](../../application_security/container_scanning/index.md) | Analyze your Docker images for known vulnerabilities. | +| [Dynamic Application Security Testing (DAST)](../../application_security/dast/index.md) | Analyze your running web applications for known vulnerabilities. | +| [Dependency Scanning](../../application_security/dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | +| [License Compliance](../../application_security/license_compliance/index.md) | Manage the licenses of your dependencies. | +| [Static Application Security Testing (SAST)](../../application_security/sast/index.md) | Analyze your source code for known vulnerabilities. | ## Authorization for merge requests There are two main ways to have a merge request flow with GitLab: -1. Working with [protected branches][] in a single repository +1. Working with [protected branches](../protected_branches.md) in a single repository 1. Working with forks of an authoritative project [Learn more about the authorization for merge requests.](authorization_for_merge_requests.md) - -## Cherry-pick changes - -Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button -in a merged merge requests or a commit. - -[Learn more about cherry-picking changes.](cherry_pick_changes.md) - -## Semi-linear history merge requests - -A merge commit is created for every merge, but the branch is only merged if -a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build will also succeed after merging. - -Navigate to a project's settings, select the **Merge commit with semi-linear -history** option under **Merge Requests: Merge method** and save your changes. - -## Fast-forward merge requests - -If you prefer a linear Git history and a way to accept merge requests without -creating merge commits, you can configure this on a per-project basis. - -[Read more about fast-forward merge requests.](fast_forward_merge.md) - -## Merge when pipeline succeeds - -When reviewing a merge request that looks ready to merge but still has one or -more CI jobs running, you can set it to be merged automatically when CI -pipeline succeeds. This way, you don't have to wait for the pipeline to finish -and remember to merge the request manually. - -[Learn more about merging when pipeline succeeds.](merge_when_pipeline_succeeds.md) - -## Resolve threads in merge requests reviews - -Keep track of the progress during a code review with resolving comments. -Resolving comments prevents you from forgetting to address feedback and lets -you hide threads that are no longer relevant. - -[Read more about resolving threads in merge requests reviews.](../../discussions/index.md) - -## View changes between file versions - -The **Changes** tab of a merge request shows the changes to files between branches or -commits. This view of changes to a file is also known as a **diff**. By default, the diff view -compares the file in the merge request branch and the file in the target branch. - -The diff view includes the following: - -- The file's name and path. -- The number of lines added and deleted. -- Buttons for the following options: - - Toggle comments for this file; useful for inline reviews. - - Edit the file in the merge request's branch. - - Show full file, in case you want to look at the changes in context with the rest of the file. - - View file at the current commit. - - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). -- The changed lines, with the specific changes highlighted. - - - -## Commenting on any file line in merge requests - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13950) in GitLab 11.5. - -GitLab provides a way of leaving comments in any part of the file being changed -in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. - - - -## Perform a Review **(PREMIUM)** - -Start a review in order to create multiple comments on a diff and publish them once you're ready. -Starting a review allows you to get all your thoughts in order and ensure you haven't missed anything -before submitting all your comments. - -[Learn more about Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) - -## Squash and merge - -GitLab allows you to squash all changes present in a merge request into a single -commit when merging, to allow for a neater commit history. - -[Learn more about squash and merge.](squash_and_merge.md) - -## Suggest changes - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/18008) in GitLab 11.6. - -As a reviewer, you can add suggestions to change the content in -merge request threads, and users with appropriate [permission](../../permissions.md) -can easily apply them to the codebase directly from the UI. Read -through the documentation on [Suggest changes](../../discussions/index.md#suggest-changes) -to learn more. - -## Multiple assignees **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) -in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). - -Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests to indicate everyone that is reviewing or accountable for it. - - - -To assign multiple assignees to a merge request: - -1. From a merge request, expand the right sidebar and locate the **Assignees** section. -1. Click on **Edit** and from the dropdown menu, select as many users as you want - to assign the merge request to. - -Similarly, assignees are removed by deselecting them from the same dropdown menu. - -It's also possible to manage multiple assignees: - -- When creating a merge request. -- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). - -## Resolve conflicts - -When a merge request has conflicts, GitLab may provide the option to resolve -those conflicts in the GitLab UI. - -[Learn more about resolving merge conflicts in the UI.](resolve_conflicts.md) - -## Create new merge requests by email - -_This feature needs [incoming email](../../../administration/incoming_email.md) -to be configured by a GitLab administrator to be available for CE/EE users, and -it's available on GitLab.com._ - -You can create a new merge request by sending an email to a user-specific email -address. The address can be obtained on the merge requests page by clicking on -a **Email a new merge request to this project** button. The subject will be -used as the source branch name for the new merge request and the target branch -will be the default branch for the project. The message body (if not empty) -will be used as the merge request description. You need -["Reply by email"](../../../administration/reply_by_email.md) enabled to use -this feature. If it's not enabled to your instance, you may ask your GitLab -administrator to do so. - -This is a private email address, generated just for you. **Keep it to yourself** -as anyone who gets ahold of it can create issues or merge requests as if they were you. -You can add this address to your contact list for easy access. - - - -_In GitLab 11.7, we updated the format of the generated email address. -However the older format is still supported, allowing existing aliases -or contacts to continue working._ - -### Adding patches when creating a merge request via e-mail - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22723) in GitLab 11.5. - -You can add commits to the merge request being created by adding -patches as attachments to the email. All attachments with a filename -ending in `.patch` will be considered patches and they will be processed -ordered by name. - -The combined size of the patches can be 2MB. - -If the source branch from the subject does not exist, it will be -created from the repository's HEAD or the specified target branch to -apply the patches. The target branch can be specified using the -[`/target_branch` quick action](../quick_actions.md). If the source -branch already exists, the patches will be applied on top of it. - -## Use Git push options with merge requests - -Use [Git push options](../push_options.md) to create or update merge requests when -pushing changes to GitLab with Git, without needing to use the GitLab interface. - -## Find the merge request that introduced a change - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2383) in GitLab 10.5. - -When viewing the commit details page, GitLab will link to the merge request (or -merge requests, if it's in more than one) containing that commit. - -This only applies to commits that are in the most recent version of a merge -request - if a commit was in a merge request, then rebased out of that merge -request, they will not be linked. - -[Read more about merge request versions](versions.md) - -## Revert changes - -GitLab implements Git's powerful feature to revert any commit with introducing -a **Revert** button in merge requests and commit details. - -[Learn more about reverting changes in the UI](revert_changes.md) - -## Merge requests versions - -Every time you push to a branch that is tied to a merge request, a new version -of merge request diff is created. When you visit a merge request that contains -more than one pushes, you can select and compare the versions of those merge -request diffs. - -[Read more about merge request versions](versions.md) - -## Work In Progress merge requests - -To prevent merge requests from accidentally being accepted before they're -completely ready, GitLab blocks the "Accept" button for merge requests that -have been marked as a **Work In Progress**. - -[Learn more about setting a merge request as "Work In Progress".](work_in_progress_merge_requests.md) - -## Merge Requests for Confidential Issues - -Create [merge requests to resolve confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) -for preventing leakage or early release of sensitive data through regular merge requests. - -## Merge request approvals **(STARTER)** - -> Included in [GitLab Starter](https://about.gitlab.com/product/). - -If you want to make sure every merge request is approved by one or more people, -you can enforce this workflow by using merge request approvals. Merge request -approvals allow you to set the number of necessary approvals and predefine a -list of approvers that will need to approve every merge request in a project. - -[Read more about merge request approvals.](merge_request_approvals.md) - -## Code Quality **(STARTER)** - -> Introduced in [GitLab Starter](https://about.gitlab.com/product/) 9.3. - -If you are using [GitLab CI][ci], you can analyze your source code quality using -the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab -can show the Code Climate report right in the merge request widget area. - -[Read more about Code Quality reports.](code_quality.md) - -## Metrics Reports **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9788) in [GitLab Premium](https://about.gitlab.com/product/) 11.10. -Requires GitLab Runner 11.10 and above. - -If you are using [GitLab CI][ci], you can configure your job to output custom -metrics and GitLab will display the Metrics Report on the merge request so -that it's fast and easy to identify changes to important metrics. - -[Read more about Metrics Report](../../../ci/metrics_reports.md). - -## Browser Performance Testing **(PREMIUM)** - -> Introduced in [GitLab Premium](https://about.gitlab.com/product/) 10.3. - -If your application offers a web interface and you are using [GitLab CI/CD][ci], you can quickly determine the performance impact of pending code changes. GitLab uses [Sitespeed.io][sitespeed], a free and open source tool for measuring the performance of web sites, to analyze the performance of specific pages. - -GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the difference in overall performance scores between the source and target branches. - -[Read more about Browser Performance Testing.](browser_performance_testing.md) - -## Merge Request Dependencies **(PREMIUM)** - -> Introduced in [GitLab Premium](https://about.gitlab.com/product/) 12.2. - -A single logical change may be split across several merge requests, across -several projects. When this happens, the order in which MRs are merged is -important. - -GitLab allows you to specify that a merge request depends on other MRs. With -this relationship in place, the merge request cannot be merged until all of its -dependencies have also been merged, helping to maintain the consistency of a -single logical change. - -[Read more about merge request dependencies.](merge_request_dependencies.md) - -## Security reports **(ULTIMATE)** - -GitLab can scan and report any vulnerabilities found in your project. - -[Read more about security reports.](../../application_security/index.md) - -## JUnit test reports - -Configure your CI jobs to use JUnit test reports, and let GitLab display a report -on the merge request so that it’s easier and faster to identify the failure -without having to check the entire job log. - -[Read more about JUnit test reports](../../../ci/junit_test_reports.md). - -## Merge request diff file navigation - -When reviewing changes in the **Changes** tab the diff can be navigated using -the file tree or file list. As you scroll through large diffs with many -changes, you can quickly jump to any changed file using the file tree or file -list. - - - -### Incrementally expand merge request diffs - -By default, the diff shows only the parts of a file which are changed. -To view more unchanged lines above or below a change click on the -**Expand up** or **Expand down** icons. You can also click on **Show all lines** -to expand the entire file. - - - -## Ignore whitespace changes in Merge Request diff view - -If you click the **Hide whitespace changes** button, you can see the diff -without whitespace changes (if there are any). This is also working when on a -specific commit page. - - - ->**Tip:** -You can append `?w=1` while on the diffs page of a merge request to ignore any -whitespace changes. - -## Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/product/review-apps/) for your project, -you can preview the changes submitted to a feature-branch through a merge request -in a per-branch basis. No need to checkout the branch, install and preview locally; -all your changes will be available to preview by anyone with the Review Apps link. - -With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the -merge request widget takes you directly to the pages changed, making it easier and -faster to preview proposed modifications. - -[Read more about Review Apps](../../../ci/review_apps/index.md). - -## Pipelines for merge requests - -When a developer updates a merge request, a pipeline should quickly report back -its result to the developer, but often pipelines take long time to complete -because general branch pipelines contain unnecessary jobs from the merge request standpoint. -You can customize a specific pipeline structure for merge requests in order to -speed the cycle up by running only important jobs. - -Learn more about [pipelines for merge requests](../../../ci/merge_request_pipelines/index.md). - -## Pipeline status in merge requests - -If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you will be able to see: - -- Both pre and post-merge pipelines and the environment information if any. -- Which deployments are in progress. - -If there's an [environment](../../../ci/environments.md) and the application is -successfully deployed to it, the deployed environment and the link to the -Review App will be shown as well. - -### Post-merge pipeline status - -When a merge request is merged, you can see the post-merge pipeline status of -the branch the merge request was merged into. For example, when a merge request -is merged into the master branch and then triggers a deployment to the staging -environment. - -Deployments that are ongoing will be shown, as well as the deploying/deployed state -for environments. If it's the first time the branch is deployed, the link -will return a `404` error until done. During the deployment, the stop button will -be disabled. If the pipeline fails to deploy, the deployment info will be hidden. - - - -For more information, [read about pipelines](../../../ci/pipelines.md). - -## Bulk editing merge requests - -Find out about [bulk editing merge requests](../../project/bulk_editing.md). - -## Troubleshooting - -Sometimes things don't go as expected in a merge request, here are some -troubleshooting steps. - -### Merge request cannot retrieve the pipeline status - -This can occur if Sidekiq doesn't pick up the changes fast enough. - -#### Sidekiq - -Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status will update automatically. - -#### Bug - -Merge Request pipeline statuses can't be retrieved when the following occurs: - -1. A Merge Request is created -1. The Merge Request is closed -1. Changes are made in the project -1. The Merge Request is reopened - -To enable the pipeline status to be properly retrieved, close and reopen the -Merge Request again. - -## Tips - -Here are some tips that will help you be more efficient with merge requests in -the command line. - -> **Note:** -This section might move in its own document in the future. - -### Checkout merge requests locally - -A merge request contains all the history from a repository, plus the additional -commits added to the branch associated with the merge request. Here's a few -tricks to checkout a merge request locally. - -Please note that you can checkout a merge request locally even if the source -project is a fork (even a private fork) of the target project. - -#### Checkout locally by adding a Git alias - -Add the following alias to your `~/.gitconfig`: - -``` -[alias] - mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - -``` - -Now you can check out a particular merge request from any repository and any -remote. For example, to check out the merge request with ID 5 as shown in GitLab -from the `origin` remote, do: - -``` -git mr origin 5 -``` - -This will fetch the merge request into a local `mr-origin-5` branch and check -it out. - -#### Checkout locally by modifying `.git/config` for a given repository - -Locate the section for your GitLab remote in the `.git/config` file. It looks -like this: - -``` -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* -``` - -You can open the file with: - -``` -git config -e -``` - -Now add the following line to the above section: - -``` -fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -In the end, it should look like this: - -``` -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* - fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -Now you can fetch all the merge requests: - -``` -git fetch origin - -... -From https://gitlab.com/gitlab-org/gitlab-foss.git - * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 - * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 -... -``` - -And to check out a particular merge request: - -``` -git checkout origin/merge-requests/1 -``` - -All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. - -[protected branches]: ../protected_branches.md -[ci]: ../../../ci/README.md -[cc]: https://codeclimate.com/ -[cd]: https://hub.docker.com/r/codeclimate/codeclimate/ -[sitespeed]: https://www.sitespeed.io -[sitespeed-container]: https://hub.docker.com/r/sitespeedio/sitespeed.io/ -[ee]: https://about.gitlab.com/pricing/ "GitLab Enterprise Edition" diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 2aa92ba2316..76c348eb93e 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -75,9 +75,9 @@ request approval rules: 1. Click **Add approvers** to create a new approval rule. 1. Just like in [GitLab Starter](#editing-approvals), select the approval members and approvals required. 1. Give the approval rule a name that describes the set of approvers selected. -1. Click **Add approvers** to submit the new rule. +1. Click **Add approval rule** to submit the new rule. -  +  ## Multiple approval rules **(PREMIUM)** @@ -219,8 +219,6 @@ and the project level approvers are changed after a merge request is created, the merge request retains the previous approvers. However, the approvers can be changed by [editing the merge request](#overriding-the-merge-request-approvals-default-settings). ---- - The default approval settings can now be overridden when creating a [merge request](index.md) or by editing it after it's been created: diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index dab2184448a..6630179ea47 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -85,3 +85,8 @@ 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. --> + +## Use it from the command line + +You can use [Push Options](../push_options.md) to trigger this feature when +pushing. diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md new file mode 100644 index 00000000000..f693b0b1e72 --- /dev/null +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -0,0 +1,251 @@ +--- +type: index, reference +--- + +# Reviewing and managing merge requests + +Merge requests are the primary method of making changes to files in a GitLab project. +Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), +which is then reviewed, and accepted (or rejected). + +## View project merge requests + +View all the merge requests within a project by navigating to **Project > Merge Requests**. + +When you access your project's merge requests, GitLab will present them in a list, +and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#issues-and-merge-requests-per-project). + + + +## View merge requests for all projects in a group + +View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. + +You can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group) from here. + + + +## Semi-linear history merge requests + +A merge commit is created for every merge, but the branch is only merged if +a fast-forward merge is possible. This ensures that if the merge request build +succeeded, the target branch build will also succeed after merging. + +Navigate to a project's settings, select the **Merge commit with semi-linear history** +option under **Merge Requests: Merge method** and save your changes. + +## View changes between file versions + +The **Changes** tab, below the main merge request details and next to the discussion tab, +shows the changes to files between branches or commits. This view of changes to a +file is also known as a **diff**. By default, the diff view compares the file in the +merge request branch and the file in the target branch. + +The diff view includes the following: + +- The file's name and path. +- The number of lines added and deleted. +- Buttons for the following options: + - Toggle comments for this file; useful for inline reviews. + - Edit the file in the merge request's branch. + - Show full file, in case you want to look at the changes in context with the rest of the file. + - View file at the current commit. + - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). +- The changed lines, with the specific changes highlighted. + + + +### Merge request diff file navigation + +When reviewing changes in the **Changes** tab the diff can be navigated using +the file tree or file list. As you scroll through large diffs with many +changes, you can quickly jump to any changed file using the file tree or file +list. + + + +### Incrementally expand merge request diffs + +By default, the diff shows only the parts of a file which are changed. +To view more unchanged lines above or below a change click on the +**Expand up** or **Expand down** icons. You can also click on **Show all lines** +to expand the entire file. + + + +### Ignore whitespace changes in Merge Request diff view + +If you click the **Hide whitespace changes** button, you can see the diff +without whitespace changes (if there are any). This is also working when on a +specific commit page. + + + +>**Tip:** +You can append `?w=1` while on the diffs page of a merge request to ignore any +whitespace changes. + +## Commenting on any file line in merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13950) in GitLab 11.5. + +GitLab provides a way of leaving comments in any part of the file being changed +in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. + + + +## Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/product/review-apps/) for your project, +you can preview the changes submitted to a feature-branch through a merge request +in a per-branch basis. No need to checkout the branch, install and preview locally; +all your changes will be available to preview by anyone with the Review Apps link. + +With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../ci/review_apps/index.md). + +## Pipeline status in merge requests + +If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +you will be able to see: + +- Both pre and post-merge pipelines and the environment information if any. +- Which deployments are in progress. + +If there's an [environment](../../../ci/environments.md) and the application is +successfully deployed to it, the deployed environment and the link to the +Review App will be shown as well. + +### Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the master branch and then triggers a deployment to the staging +environment. + +Deployments that are ongoing will be shown, as well as the deploying/deployed state +for environments. If it's the first time the branch is deployed, the link +will return a `404` error until done. During the deployment, the stop button will +be disabled. If the pipeline fails to deploy, the deployment info will be hidden. + + + +For more information, [read about pipelines](../../../ci/pipelines.md). + +## Troubleshooting + +Sometimes things don't go as expected in a merge request, here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur if Sidekiq doesn't pick up the changes fast enough. + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status will update automatically. + +#### Bug + +Merge Request pipeline statuses can't be retrieved when the following occurs: + +1. A Merge Request is created +1. The Merge Request is closed +1. Changes are made in the project +1. The Merge Request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +Merge Request again. + +## Tips + +Here are some tips that will help you be more efficient with merge requests in +the command line. + +> **Note:** +This section might move in its own document in the future. + +### Checkout merge requests locally + +A merge request contains all the history from a repository, plus the additional +commits added to the branch associated with the merge request. Here's a few +tricks to checkout a merge request locally. + +Please note that you can checkout a merge request locally even if the source +project is a fork (even a private fork) of the target project. + +#### Checkout locally by adding a Git alias + +Add the following alias to your `~/.gitconfig`: + +``` +[alias] + mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - +``` + +Now you can check out a particular merge request from any repository and any +remote. For example, to check out the merge request with ID 5 as shown in GitLab +from the `origin` remote, do: + +``` +git mr origin 5 +``` + +This will fetch the merge request into a local `mr-origin-5` branch and check +it out. + +#### Checkout locally by modifying `.git/config` for a given repository + +Locate the section for your GitLab remote in the `.git/config` file. It looks +like this: + +``` +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* +``` + +You can open the file with: + +``` +git config -e +``` + +Now add the following line to the above section: + +``` +fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +In the end, it should look like this: + +``` +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* + fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +Now you can fetch all the merge requests: + +``` +git fetch origin + +... +From https://gitlab.com/gitlab-org/gitlab-foss.git + * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 + * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 +... +``` + +And to check out a particular merge request: + +``` +git checkout origin/merge-requests/1 +``` + +All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index fbe216c3aed..ffd0efb365a 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -35,6 +35,17 @@ changes appears as a system note.  +## Find the merge request that introduced a change + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/2383) in GitLab 10.5. + +When viewing the commit details page, GitLab will link to the merge request (or +merge requests, if it's in more than one) containing that commit. + +This only applies to commits that are in the most recent version of a merge +request - if a commit was in a merge request, then rebased out of that merge +request, they will not be linked. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 105854ccd33..21a4e3d8ead 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -12,23 +12,21 @@ Milestones allow you to organize issues and merge requests into a cohesive group ## Milestones as Agile sprints -Milestones can be used as Agile sprints. -Set the milestone start date and due date to represent -the start and end of your Agile sprint. -Set the milestone title to the name of your Agile sprint, -such as `November 2018 sprint`. -Add an issue to your Agile sprint by associating -the milestone to the issue. +Milestones can be used as Agile sprints so that you can track all issues and merge requests related to a particular sprint. To do so: + +1. Set the milestone start date and due date to represent the start and end of your Agile sprint. +1. Set the milestone title to the name of your Agile sprint, such as `November 2018 sprint`. +1. Add an issue to your Agile sprint by associating the desired milestone from the issue's right-hand sidebar. ## Milestones as releases -Milestones can be used as releases. -Set the milestone due date to represent the release date of your release. -(And leave the milestone start date blank.) -Set the milestone title to the version of your release, -such as `Version 9.4`. -Add an issue to your release by associating -the milestone to the issue. +Similarily, milestones can be used as releases. To do so: + +1. Set the milestone due date to represent the release date of your release and leave the milestone start date blank. +1. Set the milestone title to the version of your release, such as `Version 9.4`. +1. Add an issue to your release by associating the desired milestone from the issue's right-hand sidebar. + +Additionally, you can integrate milestones with GitLab's [Releases feature](../releases/index.md#releases-associated-with-milestones). ## Project milestones and group milestones @@ -103,30 +101,18 @@ When filtering by milestone, in addition to choosing a specific project mileston ## Milestone view -Not all features in the project milestone view are available in the group milestone view. This table summarizes the differences: - -| Feature | Project milestone view | Group milestone view | -|--------------------------------------|:----------------------:|:--------------------:| -| Title an description | ✓ | ✓ | -| Issues assigned to milestone | ✓ | | -| Merge requests assigned to milestone | ✓ | | -| Participants and labels used | ✓ | | -| Percentage complete | ✓ | ✓ | -| Start date and due date | ✓ | ✓ | -| Total issue time spent | ✓ | ✓ | -| Total issue weight | ✓ | | -| Burndown chart **[STARTER}** | ✓ | ✓ | - The milestone view shows the title and description. -### Project milestone features - -These features are only available for project milestones and not group milestones. +There are also tabs below these that show the following: -- Issues assigned to the milestone are displayed in three columns: Unstarted issues, ongoing issues, and completed issues. -- Merge requests assigned to the milestone are displayed in four columns: Work in progress merge requests, waiting for merge, rejected, and closed. -- Participants and labels that are used in issues and merge requests that have the milestone assigned are displayed. -- [Burndown chart](#project-burndown-charts-starter). +- Issues + Shows all issues assigned to the milestone. These are displayed in three columns: Unstarted issues, ongoing issues, and completed issues. +- Merge requests + Shows all merge requests assigned to the milestone. These are displayed in four columns: Work in progress merge requests, waiting for merge, rejected, and closed. +- Participants + Shows all assignees of issues assigned to the milestone. +- Labels + Shows all labels that are used in issues assigned to the milestone. ### Project Burndown Charts **(STARTER)** @@ -144,9 +130,8 @@ The milestone sidebar on the milestone view shows the following: - Percentage complete, which is calculated as number of closed issues divided by total number of issues. - The start date and due date. -- The total time spent on all issues that have the milestone assigned. - -For project milestones only, the milestone sidebar shows the total issue weight of all issues that have the milestone assigned. +- The total time spent on all issues assigned to the milestone. +- The total issue weight of all issues assigned to the milestone.  diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 1b319c5641c..04eda026bc3 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -6,7 +6,7 @@ Error tracking allows developers to easily discover and view the errors that the ## Sentry error tracking -[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab, to allow users to view a list of Sentry errors in GitLab itself. +[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab, to allow users to view a list of Sentry errors in GitLab. ### Deploying Sentry @@ -20,6 +20,7 @@ You will need at least Maintainer [permissions](../../permissions.md) to enable GitLab provides an easy way to connect Sentry to your project: 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. +1. [Create](https://docs.sentry.io/guides/integrate-frontend/create-new-project/) a new Sentry project. For each GitLab project that you want to integrate, we recommend that you create a new Sentry project. 1. [Find or generate](https://docs.sentry.io/api/auth/) a Sentry auth token for your Sentry project. Make sure to give the token at least the following scopes: `event:read` and `project:read`. 1. Navigate to your project’s **Settings > Operations**. @@ -31,11 +32,27 @@ GitLab provides an easy way to connect Sentry to your project: 1. Click **Save changes** for the changes to take effect. 1. You can now visit **Operations > Error Tracking** in your project's sidebar to [view a list](#error-tracking-list) of Sentry errors. +### Enabling Gitlab issues links + +You may also want to enable Sentry's GitLab integration by following the steps in the [Sentry documentation](https://docs.sentry.io/workflow/integrations/global-integrations/#gitlab) + ## Error Tracking List NOTE: **Note:** You will need at least Reporter [permissions](../../permissions.md) to view the Error Tracking list. The Error Tracking list may be found at **Operations > Error Tracking** in your project's sidebar. +Errors can be filtered by title.  + +## Error Details + +From error list, users can navigate to the error details page by clicking the title of any error. + +This page has: + +- A link to Sentry issue. +- A full stack trace along with other details. + + diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index 08df92959c3..c05f8fa8bc4 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -81,7 +81,14 @@ NOTE: **NOTE** We'd highly recommend you to use the [Environment](../../../ci/environments.md) feature in order to quickly assess which flag is enabled per environment. -## Rollout strategy +## Feature Flag strategies + +GitLab Feature Flag adopts [Unleash](https://unleash.github.io) +as the feature flag engine. In unleash, there is a concept of rulesets for granular feature flag controls, +called [strategies](https://unleash.github.io/docs/activation_strategy). +Supported strategies for GitLab Feature Flags are described below. + +### Rollout strategy > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8240) in GitLab 12.2. @@ -91,13 +98,13 @@ The status of an environment spec ultimately determines whether or not a feature For instance, a feature will always be disabled for every user if the matching environment spec has a disabled status, regardless of the chosen rollout strategy. However, a feature will be enabled for 50% of logged-in users if the matching environment spec has an enabled status along with a **Percent rollout (logged in users)** strategy set to 50%. -### All users +#### All users Enables the feature for all users. It is implemented using the Unleash [`default`](https://unleash.github.io/docs/activation_strategy#default) activation strategy. -### Percent rollout (logged in users) +#### Percent rollout (logged in users) Enables the feature for a percentage of authenticated users. It is implemented using the Unleash @@ -112,7 +119,7 @@ CAUTION: **Caution:** If this strategy is selected, then the Unleash client **must** be given a user ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below. -## Target users +### Target users strategy > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/8240) in GitLab 12.2. @@ -134,7 +141,7 @@ In order to use Feature Flags, you need to first [get the access credentials](#configuring-feature-flags) from GitLab and then prepare your application and hook it with a [client library](#client-libraries). -### Configuring Feature Flags +## Configuring Feature Flags To get the access credentials that your application will need to talk to GitLab: @@ -153,7 +160,7 @@ if **Instance ID** will be single token or multiple tokens, assigned to the **Environment**. Also, **Application name** could describe the version of application instead of the running environment. -### Client libraries +## Client libraries GitLab currently implements a single backend that is compatible with [Unleash](https://github.com/Unleash/unleash#client-implementations) clients. @@ -178,7 +185,7 @@ Community contributed clients: - [Unofficial .Net Core Unleash client](https://github.com/onybo/unleash-client-core) - [Unleash client for Python 3](https://github.com/aes/unleash-client-python) -### Golang application example +## Golang application example Here's an example of how to integrate the feature flags in a Golang application: @@ -219,7 +226,7 @@ func main() { } ``` -### Ruby application example +## Ruby application example Here's an example of how to integrate the feature flags in a Ruby application. @@ -249,3 +256,11 @@ else puts "hello, world!" end ``` + +## Feature Flags API + +You can create, update, read, and delete Feature Flags via API +to control them in an automated flow: + +- [Feature Flags API](../../../api/feature_flags.md) +- [Feature Flag Specs API](../../../api/feature_flag_specs.md) diff --git a/doc/user/project/operations/img/error_details_v12_5.png b/doc/user/project/operations/img/error_details_v12_5.png Binary files differnew file mode 100644 index 00000000000..5e3e6300640 --- /dev/null +++ b/doc/user/project/operations/img/error_details_v12_5.png diff --git a/doc/user/project/operations/img/error_tracking_list.png b/doc/user/project/operations/img/error_tracking_list.png Binary files differindex 194c7b440a4..79b464e021e 100644 --- a/doc/user/project/operations/img/error_tracking_list.png +++ b/doc/user/project/operations/img/error_tracking_list.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 326a2d302d2..2f16606c5a8 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -169,6 +169,22 @@ from the GitLab project. in place: your domain will be periodically reverified, and may be disabled if the record is removed. +##### Troubleshooting Pages domain verification + +To manually verify that you have properly configured the domain verification +`TXT` DNS entry, you can run the following command in your terminal: + +``` +dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT +``` + +Expect the output: + +``` +;; ANSWER SECTION: +_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" +``` + ### Adding more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. 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 c9b504dc6ee..1d64e843e46 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 @@ -5,7 +5,8 @@ description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." # GitLab Pages integration with Let's Encrypt -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). +This feature is in **beta** and may still have bugs. See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) for more information. The GitLab Pages integration with Let's Encrypt (LE) allows you to use LE certificates for your Pages website with custom domains @@ -16,19 +17,11 @@ GitLab does it for you, out-of-the-box. 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-foss/issues/64870). -See all the related issues linked from this [issue's description](https://gitlab.com/gitlab-org/gitlab-foss/issues/28996) -for more information. - -CAUTION: **Caution:** -This feature covers only certificates for **custom domains**, -not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. -Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3342). +This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3342). ## Requirements -Before you can enable automatic provisioning of a SSL certificate for your domain, make sure you have: +Before you can enable automatic provisioning of an SSL certificate for your domain, make sure you have: - Created a [project](../getting_started_part_two.md) in GitLab containing your website's source code. @@ -36,7 +29,7 @@ Before you can enable automatic provisioning of a SSL certificate for your domai pointing it to your Pages website. - [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) and verified your ownership. -- Have your website up and running, accessible through your custom domain. +- Verified your website is up and running, accessible through your custom domain. NOTE: **Note:** GitLab's Let's Encrypt integration is enabled and available on GitLab.com. @@ -45,7 +38,7 @@ For **self-managed** GitLab instances, make sure your administrator has ## Enabling Let's Encrypt integration for your custom domain -Once you've met the requirements, to enable Let's Encrypt integration: +Once you've met the requirements, enable Let's Encrypt integration: 1. Navigate to your project's **Settings > Pages**. 1. Find your domain and click **Details**. diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md new file mode 100644 index 00000000000..ac1a29ca2a0 --- /dev/null +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -0,0 +1,61 @@ +--- +type: reference, howto +--- + +# New Pages website from a forked sample + +To get started with GitLab Pages from a sample website, the easiest +way to do it is by using one of the [bundled templates](pages_bundled_template.md). +If you don't find one that suits your needs, you can opt by +forking (copying) a [sample project from the most popular Static Site Generators](https://gitlab.com/pages). + +<table class="borderless-table center fixed-table middle width-80"> + <tr> + <td style="width: 30%"><img src="../img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="../img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="../img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> + </tr> + <tr> + <td><em>Fork an example project</em></td> + <td></td> + <td><em>Deploy your website</em></td> + <td></td> + <td><em>Visit your website's URL</em></td> + </tr> +</table> + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps below.** + +1. [Fork](../../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. +1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** + and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + site to the server. +1. Once the pipeline has finished successfully, find the link to visit your + website from your project's **Settings > Pages**. It can take aproximatelly + 30 minutes to be deployed. + +You can also take some **optional** further steps: + +- _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: + +  + +- _Make it a user or group website._ To turn a **project website** forked + from the Pages group into a **user/group** website, you'll need to: + - Rename it to `namespace.gitlab.io`: go to your project's + **Settings > General** and expand **Advanced**. Scroll down to + **Rename repository** and change the path to `namespace.gitlab.io`. + - Adjust your SSG's [base URL](../getting_started_part_one.md#urls-and-baseurls) from `"project-name"` to + `""`. This setting will be at a different place for each SSG, as each of them + have their own structure and file tree. Most likely, it will be in the SSG's + config file. diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md new file mode 100644 index 00000000000..62b5fa33117 --- /dev/null +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -0,0 +1,45 @@ +--- +type: reference, howto +--- + +# Start a new Pages website from scratch or deploy an existing website + +If you already have a website and want to deploy it with GitLab Pages, +or, if you want to start a new site from scratch, you'll need to: + +- Create a new project in GitLab to hold your site content. +- Set up GitLab CI/CD to deploy your website to Pages. + +To do so, follow the steps below. + +1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, + click **New project**, and name it according to the + [Pages domain names](../getting_started_part_one.md#gitlab-pages-default-domain-names). +1. Clone it to your local computer, add your website + files to your project, add, commit and push to GitLab. + Alternativelly, you can run `git init` in your local directory, + add the remote URL: + `git remote add origin git@gitlab.com:namespace/project-name.git`, + then add, commit, and push to GitLab. +1. From the your **Project**'s page, click **Set up CI/CD**: + +  + +1. Choose one of the templates from the dropbox menu. + Pick up the template corresponding to the SSG you're using (or plain HTML). + +  + + Note that, if you don't find a corresponding template, you can look into + [GitLab Pages group of sample projects](https://gitlab.com/pages), + you may find one among them that suits your needs, from which you + can copy `.gitlab-ci.yml`'s content and adjust for your case. + If you don't find it there either, [learn how to write a `.gitlab-ci.yml` + file for GitLab Pages](../getting_started_part_four.md). + +Once you have both site files and `.gitlab-ci.yml` in your project's +root, GitLab CI/CD will build your site and deploy it with Pages. +Once the first build passes, you access your site by +navigating to your **Project**'s **Settings** > **Pages**, +where you'll find its default URL. It can take approximately 30 min to be +deployed. diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md new file mode 100644 index 00000000000..802abeb3cc2 --- /dev/null +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -0,0 +1,29 @@ +--- +type: reference, howto +--- + +# New Pages website from a bundled template + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) +in GitLab 11.8. + +The simplest way to create a GitLab Pages site is to use one of the most +popular templates, which come already bundled with GitLab and are ready to go. + +1. From the top navigation, click the **+** button and select **New project**. +1. Select **Create from Template**. +1. Choose one of the templates starting with **Pages**: + +  + +1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** + and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + site to the server. +1. After the pipeline has finished successfully, wait approximately 30 minutes + for your website to be visible. After waiting 30 minutes, find the link to + visit your website from your project's **Settings > Pages**. If the link + leads to a 404 page, wait a few minutes and try again. + +Your website is then visible on your domain and you can modify your files +as you wish. For every modification pushed to your repository, GitLab CI/CD +will run a new pipeline to immediately publish your changes to the server. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 0b1cae9ab4c..b876e547ba5 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -3,25 +3,12 @@ last_updated: 2018-06-04 type: concepts, reference --- -# Static sites and GitLab Pages domains +# GitLab Pages domain names, URLs, and baseurls On this document, learn how to name your project for GitLab Pages according to your intended website's URL. -## Static sites - -GitLab Pages only supports static websites, meaning, -your output files must be HTML, CSS, and JavaScript only. - -To create your static site, you can either hardcode in HTML, -CSS, and JS, or use a [Static Site Generator (SSG)](https://www.staticgen.com/) -to simplify your code and build the static site for you, -which is highly recommendable and much faster than hardcoding. - -See the [further reading](#further-reading) section below for -references on static site concepts. - -## GitLab Pages domain names +## GitLab Pages default domain names >**Note:** If you use your own GitLab instance to deploy your @@ -93,11 +80,35 @@ To understand Pages domains clearly, read the examples below. - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. -_Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._ +## URLs and baseurls + +Every Static Site Generator (SSG) default configuration expects +to find your website under a (sub)domain (`example.com`), not +in a subdirectory of that domain (`example.com/subdir`). Therefore, +whenever you publish a project website (`namespace.gitlab.io/project-name`), +you'll have to look for this configuration (base URL) on your SSG's +documentation and set it up to reflect this pattern. + +For example, for a Jekyll site, the `baseurl` is defined in the Jekyll +configuration file, `_config.yml`. If your website URL is +`https://john.gitlab.io/blog/`, you need to add this line to `_config.yml`: + +```yaml +baseurl: "/blog" +``` + +On the contrary, if you deploy your website after forking one of +our [default examples](https://gitlab.com/pages), the baseurl will +already be configured this way, as all examples there are project +websites. If you decide to make yours a user or group website, you'll +have to remove this configuration from your project. For the Jekyll +example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: + +```yaml +baseurl: "" +``` -### Further reading +## Custom domains -- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) -- Understand [how modern Static Site Generators work](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) and what you can add to your static site -- You can use [any SSG with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) -- Fork an [example project](https://gitlab.com/pages) to build your website based upon +GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. +See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information. diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index ff752917087..70e84f5d486 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -1,172 +1,5 @@ --- -last_updated: 2019-06-04 -type: reference, howto +redirect_to: 'index.md' --- -# Projects for GitLab Pages and URL structure - -## What you need to get started - -To get started with GitLab Pages, you need: - -1. A project, thus a repository to hold your website's codebase. -1. A configuration file (`.gitlab-ci.yml`) to deploy your site. -1. A specific `job` called `pages` in the configuration file - that will make GitLab aware that you are deploying a GitLab Pages website. -1. A `public` directory with the static content of the website. - -Optional Features: - -1. A custom domain or subdomain. -1. A DNS pointing your (sub)domain to your Pages site. - 1. **Optional**: an SSL/TLS certificate so your custom - domain is accessible under HTTPS. - -The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md)). - -## Project - -Your GitLab Pages project is a regular project created the -same way you do for the other ones. To get started with GitLab Pages, you have three ways: - -- [Use one of the popular project templates bundled with GitLab](#use-one-of-the-popular-pages-templates-bundled-with-gitlab). -- [Fork one of the templates from Page Examples](#fork-a-project-to-get-started-from). -- [Create a new project from scratch](#create-a-project-from-scratch). - -### Use one of the popular Pages templates bundled with GitLab - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/47857) -in GitLab 11.8. - -The simplest way to create a GitLab Pages site is to -[use one of the most popular templates](index.md#getting-started), -which come already bundled with GitLab and are ready to go. - -### Fork a project to get started from - -If you don't find an existing project template that suits you, -we've created this [group](https://gitlab.com/pages) of default projects -containing the most popular SSGs templates to get you started. - -<table class="borderless-table center fixed-table middle width-80"> - <tr> - <td style="width: 30%"><img src="img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> - <td style="width: 10%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 30%"><img src="img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> - </tr> - <tr> - <td><em>Fork an example project</em></td> - <td></td> - <td><em>Deploy your website</em></td> - <td></td> - <td><em>Visit your website's URL</em></td> - </tr> -</table> - -**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps below.** - -1. [Fork](../../../gitlab-basics/fork-project.md) a sample project from the [GitLab Pages examples](https://gitlab.com/pages) group. -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site to the server. -1. Once the pipeline has finished successfully, find the link to visit your - website from your project's **Settings > Pages**. - -You can also take some **optional** further steps: - -- _Remove the fork relationship._ The fork relationship is necessary to contribute back to the project you originally forked from. If you don't have any intentions to do so, you can remove it. To do so, navigate to your project's **Settings**, expand **Advanced settings**, and scroll down to **Remove fork relationship**: - -  - -- _Make it a user or group website._ To turn a **project website** forked - from the Pages group into a **user/group** website, you'll need to: - - Rename it to `namespace.gitlab.io`: go to your project's - **Settings > General** and expand **Advanced**. Scroll down to - **Rename repository** and change the path to `namespace.gitlab.io`. - - Adjust your SSG's [base URL](#urls-and-baseurls) from `"project-name"` to - `""`. This setting will be at a different place for each SSG, as each of them - have their own structure and file tree. Most likely, it will be in the SSG's - config file. - -### Create a project from scratch - -1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, - click **New project**, and name it according to the - [Pages domain names](getting_started_part_one.md#gitlab-pages-domain-names). -1. Clone it to your local computer, add your website - files to your project, add, commit and push to GitLab. -1. From the your **Project**'s page, click **Set up CI/CD**: - -  - -1. Choose one of the templates from the dropbox menu. - Pick up the template corresponding to the SSG you're using (or plain HTML). - -  - -Once you have both site files and `.gitlab-ci.yml` in your project's -root, GitLab CI/CD will build your site and deploy it with Pages. -Once the first build passes, you see your site is live by -navigating to your **Project**'s **Settings** > **Pages**, -where you'll find its default URL. - -> **Notes:** -> -> - GitLab Pages [supports any SSG](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/), but, -> if you don't find yours among the templates, you'll need -> to configure your own `.gitlab-ci.yml`. To do that, please -> read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among -> the [example projects](https://gitlab.com/pages). If you set -> up a new one, please -> [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md) -> to our examples. -> -> - The second step _"Clone it to your local computer"_, can be done -> differently, achieving the same results: instead of cloning the bare -> repository to you local computer and moving your site files into it, -> you can run `git init` in your local website directory, add the -> remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, -> then add, commit, and push to GitLab. - -## URLs and Baseurls - -Every Static Site Generator (SSG) default configuration expects -to find your website under a (sub)domain (`example.com`), not -in a subdirectory of that domain (`example.com/subdir`). Therefore, -whenever you publish a project website (`namespace.gitlab.io/project-name`), -you'll have to look for this configuration (base URL) on your SSG's -documentation and set it up to reflect this pattern. - -For example, for a Jekyll site, the `baseurl` is defined in the Jekyll -configuration file, `_config.yml`. If your website URL is -`https://john.gitlab.io/blog/`, you need to add this line to `_config.yml`: - -```yaml -baseurl: "/blog" -``` - -On the contrary, if you deploy your website after forking one of -our [default examples](https://gitlab.com/pages), the baseurl will -already be configured this way, as all examples there are project -websites. If you decide to make yours a user or group website, you'll -have to remove this configuration from your project. For the Jekyll -example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: - -```yaml -baseurl: "" -``` - -## Custom Domains - -GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. -See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information. +This document was moved to [another location](index.md#getting-started). diff --git a/doc/user/project/pages/img/new_project_for_pages_v12_5.png b/doc/user/project/pages/img/new_project_for_pages_v12_5.png Binary files differnew file mode 100644 index 00000000000..8d2dc0bf9f5 --- /dev/null +++ b/doc/user/project/pages/img/new_project_for_pages_v12_5.png diff --git a/doc/user/project/pages/img/pages_workflow_v12_5.png b/doc/user/project/pages/img/pages_workflow_v12_5.png Binary files differnew file mode 100644 index 00000000000..ca5190fca79 --- /dev/null +++ b/doc/user/project/pages/img/pages_workflow_v12_5.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 7d533c6f9d1..abd67c90dd6 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -19,38 +19,7 @@ You can use it either for personal or business websites, such as portfolios, documentation, manifestos, and business presentations. You can also attribute any license to your content. -<table class="borderless-table center fixed-table"> - <tr> - <td style="width: 22%"><img src="img/icons/cogs.png" alt="SSGs" class="image-noshadow half-width"></td> - <td style="width: 4%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 22%"><img src="img/icons/monitor.png" alt="Websites" class="image-noshadow half-width"></td> - <td style="width: 4%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 22%"><img src="img/icons/free.png" alt="Pages is free" class="image-noshadow half-width"></td> - <td style="width: 4%"> - <strong> - <i class="fa fa-angle-double-right" aria-hidden="true"></i> - </strong> - </td> - <td style="width: 22%"><img src="img/icons/lock.png" alt="Secure your website" class="image-noshadow half-width"></td> - </tr> - <tr> - <td><em>Use any static website generator or plain HTML</em></td> - <td></td> - <td><em>Create websites for your projects, groups, or user account</em></td> - <td></td> - <td><em>Host on GitLab.com for free, or on your own GitLab instance</em></td> - <td></td> - <td><em>Connect your custom domain(s) and TLS certificates</em></td> - </tr> -</table> +<img src="img/pages_workflow_v12_5.png" alt="Pages websites workflow" class="image-noshadow"> Pages is available for free for all GitLab.com users as well as for self-managed instances (GitLab Core, Starter, Premium, and Ultimate). @@ -73,6 +42,7 @@ publish any website written directly in plain HTML, CSS, and JavaScript.</p> To use GitLab Pages, first you need to create a project in GitLab to upload your website's files to. These projects can be either public, internal, or private, at your own choice. + GitLab will always deploy your website from a very specific folder called `public` in your repository. Note that when you create a new project in GitLab, a [repository](../repository/index.md) becomes available automatically. @@ -80,67 +50,50 @@ becomes available automatically. To deploy your site, GitLab will use its built-in tool called [GitLab CI/CD](../../../ci/README.md), to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named -`.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. +`.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. -You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain-names), +You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), `*.gitlab.io`, or your own domain (`example.com`). In that case, you'll need admin access to your domain's registrar (or control panel) to set it up with Pages. -Optionally, when adding your own domain, you can add an SSL/TLS certificate to secure your -site under the HTTPS protocol. - ### Getting started To get started with GitLab Pages, you can either: -- [Create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch). -- [Copy an existing example project](getting_started_part_two.md#fork-a-project-to-get-started-from). -- Use a bundled project template ready to go: - -1. From the top navigation, click the **+** button and select **New project**. -1. Select **Create from Template**. -1. Choose one of the templates starting with **Pages**: - -  +- [Use a bundled website template ready to go](getting_started/pages_bundled_template.md). +- [Copy an existing sample](getting_started/fork_sample_project.md). +- [Create a website from scratch or deploy an existing one](getting_started/new_or_existing_website.md). -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your - site to the server. -1. After the pipeline has finished successfully, wait approximately 30 minutes - for your website to be visible. After waiting 30 minutes, find the link to - visit your website from your project's **Settings > Pages**. If the link - leads to a 404 page, wait a few minutes and try again. +<img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages" class="image-noshadow"> -Your website is then visible on your domain and you can modify your files -as you wish. For every modification pushed to your repository, GitLab CI/CD -will run a new pipeline to immediately publish your changes to the server. +Optional features: -_Advanced options:_ +- Use a [custom domain or subdomain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain). +- Add an [SSL/TLS certificate to secure your site under the HTTPS protocol](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages). -- [Use a custom domain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) -- Apply [SSL/TLS certification](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages) to your custom domain +Note that, if you're using GitLab Pages default domain (`.gitlab.io`), +your website will be automatically secure and available under +HTTPS. If you're using your own custom domain, you can +optionally secure it with SSL/TLS certificates. ## Availability If you're using GitLab.com, your website will be publicly available to the internet. + +To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). + If you're using self-managed instances (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the [Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, who can opt for making them public or internal to your server. -Note that, if you're using GitLab Pages default domain (`.gitlab.io`), -your website will be automatically secure and available under -HTTPS. If you're using your own custom domain, you can -optionally secure it with SSL/TLS certificates. - ## Explore GitLab Pages To learn more about configuration options for GitLab Pages, read the following: | Document | Description | | --- | --- | -| [Static websites and Pages domains](getting_started_part_one.md) | Understand what is a static website, and how GitLab Pages default domains work. | -| [Projects and URL structure](getting_started_part_two.md) | Forking projects and creating new ones from scratch, understanding URLs structure and baseurls. | +| [GitLab Pages domain names, URLs, and baseurls](getting_started_part_one.md) | Understand how GitLab Pages default domains work. | | [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. | | [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, Access Control, custom 404 pages, limitations, FAQ. | |---+---| diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 86257e2aa03..01e1909f6d6 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -69,40 +69,7 @@ don't have to create and edit HTML files manually. For example, Jekyll has the ## GitLab Pages Access Control **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. - -You can enable Pages access control on your project, so that only -[members of your project](../../permissions.md#project-members-permissions) -(at least Guest) can access your website: - -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). - -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. - -1. Click **Save changes**. - ---- - -The next time someone tries to access your website and the access control is -enabled, they will be presented with a page to sign into GitLab and verify they -can access the website. +To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). ## Unpublishing your Pages diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 1338c7e58f5..c9bd3e35a5f 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -21,8 +21,8 @@ open source Certificate Authority. To follow along with this tutorial, we assume you already have: -- Created a [project](getting_started_part_two.md) in GitLab which - contains your website's source code. +- [Created a project](index.md#getting-started) in GitLab + containing your website's source code. - Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) pointing it to your Pages website. - [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps) diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md new file mode 100644 index 00000000000..cd715c6e3b9 --- /dev/null +++ b/doc/user/project/pages/pages_access_control.md @@ -0,0 +1,48 @@ +--- +type: reference, howto +--- + +# GitLab Pages Access Control + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/33422) in GitLab 11.5. +> - Available on GitLab.com in GitLab 12.4. + +You can enable Pages access control on your project, so that only +[members of your project](../../permissions.md#project-members-permissions) +(at least Guest) can access your website: + +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). + +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. + +1. Click **Save changes**. + +The next time someone tries to access your website and the access control is +enabled, they will be presented with a page to sign into GitLab and verify they +can access the website. + +## Terminating a Pages session + +If you want to log out from your Pages website, +you can do so by revoking application access token for GitLab Pages: + +1. Navigate to your profile's **Settings > Applications**. +1. Find **Authorized applications** at the bottom of the page. +1. Find **GitLab Pages** and press the **Revoke** button. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index b7c9faeb1df..8ce575222b9 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -55,7 +55,7 @@ the actions that different roles can perform with the protected branch. For example, you could set "Allowed to push" to "No one", and "Allowed to merge" to "Developers + Maintainers", to require _everyone_ to submit a merge request for changes going into the protected branch. This is compatible with workflows like -the [GitLab workflow](../../workflow/gitlab_flow.md). +the [GitLab workflow](../../topics/gitlab_flow.md). However, there are workflows where that is not needed, and only protecting from force pushes and branch removal is useful. For those workflows, you can allow @@ -118,10 +118,11 @@ all matching branches: When a protected branch or wildcard protected branches are set to [**No one** is **Allowed to push**](#using-the-allowed-to-merge-and-allowed-to-push-settings), -Developers (and users with higher [permission levels](../permissions.md)) are allowed -to create a new protected branch, but only via the UI or through the API (to avoid -creating protected branches accidentally from the command line or from a Git -client application). +Developers (and users with higher [permission levels](../permissions.md)) are +allowed to create a new protected branch as long as they are +[**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings). +This can only be done via the UI or through the API (to avoid creating protected +branches accidentally from the command line or from a Git client application). To create a new branch through the user interface: diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 51c46dbd1d4..8952f845b96 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -75,3 +75,33 @@ merge request, and target a branch named `my-target-branch`: ```shell git push -o merge_request.create -o merge_request.target=my-target-branch ``` + +Additionally if you want the merge request to merge as soon as the pipeline succeeds you can do: + +```shell +git push -o merge_request.create -o merge_request.target=my-target-branch -o merge_request.merge_when_pipeline_succeeds +``` + +## Useful Git aliases + +As shown above, Git push options can cause Git commands to grow very long. If +you use the same push options frequently, it's useful to create [Git +aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases). Git aliases +are command line shortcuts for Git which can significantly simplify the use of +long Git commands. + +### Merge when pipeline succeeds alias + +To set up a Git alias for the [merge when pipeline succeeds Git push +option](#push-options-for-merge-requests): + +```shell +git config --global alias.mwps "push -o merge_request.create -o merge_request.target=master -o merge_request.merge_when_pipeline_succeeds" +``` + +Then to quickly push a local branch that will target master and merge when the +pipeline succeeds: + +```shell +git mwps origin <local-branch-name> +``` diff --git a/doc/user/project/releases/img/edit_release_page_v12_5.png b/doc/user/project/releases/img/edit_release_page_v12_5.png Binary files differnew file mode 100644 index 00000000000..8b9c502a2ef --- /dev/null +++ b/doc/user/project/releases/img/edit_release_page_v12_5.png diff --git a/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png b/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png Binary files differnew file mode 100644 index 00000000000..2e3ec08ba87 --- /dev/null +++ b/doc/user/project/releases/img/milestone_list_with_releases_v12_5.png diff --git a/doc/user/project/releases/img/milestone_with_releases_v12_5.png b/doc/user/project/releases/img/milestone_with_releases_v12_5.png Binary files differnew file mode 100644 index 00000000000..8719a58ce4e --- /dev/null +++ b/doc/user/project/releases/img/milestone_with_releases_v12_5.png diff --git a/doc/user/project/releases/img/new_tag_12_5.png b/doc/user/project/releases/img/new_tag_12_5.png Binary files differnew file mode 100644 index 00000000000..6137ad2ee56 --- /dev/null +++ b/doc/user/project/releases/img/new_tag_12_5.png diff --git a/doc/user/project/releases/img/release_edit_button_v12_5.png b/doc/user/project/releases/img/release_edit_button_v12_5.png Binary files differnew file mode 100644 index 00000000000..f60b0ecb1be --- /dev/null +++ b/doc/user/project/releases/img/release_edit_button_v12_5.png diff --git a/doc/user/project/releases/img/release_with_milestone_v12_5.png b/doc/user/project/releases/img/release_with_milestone_v12_5.png Binary files differnew file mode 100644 index 00000000000..2a7a2ee9754 --- /dev/null +++ b/doc/user/project/releases/img/release_with_milestone_v12_5.png diff --git a/doc/user/project/releases/img/tags_12_5.png b/doc/user/project/releases/img/tags_12_5.png Binary files differnew file mode 100644 index 00000000000..4c032f96125 --- /dev/null +++ b/doc/user/project/releases/img/tags_12_5.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index ceb077ab8af..8372aefc94c 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -58,6 +58,31 @@ links from your GitLab instance. NOTE: **NOTE** You can manipulate links of each release entry with [Release Links API](../../../api/releases/links.md) +#### Releases associated with milestones + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/29020) in GitLab 12.5. + +Releases can optionally be associated with one or more +[project milestones](../milestones/index.md#project-milestones-and-group-milestones) +by including a `milestones` array in your requests to the +[Releases API](../../../api/releases/index.md#create-a-release). + +Releases display this association with the **Milestone** indicator near +the top of the Release block on the **Project overview > Releases** page. + + + +Below is an example of milestones with no Releases, one Release, and two +Releases, respectively. + + + +This relationship is also visible in the **Releases** section of the sidebar +when viewing a specific milestone. Below is an example of a milestone +associated with a large number of Releases. + + + ## Releases list Navigate to **Project > Releases** in order to see the list of releases for a given @@ -65,6 +90,27 @@ project.  +## Editing a release + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26016) in GitLab 12.5. + +To edit the details of a release, navigate to **Project overview > Releases** and click +the edit button (pencil icon) in the top-right corner of the release you want to modify. + + + +This will bring you to the **Edit Release** page, from which you can +change some of the release's details. + + + +Currently, it is only possible to edit the release title and notes. +To change other release information, such as its tag, associated +milestones, or release date, use the +[Releases API](../../../api/releases/index.md#update-a-release). Editing this +information through the **Edit Release** page is planned for a future version +of GitLab. + ## Notification for Releases > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26001) in GitLab 12.4. @@ -77,6 +123,91 @@ following modal window will be then displayed, from which you can select **New r  +## Add release notes to Git tags + +You can add release notes to any Git tag using the notes feature. Release notes +behave like any other markdown form in GitLab so you can write text and +drag and drop files to it. Release notes are stored in GitLab's database. + +There are several ways to add release notes: + +- In the interface, when you create a new Git tag. +- In the interface, by adding a note to an existing Git tag. +- Using the GitLab API. + +To create a new tag, navigate to your project's **Repository > Tags** and +click **New tag**. From there, you can fill the form with all the information +about the release: + + + +You can also edit an existing tag to add release notes: + + + +## Release Evidence + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/26019) in GitLab 12.5. + +Each time a new release is created, specific related data is collected in +parallel. This dataset will be a snapshot this new release (including linked +milestones and issues) at moment of creation. Such collection of data will +provide a chain of custody and facilitate processes like external audits, for example. + +The gathered Evidence data is stored in the database upon creation of a new +release as a JSON object. In GitLab 12.5, a link to +the Evidence data is provided for [each Release](#releases-list). + +Here's what this object can look like: + +```json +{ + "release": { + "id": 5, + "tag": "v4.0", + "name": "New release", + "project_id": 45, + "project_name": "Project name", + "released_at": "2019-06-28 13:23:40 UTC", + "milestones": [ + { + "id": 11, + "title": "v4.0-rc1", + "state": "closed", + "due_date": "2019-05-12 12:00:00 UTC", + "created_at": "2019-04-17 15:45:12 UTC", + "issues": [ + { + "id": 82, + "title": "The top-right popup is broken", + "author_name": "John Doe", + "author_email": "john@doe.com", + "state": "closed", + "due_date": "2019-05-10 12:00:00 UTC" + }, + { + "id": 89, + "title": "The title of this page is misleading", + "author_name": "Jane Smith", + "author_email": "jane@smith.com", + "state": "closed", + "due_date": "nil" + } + ] + }, + { + "id": 12, + "title": "v4.0-rc2", + "state": "closed", + "due_date": "2019-05-30 18:30:00 UTC", + "created_at": "2019-04-17 15:45:12 UTC", + "issues": [] + } + ] + } +} +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md new file mode 100644 index 00000000000..576001d4305 --- /dev/null +++ b/doc/user/project/repository/file_finder.md @@ -0,0 +1,45 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' +--- + +# File finder + +> [Introduced][gh-9889] in GitLab 8.4. + +The file finder feature allows you to search for a file in a repository using the +GitLab UI. + +You can find the **Find File** button when in the **Files** section of a +project. + + + +For those who prefer to keep their fingers on the keyboard, there is a +[shortcut button](../../shortcuts.md) as well, which you can invoke from _anywhere_ +in a project. + +Press `t` to launch the File search function when in **Issues**, +**Merge requests**, **Milestones**, even the project's settings. + +Start typing what you are searching for and watch the magic happen. With the +up/down arrows, you go up and down the results, with `Esc` you close the search +and go back to **Files**. + +## How it works + +The File finder feature is powered by the [Fuzzy filter](https://github.com/jeancroy/fuzz-aldrin-plus) library. + +It implements a fuzzy search with highlight, and tries to provide intuitive +results by recognizing patterns that people use while searching. + +For example, consider the [GitLab CE repository][ce] and that we want to open +the `app/controllers/admin/deploy_keys_controller.rb` file. + +Using fuzzy search, we start by typing letters that get us closer to the file. + +**Protip:** To narrow down your search, include `/` in your search terms. + + + +[gh-9889]: https://github.com/gitlabhq/gitlabhq/pull/9889 "File finder pull request" +[ce]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master "GitLab CE repository" diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md new file mode 100644 index 00000000000..8756760fe4b --- /dev/null +++ b/doc/user/project/repository/forking_workflow.md @@ -0,0 +1,55 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' +--- + +# Project forking workflow + +Forking a project to your own namespace is useful if you have no write +access to the project you want to contribute to. If you do have write +access or can request it, we recommend working together in the same +repository since it is simpler. See our [GitLab Flow](../../../topics/gitlab_flow.md) +document more information about using branches to work together. + +## Creating a fork + +Forking a project is in most cases a two-step process. + +1. Click on the fork button located located in between the star and clone buttons on the project's home page. + +  + +1. Once you do that, you'll be presented with a screen where you can choose + the namespace to fork to. Only namespaces (groups and your own + namespace) where you have write access to, will be shown. Click on the + namespace to create your fork there. + +  + + **Note:** + If the namespace you chose to fork the project to has another project with + the same path name, you will be presented with a warning that the forking + could not be completed. Try to resolve the error before repeating the forking + process. + +  + +After the forking is done, you can start working on the newly created +repository. There, you will have full [Owner](../../permissions.md) +access, so you can set it up as you please. + +## Merging upstream + +Once you are ready to send your code back to the main project, you need +to create a merge request. Choose your forked project's main branch as +the source and the original project's main branch as the destination and +create the [merge request](../merge_requests/index.md). + + + +You can then assign the merge request to someone to have them review +your changes. Upon pressing the 'Submit Merge Request' button, your +changes will be added to the repository and branch you're merging into. + + + +[gitlab flow]: https://about.gitlab.com/blog/2014/09/29/gitlab-flow/ "GitLab Flow blog post" diff --git a/doc/user/project/repository/img/file_finder_find_button.png b/doc/user/project/repository/img/file_finder_find_button.png Binary files differnew file mode 100644 index 00000000000..0c2d7d7bc73 --- /dev/null +++ b/doc/user/project/repository/img/file_finder_find_button.png diff --git a/doc/user/project/repository/img/file_finder_find_file.png b/doc/user/project/repository/img/file_finder_find_file.png Binary files differnew file mode 100644 index 00000000000..c2212c7cd9e --- /dev/null +++ b/doc/user/project/repository/img/file_finder_find_file.png diff --git a/doc/user/project/repository/img/forking_workflow_branch_select.png b/doc/user/project/repository/img/forking_workflow_branch_select.png Binary files differnew file mode 100644 index 00000000000..0ea5410f832 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_branch_select.png diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace.png b/doc/user/project/repository/img/forking_workflow_choose_namespace.png Binary files differnew file mode 100644 index 00000000000..eb023ca85f2 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_choose_namespace.png diff --git a/doc/user/project/repository/img/forking_workflow_fork_button.png b/doc/user/project/repository/img/forking_workflow_fork_button.png Binary files differnew file mode 100644 index 00000000000..7fb07529b6d --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_fork_button.png diff --git a/doc/user/project/repository/img/forking_workflow_merge_request.png b/doc/user/project/repository/img/forking_workflow_merge_request.png Binary files differnew file mode 100644 index 00000000000..43851203f3f --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_merge_request.png diff --git a/doc/user/project/repository/img/forking_workflow_path_taken_error.png b/doc/user/project/repository/img/forking_workflow_path_taken_error.png Binary files differnew file mode 100644 index 00000000000..ef62d0ab6a9 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_path_taken_error.png diff --git a/doc/user/project/repository/img/repository_mirroring_copy_ssh_public_key_button.png b/doc/user/project/repository/img/repository_mirroring_copy_ssh_public_key_button.png Binary files differnew file mode 100644 index 00000000000..e20dae09a4d --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_copy_ssh_public_key_button.png diff --git a/doc/user/project/repository/img/repository_mirroring_force_update.png b/doc/user/project/repository/img/repository_mirroring_force_update.png Binary files differnew file mode 100644 index 00000000000..1e6dcb9ea08 --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_force_update.png diff --git a/doc/user/project/repository/img/repository_mirroring_pull_settings_lower.png b/doc/user/project/repository/img/repository_mirroring_pull_settings_lower.png Binary files differnew file mode 100644 index 00000000000..a3e0b74ddf8 --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_pull_settings_lower.png diff --git a/doc/user/project/repository/img/repository_mirroring_pull_settings_upper.png b/doc/user/project/repository/img/repository_mirroring_pull_settings_upper.png Binary files differnew file mode 100644 index 00000000000..8e15b5a0784 --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_pull_settings_upper.png diff --git a/doc/user/project/repository/img/repository_mirroring_push_settings.png b/doc/user/project/repository/img/repository_mirroring_push_settings.png Binary files differnew file mode 100644 index 00000000000..3c0eacaa2df --- /dev/null +++ b/doc/user/project/repository/img/repository_mirroring_push_settings.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index c14783b72bd..5a6e011220c 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -11,7 +11,8 @@ A repository is part of a [project](../index.md), which has a lot of other featu ## Create a repository To create a new repository, all you need to do is -[create a new project](../../../gitlab-basics/create-project.md). +[create a new project](../../../gitlab-basics/create-project.md) or +[fork an existing project](forking_workflow.md). Once you create a new project, you can add new files via UI (read the section below) or via command line. @@ -55,7 +56,7 @@ To get started with the command line, please read through the ### Find files -Use GitLab's [file finder](../../../workflow/file_finder.md) to search for files in a repository. +Use GitLab's [file finder](file_finder.md) to search for files in a repository. ### Supported markup languages and extensions diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md new file mode 100644 index 00000000000..a682983ab83 --- /dev/null +++ b/doc/user/project/repository/repository_mirroring.md @@ -0,0 +1,430 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' +--- + +# Repository mirroring + +Repository mirroring allows for mirroring of repositories to and from external sources. It can be +used to mirror branches, tags, and commits between repositories. + +A repository mirror at GitLab will be updated automatically. You can also manually trigger an update +at most once every 5 minutes. + +## Overview + +Repository mirroring is useful when you want to use a repository outside of GitLab. + +There are two kinds of repository mirroring supported by GitLab: + +- Push: for mirroring a GitLab repository to another location. +- Pull: for mirroring a repository from another location to GitLab. **(STARTER)** + +When the mirror repository is updated, all new branches, tags, and commits will be visible in the +project's activity feed. + +Users with at least [developer access](../../permissions.md) to the project can also force an +immediate update, unless: + +- The mirror is already being updated. +- 5 minutes haven't elapsed since its last update. + +## Use cases + +The following are some possible use cases for repository mirroring: + +- You migrated to GitLab but still need to keep your project in another source. In that case, you + can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, + and branches will be available in your GitLab instance. **(STARTER)** +- You have old projects in another source that you don't use actively anymore, but don't want to + remove for archiving purposes. In that case, you can create a push mirror so that your active + GitLab repository can push its changes to the old location. + +## Pushing to a remote repository **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/249) in GitLab Enterprise Edition 8.7. +> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/18715) in 10.8. + +For an existing project, you can set up push mirroring as follows: + +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. Enter a repository URL. +1. Select **Push** from the **Mirror direction** dropdown. +1. Select an authentication method from the **Authentication method** dropdown, if necessary. +1. Check the **Only mirror protected branches** box, if necessary. +1. Click the **Mirror repository** button to save the configuration. + + + +When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the +mirror diverging. All changes will end up in the mirrored repository whenever: + +- Commits are pushed to GitLab. +- A [forced update](#forcing-an-update-core) is initiated. + +Changes pushed to files in the repository are automatically pushed to the remote mirror at least: + +- Within five minutes of being received. +- Within one minute if **Only mirror protected branches** is enabled. + +In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories** +section. + +### Push only protected branches **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/3350) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. +> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/18715) in 10.8. + +You can choose to only push your protected branches from GitLab to your remote repository. + +To use this option, check the **Only mirror protected branches** box when creating a repository +mirror. + +## Setting up a push mirror from GitLab to GitHub **(CORE)** + +To set up a mirror from GitLab to GitHub, you need to follow these steps: + +1. Create a [GitHub personal access token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) with the `public_repo` box checked. +1. Fill in the **Git repository URL** field using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. +1. Fill in **Password** field with your GitHub personal access token. +1. Click the **Mirror repository** button. + +The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. + +The repository will push soon. To force a push, click the appropriate button. + +## Setting up a push mirror to another GitLab instance with 2FA activated + +1. On the destination GitLab instance, create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. +1. On the source GitLab instance: + 1. Fill in the **Git repository URL** field using this format: `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. + 1. Fill in **Password** field with the GitLab personal access token created on the destination GitLab instance. + 1. Click the **Mirror repository** button. + +## Pulling from a remote repository **(STARTER)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/51) in GitLab Enterprise Edition 8.2. +> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. + +NOTE: **Note:** This feature [is available for free](https://gitlab.com/gitlab-org/gitlab/issues/10361) to +GitLab.com users until March 22nd, 2020. + +You can set up a repository to automatically have its branches, tags, and commits updated from an +upstream repository. + +This is useful when a repository you're interested in is located on a different server, and you want +to be able to browse its content and its activity using the familiar GitLab interface. + +To configure mirror pulling for an existing project: + +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** + section. +1. Enter a repository URL. +1. Select **Pull** from the **Mirror direction** dropdown. +1. Select an authentication method from the **Authentication method** dropdown, if necessary. +1. If necessary, check the following boxes: + - **Overwrite diverged branches**. + - **Trigger pipelines for mirror updates**. + - **Only mirror protected branches**. +1. Click the **Mirror repository** button to save the configuration. + + + +--- + + + +Because GitLab is now set to pull changes from the upstream repository, you should not push commits +directly to the repository on GitLab. Instead, any commits should be pushed to the upstream repository. +Changes pushed to the upstream repository will be pulled into the GitLab repository, either: + +- Automatically within a certain period of time. +- When a [forced update](#forcing-an-update-core) is initiated. + +CAUTION: **Caution:** +If you do manually update a branch in the GitLab repository, the branch will become diverged from +upstream and GitLab will no longer automatically update this branch to prevent any changes from being lost. + +### How it works + +Once the pull mirroring feature has been enabled for a repository, the repository is added to a queue. + +Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on: + +- The capacity available. This is determined by Sidekiq settings. For GitLab.com, see [GitLab.com Sidekiq settings](../../gitlab_com/index.md#sidekiq). +- The number of repository mirrors already in the queue that are due to be updated. Being due depends on when the repository mirror was last updated and how many times it's been retried. + +Repository mirrors are updated as Sidekiq becomes available to process them. If the process of updating the repository mirror: + +- Succeeds, an update will be enqueued again with at least a 30 minute wait. +- Fails (for example, a branch diverged from upstream), it will be attempted again later. Mirrors can fail + up to 14 times before they will not be enqueued for update again. + +### SSH authentication + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/2551) for Pull mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22982) for Push mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 + +SSH authentication is mutual: + +- You have to prove to the server that you're allowed to access the repository. +- The server also has to prove to *you* that it's who it claims to be. + +You provide your credentials as a password or public key. The server that the +other repository resides on provides its credentials as a "host key", the +fingerprint of which needs to be verified manually. + +If you're mirroring over SSH (that is, using an `ssh://` URL), you can authenticate using: + +- Password-based authentication, just as over HTTPS. +- Public key authentication. This is often more secure than password authentication, + especially when the other repository supports [Deploy Keys](../../../ssh/README.md#deploy-keys). + +To get started: + +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. Enter an `ssh://` URL for mirroring. + +NOTE: **Note:** +SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time. + +Entering the URL adds two buttons to the page: + +- **Detect host keys**. +- **Input host keys manually**. + +If you click the: + +- **Detect host keys** button, GitLab will fetch the host keys from the server and display the fingerprints. +- **Input host keys manually** button, a field is displayed where you can paste in host keys. + +Assuming you used the former, you now need to verify that the fingerprints are +those you expect. GitLab.com and other code hosting sites publish their +fingerprints in the open for you to check: + +- [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) +- [Bitbucket](https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html) +- [GitHub](https://help.github.com/en/articles/githubs-ssh-key-fingerprints) +- [GitLab.com](../../gitlab_com/index.md#ssh-host-keys-fingerprints) +- [Launchpad](https://help.launchpad.net/SSHFingerprints) +- [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) +- [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) + +Other providers will vary. If you're running self-managed GitLab, or otherwise +have access to the server for the other repository, you can securely gather the +key fingerprints: + +```sh +$ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - +256 MD5:f4:28:9f:23:99:15:21:1b:bf:ed:1f:8e:a0:76:b2:9d root@example.com (ECDSA) +256 MD5:e6:eb:45:8a:3c:59:35:5f:e9:5b:80:12:be:7e:22:73 root@example.com (ED25519) +2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) +``` + +NOTE: **Note:** +You may need to exclude `-E md5` for some older versions of SSH. + +When mirroring the repository, GitLab will now check that at least one of the +stored host keys matches before connecting. This can prevent malicious code from +being injected into your mirror, or your password being stolen. + +### SSH public key authentication + +To use SSH public key authentication, you'll also need to choose that option +from the **Authentication method** dropdown. When the mirror is created, +GitLab generates a 4096-bit RSA key that can be copied by clicking the **Copy SSH public key** button. + + + +You then need to add the public SSH key to the other repository's configuration: + +- If the other repository is hosted on GitLab, you should add the public SSH key + as a [Deploy Key](../../../ssh/README.md#deploy-keys). +- If the other repository is hosted elsewhere, you may need to add the key to + your user's `authorized_keys` file. Paste the entire public SSH key into the + file on its own line and save it. + +If you need to change the key at any time, you can remove and re-add the mirror +to generate a new key. You'll have to update the other repository with the new +key to keep the mirror running. + +### Overwrite diverged branches **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. + +You can choose to always update your local branches with remote versions, even if they have +diverged from the remote. + +CAUTION: **Caution:** +For mirrored branches, enabling this option results in the loss of local changes. + +To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. + +### Only mirror protected branches **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/3326) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. + +You can choose to pull mirror only the protected branches from your remote repository to GitLab. +Non-protected branches are not mirrored and can diverge. + +To use this option, check the **Only mirror protected branches** box when creating a repository mirror. + +### Hard failure **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. + +Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard +failed. This will become visible in either the: + +- Project's main dashboard. +- Pull mirror settings page. + +When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the +project mirroring again by [Forcing an update](#forcing-an-update-core). + +### Trigger update using API **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. + +Pull mirroring uses polling to detect new branches and commits added upstream, often minutes +afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter), +updates will be pulled immediately. + +For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter). + +## Forcing an update **(CORE)** + +While mirrors are scheduled to update automatically, you can always force an update by using the +update button which is available on the **Mirroring repositories** section of the **Repository Settings** page. + + + +## Bidirectional mirroring **(STARTER)** + +CAUTION: **Caution:** +Bidirectional mirroring may cause conflicts. + +If you configure a GitLab repository to both pull from, and push to, the same remote source, there +is no guarantee that either repository will update correctly. If you set up a repository for +bidirectional mirroring, you should prepare for the likely conflicts by deciding who will resolve +them and how they will be resolved. + +Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can +be prevented by: + +- [Pulling only protected branches](#only-mirror-protected-branches-starter). +- [Pushing only protected branches](#push-only-protected-branches-core). + +You should [protect the branches](../protected_branches.md) you wish to mirror on both +remotes to prevent conflicts caused by rewriting history. + +Bidirectional mirroring also creates a race condition where commits made close together to the same +branch causes conflicts. The race condition can be mitigated by reducing the mirroring delay by using +a [Push event webhook](../integrations/webhooks.md#push-events) to trigger an immediate +pull to GitLab. Push mirroring from GitLab is rate limited to once per minute when only push mirroring +protected branches. + +### Preventing conflicts using a `pre-receive` hook + +CAUTION: **Warning:** +The solution proposed will negatively impact the performance of +Git push operations because they will be proxied to the upstream Git +repository. + +A server-side `pre-receive` hook can be used to prevent the race condition +described above by only accepting the push after first pushing the commit to +the upstream Git repository. In this configuration one Git repository acts as +the authoritative upstream, and the other as downstream. The `pre-receive` hook +will be installed on the downstream repository. + +Read about [configuring custom Git hooks](../../../administration/custom_hooks.md) on the GitLab server. + +A sample `pre-receive` hook is provided below. + +```bash +#!/usr/bin/env bash + +# --- Assume only one push mirror target +# Push mirroring remotes are named `remote_mirror_<id>`, this finds the first remote and uses that. +TARGET_REPO=$(git remote | grep -m 1 remote_mirror) + +proxy_push() +{ + # --- Arguments + OLDREV=$(git rev-parse $1) + NEWREV=$(git rev-parse $2) + REFNAME="$3" + + # --- Pattern of branches to proxy pushes + whitelisted=$(expr "$branch" : "\(master\)") + + case "$refname" in + refs/heads/*) + branch=$(expr "$refname" : "refs/heads/\(.*\)") + + if [ "$whitelisted" = "$branch" ]; then + error="$(git push --quiet $TARGET_REPO $NEWREV:$REFNAME 2>&1)" + fail=$? + + if [ "$fail" != "0" ]; then + echo >&2 "" + echo >&2 " Error: updates were rejected by upstream server" + echo >&2 " This is usually caused by another repository pushing changes" + echo >&2 " to the same ref. You may want to first integrate remote changes" + echo >&2 "" + return + fi + fi + ;; + esac +} + +# Allow dual mode: run from the command line just like the update hook, or +# if no arguments are given then run as a hook script +if [ -n "$1" -a -n "$2" -a -n "$3" ]; then + # Output to the terminal in command line mode - if someone wanted to + # resend an email; they could redirect the output to sendmail + # themselves + PAGER= proxy_push $2 $3 $1 +else + # Push is proxied upstream one ref at a time. Because of this it is possible + # for some refs to succeed, and others to fail. This will result in a failed + # push. + while read oldrev newrev refname + do + proxy_push $oldrev $newrev $refname + done +fi +``` + +### Mirroring with Perforce Helix via Git Fusion **(STARTER)** + +CAUTION: **Warning:** +Bidirectional mirroring should not be used as a permanent configuration. Refer to +[Migrating from Perforce Helix](../import/perforce.md) for alternative migration approaches. + +[Git Fusion](https://www.perforce.com/manuals/git-fusion/#Git-Fusion/section_avy_hyc_gl.html) provides a Git interface +to [Perforce Helix](https://www.perforce.com/products) which can be used by GitLab to bidirectionally +mirror projects with GitLab. This may be useful in some situations when migrating from Perforce Helix +to GitLab where overlapping Perforce Helix workspaces cannot be migrated simultaneously to GitLab. + +If using mirroring with Perforce Helix, you should only mirror protected branches. Perforce Helix +will reject any pushes that rewrite history. Only the fewest number of branches should be mirrored +due to the performance limitations of Git Fusion. + +When configuring mirroring with Perforce Helix via Git Fusion, the following Git Fusion +settings are recommended: + +- `change-pusher` should be disabled. Otherwise, every commit will be rewritten as being committed + by the mirroring account, rather than being mapped to existing Perforce Helix users or the `unknown_git` user. +- `unknown_git` user will be used as the commit author if the GitLab user does not exist in + Perforce Helix. + +Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manuals/git-fusion/Content/Git-Fusion/section_vss_bdw_w3.html#section_zdp_zz1_3l). + +## Troubleshooting + +Should an error occur during a push, GitLab will display an "Error" highlight for that repository. Details on the error can then be seen by hovering over the highlight text. + +### 13:Received RST_STREAM with error code 2 with GitHub + +If you receive an "13:Received RST_STREAM with error code 2" while mirroring to a GitHub repository, your GitHub settings might be set to block pushes that expose your email address used in commits. Either set your email address on GitHub to be public, or disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 131999dbf60..2dc507901d0 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -49,10 +49,11 @@ Add an [issue description template](../description_templates.md#description-temp Set up your project's merge request settings: - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.html)). -- Merge request [description templates](../description_templates.md#description-templates). +- Add merge request [description templates](../description_templates.md#description-templates). - Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **(STARTER)** -- Enable [merge only of pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all discussions are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). +- Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). +- Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). +- Enable [`delete source branch after merge` option by default](../merge_requests/creating_merge_requests.md#deleting-the-source-branch)  diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md new file mode 100644 index 00000000000..9cdee0f2b5a --- /dev/null +++ b/doc/user/project/time_tracking.md @@ -0,0 +1,92 @@ +--- +type: reference +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' +--- + +# Time Tracking + +> Introduced in GitLab 8.14. + +Time Tracking allows you to track estimates and time spent on issues and merge +requests within GitLab. + +## Overview + +Time Tracking allows you to: + +- Record the time spent working on an issue or a merge request. +- Add an estimate of the amount of time needed to complete an issue or a merge + request. + +You don't have to indicate an estimate to enter the time spent, and vice versa. + +Data about time tracking is shown on the issue/merge request sidebar, as shown +below. + + + +## How to enter data + +Time Tracking uses two [quick actions](quick_actions.md) +that GitLab introduced with this new feature: `/spend` and `/estimate`. + +Quick actions can be used in the body of an issue or a merge request, but also +in a comment in both an issue or a merge request. + +Below is an example of how you can use those new quick actions inside a comment. + + + +Adding time entries (time spent or estimates) is limited to project members. + +### Estimates + +To enter an estimate, write `/estimate`, followed by the time. For example, if +you need to enter an estimate of 3 days, 5 hours and 10 minutes, you would write +`/estimate 3d 5h 10m`. Time units that we support are listed at the bottom of +this help page. + +Every time you enter a new time estimate, any previous time estimates will be +overridden by this new value. There should only be one valid estimate in an +issue or a merge request. + +To remove an estimation entirely, use `/remove_estimate`. + +### Time spent + +To enter a time spent, use `/spend 3d 5h 10m`. + +Every new time spent entry will be added to the current total time spent for the +issue or the merge request. + +You can remove time by entering a negative amount: `/spend -3d` will remove 3 +days from the total time spent. You can't go below 0 minutes of time spent, +so GitLab will automatically reset the time spent if you remove a larger amount +of time compared to the time that was entered already. + +To remove all the time spent at once, use `/remove_time_spent`. + +## Configuration + +The following time units are available: + +- Months (mo) +- Weeks (w) +- Days (d) +- Hours (h) +- Minutes (m) + +Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h. + +### Limit displayed units to hours **(CORE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/29469/) in GitLab 12.1. + +In GitLab self-managed instances, the display of time units can be limited to +hours through the option in **Admin Area > Settings > Preferences** under **Localization**. + +With this option enabled, `75h` is displayed instead of `1w 4d 3h`. + +## Other interesting links + +- [Time Tracking landing page in the GitLab handbook](https://about.gitlab.com/solutions/time-tracking/) diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index d65dd32fe11..faa3a118137 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -17,6 +17,8 @@ The Advanced Syntax Search is a subset of the [Advanced Global Search](advanced_global_search.md), which you can use if you want to have more specific search results. +Advanced Global Search only supports searching the [default branch](../project/repository/branches/index.md#default-branch). + ## Use cases Let's say for example that the product you develop relies on the code of another diff --git a/doc/user/search/img/issue_search_filter_v12_5.png b/doc/user/search/img/issue_search_filter_v12_5.png Binary files differnew file mode 100644 index 00000000000..1e2dd3d98a3 --- /dev/null +++ b/doc/user/search/img/issue_search_filter_v12_5.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 8d7b4a429aa..bc31052b758 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -32,13 +32,14 @@ on the search field on the top-right of your screen: If you want to search for issues present in a specific project, navigate to a project's **Issues** tab, and click on the field **Search or filter results...**. It will display a dropdown menu, from which you can add filters per author, assignee, milestone, -label, weight, and 'my-reaction' (based on your emoji votes). When done, press **Enter** on your keyboard to filter the issues. +release, label, weight, confidentiality, and "my-reaction" (based on your emoji votes). +When done, press **Enter** on your keyboard to filter the issues. - + The same process is valid for merge requests. Navigate to your project's **Merge Requests** tab, and click **Search or filter results...**. Merge requests can be filtered by author, assignee, -milestone, and label. +approver, milestone, release, label, "my-reaction", "work in progess" status, and target branch. ### Filtering by **None** / **Any** @@ -99,8 +100,8 @@ quickly access issues and merge requests created or assigned to you within that ## To-Do List -Your [To-Do List](../../workflow/todos.md#gitlab-to-do-list) can be searched by "to do" and "done". -You can [filter](../../workflow/todos.md#filtering-your-to-do-list) them per project, +Your [To-Do List](../todos.md#gitlab-to-do-list) can be searched by "to do" and "done". +You can [filter](../todos.md#filtering-your-to-do-list) them per project, author, type, and action. Also, you can sort them by [**Label priority**](../../user/project/labels.md#label-priority), **Last created** and **Oldest created**. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md new file mode 100644 index 00000000000..54e7938d8f7 --- /dev/null +++ b/doc/user/shortcuts.md @@ -0,0 +1,135 @@ +--- +type: reference +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' +--- + +# GitLab keyboard shortcuts + +GitLab has many useful keyboard shortcuts to make it easier to access different features. +You can see the quick reference sheet within GitLab itself with <kbd>Shift</kbd> + <kbd>?</kbd>. + +The [Global Shortcuts](#global-shortcuts) work from any area of GitLab, but you must +be in specific pages for the other shortcuts to be available, as explained in each +section below. + +## Global Shortcuts + +These shortcuts are available in most areas of GitLab + +| Keyboard Shortcut | Description | +| ------------------------------- | ----------- | +| <kbd>?</kbd> | Show/hide shortcut reference sheet. | +| <kbd>Shift</kbd> + <kbd>p</kbd> | Go to your Projects page. | +| <kbd>Shift</kbd> + <kbd>g</kbd> | Go to your Groups page. | +| <kbd>Shift</kbd> + <kbd>a</kbd> | Go to your Activity page. | +| <kbd>Shift</kbd> + <kbd>l</kbd> | Go to your Milestones page. | +| <kbd>Shift</kbd> + <kbd>s</kbd> | Go to your Snippets page. | +| <kbd>s</kbd> | Put cursor in the issues/merge requests search. | +| <kbd>Shift</kbd> + <kbd>i</kbd> | Go to your Issues page. | +| <kbd>Shift</kbd> + <kbd>m</kbd> | Go to your Merge requests page.| +| <kbd>Shift</kbd> + <kbd>t</kbd> | Go to your To-Do List page. | +| <kbd>p</kbd> + <kbd>b</kbd> | Show/hide the Performance Bar. | + +Additionally, the following shortcuts are available when editing text in text fields, +for example comments, replies, or issue and merge request descriptions: + +| Keyboard Shortcut | Description | +| ---------------------------------------------------------------------- | ----------- | +| <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field below a thread, and you must already have at least one comment in the thread. | +| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview, when editing text in a text field that has **Write** and **Preview** tabs at the top. | + +## Project + +These shortcuts are available from any page within a project. You must type them +relatively quickly to work, and they will take you to another page in the project. + +| Keyboard Shortcut | Description | +| --------------------------- | ----------- | +| <kbd>g</kbd> + <kbd>p</kbd> | Go to the project home page (**Project > Details**). | +| <kbd>g</kbd> + <kbd>v</kbd> | Go to the project activity feed (**Project > Activity**). | +| <kbd>g</kbd> + <kbd>r</kbd> | Go to the project releases list (**Project > Releases**). | +| <kbd>g</kbd> + <kbd>f</kbd> | Go to the [project files](#project-files) list (**Repository > Files**). | +| <kbd>t</kbd> | Go to the project file search page. (**Repository > Files**, click **Find Files**). | +| <kbd>g</kbd> + <kbd>c</kbd> | Go to the project commits list (**Repository > Commits**). | +| <kbd>g</kbd> + <kbd>n</kbd> | Go to the [repository graph](#repository-graph) page (**Repository > Graph**). | +| <kbd>g</kbd> + <kbd>d</kbd> | Go to repository charts (**Repository > Charts**). | +| <kbd>g</kbd> + <kbd>i</kbd> | Go to the project issues list (**Issues > List**). | +| <kbd>i</kbd> | Go to the New Issue page (**Issues**, click **New Issue** ). | +| <kbd>g</kbd> + <kbd>b</kbd> | Go to the project issue boards list (**Issues > Boards**). | +| <kbd>g</kbd> + <kbd>m</kbd> | Go to the project merge requests list (**Merge Requests**). | +| <kbd>g</kbd> + <kbd>j</kbd> | Go to the CI/CD jobs list (**CI/CD > Jobs**). | +| <kbd>g</kbd> + <kbd>l</kbd> | Go to the project metrics (**Operations > Metrics**). | +| <kbd>g</kbd> + <kbd>e</kbd> | Go to the project environments (**Operations > Environments**). | +| <kbd>g</kbd> + <kbd>k</kbd> | Go to the project Kubernetes cluster integration page (**Operations > Kubernetes**). Note that you must have at least [`maintainer` permissions](permissions.md) to access this page. | +| <kbd>g</kbd> + <kbd>s</kbd> | Go to the project snippets list (**Snippets**). | +| <kbd>g</kbd> + <kbd>w</kbd> | Go to the project wiki (**Wiki**), if enabled. | + +### Issues and Merge Requests + +These shortcuts are available when viewing issues and merge requests. + +| Keyboard Shortcut | Description | +| ---------------------------- | ----------- | +| <kbd>e</kbd> | Edit description. | +| <kbd>a</kbd> | Change assignee. | +| <kbd>m</kbd> | Change milestone. | +| <kbd>l</kbd> | Change label. | +| <kbd>r</kbd> | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. | +| <kbd>n</kbd> | Move to next unresolved discussion (Merge requests only). | +| <kbd>p</kbd> | Move to previous unresolved discussion (Merge requests only). | +| <kbd>]</kbd> or <kbd>j</kbd> | Move to next file (Merge requests only). | +| <kbd>[</kbd> or <kbd>k</kbd> | Move to previous file (Merge requests only). | + +### Project Files + +These shortcuts are available when browsing the files in a project (navigate to +**Repository** > **Files**): + +| Keyboard Shortcut | Description | +| ----------------- | ----------- | +| <kbd>↑</kbd> | Move selection up. | +| <kbd>↓</kbd> | Move selection down. | +| <kbd>enter</kbd> | Open selection. | +| <kbd>esc</kbd> | Go back to file list screen (only while searching for files, **Repository > Files** then click on **Find File**). | +| <kbd>y</kbd> | Go to file permalink (only while viewing a file). | + +### Web IDE + +These shortcuts are available when editing a file with the [Web IDE](project/web_ide/index.md): + +| Keyboard Shortcut | Description | +| ------------------------------------------------------- | ----------- | +| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>p</kbd> | Search for, and then open another file for editing. | +| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). | + +### Repository Graph + +These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-graph) +page (navigate to **Repository > Graph**): + +| Keyboard Shortcut | Description | +| ------------------------------------------------------------------ | ----------- | +| <kbd>←</kbd> or <kbd>h</kbd> | Scroll left. | +| <kbd>→</kbd> or <kbd>l</kbd> | Scroll right. | +| <kbd>↑</kbd> or <kbd>k</kbd> | Scroll up. | +| <kbd>↓</kbd> or <kbd>j</kbd> | Scroll down. | +| <kbd>Shift</kbd> + <kbd>↑</kbd> or <kbd>Shift</kbd> + <kbd>k</kbd> | Scroll to top. | +| <kbd>Shift</kbd> + <kbd>↓</kbd> or <kbd>Shift</kbd> + <kbd>j</kbd> | Scroll to bottom. | + +### Wiki pages + +This shortcut is available when viewing a [wiki page](project/wiki/index.md): + +| Keyboard Shortcut | Description | +| ----------------- | ----------- | +| <kbd>e</kbd> | Edit wiki page. | + +## Epics **(ULTIMATE)** + +These shortcuts are available when viewing [Epics](group/epics/index.md): + +| Keyboard Shortcut | Description | +| ----------------- | ----------- | +| <kbd>r</kbd> | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. | +| <kbd>e</kbd> | Edit description. | +| <kbd>l</kbd> | Change label. | diff --git a/doc/user/todos.md b/doc/user/todos.md new file mode 100644 index 00000000000..d53baa688a4 --- /dev/null +++ b/doc/user/todos.md @@ -0,0 +1,142 @@ +--- +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/todos.html' +--- + +# GitLab To-Do List + +> [Introduced][ce-2817] in GitLab 8.5. + +When you log into GitLab, you normally want to see where you should spend your +time, take some action, or know what you need to keep an eye on without +a huge pile of e-mail notifications. GitLab is where you do your work, +so being able to get started quickly is important. + +Your To-Do List offers a chronological list of items that are waiting for your input, all +in a simple dashboard. + + + +You can quickly access your To-Do List by clicking the checkmark icon next to the +search bar in the top navigation. If the count is: + +- Less than 100, the number in blue is the number of To-Do items. +- 100 or more, the number displays as 99+. The exact number displays + on the To-Do List. +you still have open. Otherwise, the number displays as 99+. The exact number +displays on the To-Do List. + + + +## What triggers a To Do + +A To Do displays on your To-Do List when: + +- An issue or merge request is assigned to you +- You are `@mentioned` in the description or comment of an: + - Issue + - Merge Request + - Epic **(ULTIMATE)** +- You are `@mentioned` in a comment on a commit +- A job in the CI pipeline running for your merge request failed, but this + job is not allowed to fail +- An open merge request becomes unmergeable due to conflict, and you are either: + - The author + - Have set it to automatically merge once the pipeline succeeds + +To-do triggers are not affected by [GitLab Notification Email settings](profile/notifications.md). + +NOTE: **Note:** +When a user no longer has access to a resource related to a To Do (like an issue, merge request, project, or group) the related To-Do items are deleted within the next hour for security reasons. The delete is delayed to prevent data loss, in case the user's access was revoked by mistake. + +### Directly addressing a To Do + +> [Introduced][ce-7926] in GitLab 9.0. + +If you are mentioned at the start of a line, the To Do you receive will be listed +as 'directly addressed'. For example, in this comment: + +```markdown +@alice What do you think? cc: @bob + +- @carol can you please have a look? + +>>> +@dan what do you think? +>>> + +@erin @frank thank you! +``` + +The people receiving directly addressed To-Do items are `@alice`, `@erin`, and +`@frank`. Directly addressed To-Do items only differ from mentions in their type +for filtering purposes; otherwise, they appear as normal. + +### Manually creating a To Do + +You can also add the following to your To-Do List by clicking the **Add a To Do** button on an: + +- Issue +- Merge Request +- Epic **(ULTIMATE)** + + + +## Marking a To Do as done + +Any action to the following will mark the corresponding To Do as done: + +- Issue +- Merge Request +- Epic **(ULTIMATE)** + +Actions that dismiss To-Do items include: + +- Changing the assignee +- Changing the milestone +- Adding/removing a label +- Commenting on the issue + +Your To-Do List is personal, and items are only marked as done if the action comes from +you. If you close the issue or merge request, your To Do is automatically +marked as done. + +To prevent other users from closing issues without you being notified, if someone else closes, merges, or takes action on the any of the following, your To Do will remain pending: + +- Issue +- Merge request +- Epic **(ULTIMATE)** + +There is just one To Do for each of these, so mentioning a user a hundred times in an issue will only trigger one To Do. + +If no action is needed, you can manually mark the To Do as done by clicking the +corresponding **Done** button, and it will disappear from your To-Do List. + + + +You can also mark a To Do as done by clicking the **Mark as done** button in the sidebar of the following: + +- Issue +- Merge Request +- Epic **(ULTIMATE)** + + + +You can mark all your To-Do items as done at once by clicking the **Mark all as +done** button. + +## Filtering your To-Do List + +There are four kinds of filters you can use on your To-Do List. + +| Filter | Description | +| ------- | ----------- | +| Project | Filter by project | +| Group | Filter by group | +| Author | Filter by the author that triggered the To Do | +| Type | Filter by issue, merge request, or epic **(ULTIMATE)** | +| Action | Filter by the action that triggered the To Do | + +You can also filter by more than one of these at the same time. The possible Actions are `Any Action`, `Assigned`, `Mentioned`, `Added`, `Pipelines`, and `Directly Addressed`, [as described above](#what-triggers-a-to-do). + +[ce-2817]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/2817 +[ce-7926]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/7926 |
