diff options
Diffstat (limited to 'doc/user')
222 files changed, 4897 insertions, 3852 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index 7ddddfc5e53..b5294bb265d 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # DevOps Report **(FREE SELF)** -> [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) in GitLab 12.6. +> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) from Conversational Development Index in GitLab 12.6. The DevOps Report gives you an overview of your entire instance's adoption of [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 0ffa8289d37..0b264ef22b9 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -39,7 +39,7 @@ of the page to activate it in the GitLab instance. ## System header and footer messages -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to GitLab Free in 11.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) from GitLab Premium to GitLab Free in 11.9. You can add a small header message, a small footer message, or both, to the interface of your GitLab instance. These messages appear on all projects and pages of the diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 8c0586e5851..976d8e4efcf 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -7,7 +7,7 @@ type: reference # Custom instance-level project templates **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. GitLab administrators can set a group to be the source of project templates that are selectable when a new project is created on the instance. These templates can be selected diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index a2354e68d72..f2b899f0be9 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -22,45 +22,45 @@ All Geo sites have the following settings: | Setting | Description | | --------| ----------- | | Primary | This marks a Geo site as **primary** site. There can be only one **primary** site. | -| Name | The unique identifier for the Geo site. It's highly recommended to use a physical location as a name. Good examples are "London Office" or "us-east-1". Avoid words like "primary", "secondary", "Geo", or "DR". This makes the failover process easier because the physical location does not change, but the Geo site role can. All nodes in a single Geo site use the same site name. Nodes use the `gitlab_rails['geo_node_name']` setting in `/etc/gitlab/gitlab.rb` to lookup their Geo site record in the PostgreSQL database. If `gitlab_rails['geo_node_name']` is not set, then the node's `external_url` with trailing slash is used as fallback. The value of `Name` is case-sensitive, and most characters are allowed. | +| Name | The unique identifier for the Geo site. It's highly recommended to use a physical location as a name. Good examples are "London Office" or "us-east-1". Avoid words like "primary", "secondary", "Geo", or "DR". This makes the failover process easier because the physical location does not change, but the Geo site role can. All nodes in a single Geo site use the same site name. Nodes use the `gitlab_rails['geo_node_name']` setting in `/etc/gitlab/gitlab.rb` to lookup their Geo site record in the PostgreSQL database. If `gitlab_rails['geo_node_name']` is not set, the node's `external_url` with trailing slash is used as fallback. The value of `Name` is case-sensitive, and most characters are allowed. | | URL | The instance's user-facing URL. | The site you're currently browsing is indicated with a blue `Current` label, and the **primary** node is listed first as `Primary site`. -## **Secondary** site settings +## Secondary site settings **Secondary** sites have a number of additional settings available: | Setting | Description | |---------------------------|-------------| | Selective synchronization | Enable Geo [selective sync](../../administration/geo/replication/configuration.md#selective-synchronization) for this **secondary** site. | -| Repository sync capacity | Number of concurrent requests this **secondary** site will make to the **primary** site when backfilling repositories. | -| File sync capacity | Number of concurrent requests this **secondary** site will make to the **primary** site when backfilling files. | +| Repository sync capacity | Number of concurrent requests this **secondary** site makes to the **primary** site when backfilling repositories. | +| File sync capacity | Number of concurrent requests this **secondary** site makes to the **primary** site when backfilling files. | ## Geo backfill **Secondary** sites are notified of changes to repositories and files by the **primary** site, -and will always attempt to synchronize those changes as quickly as possible. +and always attempt to synchronize those changes as quickly as possible. Backfill is the act of populating the **secondary** site with repositories and files that -existed *before* the **secondary** site was added to the database. Since there may be -extremely large numbers of repositories and files, it's infeasible to attempt to -download them all at once, so GitLab places an upper limit on the concurrency of +existed *before* the **secondary** site was added to the database. Because there may be +extremely large numbers of repositories and files, it's not feasible to attempt to +download them all at once; so, GitLab places an upper limit on the concurrency of these operations. -How long the backfill takes is a function of the maximum concurrency, but higher +How long the backfill takes is dependent on the maximum concurrency, but higher values place more strain on the **primary** site. From [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3107), the limits are configurable. If your **primary** site has lots of surplus capacity, you can increase the values to complete backfill in a shorter time. If it's -under heavy load and backfill is reducing its availability for normal requests, +under heavy load and backfill reduces its availability for normal requests, you can decrease them. ## Using a different URL for synchronization The **primary** site's Internal URL is used by **secondary** sites to contact it (to sync repositories, for example). The name Internal URL distinguishes it from -[External URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab) +[External URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab), which is used by users. Internal URL does not need to be a private address. Internal URL defaults to external URL, but you can also customize it: @@ -79,21 +79,21 @@ terminated at the load balancer. WARNING: Starting with GitLab 13.3 and [until 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/325522), -using an internal URL that is not accessible to the users will result in the -OAuth authorization flow not working properly, as the users will get redirected +if you use an internal URL that is not accessible to the users, the +OAuth authorization flow does not work properly, because users are redirected to the internal URL instead of the external one. ## Multiple secondary sites behind a load balancer -In GitLab 11.11, **secondary** sites can use identical external URLs as long as +In GitLab 11.11, **secondary** sites can use identical external URLs if a unique `name` is set for each Geo site. The `gitlab.rb` setting `gitlab_rails['geo_node_name']` must: - Be set for each GitLab instance that runs `puma`, `sidekiq`, or `geo_logcursor`. - Match a Geo site name. -The load balancer must use sticky sessions in order to avoid authentication -failures and cross site request errors. +The load balancer must use sticky sessions to avoid authentication +failures and cross-site request errors. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index a5c3a2a7aeb..27d2bd8f764 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -8,7 +8,7 @@ type: reference # GitLab Admin Area **(FREE SELF)** The Admin Area provides a web UI to manage and configure some features of GitLab -self-managed instances. If you are an Admin user, you can access the Admin Area +self-managed instances. If you are an administrator, you can access the Admin Area by visiting `/admin` on your self-managed instance. You can also access it through the UI: @@ -16,7 +16,7 @@ the UI: - GitLab versions 13.12 and earlier: on the top bar, select the Admin Area icon (**{admin}**). NOTE: -Only admin users can access the Admin Area. +Only administrators can access the Admin Area. ## Admin Area sections @@ -24,7 +24,7 @@ The Admin Area is made up of the following sections: | Section | Description | |:-----------------------------------------------|:------------| -| **{overview}** [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | +| **{overview}** [Overview](#overview-section) | View your GitLab [Dashboard](#admin-area-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [topics](#administering-topics), [jobs](#administering-jobs), [runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | | **{monitor}** Monitoring | View GitLab [system information](#system-information), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit events](#audit-events). | | **{messages}** Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | | **{hook}** System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | @@ -41,7 +41,7 @@ The Admin Area is made up of the following sections: | **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | | **{settings}** Settings | Modify the [settings](settings/index.md) for your GitLab instance. | -## Admin Dashboard +## Admin Area dashboard The Dashboard provides statistics and system information about the GitLab instance. @@ -151,7 +151,7 @@ you must provide the complete email address. #### User impersonation -An administrator can "impersonate" any other user, including other administrator users. +An administrator can "impersonate" any other user, including other administrators. This allows the administrator to "see what the user sees," and take actions on behalf of the user. You can impersonate a user in the following ways: @@ -237,6 +237,26 @@ insensitive, and applies partial matching. To [Create a new group](../group/index.md#create-a-group) click **New group**. +### Administering Topics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.4. + +You can administer all topics in the GitLab instance from the Admin Area's Topics page. + +To access the Topics page: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Topics**. + +For each topic, the page displays their name and number of projects labeled with the topic. + +To create a new topic, select **New topic**. + +To edit a topic, select **Edit** in that topic's row. + +To search for topics by name, enter your criteria in the search box. The topic search is case +insensitive, and applies partial matching. + ### Administering Jobs You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. @@ -369,7 +389,7 @@ The Sidekiq dashboard consists of the following elements: ### Logs -Since GitLab 13.0, **Log** view has been removed from the admin dashboard since the logging does not work in multi-node setups and could cause confusion for administrators by displaying partial information. +Since GitLab 13.0, **Log** view has been removed from the Admin Area dashboard since the logging does not work in multi-node setups and could cause confusion for administrators by displaying partial information. For multi-node systems we recommend ingesting the logs into services like Elasticsearch and Splunk. diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 4e97cb8e49c..d984f6f4092 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Activating GitLab EE +# Activating GitLab EE **(PREMIUM SELF)** To enable features of GitLab Enterprise Edition (EE), you need to activate your instance. Ensure you are running an enterprise edition. To verify, sign in to GitLab and browse to `/help`. The GitLab edition and version are listed at the top of the **Help** page. @@ -15,7 +15,7 @@ As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an uploaded license only has the Free features active. A trial license activates all Ultimate features, but after [the trial expires](#what-happens-when-your-license-expires), some functionality is locked. -## Activate GitLab EE with an Activation Code **(PREMIUM SELF)** +## Activate GitLab EE with an Activation Code As of GitLab Enterprise Edition 14.1, you need an activation code to activate your instance. You can obtain an activation code by [purchasing a license](https://about.gitlab.com/pricing/) or by signing up for a [free trial](https://about.gitlab.com/free-trial/). This activation code is a 24-character alphanumeric string you receive in a confirmation email. You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) to copy the activation code to your clipboard. @@ -28,9 +28,9 @@ To begin the activation process with your activation code: 1. Read and accept the terms of service. 1. Select **Activate**. -## Activate GitLab EE with a License File **(PREMIUM SELF)** +## Activate GitLab EE with a License File -If you receive a license file from GitLab (for example a new trial), you can upload it by signing into your GitLab instance as an admin or adding it during installation. The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. +If you receive a license file from GitLab (for example a new trial), you can upload it by signing into your GitLab instance as an administrator or adding it during installation. The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. ## Uploading your license diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index ffa08dee10d..18151fc17d5 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -32,4 +32,7 @@ any commits to the source branch. - **Prevent editing approval rules in projects and merge requests**. Prevents users from modifying the approvers list in project settings or in individual merge requests. -Also read the [project level merge request approval rules](../project/merge_requests/approvals/index.md), which are affected by instance level rules. +See also the following, which are affected by instance-level rules: + +- [Project-level merge request approval rules](../project/merge_requests/approvals/index.md). +- [Group-level merge request approval rules](../group/index.md#group-approval-rules) available in GitLab 13.9 and later. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 2655d927b87..c8f160f729f 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Moderate users +# Moderate users **(FREE SELF)** GitLab administrators can moderate user access by approving, blocking, banning, or deactivating users. @@ -73,7 +73,7 @@ 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](review_abuse_reports.md#blocking-users), -or directly from the Admin Area. To do this: +by removing them in LDAP, or directly from the Admin Area. To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index 5765a530baf..da245300e1d 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/329511) in GitLab 13.12. > - Enabled on GitLab.com. > - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batched-background-migrations). **(FREE SELF)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batched-background-migrations). There can be [risks when disabling released features](../../../administration/feature_flags.md#risks-when-disabling-released-features). Refer to this feature's version history for more details. @@ -21,12 +21,12 @@ are created by GitLab developers and run automatically on upgrade. However, such limited in scope to help with migrating some `integer` database columns to `bigint`. This is needed to prevent integer overflow for some tables. -## Check the status of background migrations **(FREE SELF)** +## Check the status of background migrations All migrations must have a `Finished` status before you [upgrade GitLab](../../../update/index.md). You can [check the status of existing migrations](../../../update/index.md#checking-for-background-migrations-before-upgrading). -## Enable or disable batched background migrations **(FREE SELF)** +## Enable or disable batched background migrations Batched background migrations are under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -45,21 +45,21 @@ To disable it: Feature.disable(:execute_batched_migrations_on_schedule) ``` -## Automatic batch size optimization **(FREE SELF)** +## Automatic batch size optimization > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60133) in GitLab 13.12. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/329511) in GitLab 13.12. > - Enabled on GitLab.com. > - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-automatic-batch-size-optimization). **(FREE SELF)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-automatic-batch-size-optimization). There can be [risks when disabling released features](../../../administration/feature_flags.md#risks-when-disabling-released-features). Refer to this feature's version history for more details. To maximize throughput of batched background migrations (in terms of the number of tuples updated per time unit), batch sizes are automatically adjusted based on how long the previous batches took to complete. -## Enable or disable automatic batch size optimization **(FREE SELF)** +## Enable or disable automatic batch size optimization Automatic batch size optimization for batched background migrations is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -91,13 +91,95 @@ Expected batched background migration for the given configuration to be marked a {:job_class_name=>"CopyColumnUsingBackgroundMigrationJob", :table_name=>"push_event_payloads", :column_name=>"event_id", :job_arguments=>[["event_id"], ["event_id_convert_to_bigint"]]} ``` -To fix this error: +First, check if you have followed the [version-specific upgrade instructions for 14.2](../../../update/index.md#1420). +If you have, you can [manually finish the batched background migration](#manually-finishing-a-batched-background-migration). +If you haven't, choose one of the following methods: -1. Update to either 14.0.5 or 14.1. -1. [Check the status](#check-the-status-of-background-migrations) of the batched background migration from the error message, and make sure it is listed as finished. If it is still active, either wait until it is done, or finalize it manually using the command suggested in the error, for example: +1. [Rollback and upgrade](#roll-back-and-follow-the-required-upgrade-path) through one of the required +versions before updating to 14.2+. +1. [Roll forward](#roll-forward-and-finish-the-migrations-on-the-upgraded-version), staying on the current +version and manually ensuring that the batched migrations complete successfully. + +#### Roll back and follow the required upgrade path + +1. [Rollback and restore the previously installed version](../../../update/restore_after_failure.md#roll-back-to-an-earlier-version-and-restore-a-backup) +1. Update to either 14.0.5 or 14.1 **before** updating to 14.2+ +1. [Check the status](#check-the-status-of-background-migrations) of the batched background migrations and +make sure they are all marked as finished before attempting to upgrade again. If any remain marked as active, +you can [manually finish them](#manually-finishing-a-batched-background-migration). + +#### Roll forward and finish the migrations on the upgraded version + +##### For a deployment with downtime + +To run all the batched background migrations, it can take a significant amount of time +depending on the size of your GitLab installation. + +1. [Check the status](#check-the-status-of-background-migrations) of the batched background migrations in the +database, and [manually run them](#manually-finishing-a-batched-background-migration) with the appropriate +arguments until the status query returns no rows. +1. When the status of all of all them is marked as complete, re-run migrations for your installation. +1. [Complete the database migrations](../../../administration/raketasks/maintenance.md#run-incomplete-database-migrations) from your GitLab upgrade: + + ```plaintext + sudo gitlab-rake db:migrate + ``` + +1. Run a reconfigure: + + ```plaintext + sudo gitlab-ctl reconfigure + ``` + +1. Finish the upgrade for your installation. + +##### For a no-downtime deployment + +As the failing migrations are post-deployment migrations, you can remain on a running instance of the upgraded +version and wait for the batched background migrations to finish normally. + +1. [Check the status](#check-the-status-of-background-migrations) of the batched background migration from +the error message, and make sure it is listed as finished. If it is still active, either wait until it is done, +or [manually finish it](#manually-finishing-a-batched-background-migration). +1. Re-run migrations for your installation, so the remaining post-deployment migrations finish. + +### Manually finishing a batched background migration + +If you need to manually finish a batched background migration due to an +error, you can run: + +```shell +sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>'] +``` + +Replace the values in angle brackets with the correct +arguments. For example, if you receive an error similar to this: + +```plaintext +StandardError: An error has occurred, all later migrations canceled: + +Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active': + {:job_class_name=>"CopyColumnUsingBackgroundMigrationJob", :table_name=>"push_event_payloads", :column_name=>"event_id", :job_arguments=>[["event_id"], ["event_id_convert_to_bigint"]]} +``` + +Plug the arguments from the error message into the command: ```shell sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,push_event_payloads,event_id,'[["event_id"]\, ["event_id_convert_to_bigint"]]'] ``` -1. You can now update to GitLab 14.2 or higher. +If you need to manually run a batched background migration to continue an upgrade, you can +[check the status](#check-the-status-of-background-migrations) in the database and get the +arguments from the query results. For example, if the query returns this: + +```plaintext + job_class_name | table_name | column_name | job_arguments +---------------------------------------+------------+-------------+------------------------------------ + CopyColumnUsingBackgroundMigrationJob | events | id | [["id"], ["id_convert_to_bigint"]] + ``` + +The results from the query can be plugged into the command: + +```shell +sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,events,id,'[["id"]\, ["id_convert_to_bigint"]]'] +``` diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 6494934c34d..6a8b48e7ba7 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -12,14 +12,14 @@ View and resolve abuse reports from GitLab users. GitLab administrators can view and [resolve](#resolving-abuse-reports) abuse reports in the Admin Area. -## Receiving notifications of abuse reports +## Receive notification of abuse reports by email -To receive notifications of new abuse reports by email, follow these steps: +To receive notifications of new abuse reports by email: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Reporting**. 1. Expand the **Abuse reports** section. -1. Provide an email address. +1. Provide an email address and select **Save changes**. The notification email address can also be set and retrieved [using the API](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 178b117d06c..1b6da0e2806 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -47,7 +47,7 @@ details:  -## Maximum artifacts size **(FREE SELF)** +## Maximum artifacts size The maximum size of the [job artifacts](../../../administration/job_artifacts.md) can be set at: @@ -216,6 +216,20 @@ of your GitLab instance (`.gitlab-ci.yml` if not set): It is also possible to specify a [custom CI/CD configuration file for a specific project](../../../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file). +## Enable or disable the pipeline suggestion banner + +By default, a banner displays in merge requests with no pipeline suggesting a +walkthrough on how to add one. + + + +To enable or disable the banner: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Select or clear the **Enable pipeline suggestion banner** checkbox. +1. Select **Save changes**. + ## Required pipeline configuration **(PREMIUM SELF)** WARNING: @@ -296,7 +310,7 @@ To set the maximum file size: > - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. > - Disabled on GitLab.com. > - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. **(FREE SELF)** +> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI. diff --git a/doc/user/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md new file mode 100644 index 00000000000..a2edb6da86e --- /dev/null +++ b/doc/user/admin_area/settings/deprecated_api_rate_limits.md @@ -0,0 +1,53 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference +--- + +# Deprecated API rate limits **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68645) in GitLab 14.4. + +Deprecated API endpoints are those which have been replaced with alternative +functionality, but cannot be removed without breaking backward compatibility. +Setting a restrictive rate limit on these endpoints can encourage users to +switch to the alternatives. + +## Deprecated API endpoints + +Not all deprecated API endpoints are included in this rate limit - just those +that might have a performance impact: + +- [`GET /groups/:id`](../../../api/groups.md#details-of-a-group) **without** the `with_projects=0` query parameter. + +## Define Deprecated API rate limits + +Rate limits for deprecated API endpoints are disabled by default. When enabled, they supersede +the general user and IP rate limits for requests to deprecated endpoints. You can keep any general user +and IP rate limits already in place, and increase or decrease the rate limits +for deprecated API endpoints. No other new features are provided by this override. + +Prerequisites: + +- You must have the Administrator role for your instance. + +To override the general user and IP rate limits for requests to deprecated API endpoints: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. +1. Expand **Deprecated API Rate Limits**. +1. Select the check boxes for the types of rate limits you want to enable: + - **Unauthenticated API request rate limit** + - **Authenticated API request rate limit** +1. _If you enabled unauthenticated API request rate limits:_ + 1. Select the **Maximum unauthenticated API requests per period per IP**. + 1. Select the **Unauthenticated API rate limit period in seconds**. +1. _If you enabled authenticated API request rate limits:_ + 1. Select the **Maximum authenticated API requests per period per user**. + 1. Select the **Authenticated API rate limit period in seconds**. + +## Resources + +- [Rate limits](../../../security/rate_limits.md) +- [User and IP rate limits](user_and_ip_rate_limits.md) diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index c04a9a12912..6bc9e97629c 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -72,7 +72,7 @@ To add additional text to emails: 1. Enter your text in the **Additional text** field. 1. Select **Save changes**. -## User deactivation emails **(FREE SELF)** +## User deactivation emails GitLab sends email notifications to users when their account has been deactivated. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 985f3c133d5..5f007c83e4b 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,13 +1,12 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference --- # External authorization control **(FREE SELF)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) to GitLab Free in 11.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) from GitLab Premium to GitLab Free in 11.10. In highly controlled environments, it may be necessary for access policy to be controlled by an external service that permits access based on project diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md new file mode 100644 index 00000000000..f91d4b2fb0c --- /dev/null +++ b/doc/user/admin_area/settings/files_api_rate_limits.md @@ -0,0 +1,56 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference +--- + +# Files API rate limits **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it +available, ask an administrator to [enable the `files_api_throttling` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available but can be configured by GitLab.com +administrators only. The feature is not ready for production use. + +The [Repository files API](../../../api/repository_files.md) enables you to +fetch, create, update, and delete files in your repository. To improve the security +and durability of your web application, you can enforce +[rate limits](../../../security/rate_limits.md) on this API. Any rate limits you +create for the Files API override the [general user and IP rate limits](user_and_ip_rate_limits.md). + +## Define Files API rate limits + +Rate limits for the Files API are disabled by default. When enabled, they supersede +the general user and IP rate limits for requests to the +[Repository files API](../../../api/repository_files.md). You can keep any general user +and IP rate limits already in place, and increase or decrease the rate limits +for the Files API. No other new features are provided by this override. + +Prerequisites: + +- You must have the Administrator role for your instance. +- The `files_api_throttling` feature flag must be enabled. + +To override the general user and IP rate limits for requests to the Repository files API: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. +1. Expand **Files API Rate Limits**. +1. Select the check boxes for the types of rate limits you want to enable: + - **Unauthenticated API request rate limit** + - **Authenticated API request rate limit** +1. _If you enabled unauthenticated API request rate limits:_ + 1. Select the **Max unauthenticated API requests per period per IP**. + 1. Select the **Unauthenticated API rate limit period in seconds**. +1. _If you enabled authenticated API request rate limits:_ + 1. Select the **Max authenticated API requests per period per user**. + 1. Select the **Authenticated API rate limit period in seconds**. + +## Resources + +- [Rate limits](../../../security/rate_limits.md) +- [Repository files API](../../../api/repository_files.md) +- [User and IP rate limits](user_and_ip_rate_limits.md) diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index 17c390aef0e..6bfc6dfbebd 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Federated Learning of Cohorts (FLoC) **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60933) in GitLab Free 13.12. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60933) in GitLab 13.12. Federated Learning of Cohorts (FLoC) is a new feature of the Chrome browser. It works by categorizing users into different cohorts, so that diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index 1d4f45d1f04..5da43935052 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -22,6 +22,6 @@ The following timeouts are available. | Timeout | Default | Description | |:--------|:-----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the worker timeout that can be configured for [Puma](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | +| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the worker timeout that can be configured for [Puma](../../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | | Fast | 10 seconds | Timeout for fast Gitaly operations used within requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance. | | Medium | 30 seconds | Timeout for Gitaly operations that should be fast (possibly within requests) but preferably not used multiple times within a request. For example, loading blobs. Timeout that should be set between Default and Fast. | diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index cf08b9b71db..0bf5dc1d37a 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -68,12 +68,9 @@ You can specify a custom URL to which users are directed when they: ## Redirect `/help` pages -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to -[enable the `:help_page_documentation_redirect` flag](../../../administration/feature_flags.md). -On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5. +> - [Feature flag `help_page_documentation_redirect`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71737) removed in GitLab 14.4. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71737) in GitLab 14.4. The `/help` URL of a GitLab instance displays a basic version of the documentation sourced from the [`doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) of GitLab. `/help` links diff --git a/doc/user/admin_area/settings/img/suggest_pipeline_banner.png b/doc/user/admin_area/settings/img/suggest_pipeline_banner.png Binary files differnew file mode 100644 index 00000000000..9f118ccc5ed --- /dev/null +++ b/doc/user/admin_area/settings/img/suggest_pipeline_banner.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index ec5f3ca812f..688734849e5 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -98,6 +98,8 @@ To access the default page for Admin Area settings: | [User and IP rate limits](user_and_ip_rate_limits.md) | Configure limits for web and API requests. | | [Package Registry Rate Limits](package_registry_rate_limits.md) | Configure specific limits for Packages API requests that supersede the user and IP rate limits. | | [Git LFS Rate Limits](git_lfs_rate_limits.md) | Configure specific limits for Git LFS requests that supersede the user and IP rate limits. | +| [Files API Rate Limits](files_api_rate_limits.md) | Configure specific limits for Files API requests that supersede the user and IP rate limits. | +| [Deprecated API Rate Limits](deprecated_api_rate_limits.md) | Configure specific limits for deprecated API requests that supersede the user and IP rate limits. | | [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. | | [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. | | [Incident Management](../../../operations/incident_management/index.md) Limits | Limit the number of inbound alerts that can be sent to a project. | diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 862bf3b1652..044863729db 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -31,6 +31,8 @@ After you add templates, you can use them for the entire instance. They are available in the [Web Editor's dropdown](../../project/repository/web_editor.md#template-dropdowns) and through the [API settings](../../../api/settings.md). +## Supported file types and locations + Templates must be added to a specific subdirectory in the repository, corresponding to the kind of template. The following types of custom templates are supported: diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index 061e9fa05d3..dc328fe8b7c 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -41,7 +41,7 @@ try again. ## Configure using GitLab UI -> Introduced in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31246). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31246) in GitLab 12.4. Throttling of protected paths is enabled by default and can be disabled or customized on **Admin > Network > Protected Paths**, along with these options: diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index a2e8a875ebb..50dd24de3fb 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -19,7 +19,7 @@ To can change its value: 1. Select **Save changes**. For example, if you set a limit of 300, requests using the -[Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/raw/master/app/controllers/projects/issues_controller.rb) +[Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/projects/issues_controller.rb) action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. When using [epics](../../group/epics/index.md), epic creation will share this rate limit with issues. diff --git a/doc/user/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md index c6a783beb3f..750665285b4 100644 --- a/doc/user/admin_area/settings/sidekiq_job_limits.md +++ b/doc/user/admin_area/settings/sidekiq_job_limits.md @@ -13,7 +13,6 @@ type: reference Redis. To avoid excessive memory for Redis, we: - Compress job arguments before storing them in Redis. -arguments before storing them in Redis, and rejecting jobs that exceed - Reject jobs that exceed the specified threshold limit after compression. To access Sidekiq job size limits: @@ -30,7 +29,6 @@ To access Sidekiq job size limits: |-------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Limiting mode | Compress | This mode compresses the jobs at the specified threshold and rejects them if they exceed the specified limit after compression. | | Sidekiq job compression threshold (bytes) | 100 000 (100 KB) | When the size of arguments exceeds this threshold, they are compressed before being stored in Redis. | -| Sidekiq job size limit (bytes) | 0 | The jobs exceeding this size after compression are rejected. This avoids excessive memory usage in Redis leading to instability. Setting it to 0 prevents rejecting jobs. | +| Sidekiq job size limit (bytes) | 0 | The jobs exceeding this size after compression are rejected. This avoids excessive memory usage in Redis leading to instability. Setting it to 0 prevents rejecting jobs. | -After changing these values, [restart -Sidekiq](../../../administration/restart_gitlab.md). +After changing these values, [restart Sidekiq](../../../administration/restart_gitlab.md). diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 223ffeebd44..8cee63b0ac2 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -24,6 +24,8 @@ You can restrict the password authentication for web interface and Git over HTTP - **Web interface**: When this feature is disabled, the **Standard** sign-in tab is removed and an [external authentication provider](../../../administration/auth/index.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. +In the event of an external authentication provider outage, use the [GitLab Rails console](../../../administration/operations/rails_console.md) to [re-enable the standard web sign-in form](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#re-enable-standard-web-sign-in-form). This configuration can also be changed over the [Application settings REST API](../../../api/settings.md#change-application-settings) while authenticating with an administrator account's personal access token. + ## Admin Mode > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. @@ -104,7 +106,7 @@ see [Email notification for unknown sign-ins](../../profile/unknown_sign_in_noti All users that are not logged in are redirected to the page represented by the configured **Home page URL** if value is not empty. -All users are redirected to the page represented by the configured **After sign out path** +All users are redirected to the page represented by the configured **After sign-out path** after sign out if value is not empty. In the **Sign-in restrictions** section, scroll to the **Sign-in text** field. You can add a diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index dc09d6a5132..ed80bca470e 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -31,7 +31,7 @@ To disable sign ups: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267568) in GitLab 13.6. -When this setting is enabled, any user visiting your GitLab domain and signing up for a new account +When this setting is enabled, any user visiting your GitLab domain and signing up for a new account using the registration form must be explicitly [approved](../moderate_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using their account. In GitLab 13.6 and later, this setting is enabled by default for new GitLab instances. It is only applicable if sign ups are enabled. @@ -45,6 +45,12 @@ To require administrator approval for new sign ups: In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273258), if an administrator disables this setting, the users in pending approval state are automatically approved in a background job. +NOTE: +This setting doesn't apply to LDAP or OmniAuth users. To enforce approvals for new users +signing up using OmniAuth or LDAP, set `block_auto_created_users` to `true` in the +[OmniAuth configuration](../../../integration/omniauth.md#initial-omniauth-configuration) or +[LDAP configuration](../../../administration/auth/ldap/index.md#basic-configuration-settings). + ## Require email confirmation You can send confirmation emails during sign up and require that users confirm @@ -56,7 +62,7 @@ To enforce confirmation of the email address used for new sign ups: 1. On the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Select the **Enable email restrictions for sign ups** checkbox, then select **Save changes**. -## User cap **(FREE SELF)** +## User cap > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4315) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292600) in GitLab 13.9. @@ -117,7 +123,7 @@ the minimum number of characters a user must have in their password using the Gi You can specify an inclusive or exclusive list of email domains which can be used for user sign up. These restrictions are only applied during sign up from an external user. An administrator can add a -user through the admin panel with a disallowed domain. Also, note that the users can change their +user through the administrator panel with a disallowed domain. Also, note that the users can change their email addresses to disallowed domains after sign up. ### Allowlist email domains diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index a9c8c5d2a76..c9d48b14a6c 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -7,7 +7,7 @@ type: reference # Third-party offers **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in GitLab Free 11.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in GitLab 11.1. Within GitLab, we inform users of available third-party offers they might find valuable in order to enhance the development of their projects. An example is the Google Cloud Platform free credit diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 330a25087ef..923ea9e19c1 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -12,7 +12,7 @@ to perform various actions. All usage statistics are [opt-out](#enable-or-disable-usage-statistics). -## Service Ping **(FREE SELF)** +## Service Ping Service Ping is a process that collects and sends a weekly payload to GitLab Inc. For more information, see the [Service Ping guide](../../../development/service_ping/index.md). @@ -23,7 +23,7 @@ When Service Ping is enabled, GitLab gathers data from other instances and enables certain [instance-level analytics features](../analytics/index.md) that are dependent on Service Ping. -## Version check **(FREE SELF)** +## Version check If enabled, version check informs you if a new version is available and the importance of it through a status. The status displays on the help pages (`/help`) @@ -76,7 +76,7 @@ To enable or disable Service Ping and version check: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand **Usage statistics**. -1. Select or clear the **Enable version check** and **Enable service ping** checkboxes. +1. Select or clear the **Enable version check** and **Enable Service Ping** checkboxes. 1. Select **Save changes**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index 32f08801c76..ac6fe29da28 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -189,6 +189,10 @@ The possible names are: - `throttle_unauthenticated_packages_api` - `throttle_authenticated_packages_api` - `throttle_authenticated_git_lfs` +- `throttle_unauthenticated_files_api` +- `throttle_authenticated_files_api` +- `throttle_unauthenticated_deprecated_api` +- `throttle_authenticated_deprecated_api` For example, to try out throttles for all authenticated requests to non-protected paths can be done by setting 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 7f3f4b32802..075becfd32f 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -21,10 +21,7 @@ To access the visibility and access control options: With this option, you can define [branch protections](../../project/protected_branches.md) to apply to every repository's [default branch](../../project/repository/branches/default.md). -These protections specify the user roles with permission to: - -- Push to branches. -- Delete branches. +These protections specify the user roles with permission to push to default branches. This setting applies only to each repository's default branch. To protect other branches, you must configure [branch protection in the repository](../../project/protected_branches.md), @@ -37,14 +34,14 @@ To change the default branch protection for the entire instance: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select a **Default branch protection**: - - **Not protected** - Both developers and maintainers can push new commits, - force push, or delete the branch. + - **Not protected** - Both developers and maintainers can push new commits + and force push. - **Protected against pushes** - Developers cannot push new commits, but are allowed to accept merge requests to the branch. Maintainers can push to the branch. - **Partially protected** - Both developers and maintainers can push new commits, - but cannot force push or delete the branch. + but cannot force push. - **Fully protected** - Developers cannot push new commits, but maintainers can. - No one can force push or delete the branch. + No one can force push. 1. To allow group owners to override the instance's default branch protection, select [**Allow owners to manage default branch protection per group**](#prevent-overrides-of-default-branch-protection). 1. Select **Save changes**. @@ -295,7 +292,7 @@ For more details, see [SSH key restrictions](../../../security/ssh_keys_restrict ## Enable project mirroring This option is enabled by default. By disabling it, both -[pull and push mirroring](../../project/repository/repository_mirroring.md) no longer +[pull mirroring](../../project/repository/mirror/pull.md) and [push mirroring](../../project/repository/mirror/push.md) no longer work in every repository. They can only be re-enabled by an administrator user on a per-project basis.  diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index 89026e56a27..28376923810 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cohorts **(FREE)** +# Cohorts **(FREE SELF)** You can analyze your users' GitLab activities over time. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 3c80e1f5f2a..4a42133c308 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -24,7 +24,7 @@ View pipeline duration history: ## DevOps Research and Assessment (DORA) key metrics **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. -> - Added support for [lead time for changes](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) in GitLab 13.10. +> - [Added support](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) for lead time for changes in GitLab 13.10. Customer experience is a key metric. Users want to measure platform stability and other post-deployment performance KPIs, and set targets for customer behavior, experience, and financial @@ -56,7 +56,7 @@ The following table shows the supported metrics, at which level they are support | `change_failure_rate` | Project/Group-level | To be supported | To be supported | | | `time_to_restore_service` | Project/Group-level | To be supported | To be supported | | -### Deployment frequency charts **(ULTIMATE)** +### Deployment frequency charts > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. @@ -69,7 +69,7 @@ for its deployment information to appear on the graphs. These charts are available for both groups and projects. -### Lead time charts **(ULTIMATE)** +### Lead time charts > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250329) in GitLab 13.11. diff --git a/doc/user/analytics/img/project_vsa_filter_v14_3.png b/doc/user/analytics/img/project_vsa_filter_v14_3.png Binary files differnew file mode 100644 index 00000000000..d3fcad31909 --- /dev/null +++ b/doc/user/analytics/img/project_vsa_filter_v14_3.png diff --git a/doc/user/analytics/img/project_vsa_stage_table_v14_4.png b/doc/user/analytics/img/project_vsa_stage_table_v14_4.png Binary files differnew file mode 100644 index 00000000000..e65296062f6 --- /dev/null +++ b/doc/user/analytics/img/project_vsa_stage_table_v14_4.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 5b7e6e39187..c01788f4fc4 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w When we describe GitLab analytics, we use the following terms: -- **Cycle time:** The duration of only the execution work alone. Often displayed in combination with "lead time," which is longer. GitLab measures cycle time from issue first merge request creation to issue close. This approach underestimates lead time because merge request creation is always later than commit time. GitLab displays cycle time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). +- **Cycle time:** The duration of only the execution work. Cycle time is often displayed in combination with the lead time, which is longer than the cycle time. GitLab measures cycle time from the earliest commit of a [linked issue's merge request](../project/issues/crosslinking_issues.md) to when that issue is closed. The cycle time approach underestimates the lead time because merge request creation is always later than commit time. GitLab displays cycle time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](../analytics/value_stream_analytics.md). - **Deploys:** The total number of successful deployments to production in the given time frame (across all applicable projects). GitLab displays deploys in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md) and [project-level Value Stream Analytics](value_stream_analytics.md). - **DORA (DevOps Research and Assessment)** ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): - **Speed/Velocity** diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 44b8c87ee27..af7307eab39 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue Analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in GitLab 12.9. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 44e4cd8b371..2ff15c00a3f 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -115,5 +115,5 @@ bookmark for those preferred settings in your browser. The **Merge Request Analytics** feature can be accessed only: -- On [Premium](https://about.gitlab.com/pricing/) and above. +- On [GitLab Premium](https://about.gitlab.com/pricing/) and above. - By users with [Reporter access](../permissions.md) and above. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index 391ec5c04d9..dbe71d5f743 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Productivity Analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12079) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12079) in GitLab 12.3. Track development velocity with Productivity Analytics. @@ -60,5 +60,5 @@ You can filter analytics based on a date range. To filter results: The **Productivity Analytics** dashboard can be accessed only: -- On the [Premium tier](https://about.gitlab.com/pricing/) and above. +- On [GitLab Premium](https://about.gitlab.com/pricing/) and above. - By users with [Reporter access](../permissions.md) and above. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 9016bf6393f..e8f8acf5661 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Repository Analytics +# Repository Analytics **(FREE)** Get high-level overview of the project's Git repository. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 7057d069e95..9c1a8893f95 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -43,12 +43,59 @@ The stages tracked by Value Stream Analytics by default represent the [GitLab fl - **Staging** (Continuous Deployment) - Time between merging and deploying to production +## Filter Value Stream Analytics data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326701) in GitLab 14.3 + +You can filter analytics based on the following parameters: + +- Milestones (Group level) +- Labels (Group level) +- Author +- Assignees + +To filter results: + +1. Select the **Filter results** text box. +1. Select a parameter. +1. Select a value. To find a value in the list, enter the value name. + + + ### Date ranges To filter analytics results based on a date range, select different **From** and **To** days from the date picker (default: last 30 days). +### Stage table + +> Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335974) in GitLab 14.4. + + + +The stage table shows a list of related workflow items for the selected stage. This can include: + +- CI/CD jobs +- Issues +- Merge requests +- Pipelines + +A little badge next to the workflow items table header shows the number of workflow items that +completed the selected stage. + +The stage table also includes the **Time** column, which shows how long it takes each item to pass +through the selected value stream stage. + +To sort the stage table by a table column, select the table header. +You can sort in ascending or descending order. To find items that spent the most time in a stage, +potentially causing bottlenecks in your value stream, sort the table by the **Time** column. +From there, select individual items to drill in and investigate how delays are happening. +To see which items most recently exited the stage, sort by the work item column on the left. + +The table displays 20 items per page. If there are more than 20 items, you can use the +**Prev** and **Next** buttons to navigate through the pages. + ## How Time metrics are measured The **Time** metrics near the top of the page are measured as follows: diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index 7940e072420..db0b2a32bcf 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -68,8 +68,12 @@ Install GitLab HAR Recorder: 1. Make sure proxy is used! 1. Stop the recorder. -To verify the HAR contains all requests, use the [HAR Viewer (online)](http://www.softwareishard.com/har/viewer/). -[Google Admin Toolbox HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) +To verify the HAR contains all requests, use an online HAR viewer, for example: + +- [HAR Viewer](http://www.softwareishard.com/har/viewer/) +<!-- vale gitlab.Admin = NO --> +- [Google Admin Toolbox HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) +<!-- vale gitlab.Admin = YES --> ### Insomnia API Client @@ -190,7 +194,9 @@ a text editor. Tools recommended for viewing HAR files include: - [HAR Viewer](http://www.softwareishard.com/har/viewer/) - (online) +<!-- vale gitlab.Admin = NO --> - [Google Admin Toolbox HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) - (online) +<!-- vale gitlab.Admin = YES --> - [Fiddler](https://www.telerik.com/fiddler) - local - [Insomnia API Client](https://insomnia.rest/) - local diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 98e241ba3bd..674eee5e80a 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -38,7 +38,7 @@ Select **Configuration history** to see the `.gitlab-ci.yml` file's history. You can configure the following security controls: -- Static Application Security Testing (SAST) +- Static Application Security Testing (SAST) **(FREE)** - Select **Enable SAST** to configure SAST for the current project. For more details, read [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). - Dynamic Application Security Testing (DAST) **(ULTIMATE)** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 2b3d4dbfc0a..22b54bf019c 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -42,10 +42,20 @@ To enable container scanning in your pipeline, you need the following: shared runners on GitLab.com, then this is already the case. - An image matching the [supported distributions](#supported-distributions). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) - the Docker image to your project's container registry. If using a third-party container - registry, you might need to provide authentication credentials using the `DOCKER_USER` and - `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). + the Docker image to your project's container registry. - The name of the Docker image to scan, in the `DOCKER_IMAGE` [configuration variable](#available-cicd-variables). +- If you're using a third-party container registry, you might need to provide authentication + credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). + For example, if you are connecting to AWS ECR, you might use the following: + +```yaml +export AWS_ECR_PASSWORD=$(aws ecr get-login-password --region region) + +include: + - template: Security/Container-Scanning.gitlab-ci.yml + DOCKER_USER: AWS + DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" +``` ## Configuration @@ -397,7 +407,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc We recommend that you set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to fetch the latest vulnerabilities database on a preset schedule. Automating this with a pipeline means you do not have to do it manually each time. You can use the -following `.gitlab-yml.ci` example as a template. +following `.gitlab-ci.yml` example as a template. ```yaml variables: @@ -420,6 +430,39 @@ The above template works for a GitLab Docker registry running on a local install you're using a non-GitLab Docker registry, you must change the `$CI_REGISTRY` value and the `docker login` credentials to match your local registry's details. +#### Scan images in external private registries + +To scan an image in an external private registry, you must configure access credentials so the +container scanning analyzer can authenticate itself before attempting to access the image to scan. + +If you use the GitLab [Container Registry](../../packages/container_registry/), +the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables) +are set automatically and you can skip this configuration. + +This example shows the configuration needed to scan images in a private [Google Container Registry](https://cloud.google.com/container-registry/): + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + DOCKER_USER: _json_key + DOCKER_PASSWORD: "$GCP_CREDENTIALS" + DOCKER_IMAGE: "gcr.io/path-to-you-registry/image:tag" +``` + +Before you commit this configuration, [add a CI/CD variable](../../../ci/variables/#add-a-cicd-variable-to-a-project) +for `GCP_CREDENTIALS` containing the JSON key, as described in the +[Google Cloud Platform Container Registry documentation](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key). +Also: + +- The value of the variable may not fit the masking requirements for the **Mask variable** option, + so the value could be exposed in the job logs. +- Scans may not run in unprotected feature branches if you select the **Protect variable** option. +- Consider creating credentials with read-only permissions and rotating them regularly if the + options aren't selected. + ## Running the standalone container scanning tool It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 0d5eb2b6d50..cdb2e7109bf 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -7,15 +7,26 @@ type: reference, howto # Coverage-guided fuzz testing **(ULTIMATE)** +Coverage-guided fuzzing sends random inputs to an instrumented version of your application in an +effort to cause unexpected behavior. Such behavior indicates a bug that you should address. GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover -bugs and potential security issues that other QA processes may miss. Coverage-guided fuzzing sends -random inputs to an instrumented version of your application in an effort to cause unexpected -behavior, such as a crash. Such behavior indicates a bug that you should address. +bugs and potential security issues that other QA processes may miss. We recommend that you use fuzz testing in addition to the other security scanners in [GitLab Secure](../index.md) and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), -you can run your coverage-guided fuzz tests as part your CI/CD workflow. You can take advantage of -coverage-guided fuzzing by including the CI job in your existing `.gitlab-ci.yml` file. +you can run your coverage-guided fuzz tests as part your CI/CD workflow. + +## Coverage-guided fuzz testing process + +The fuzz testing process: + +1. Compiles the target application. +1. Runs the instrumented application, using the `gitlab-cov-fuzz` tool. +1. Parses and analyzes the exception information output by the fuzzer. +1. Downloads the [corpus](../terminology/index.md#corpus) and crash events from previous pipelines. +1. Outputs the parsed crash events and data to the `gl-coverage-fuzzing-report.json` file. + +The results of the coverage-guided fuzz testing are available in the CI/CD pipeline. ## Supported fuzzing engines and languages @@ -249,6 +260,8 @@ which shows an overview of all the security vulnerabilities in your groups, proj Clicking the vulnerability opens a modal that provides additional information about the vulnerability: +<!-- vale gitlab.Acronyms = NO --> + - Status: The vulnerability's status. As with any type of vulnerability, a coverage fuzzing vulnerability can be Detected, Confirmed, Dismissed, or Resolved. - Project: The project in which the vulnerability exists. @@ -262,3 +275,5 @@ vulnerability: - Scanner: The scanner that detected the vulnerability (for example, Coverage Fuzzing). - Scanner Provider: The engine that did the scan. For Coverage Fuzzing, this can be any of the engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). + +<!-- vale gitlab.Acronyms = YES --> diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index 1489b250e4b..5ffd47527c5 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -5,65 +5,64 @@ group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CVE ID Requests **(FREE SAAS)** +# CVE ID request **(FREE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. -As part of [our role as a CVE Numbering Authority](https://about.gitlab.com/security/cve/) -([CNA](https://cve.mitre.org/cve/cna.html)), you may request -[CVE](https://cve.mitre.org/index.html) identifiers from GitLab to track -vulnerabilities found within your project. +A [CVE](https://cve.mitre.org/index.html) identifier is assigned to a publicly-disclosed software +vulnerability. GitLab is a [CVE Numbering Authority](https://about.gitlab.com/security/cve/) +([CNA](https://cve.mitre.org/cve/cna.html)). For any public project you can request +a CVE identifier (ID). -## Overview +Assigning a CVE ID to a vulnerability in your project helps your users stay secure and informed. For +example, [dependency scanning tools](../application_security/dependency_scanning/index.md) can +detect when vulnerable versions of your project are used as a dependency. -CVE identifiers track specific vulnerabilities within projects. Having a CVE assigned to a -vulnerability in your project helps your users stay secure and informed. For example, -[dependency scanning tools](../application_security/dependency_scanning/index.md) -can detect when vulnerable versions of your project are used as a dependency. +A common vulnerability workflow is: -## Conditions +1. Request a CVE for a vulnerability. +1. Reference the assigned CVE identifier in release notes. +1. Publish the vulnerability's details after the fix is released. -If the following conditions are met, a **Request CVE ID** button appears in your issue sidebar: +## Prerequisites -- The project is hosted in GitLab.com. +To [submit a CVE ID Request](#submit-a-cve-id-request) the following prerequisites must be met: + +- The project is hosted on GitLab.com. - The project is public. - You are a maintainer of the project. -- The issue is [confidential](../project/issues/confidential_issues.md). - -## Submitting a CVE ID Request - -Clicking the **Request CVE ID** button in the issue sidebar takes you to the new issue page for -the [GitLab CVE project](https://gitlab.com/gitlab-org/cves). +- The vulnerability's issue is [confidential](../project/issues/confidential_issues.md). - +## Submit a CVE ID request -Creating the [confidential issue](../project/issues/confidential_issues.md) starts the CVE request process. +To submit a CVE ID request: - +1. Go to the vulnerability's issue and select **Create CVE ID Request**. The new issue page of + the [GitLab CVE project](https://gitlab.com/gitlab-org/cves) opens. -You are required to fill in the issue description, which includes: +  -- A description of the vulnerability -- The project's vendor and name -- Impacted versions -- Fixed versions -- The vulnerability type (a [CWE](https://cwe.mitre.org/data/index.html) identifier) -- A [CVSS v3 vector](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator) +1. In the **Title** box, enter a brief description of the vulnerability. -## CVE Assignment +1. In the **Description** box, enter the following details: -GitLab triages your submitted CVE ID request and communicates with you throughout the CVE validation -and assignment process. + - A detailed description of the vulnerability + - The project's vendor and name + - Impacted versions + - Fixed versions + - The vulnerability class (a [CWE](https://cwe.mitre.org/data/index.html) identifier) + - A [CVSS v3 vector](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator) - +  -Once a CVE identifier is assigned, you may use and reference it as you see fit. +GitLab updates your CVE ID request issue when: -Details of the vulnerability submitted in the CVE ID request are published according to your -schedule. It's common to request a CVE for an unpatched vulnerability, reference the assigned CVE -identifier in release notes, and later publish the vulnerability's details after the fix is -released. +- Your submission is assigned a CVE. +- Your CVE is published. +- MITRE is notified that your CVE is published. +- MITRE has added your CVE in the NVD feed. -Separate communications notify you when different stages of the publication process are complete. +## CVE assignment - +After a CVE identifier is assigned, you can reference it as required. Details of the vulnerability +submitted in the CVE ID request are published according to your schedule. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 5094ccd2196..9c5b84f4f36 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -10,13 +10,13 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12. WARNING: -This product is an early access and is considered a [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) feature. +This product is in an early-access stage and is considered a [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) feature. GitLab DAST's new browser-based crawler is a crawl engine built by GitLab to test Single Page Applications (SPAs) and traditional web applications. Due to the reliance of modern web applications on JavaScript, handling SPAs or applications that are dependent on JavaScript is paramount to ensuring proper coverage of an application for Dynamic Application Security Testing (DAST). -The browser-based crawler works by loading the target application into a specially-instrumented Chromium browser. A snapshot of the page is taken prior to a search to find any actions that a user might perform, -such as clicking on a link or filling in a form. For each action found, the crawler will execute it, take a new snapshot and determine what in the page changed from the previous snapshot. +The browser-based crawler works by loading the target application into a specially-instrumented Chromium browser. A snapshot of the page is taken before a search to find any actions that a user might perform, +such as clicking on a link or filling in a form. For each action found, the crawler executes it, takes a new snapshot, and determines what in the page changed from the previous snapshot. Crawling continues by taking more snapshots and finding subsequent actions. The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don't understand. This results in better coverage of the website. @@ -57,17 +57,17 @@ The browser-based crawler can be configured using CI/CD variables. | `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | | `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | | `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | -| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | +| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com, we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but are likely to produce little benefit after five to seven instances. | | `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | | `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | -| `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another | -| `DAST_BROWSER_ACTION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action | -| `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis | -| `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes | -| `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `800ms` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after completing an action | -| `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or navigations | -| `DAST_BROWSER_EXTRACT_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `5s` | The maximum amount of time to allow the browser to extract newly found elements or navigations | -| `DAST_BROWSER_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis | +| `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another. | +| `DAST_BROWSER_ACTION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action. | +| `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis. | +| `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes. | +| `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `800ms` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after completing an action. | +| `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or navigations. | +| `DAST_BROWSER_EXTRACT_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `5s` | The maximum amount of time to allow the browser to extract newly found elements or navigations. | +| `DAST_BROWSER_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis. | The [DAST variables](index.md#available-cicd-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, `DAST_AUTH_URL`, `DAST_USERNAME`, `DAST_PASSWORD`, `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, `DAST_SUBMIT_FIELD`, `DAST_EXCLUDE_URLS`, `DAST_AUTH_VERIFICATION_URL`, `DAST_BROWSER_AUTH_VERIFICATION_SELECTOR`, `DAST_BROWSER_AUTH_VERIFICATION_LOGIN_FORM`, `DAST_BROWSER_AUTH_REPORT`, @@ -80,27 +80,27 @@ While the browser-based crawler crawls modern web applications efficiently, vuln The crawler runs the target website in a browser with DAST/ZAP configured as the proxy server. This ensures that all requests and responses made by the browser are passively scanned by DAST/ZAP. When running a full scan, active vulnerability checks executed by DAST/ZAP do not use a browser. This difference in how vulnerabilities are checked can cause issues that require certain features of the target website to be disabled to ensure the scan works as intended. -For example, for a target website that contains forms with Anti-CSRF tokens, a passive scan will scan as intended because the browser displays pages/forms as if a user is viewing the page. -However, active vulnerability checks run in a full scan will not be able to submit forms containing Anti-CSRF tokens. In such cases we recommend you disable Anti-CSRF tokens when running a full scan. +For example, for a target website that contains forms with Anti-CSRF tokens, a passive scan works as intended because the browser displays pages and forms as if a user is viewing the page. +However, active vulnerability checks that run in a full scan cannot submit forms containing Anti-CSRF tokens. In such cases, we recommend you disable Anti-CSRF tokens when running a full scan. ## Managing scan time -It is expected that running the browser-based crawler will result in better coverage for many web applications, when compared to the normal GitLab DAST solution. +It is expected that running the browser-based crawler results in better coverage for many web applications, when compared to the normal GitLab DAST solution. This can come at a cost of increased scan time. You can manage the trade-off between coverage and scan time with the following measures: - Limit the number of actions executed by the browser with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. - Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. -- Vertically scaling the runner and using a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. +- Vertically scale the runner and use a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. ## Timeouts Due to poor network conditions or heavy application load, the default timeouts may not be applicable to your application. -Browser-based scans offer the ability to adjust various timeouts to ensure it continues smoothly as it transitions from one page to the next. These values are configured using a [Duration string](https://golang.org/pkg/time/#ParseDuration) which allow you to configure durations with a prefix: `m` for minutes, `s` for seconds, and `ms` for milliseconds. +Browser-based scans offer the ability to adjust various timeouts to ensure it continues smoothly as it transitions from one page to the next. These values are configured using a [Duration string](https://golang.org/pkg/time/#ParseDuration), which allow you to configure durations with a prefix: `m` for minutes, `s` for seconds, and `ms` for milliseconds. -Navigations, or the act of loading a new page, usually require the most amount of time as they are +Navigations, or the act of loading a new page, usually require the most amount of time because they are loading multiple new resources such as JavaScript or CSS files. Depending on the size of these resources, or the speed at which they are returned, the default `DAST_BROWSER_NAVIGATION_TIMEOUT` may not be sufficient. Stability timeouts, such as those configurable with `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT`, and `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` can also be configured. Stability timeouts determine when browser-based scans consider @@ -110,11 +110,11 @@ a page fully loaded. Browser-based scans consider a page loaded when: 1. There are no open or outstanding requests that are deemed important, such as JavaScript and CSS. Media files are usually deemed unimportant. 1. Depending on whether the browser executed a navigation, was forcibly transitioned, or action: - - There are no new Document Object Model (DOM) modification events after the `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT` or `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` durations + - There are no new Document Object Model (DOM) modification events after the `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT`, or `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` durations. -After these events have occurred, browser-based scans consider the page loaded and ready and attempt the next action. +After these events have occurred, browser-based scans consider the page loaded and ready, and attempt the next action. -If your application experiences latency or returns many navigation failures, consider adjusting the timeout values such in this example: +If your application experiences latency or returns many navigation failures, consider adjusting the timeout values such as in this example: ```yaml include: @@ -132,7 +132,7 @@ dast: ``` NOTE: -Adjusting these values may impact scan time as they adjust how long each browser waits for various activities to complete. +Adjusting these values may impact scan time because they adjust how long each browser waits for various activities to complete. ## Debugging scans using logging @@ -168,7 +168,7 @@ The modules that can be configured for logging are as follows: | Log module | Component overview | | ---------- | ----------- | | `AUTH` | Used for creating an authenticated scan. | -| `BROWS` | Used for querying the state/page of the browser. | +| `BROWS` | Used for querying the state or page of the browser. | | `BPOOL` | The set of browsers that are leased out for crawling. | | `CRAWL` | Used for the core crawler algorithm. | | `DATAB` | Used for persisting data to the internal database. | diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index f771bc82d58..9969526c906 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -20,7 +20,7 @@ A DAST job has two executing processes: Enable the `DAST_DEBUG` CI/CD variable to debug scripts. This can help when troubleshooting the job, and outputs statements indicating what percentage of the scan is complete. -For details on using variables, see [Overriding the DAST template](index.md#customizing-the-dast-settings). +For details on using variables, see [Overriding the DAST template](index.md#customize-dast-settings). Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` variable. The following table outlines examples of values that can be set and the effect that they have on the output that is logged. diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 0d60701b030..09b55e7b395 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -269,7 +269,7 @@ image. Using the `DAST_VERSION` variable, you can choose how DAST updates: - Only update fixes by pinning to a minor version (such as `1.6`). - Prevent all updates by pinning to a specific version (such as `1.6.4`). -Find the latest DAST versions on the [Releases](https://gitlab.com/security-products/dast/-/releases) +Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. #### Configure DAST using the UI @@ -483,6 +483,13 @@ When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` CI/CD variable. +### List URLs scanned + +When DAST completes scanning, the merge request page states the number of URLs scanned. +Click **View details** to view the web console output which includes the list of scanned URLs. + + + ### View details of a vulnerability detected by DAST > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. @@ -515,15 +522,20 @@ To view details of vulnerabilities detected by DAST: | Links | Links to further details of the detected vulnerability. | | Solution | Details of a recommended solution to the vulnerability (optional). | -### Customizing the DAST settings +## Customize DAST settings + +You can customize the behavior of DAST using both CI/CD variables and command-line options. Use of CI/CD +variables overrides the values contained in the DAST template. + +### Customize DAST using CI/CD variables WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. +is no longer supported. You must use [`rules`](../../../ci/yaml/index.md#rules) instead. The DAST settings can be changed through CI/CD variables by using the -[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. -These variables are documented in [available variables](#available-cicd-variables). +[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. For details of +all DAST CI/CD variables, read [Available CI/CD variables](#available-cicd-variables). For example: @@ -539,10 +551,10 @@ variables: Because the template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline configuration, the last mention of the variable takes precedence. -#### Enabling and disabling rules +#### Enable or disable rules A complete list of the rules that DAST uses to scan for vulnerabilities can be -found in the [ZAP docs](https://www.zaproxy.org/docs/alerts/). +found in the [ZAP documentation](https://www.zaproxy.org/docs/alerts/). `DAST_EXCLUDE_RULES` disables the rules with the given IDs. @@ -559,7 +571,7 @@ can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-produ The lists for `DAST_EXCLUDE_RULES` and `DAST_ONLY_INCLUDE_RULES` **must** be enclosed in double quotes (`"`), otherwise they are interpreted as numeric values. -### Hide sensitive information +#### Hide sensitive information > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. @@ -573,7 +585,105 @@ authorization credentials. By default, the following headers are masked: Using the [`DAST_MASK_HTTP_HEADERS` CI/CD variable](#available-cicd-variables), you can list the headers whose values you want masked. For details on how to mask headers, see -[Customizing the DAST settings](#customizing-the-dast-settings). +[Customizing the DAST settings](#customize-dast-settings). + +#### Available CI/CD variables + +These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. + +| CI/CD variable | Type | Description | +|:-------------------------------------------------|:--------------|:------------------------------| +| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | +| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080`. | +| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_AUTH_REPORT` <sup>2</sup> | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | +| `DAST_AUTH_EXCLUDE_URLS` <sup>2</sup> | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | +| `DAST_AUTH_URL` <sup>1,2</sup> | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. Example: `https://login.example.com`. | +| `DAST_AUTH_VERIFICATION_LOGIN_FORM` <sup>2</sup> | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. | +| `DAST_AUTH_VERIFICATION_SELECTOR` <sup>2</sup> | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo`. | +| `DAST_AUTH_VERIFICATION_URL` <sup>1,2</sup> | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. Example: `"http://example.com/loggedin_page"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | +| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | +| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | +| `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | +| `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | +| `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | +| `DAST_PASSWORD` <sup>1,2</sup> | string | The password to authenticate to in the website. Example: `P@55w0rd!` | +| `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_REQUEST_HEADERS` <sup>1</sup> | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | +| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | +| `DAST_SPIDER_MINS` <sup>1</sup> | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | +| `DAST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. For example, `css:button[type='submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. | +| `DAST_USE_AJAX_SPIDER` <sup>1</sup> | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_USERNAME` <sup>1,2</sup> | string | The username to authenticate to in the website. Example: `admin` | +| `DAST_USERNAME_FIELD` <sup>1,2</sup> | string | The selector of username field at the sign-in HTML form. Example: `name:username` | +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | +| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | +| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | + +1. Available to an on-demand DAST scan. +1. Used for authentication. + +### Customize DAST using command-line options + +Not all DAST configuration is available via CI/CD variables. To find out all +possible options, run the following configuration. +Available command-line options are printed to the job log: + +```yaml +include: + template: DAST.gitlab-ci.yml + +dast: + script: + - /analyze --help +``` + +You must then overwrite the `script` command to pass in the appropriate +argument. For example, vulnerability definitions in alpha can be included with +`-a`. The following configuration includes those definitions: + +```yaml +include: + template: DAST.gitlab-ci.yml + +dast: + script: + - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} + - /analyze -a -t $DAST_WEBSITE +``` + +### Custom ZAProxy configuration + +The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_245801885). +Many key/values for `-config` remain undocumented, but there is an untested list of +[possible keys](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_244981023). +Note that these options are not supported by DAST, and may break the DAST scan +when used. An example of how to rewrite the Authorization header value with `TOKEN` follows: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_ZAP_CLI_OPTIONS: "-config replacer.full_list(0).description=auth -config replacer.full_list(0).enabled=true -config replacer.full_list(0).matchtype=REQ_HEADER -config replacer.full_list(0).matchstr=Authorization -config replacer.full_list(0).regex=false -config replacer.full_list(0).replacement=TOKEN" +``` ## Authentication @@ -747,59 +857,6 @@ dast: when: always ``` -## Available CI/CD variables - -These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. - -| CI/CD variable | Type | Description | -|:-------------------------------------------------|:--------------|:------------------------------| -| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | -| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | -| `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080`. | -| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_AUTH_REPORT` <sup>2</sup> | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | -| `DAST_AUTH_EXCLUDE_URLS` <sup>2</sup> | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | -| `DAST_AUTH_URL` <sup>1,2</sup> | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. Example: `https://login.example.com`. | -| `DAST_AUTH_VERIFICATION_LOGIN_FORM` <sup>2</sup> | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. | -| `DAST_AUTH_VERIFICATION_SELECTOR` <sup>2</sup> | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo`. | -| `DAST_AUTH_VERIFICATION_URL` <sup>1,2</sup> | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. Example: `"http://example.com/loggedin_page"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | -| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | -| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | -| `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | -| `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | -| `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | -| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | -| `DAST_PASSWORD` <sup>1,2</sup> | string | The password to authenticate to in the website. Example: `P@55w0rd!` | -| `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | -| `DAST_REQUEST_HEADERS` <sup>1</sup> | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | -| `DAST_SPIDER_MINS` <sup>1</sup> | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | -| `DAST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. For example, `css:button[type='submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. | -| `DAST_USE_AJAX_SPIDER` <sup>1</sup> | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_USERNAME` <sup>1,2</sup> | string | The username to authenticate to in the website. Example: `admin` | -| `DAST_USERNAME_FIELD` <sup>1,2</sup> | string | The selector of username field at the sign-in HTML form. Example: `name:username` | -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | -| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | -| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | - -1. Available to an on-demand DAST scan. -1. Used for authentication. - ### Selectors Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. @@ -848,51 +905,6 @@ When using selectors to locate specific fields we recommend you avoid searching - XPath searches as they are less performant than other selector searches. - Unscoped searches, such as those beginning with `css:*` and `xpath://*`. -### DAST command-line options - -Not all DAST configuration is available via CI/CD variables. To find out all -possible options, run the following configuration. -Available command-line options are printed to the job log: - -```yaml -include: - template: DAST.gitlab-ci.yml - -dast: - script: - - /analyze --help -``` - -You must then overwrite the `script` command to pass in the appropriate -argument. For example, vulnerability definitions in alpha can be included with -`-a`. The following configuration includes those definitions: - -```yaml -include: - template: DAST.gitlab-ci.yml - -dast: - script: - - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -a -t $DAST_WEBSITE -``` - -### Custom ZAProxy configuration - -The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_245801885). -Many key/values for `-config` remain undocumented, but there is an untested list of -[possible keys](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_244981023). -Note that these options are not supported by DAST, and may break the DAST scan -when used. An example of how to rewrite the Authorization header value with `TOKEN` follows: - -```yaml -include: - template: DAST.gitlab-ci.yml - -variables: - DAST_ZAP_CLI_OPTIONS: "-config replacer.full_list(0).description=auth -config replacer.full_list(0).enabled=true -config replacer.full_list(0).matchtype=REQ_HEADER -config replacer.full_list(0).matchstr=Authorization -config replacer.full_list(0).regex=false -config replacer.full_list(0).replacement=TOKEN" -``` - ### Bleeding-edge vulnerability definitions ZAP first creates rules in the `alpha` class. After a testing period with @@ -1002,12 +1014,15 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. #### Schedule an on-demand scan -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per user, -ask an administrator to [disable the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md). -The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the feature flag](../../../administration/feature_flags.md) named +`dast_on_demand_scans_scheduler`. +On GitLab.com, this feature is available. To schedule a scan: @@ -1185,11 +1200,9 @@ If a validated site profile's target URL is edited, the site's validation status #### Retry a failed validation -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an -administrator to [disable the `dast_failed_site_validations` flag](../../../administration/feature_flags.md). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. +> - [Deployed behind the `dast_failed_site_validations` flag](../../../administration/feature_flags.md), enabled by default. +> - [Feature flag `dast_failed_site_validations` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323961) in GitLab 14.4. If a site profile's validation fails, you can retry it by selecting the **Retry validation** button in the profiles list. @@ -1308,7 +1321,7 @@ If a scanner profile is linked to a security policy, a user cannot delete the pr page. See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. -### Auditing +## Auditing > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. @@ -1320,13 +1333,6 @@ and DAST site profiles are included in the [audit log](../../../administration/a The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in Markdown, HTML, and XML. For more information, see the [schema for DAST reports](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dast-report-format.json). -### List of URLs scanned - -When DAST completes scanning, the merge request page states the number of URLs scanned. -Click **View details** to view the web console output which includes the list of scanned URLs. - - - ### JSON WARNING: diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 055a2ceb161..3b1c91b0be4 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -635,7 +635,7 @@ can be added, removed, and modified by creating a custom configuration. | `DAST_API_TARGET_URL` | Base URL of API testing target. | |[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | -|[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | +|[`DAST_API_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | @@ -899,7 +899,7 @@ variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. -When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `FUZZAPI_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. +When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `DAST_API_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. To verify the paths are excluded, review the `Tested Operations` and `Excluded Operations` portion of the job output. You should not see any excluded paths listed under `Tested Operations`. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index fae0f457a20..8559d5af02e 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -47,7 +47,7 @@ In `.gitlab-ci.yml` define: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml + template: Security/Dependency-Scanning.gitlab-ci.yml variables: SECURE_ANALYZERS_PREFIX: my-docker-registry/gl-images @@ -64,7 +64,7 @@ In `.gitlab-ci.yml` define: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml + template: Security/Dependency-Scanning.gitlab-ci.yml variables: DS_EXCLUDED_ANALYZERS: "bundler-audit, gemnasium" @@ -77,7 +77,7 @@ In `.gitlab-ci.yml` define: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml + template: Security/Dependency-Scanning.gitlab-ci.yml variables: DS_EXCLUDED_ANALYZERS: "gemnasium, gemnasium-maven, gemnasium-python, bundler-audit, retire.js" diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index d903ce58982..1f840c96663 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -82,6 +82,7 @@ table.supported-languages tr td:last-child { } table.supported-languages ul { + font-size: 1em; list-style-type: none; padding-left: 0px; margin-bottom: 0px; @@ -346,7 +347,7 @@ Add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml ``` The included template creates dependency scanning jobs in your CI/CD @@ -380,7 +381,7 @@ For example: ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml variables: SECURE_LOG_LEVEL: error @@ -402,7 +403,7 @@ the `gemnasium` analyzer: ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml gemnasium-dependency_scanning: variables: @@ -413,7 +414,7 @@ To override the `dependencies: []` attribute, add an override job as above, targ ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml gemnasium-dependency_scanning: dependencies: ["build"] @@ -712,7 +713,7 @@ value of `GEMNASIUM_DB_REMOTE_URL` to the location of your offline Git copy of t ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml variables: SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers" @@ -867,7 +868,7 @@ to the supported `requirements.txt` as follows. ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml stages: - test @@ -926,3 +927,37 @@ gemnasium-maven-dependency_scanning: - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import ``` + +### Dependency Scanning job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` + +Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: + +- Disabled by default in GitLab 13.0 and later. +- Unsupported from GitLab 13.4 and later. + +To fix this error, disable Docker-in-Docker for dependency scanning. Individual +`<analyzer-name>-dependency_scanning` jobs are created for each analyzer that runs in your CI/CD +pipeline. + +```yaml +include: + - template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DISABLE_DIND: "true" +``` + +### Message `<file> does not exist in <commit SHA>` + +When the `Location` of a dependency in a file is shown, the path in the link goes to a specific Git +SHA. + +If the lock file that our dependency scanning tools reviewed was cached, however, selecting that +link redirects you to the repository root, with the message: +`<file> does not exist in <commit SHA>`. + +The lock file is cached during the build phase and passed to the dependency scanning job before the +scan occurs. Because the cache is downloaded before the analyzer run occurs, the existence of a lock +file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. + +We recommend committing the lock files, which prevents this warning. diff --git a/doc/user/application_security/img/cve_request_communication.png b/doc/user/application_security/img/cve_request_communication.png Binary files differdeleted file mode 100644 index 5c58df463ef..00000000000 --- a/doc/user/application_security/img/cve_request_communication.png +++ /dev/null diff --git a/doc/user/application_security/img/cve_request_communication_publication.png b/doc/user/application_security/img/cve_request_communication_publication.png Binary files differdeleted file mode 100644 index 9eb6f2f8d9f..00000000000 --- a/doc/user/application_security/img/cve_request_communication_publication.png +++ /dev/null diff --git a/doc/user/application_security/img/new_cve_request_issue.png b/doc/user/application_security/img/new_cve_request_issue.png Binary files differindex 6ea7ca4a2ab..5f9deeb7bd9 100644 --- a/doc/user/application_security/img/new_cve_request_issue.png +++ b/doc/user/application_security/img/new_cve_request_issue.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index bd143d8608a..e1ddb3167ff 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -1,18 +1,14 @@ --- stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Policies **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. Deployed behind a feature flag, disabled by default. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.3. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to [disable the `security_orchestration_policies_configuration` flag](../../../administration/feature_flags.md). -On GitLab.com, this feature is available. +> - Introduced in GitLab Ultimate 13.10 [with a flag](https://gitlab.com/groups/gitlab-org/-/epics/5329) named `security_orchestration_policies_configuration`. Disabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab Ultimate 14.3. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.4. Policies in GitLab provide security teams a way to require scans of their choice to be run whenever a project pipeline runs according to the configuration specified. Security teams can @@ -28,8 +24,8 @@ GitLab supports the following security policies: The Policies page displays deployed policies for all available environments. You can check a -policy's information (for example description, enforcement -status, etc.), and create and edit deployed policies: +policy's information (for example, description or enforcement +status), and create and edit deployed policies: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Policies**. @@ -53,7 +49,7 @@ users must make changes by following the ## Policy editor -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in GitLab Ultimate 13.4. You can use the policy editor to create, edit, and delete policies: @@ -83,7 +79,7 @@ mode to fix your policy before Rule mode is available again. ## Container Network Policy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in GitLab Ultimate 12.9. The **Container Network Policy** section provides packet flow metrics for your application's Kubernetes namespace. This section has the following @@ -158,7 +154,7 @@ at the bottom of the editor. ### Configure a Network Policy Alert -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab Ultimate 13.9. > - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. You can use policy alerts to track your policy's impact. Alerts are only available if you've @@ -255,6 +251,10 @@ The policy editor currently only supports the YAML mode. The Rule mode is tracke The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key. +When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json). +If you're not familiar with how to read [JSON schemas](https://json-schema.org/), +the following sections and tables provide an alternative. + | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| | `scan_execution_policy` | `array` of Scan Execution Policy | | List of scan execution policies (maximum 5) | @@ -291,6 +291,8 @@ This rule enforces the defined actions and schedules a scan on the provided date #### `cluster` schema +Use this schema to define `clusters` objects in the [`schedule` rule type](#schedule-rule-type). + | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| | `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). | @@ -323,13 +325,16 @@ Note the following: - For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) are not supported. - A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in - [`historic`](../secret_detection/index.md#full-history-secret-scan) + [`historic`](../secret_detection/index.md#full-history-secret-detection) mode when executed as part of a scheduled scan. - A container scanning and cluster image scanning scans configured for the `pipeline` rule type will ignore the cluster defined in the `clusters` object. They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). -Here's an example: +### Example security policies project + +You can use this example in a `.gitlab/security-policies/policy.yml`, as described in +[Security policies project](#security-policies-project). ```yaml --- @@ -398,6 +403,24 @@ In this example: - Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. +### Example for scan execution policy editor + +You can use this example in the YAML mode of the [Scan Execution Policy editor](#scan-execution-policy-editor). +It corresponds to a single object from the previous example. + +```yaml +name: Enforce Secret Detection and Container Scanning in every default branch pipeline +description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch +enabled: true +rules: + - type: pipeline + branches: + - main +actions: + - scan: secret_detection + - scan: container_scanning +``` + ## Roadmap See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/) diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 3caa1771a5b..7ffefd34e40 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -27,6 +27,8 @@ analysis are available in the [security dashboards](../security_dashboard/index. The results are sorted by the priority of the vulnerability: +<!-- vale gitlab.SubstitutionWarning = NO --> + 1. Critical 1. High 1. Medium @@ -34,6 +36,8 @@ The results are sorted by the priority of the vulnerability: 1. Info 1. Unknown +<!-- vale gitlab.SubstitutionWarning = YES --> + A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard does not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard does not show SAST results. On failure, @@ -71,10 +75,11 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | | .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | | Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | -| C | [Semgrep](https://semgrep.dev) | 14.2 | +| C | [Semgrep](https://semgrep.dev) | 14.2 | | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | | Go | [Gosec](https://github.com/securego/gosec) | 10.7 | +| Go | [Semgrep](https://semgrep.dev) | 14.4 | | Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | | Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | | Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | @@ -184,26 +189,60 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. -### Configure SAST in the UI **(ULTIMATE)** +### Configure SAST in the UI + +You can enable and configure SAST in the UI, either with default settings, or with customizations. +Use the method that best meets your needs. + +- [Configure SAST in the UI with default settings](#configure-sast-in-the-ui-with-default-settings) +- [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations) + +### Configure SAST in the UI with default settings **(FREE)** + +> [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 + +To enable and configure SAST with default settings: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance** > **Configuration**. +1. In the SAST section, select `Enable via MR`. +1. Review the draft MR that enables SAST with the default recommended settings in the + `.gitlab-ci.yml` file. +1. Merge the MR to enable SAST. You should see SAST jobs run in that MR's pipeline. + +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + +### Configure SAST in the UI with customizations **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab Ultimate 13.4. > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/3635) in GitLab Ultimate 13.5. -You can enable and configure SAST with a basic configuration using the **SAST Configuration** -page: +To enable and configure SAST with customizations: -1. From the project's home page, go to **Security & Compliance** > **Configuration** in the - left sidebar. -1. If the project does not have a `.gitlab-ci.yml` file, click **Enable** in the Static Application Security Testing (SAST) row, otherwise click **Configure**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. If the project does not have a `.gitlab-ci.yml` file, select **Enable** in the Static Application + Security Testing (SAST) row, otherwise select **Configure**. 1. Enter the custom SAST values. - Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. + Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST + Configuration page, their values are left unchanged. Default values are inherited from the GitLab + SAST template. -1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. -1. Click **Create Merge Request**. +1. Optionally, expand the **SAST analyzers** section, select individual + [SAST analyzers](analyzers.md) and enter custom analyzer values. +1. Select **Create Merge Request**. 1. Review and merge the merge request. +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + ### Customizing the SAST settings The SAST settings can be changed through [CI/CD variables](#available-cicd-variables) @@ -250,12 +289,16 @@ versions are pulled, there are certain cases where it can be beneficial to pin an analyzer to a specific release. To do so, override the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable in the job template directly. -In the example below, we are pinning to a specific patch version of the `spotbugs` analyzer: +In the example below, we pin to a specific patch version of the `spotbugs` analyzer and minor version of the `semgrep` analyzer: ```yaml include: - template: Security/SAST.gitlab-ci.yml +semgrep-sast: + variables: + SAST_ANALYZER_IMAGE_TAG: "2.12" + spotbugs-sast: variables: SAST_ANALYZER_IMAGE_TAG: "2.28.1" @@ -361,9 +404,6 @@ To create a custom ruleset: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292686) in GitLab 14.2. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the `vulnerability_flags` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available. - Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. ### Using CI/CD variables to pass credentials for private repositories @@ -536,9 +576,11 @@ all [custom variables](../../../ci/variables/index.md#custom-cicd-variables) are to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. -WARNING: -Variables having names starting with these prefixes are **not** propagated to the SAST Docker container and/or -analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. +NOTE: +In [GitLab 13.3 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/220540), +variables whose names started with the following prefixes are **not** propagated to either the +analyzer containers or SAST Docker container: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, +`OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. ### Experimental features @@ -807,3 +849,55 @@ This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, ### Semgrep slowness, unexpected results, or other errors If Semgrep is slow, reports too many false positives or false negatives, crashes, fails, or is otherwise broken, see the Semgrep docs for [troubleshooting GitLab SAST](https://semgrep.dev/docs/troubleshooting/gitlab-sast/). + +### SAST job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` + +Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: + +- Disabled by default in GitLab 13.0 and later. +- Unsupported from GitLab 13.4 and later. + +Several workarounds are available. From GitLab version 13.0 and later, you must not use +Docker-in-Docker. + +#### Workaround 1: Pin analyzer versions (GitLab 12.1 and earlier) + +Set the following variables for the SAST job. This pins the analyzer versions to the last known +working version, allowing SAST with Docker-in-Docker to complete as it did previously: + +```yaml +sast: + variables: + SAST_DEFAULT_ANALYZERS: "" + SAST_ANALYZER_IMAGES: "registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2.9.6, registry.gitlab.com/gitlab-org/security-products/analyzers/brakeman:2.11.0, registry.gitlab.com/gitlab-org/security-products/analyzers/eslint:2.10.0, registry.gitlab.com/gitlab-org/security-products/analyzers/flawfinder:2.11.1, registry.gitlab.com/gitlab-org/security-products/analyzers/gosec:2.14.0, registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2.11.0, registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2.9.1, registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2.9.0, registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3.12.0, registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2.13.0, registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2.8.0, registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2.13.6, registry.gitlab.com/gitlab-org/security-products/analyzers/tslint:2.4.0" +``` + +Remove any analyzers you don't need from the `SAST_ANALYZER_IMAGES` list. Keep +`SAST_DEFAULT_ANALYZERS` set to an empty string `""`. + +#### Workaround 2: Disable Docker-in-Docker for SAST and Dependency Scanning (GitLab 12.3 and later) + +Disable Docker-in-Docker for SAST. Individual `<analyzer-name>-sast` jobs are created for each +analyzer that runs in your CI/CD pipeline. + +```yaml +include: + - template: SAST.gitlab-ci.yml + +variables: + SAST_DISABLE_DIND: "true" +``` + +#### Workaround 3: Upgrade to GitLab 13.x and use the defaults + +From GitLab 13.0, SAST defaults to not using Docker-in-Docker. In GitLab 13.4 and later, SAST using +Docker-in-Docker is [no longer supported](https://gitlab.com/gitlab-org/gitlab/-/issues/220540). +If you have this problem on GitLab 13.x and later, you have customized your SAST job to +use Docker-in-Docker. To resolve this, comment out any customizations you've made to +your SAST CI job definition and [follow the documentation](index.md#configuration) +to reconfigure, using the new and improved job definition default values. + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml +``` diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index cd1014d36a6..5933496ea00 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -138,7 +138,7 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. -### Enable Secret Detection via an automatic merge request **(ULTIMATE SELF)** +### Enable Secret Detection via an automatic merge request **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1. @@ -151,7 +151,12 @@ from the Security Configuration page. 1. In the **Secret Detection** row, select **Configure via Merge Request**. This automatically creates a merge request with the changes necessary to enable Secret Detection -that you can review and merge to complete the configuration. +that you can review and merge to complete the configuration. + +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. ### Customizing settings @@ -167,12 +172,12 @@ WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. -#### GIT_DEPTH +#### `GIT_DEPTH` variable The [`GIT_DEPTH` CI/CD variable](../../../ci/runners/configure_runners.md#shallow-cloning) affects Secret Detection. The Secret Detection analyzer relies on generating patches between commits to scan content for secrets. If you override the default, ensure the value is greater than 1. If the number of commits -in an MR is greater than the GIT_DEPTH value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). +in an MR is greater than the `GIT_DEPTH` value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). #### Custom settings example @@ -285,20 +290,20 @@ sequenceDiagram Cloud Vendor-->>+RevocationAPI: ACCEPTED ``` -## Full History Secret Scan +## Full History Secret Detection GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality is particularly useful when you are enabling Secret Detection in a repository for the first time and you -want to perform a full secret scan. Running a secret scan on the full history can take a long time, +want to perform a full secret detection scan. Running a secret detection scan on the full history can take a long time, especially for larger repositories with lengthy Git histories. We recommend not setting this CI/CD variable as part of your normal job definition. A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-cicd-variables)) can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. -We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret scan. +We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret detection scan. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=wDtc_K00Y0A">Walkthrough of historical secret scan</a>. + See the video: <a href="https://www.youtube.com/watch?v=wDtc_K00Y0A">Walkthrough of historical secret detection scan</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe> diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 8b811c62ec3..f5b0194c320 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -45,6 +45,8 @@ From the Vulnerability Report you can: You can filter the vulnerabilities table by: +<!-- vale gitlab.SubstitutionWarning = NO --> + | Filter | Available options | |:---------|:------------------| | Status | Detected, Confirmed, Dismissed, Resolved. | @@ -53,6 +55,8 @@ You can filter the vulnerabilities table by: | Project | For more details, see [Project filter](#project-filter). | | Activity | For more details, see [Activity filter](#activity-filter). | +<!-- vale gitlab.SubstitutionWarning = YES --> + ### Filter the list of vulnerabilities To filter the list of vulnerabilities: diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 8313b20e795..cd166666ad6 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # AsciiDoc **(FREE)** @@ -85,7 +84,7 @@ I believe I shall--no, actually I won't. **Macros** ```plaintext -// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements, etc. +// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow]. The pass:c[->] operator is often referred to as the stabby lambda. Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}]. @@ -151,7 +150,7 @@ This paragraph has a footnote.footnote:[This is the text of the footnote.] ** level 2 *** level 3 **** level 4 -***** etc. +***** level 5 * back at level 1 + Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block). @@ -240,10 +239,10 @@ include::basics.adoc[] include::https://example.org/installation.adoc[] ``` -To guarantee good system performance and prevent malicious documents causing -problems, GitLab enforces a **maximum limit** on the number of include directives -processed in any one document. Currently a total of 32 documents can be -included, a number that is inclusive of transitive dependencies. +To guarantee good system performance and prevent malicious documents from causing +problems, GitLab enforces a maximum limit on the number of include directives +processed in any one document. You can include up to 32 documents, which is +inclusive of transitive dependencies. ### Blocks @@ -428,7 +427,7 @@ If you're new to using Mermaid or need help identifying issues in your Mermaid c the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams. -In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block: +To generate a diagram or flowchart, enter your text in a `mermaid` block: ```plaintext [mermaid] @@ -447,7 +446,7 @@ Kroki supports more than a dozen diagram libraries. To make Kroki available in GitLab, a GitLab administrator needs to enable it first. Read more in the [Kroki integration](../administration/integration/kroki.md) page. -Once Kroki is enabled, you can create a wide variety of diagrams in AsciiDoc and Markdown documents. +After Kroki is enabled, you can create diagrams in AsciiDoc and Markdown documents. Here's an example using a GraphViz diagram: **AsciiDoc** @@ -476,7 +475,7 @@ digraph G { To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. Read more in [PlantUML & GitLab](../administration/integration/plantuml.md). -Once enabled, you should write your text inside the `plantuml` block: +After PlantUML is enabled, enter your text in a `plantuml` block: ```plaintext [plantuml] diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index de250bc5fb4..88651688779 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -6,11 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Award emoji **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/1825) in GitLab 8.2. -> - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9570) the usage of native emoji if the platform -> supports them and falls back to images or CSS sprites. This change greatly -> improved award emoji performance overall. - When you're collaborating online, you get fewer opportunities for high-fives and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md), [snippets](snippets.md), and anywhere you can have a thread. @@ -24,8 +19,6 @@ For information on the relevant API, see [Award Emoji API](../api/award_emoji.md ## Sort issues and merge requests on vote count -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2781) in GitLab 8.5. - You can quickly sort issues and merge requests by the number of votes they have received. The sort options can be found in the dropdown menu as "Most popular" and "Least popular". @@ -38,8 +31,6 @@ downvotes. ## Award emoji for comments -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4291) in GitLab 8.9. - Award emoji can also be applied to individual comments when you want to celebrate an accomplishment or agree with an opinion. diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 1ea5168f30c..6c8b7c95771 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -10,6 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. > - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +WARNING: +The CI/CD Tunnel is not supported for GitLab self-managed instances installed via Omnibus. We +plan to [add support for Omnibus](https://gitlab.com/gitlab-org/gitlab/-/issues/324272) in the future. + The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index d2dc57c0849..557d389147d 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -15,7 +15,7 @@ The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/ is an active in-cluster component for solving GitLab and Kubernetes integration tasks in a secure and cloud-native way. It enables: -- Integrating GitLab with a Kubernetes cluster behind a firewall or NAT +- GitLab integration with a Kubernetes cluster behind a firewall or NAT (network address translation). - Pull-based GitOps deployments. - [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster. @@ -28,7 +28,7 @@ and [our development documentation](https://gitlab.com/gitlab-org/cluster-integr ## GitLab Agent GitOps workflow -The GitLab Agent uses multiple GitLab projects to provide a flexible workflow +The GitLab Agent, herein _Agent_, uses multiple GitLab projects to provide a flexible workflow that can suit various needs. This diagram shows these repositories and the main actors involved in a deployment: @@ -54,10 +54,10 @@ There are several components that work in concert for the Agent to accomplish Gi - A properly-configured Kubernetes cluster where the Agent is running. - A configuration repository that contains a `config.yaml` file, which tells the - Agent which repositories to synchronize with the cluster. + Agent the repositories to synchronize with the cluster. - A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster. -You can use the same GitLab project or separate projects for configuration and manifest files, as follows: +You can use the same GitLab project or projects for configuration and manifest files, as follows: - Single GitLab project (recommended): when you use a single repository to hold both the manifest and the configuration files, these projects can be either private or public, as you prefer. - Two GitLab projects: when you opt to use two different GitLab projects, one for manifest files, and another for configuration files, the manifests project must be public, while the configuration project can be either private or public. Our backlog contains issues for adding support for @@ -73,8 +73,8 @@ The setup process involves a few steps to enable GitOps deployments: 1. [Set up the Kubernetes Agent Server](#set-up-the-kubernetes-agent-server) for your GitLab instance. 1. [Define a configuration repository](#define-a-configuration-repository). 1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). -1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). 1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). +1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). 1. [Create manifest files](#create-manifest-files). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. @@ -200,7 +200,7 @@ For more advanced configurations, we recommend to use [the `kpt` based installat Otherwise, follow the manual installation steps described below. -##### Create the Kubernetes secret +### Create the Kubernetes secret After generating the token, you must apply it to the Kubernetes cluster. @@ -256,7 +256,7 @@ NAMESPACE NAME READY S gitlab-kubernetes-agent gitlab-kubernetes-agent-77689f7dcb-5skqk 1/1 Running 0 51s ``` -##### Example `resources.yml` file +#### Example `resources.yml` file ```yaml --- @@ -403,7 +403,7 @@ The following example projects can help you get started with the Kubernetes Agen - [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) - This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) -### Deploying GitLab Runner with the Agent +### GitLab Runner Deployment with the Agent You can use the Kubernetes Agent to [deploy GitLab Runner in a Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes-agent.html). @@ -444,6 +444,41 @@ the current project, and the configuration directory for each agent: Additional management interfaces are planned for the GitLab Kubernetes Agent. [Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). +## Remove the GitLab Kubernetes Agent + +1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`. + + ```graphql + mutation deleteAgent { + clusterAgentDelete(input: { id: "<cluster-agent-id>" } ) { + errors + } + } + + mutation deleteToken { + clusterAgentTokenDelete(input: { id: "<cluster-agent-token-id>" }) { + errors + } + } + ``` + +1. Verify whether the removal occurred successfully. If the output in the Pod logs includes `unauthenticated`, it means that the agent was successfully removed: + + ```json + { + "level": "warn", + "time": "2021-04-29T23:44:07.598Z", + "msg": "GetConfiguration.Recv failed", + "error": "rpc error: code = Unauthenticated desc = unauthenticated" + } + ``` + +1. Delete the GitLab Kubernetes Agent in your cluster: + + ```shell + kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml + ``` + ## Troubleshooting If you face any issues while using GitLab Kubernetes Agent, you can read the @@ -455,10 +490,17 @@ kubectl logs -f -l=app=gitlab-kubernetes-agent -n gitlab-kubernetes-agent GitLab administrators can additionally view the [Kubernetes Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). -### Agent logs - Transport: Error while dialing failed to WebSocket dial +### Agent logs + +#### Transport: Error while dialing failed to WebSocket dial ```json -{"level":"warn","time":"2020-11-04T10:14:39.368Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""} +{ + "level": "warn", + "time": "2020-11-04T10:14:39.368Z", + "msg": "GetConfiguration failed", + "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\"" +} ``` This error is shown if there are some connectivity issues between the address @@ -466,27 +508,45 @@ specified as `kas-address`, and your Agent pod. To fix it, make sure that you specified the `kas-address` correctly. ```json -{"level":"error","time":"2021-06-25T21:15:45.335Z","msg":"Reverse tunnel","mod_name":"reverse_tunnel","error":"Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\""} +{ + "level": "error", + "time": "2021-06-25T21:15:45.335Z", + "msg": "Reverse tunnel", + "mod_name": "reverse_tunnel", + "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\"" +} ``` This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the `wss` or `ws` URL ends with a training slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. -### Agent logs - ValidationError(Deployment.metadata) +#### ValidationError(Deployment.metadata) ```json -{"level":"info","time":"2020-10-30T08:56:54.329Z","msg":"Synced","project_id":"root/kas-manifest001","resource_key":"apps/Deployment/kas-test001/nginx-deployment","sync_result":"error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"} +{ + "level": "info", + "time": "2020-10-30T08:56:54.329Z", + "msg": "Synced", + "project_id": "root/kas-manifest001", + "resource_key": "apps/Deployment/kas-test001/nginx-deployment", + "sync_result": "error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]" +} ``` This error is shown if a manifest file is malformed, and Kubernetes can't create specified objects. Make sure that your manifest files are valid. You may try using them to create objects in Kubernetes directly for more troubleshooting. -### Agent logs - Error while dialing failed to WebSocket dial: failed to send handshake request +#### Error while dialing failed to WebSocket dial: failed to send handshake request ```json -{"level":"warn","time":"2020-10-30T09:50:51.173Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""} +{ + "level": "warn", + "time": "2020-10-30T09:50:51.173Z", + "msg": "GetConfiguration failed", + "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\"" +} ``` This error is shown if you configured `wss` as `kas-address` on the agent side, @@ -499,19 +559,30 @@ issue is in progress, directly edit the deployment with the `kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use `grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`. -### Agent logs - Decompressor is not installed for grpc-encoding +#### Decompressor is not installed for grpc-encoding ```json -{"level":"warn","time":"2020-11-05T05:25:46.916Z","msg":"GetConfiguration.Recv failed","error":"rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""} +{ + "level": "warn", + "time": "2020-11-05T05:25:46.916Z", + "msg": "GetConfiguration.Recv failed", + "error": "rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\"" +} ``` This error is shown if the version of the agent is newer that the version of KAS. To fix it, make sure that both `agentk` and KAS use the same versions. -### Agent logs - Certificate signed by unknown authority +#### Certificate signed by unknown authority ```json -{"level":"error","time":"2021-02-25T07:22:37.158Z","msg":"Reverse tunnel","mod_name":"reverse_tunnel","error":"Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\""} +{ + "level": "error", + "time": "2021-02-25T07:22:37.158Z", + "msg": "Reverse tunnel", + "mod_name": "reverse_tunnel", + "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\"" +} ``` This error is shown if your GitLab instance is using a certificate signed by an internal CA that @@ -580,34 +651,3 @@ Alternatively, you can mount the certificate file at a different location and in mountPath: /tmp/myCA.pem subPath: myCA.pem ``` - -## Remove the GitLab Kubernetes Agent - -1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`. - - ```graphql - mutation deleteAgent { - clusterAgentDelete(input: { id: "<cluster-agent-id>" } ) { - errors - } - } - - mutation deleteToken { - clusterAgentTokenDelete(input: { id: "<cluster-agent-token-id>" }) { - errors - } - } - ``` - -1. Verify whether the removal occurred successfully. If the output in the Pod logs includes `unauthenticated`, it means that the agent was successfully removed: - - ```json - {"level":"warn","time":"2021-04-29T23:44:07.598Z","msg":"GetConfiguration.Recv failed","error":"rpc error: - code = Unauthenticated desc = unauthenticated"} - ``` - -1. Delete the GitLab Kubernetes Agent in your cluster: - - ```shell - kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml - ``` diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index ea57ded3320..cbb27a3f343 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -152,6 +152,11 @@ gitops: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the `group_authorized_agents` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available. + If you use the same cluster across multiple projects, you can set up the CI/CD Tunnel to grant the Agent access to one or more groups. This way, all the projects that belong to the authorized groups can access the same Agent. This enables you to save resources and @@ -168,8 +173,8 @@ An Agent can only authorize groups in the same group hierarchy as the Agent's co To authorize a group: -1. Edit your `.config.yaml` file under the `.gitlab/agents/<agent name>` directory. -1. Add the `ci_access` attribute. +1. Edit your `config.yaml` file under the `.gitlab/agents/<agent name>` directory. +1. Add the `ci_access` root attribute. 1. Add the `groups` attribute into `ci_access`. 1. Add the group `id` into `groups`, identifying the authorized group through its path. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 2da8396cfd7..31dd503a0cf 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -485,7 +485,7 @@ config: agent: monitor: - eventTypes: ["drop"] + eventTypes: ["drop"] # Note: possible values are documented at https://docs.cilium.io/en/stable/cmdref/cilium_monitor/ ``` The Cilium monitor log for traffic is logged out by the diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index cad55f0cf0b..470f65db61b 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -33,7 +33,7 @@ owners](../permissions.md#group-members-permissions) In order to: - Track environments for the cluster, you must - [deploy to a Kubernetes cluster](../project/clusters/index.md#deploying-to-a-kubernetes-cluster) + [deploy to a Kubernetes cluster](../project/clusters/deploy_to_cluster.md) successfully. - Show pod usage correctly, you must [enable deploy boards](../project/deploy_boards.md#enabling-deploy-boards). diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 9e2b00a0f54..305f66c5ec5 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w With a [cluster management project](management_project.md) you can manage your cluster's deployment and applications through a repository in GitLab. -The Custer Management project template provides you a baseline to get +The Cluster Management project template provides you a baseline to get started and flexibility to customize your project to your cluster's needs. For instance, you can: @@ -91,10 +91,6 @@ the pipeline runs, Helmfile tries to either install or update your apps accordin cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile tries try to uninstall this app from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works. -Furthermore, each app has an `applications/{app}/values.yaml` file (`applicaton/{app}/values.yaml.gotmpl` in case of GitLab Runner). This is the -place where you can define default values for your app's Helm chart. Some apps already have defaults -pre-defined by GitLab. - ### Built-in applications The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are: @@ -110,3 +106,9 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp - [Prometheus](../infrastructure/clusters/manage/management_project_applications/prometheus.md) - [Sentry](../infrastructure/clusters/manage/management_project_applications/sentry.md) - [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md) + +#### How to customize your applications + +Each app has an `applications/{app}/values.yaml` file (`applicaton/{app}/values.yaml.gotmpl` in case of GitLab Runner). This is the +place where you can define default values for your app's Helm chart. Some apps already have defaults +pre-defined by GitLab. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index d30cedfb3cd..63dd06bcfdb 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -30,7 +30,7 @@ Prerequisites: To view the compliance report: 1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Security & Compliance > Compliance**. +1. On the left sidebar, select **Security & Compliance > Compliance report**. NOTE: The compliance report shows only the latest merge request on each project. @@ -87,7 +87,7 @@ Depending on the merge strategy, the merge commit SHA can be a merge commit, squ To download the Chain of Custody report: 1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Security & Compliance > Compliance**. +1. On the left sidebar, select **Security & Compliance > Compliance report**. 1. Select **List of all merge commits**. ### Commit-specific Chain of Custody Report **(ULTIMATE)** @@ -97,7 +97,7 @@ To download the Chain of Custody report: You can generate a commit-specific Chain of Custody report for a given commit SHA. 1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Security & Compliance > Compliance**. +1. On the left sidebar, select **Security & Compliance > Compliance report**. 1. At the top of the compliance report, to the right of **List of all merge commits**, select the down arrow (**{angle-down}**). 1. Enter the merge commit SHA, and then select **Export commit custody report**. SHA and then select **Export commit custody report**. diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_add_v13_2.png b/doc/user/compliance/license_compliance/img/policies_maintainer_add_v13_2.png Binary files differdeleted file mode 100644 index 2d5946503cf..00000000000 --- a/doc/user/compliance/license_compliance/img/policies_maintainer_add_v13_2.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_add_v14_3.png b/doc/user/compliance/license_compliance/img/policies_maintainer_add_v14_3.png Binary files differnew file mode 100644 index 00000000000..7a27899f8c9 --- /dev/null +++ b/doc/user/compliance/license_compliance/img/policies_maintainer_add_v14_3.png diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png Binary files differdeleted file mode 100644 index 2ad08919f86..00000000000 --- a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png Binary files differnew file mode 100644 index 00000000000..85b2a52e04b --- /dev/null +++ b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 165150a58a1..5318f4deed1 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -47,7 +47,7 @@ When GitLab detects a **Denied** license, you can view it in the [license list](  You can view and modify existing policies from the [policies](#policies) tab. - + ## License expressions @@ -742,8 +742,9 @@ which enables a designated approver that can approve and then merge a merge requ The **Policies** tab in the project's license compliance section displays your project's license policies. Project maintainers can specify policies in this section. - - + + + Developers of the project can view the policies configured in a project. @@ -753,6 +754,10 @@ Developers of the project can view the policies configured in a project. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +Prerequisites: + +- Maintainer or Owner [role](../../permissions.md#project-members-permissions). + `License-Check` is a [merge request approval](../../project/merge_requests/approvals/index.md) rule you can enable to allow an individual or group to approve a merge request that contains a `denied` license. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 23765de8f46..e0cc79fe0fb 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -139,7 +139,7 @@ the related documentation. | [Max pipelines per schedule](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day) | `24` for Free tier, `288` for all paid tiers | Unlimited | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | | Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | -| [Max registered runners](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | `50` per-project and per-group for Free tier,<br/>`1_000` per-group for all paid tiers / `1_000` per-project for all paid tiers | `1_000` per-group / `1_000` per-project | +| [Max registered runners](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | Free tier: `50` per-group / `50` per-project <br/> All paid tiers: `1_000` per-group / `1_000` per-project | `1_000` per-group / `1_000` per-project | ## Account and limit settings @@ -270,7 +270,7 @@ for `shared_buffers` is quite high, and we are ## Puma -GitLab.com uses the default of 60 seconds for [Puma request timeouts](https://docs.gitlab.com/omnibus/settings/puma.html#worker-timeout). +GitLab.com uses the default of 60 seconds for [Puma request timeouts](../../administration/operations/puma.md#worker-timeout). ## GitLab.com-specific rate limits diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 0d885183a41..25eff076d8d 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -14,8 +14,10 @@ Similar to [project-level](../../project/clusters/index.md) and group-level Kubernetes clusters allow you to connect a Kubernetes cluster to your group, enabling you to use the same cluster across multiple projects. -To view your group level Kubernetes clusters, navigate to your project and select -**Kubernetes** from the left-hand menu. +To view your group-level Kubernetes clusters: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Kubernetes**. ## Cluster management project @@ -58,7 +60,7 @@ differentiate the new cluster from your other clusters. You can choose to allow GitLab to manage your cluster for you. If GitLab manages your cluster, resources for your projects are automatically created. See the -[Access controls](../../project/clusters/add_remove_clusters.md#access-controls) +[Access controls](../../project/clusters/cluster_access.md) section for details on which resources GitLab creates for you. For clusters not managed by GitLab, project-specific resources aren't created @@ -82,10 +84,11 @@ your cluster, which can cause deployment jobs to fail. To clear the cache: -1. Navigate to your group's **Kubernetes** page, - and select your cluster. -1. Expand the **Advanced settings** section. -1. Click **Clear cluster cache**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Kubernetes**. +1. Select your cluster. +1. Expand **Advanced settings**. +1. Select **Clear cluster cache**. ## Base domain @@ -169,7 +172,7 @@ documentation for project-level clusters. ## More information For information on integrating GitLab and Kubernetes, see -[Kubernetes clusters](../../project/clusters/index.md). +[Kubernetes clusters](../../infrastructure/clusters/index.md). <!-- ## Troubleshooting diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index a2d7f358cd9..b13dd3f63cb 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -11,15 +11,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w With Contribution Analytics you can get an overview of the [contribution actions](../../../api/events.md#action-types) in your group. -To view the Contribution Analytics, go to your group and select **Analytics > Contribution**. - -## Use cases - - Analyze your team's contributions over a period of time, and offer a bonus for the top contributors. - Identify opportunities for improvement with group members who may benefit from additional support. +## View Contribution Analytics + +To view Contribution Analytics: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Contribution**. + ## Using Contribution Analytics There are three main bar graphs that illustrate the number of contributions per group diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 41046477b90..a9c56139b4d 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -17,6 +17,12 @@ in the group and select the **Group** tab. Every project in the subgroup, but not nested subgroups, can be selected by members of the group when a new project is created. +- Public projects can be selected by any signed-in user as a template for a new project, + if all enabled [project features](../project/settings/index.md#sharing-and-permissions) + except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. + The same applies to internal projects. +- Private projects can be selected only by users who are members of the projects. + Repository and database information that is copied over to each new project is identical to the data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 554d01039ad..e3b858aff7d 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -14,6 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. > - Multiselect [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. > - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. +> - Adoption over time chart [added](https://gitlab.com/gitlab-org/gitlab/-/issues/337561) in GitLab 14.4. Prerequisites: @@ -69,6 +70,13 @@ Each group appears as a separate row in the table. For each row, a feature is considered "adopted" if it has been used in a project in the given group during the time period (including projects in any subgroups of the given group). +## Adoption over time + +The **Adoption over time** chart in the **Overview** tab displays DevOps Adoption over time. The chart displays the total number of adopted features from the previous twelve months, +from when you enabled DevOps Adoption for the group. + +The tooltip displays information about the features tracked for individual months. + ## When is a feature considered adopted A feature is considered "adopted" if it has been used anywhere in the group in the specified time. diff --git a/doc/user/group/epics/img/epic_view_roadmap_v12_9.png b/doc/user/group/epics/img/epic_view_roadmap_v12_9.png Binary files differindex e8224ced7e9..3a33a6c4cf8 100644 --- a/doc/user/group/epics/img/epic_view_roadmap_v12_9.png +++ b/doc/user/group/epics/img/epic_view_roadmap_v12_9.png diff --git a/doc/user/group/import/img/import_panel_v14_1.png b/doc/user/group/import/img/import_panel_v14_1.png Binary files differindex 28417383b6c..52791a82c3c 100644 --- a/doc/user/group/import/img/import_panel_v14_1.png +++ b/doc/user/group/import/img/import_panel_v14_1.png diff --git a/doc/user/group/import/img/new_group_navigation_v13_8.png b/doc/user/group/import/img/new_group_navigation_v13_8.png Binary files differindex 307175727c7..40be3dd41d2 100644 --- a/doc/user/group/import/img/new_group_navigation_v13_8.png +++ b/doc/user/group/import/img/new_group_navigation_v13_8.png diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 31c3a8e774e..1f5de36303e 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import groups from another instance of GitLab **(FREE)** +# Migrate groups from another instance of GitLab **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7. > - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. @@ -102,8 +102,10 @@ This might involve reconfiguring your firewall to prevent blocking connection on ### Connect to the remote GitLab instance -1. Navigate to the New Group page, either via the `+` button in the top navigation bar, or the **New subgroup** button -on an existing group's page. +1. Go to the New Group page: + + - On the top bar, select `+` and then **New group**. + - Or, on an existing group's page, in the top right, select **New subgroup**.  @@ -111,21 +113,20 @@ on an existing group's page.  -1. Fill in source URL of your GitLab. -1. Fill in [personal access token](../../../user/profile/personal_access_tokens.md) for remote GitLab instance. -1. Click "Connect instance". +1. Enter the source URL of your GitLab instance. +1. Generate or copy a [personal access token](../../../user/profile/personal_access_tokens.md) + with the `api` and `read_repository` scopes on your remote GitLab instance. +1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your remote GitLab instance. +1. Select **Connect instance**. ### Selecting which groups to import After you have authorized access to the GitLab instance, you are redirected to the GitLab Group -Migration importer page. Listed are the remote GitLab groups to which you have the Owner role. +Migration importer page. The remote groups you have the Owner role for are listed. 1. By default, the proposed group namespaces match the names as they exist in remote instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. - -1. Select the **Import** button next to any number of groups. - -1. The **Status** column shows the import status of each group. You can choose to leave the page open and it updates in real-time. - -1. Once a group has been imported, click its GitLab path to open its GitLab URL. +1. Next to the groups you want to import, select **Import**. +1. The **Status** column shows the import status of each group. If you leave the page open, it updates in real-time. +1. After a group has been imported, select its GitLab path to open its GitLab URL.  diff --git a/doc/user/group/index.md b/doc/user/group/index.md index caf874cfe28..15d2da50012 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -571,10 +571,11 @@ To restrict group access by IP address: ## Restrict group access by domain **(PREMIUM)** ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. ->- Support for specifying multiple email domains [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) added in GitLab 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. +> - Support for restricting access to projects within the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. -You can prevent users with email addresses in specific domains from being added to a group. +You can prevent users with email addresses in specific domains from being added to a group and its projects. To restrict group access by domain: @@ -593,9 +594,6 @@ Some domains cannot be restricted. These are the most popular public email domai - `hotmail.com`, `hotmail.co.uk`, `hotmail.fr` - `msn.com`, `live.com`, `outlook.com` -NOTE: -Domain restrictions apply to groups only. They do not prevent users from being added as members of projects owned by the restricted group. - ## Group file templates **(PREMIUM)** Use group file templates to share a set of templates for common file @@ -732,6 +730,27 @@ The group's new subgroups have push rules set for them based on either: - The closest parent group with push rules defined. - Push rules set at the instance level, if no parent groups have push rules defined. +## Group approval rules **(PREMIUM)** + +> Introduced in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +per group, ask an administrator to [enable the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md). +The feature is not ready for production use. + +Group approval rules are an in-development feature that provides an interface for managing +[project merge request approval rules](../project/merge_requests/approvals/index.md) at the +top-level group level. When rules are configured [at the instance level](../admin_area/merge_requests_approvals.md), +you can't edit locked rules. + +To view the merge request approval rules UI for a group: + +1. Go to the top-level group's **Settings > General** page. +1. Expand the **Merge request approvals** section. +1. Select the settings you want. +1. Select **Save changes**. + ## Related topics - [Group wikis](../project/wiki/index.md) @@ -769,3 +788,22 @@ If a user sees a 404 when they would normally expect access, and the problem is In viewing the log entries, compare the `remote.ip` with the list of [allowed IPs](#restrict-group-access-by-ip-address) for the group. + +### Validation errors on namespaces and groups + +[GitLab 14.4 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70365) performs +the following checks when creating or updating namespaces or groups: + +- Namespaces must not have parents. +- Group parents must be groups and not namespaces. + +You can disable the validation if GitLab shows the following errors: + +- `A user namespace cannot have a parent`. +- `A group cannot have a user namespace as its parent`. + +To disable the validation, +[disable the `validate_namespace_parent_type` flag](../../administration/feature_flags.md). + +In the unlikely event that you had to disable this feature flag to prevent errors, +[contact Support](https://about.gitlab.com/support/) so that we can improve this validation. diff --git a/doc/user/group/insights/img/insights_group_configuration.png b/doc/user/group/insights/img/insights_group_configuration.png Binary files differdeleted file mode 100644 index d181a1e94c3..00000000000 --- a/doc/user/group/insights/img/insights_group_configuration.png +++ /dev/null diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 18177d656ab..9f841691eb8 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -9,34 +9,35 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -Configure the Insights that matter for your groups to explore data such as -triage hygiene, issues created/closed per a given period, average time for merge -requests to be merged and much more. +Configure the Insights that matter for your groups. Explore data such as +triage hygiene, issues created or closed for a given period, average time for merge +requests to be merged, and much more.  ## View your group's Insights -You can access your group's Insights by clicking the **Analytics > Insights** -link in the left sidebar. +To access your group's Insights: -## Configure your Insights - -Navigate to your group's **Settings > General**, expand **Insights**, and choose -the project that holds your `.gitlab/insights.yml` configuration file: +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Insights**. - +## Configure your Insights -If no configuration was set, a [default configuration file]( -https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml) -will be used. +GitLab reads Insights from the [default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). +If you want to customize it: -See the [Project's Insights documentation](../../project/insights/index.md) for -more details about the `.gitlab/insights.yml` configuration file. +1. Create a new file [`.gitlab/insights.yml`](../../project/insights/index.md) +in a project that belongs to your group. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Insights**. +1. Select the project that contains your `.gitlab/insights.yml` configuration file. +1. Select **Save changes**. ## Permissions -If you have access to view a group, then you have access to view their Insights. +If you have access to view a group, then you have access to view its Insights. NOTE: Issues or merge requests that you don't have access to (because you don't have diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 685c4601ac4..c6cd763355b 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -7,16 +7,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Repositories Analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in GitLab 13.4.  ## Current group code coverage -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in GitLab 13.7. The **Analytics > Repositories** group page displays the overall test coverage of all your projects in your group. In the **Overall activity** section, you can see: @@ -27,46 +24,47 @@ In the **Overall activity** section, you can see: ## Average group test coverage from the last 30 days -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in GitLab 13.9. The **Analytics > Repositories** group page displays the average test coverage of all your projects in your group in a graph for the last 30 days. ## Latest project test coverage list -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in GitLab 13.6. To see the latest code coverage for each project in your group: -1. Go to **Analytics > Repositories** in the group (not from a project). -1. In the **Latest test coverage results** section, use the **Select projects** dropdown to choose the projects you want to check. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Repositories**. +1. In the **Latest test coverage results** section, from the **Select projects** dropdown list, choose the projects you want to check. You can download code coverage data for specific projects using [code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history). ## Download historic test coverage data -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in GitLab 13.4. You can get a CSV of the code coverage data for all of the projects in your group. This report has a maximum of 1000 records. The code coverage data is from the default branch in each project. To get the report: -1. Go to your group's **Analytics > Repositories** page -1. Click **Download historic test coverage data (`.csv`)**, -1. In the popup, select the projects you want to include in the report. -1. Select the date range for the report from the preset options. -1. Click **Download test coverage data (`.csv`)**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Repositories**. +1. Select **Download historic test coverage data (.csv)**. +1. Select the projects and date range you want to include in the report. +1. Select **Download test coverage data (.csv)**. The projects dropdown shows up to 100 projects from your group. If the project you want to check is not in the dropdown list, you can select **All projects** to download the report for all projects in your group, including any projects that are not listed. There is a plan to improve this behavior in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/250684). -For each day that a coverage report was generated by a job in a project's pipeline, there will be a row in the CSV which includes: +For each day that a coverage report was generated by a job in a project's pipeline, a row in the CSV includes: -- The date when the coverage job ran +- The date the coverage job ran - The name of the job that generated the coverage report - The name of the project - The coverage value -If the project's code coverage was calculated more than once in a day, we will take the last value from that day. +If the project's code coverage was calculated more than once in a day, the last value from that day is used. NOTE: [In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage diff --git a/doc/user/group/roadmap/img/roadmap_view_v14_3.png b/doc/user/group/roadmap/img/roadmap_view_v14_3.png Binary files differindex ca4b87b9fdd..ea5e870680e 100644 --- a/doc/user/group/roadmap/img/roadmap_view_v14_3.png +++ b/doc/user/group/roadmap/img/roadmap_view_v14_3.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 8f6b3e7244a..1c894550a14 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 11.0. -This page describes SAML for Groups. For instance-wide SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md). +This page describes SAML for groups. For instance-wide SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md). [View the differences between SaaS and Self-Managed Authentication and Authorization Options](../../../administration/auth/index.md#saas-vs-self-managed-comparison). SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. @@ -23,7 +23,8 @@ If required, you can find [a glossary of common terms](../../../integration/saml ## Configuring your identity provider -1. Navigate to the GitLab group and select **Settings > SAML SSO**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > SAML SSO**. 1. Configure your SAML identity provider using the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [specific identity provider documentation](#providers) for more details. @@ -42,7 +43,7 @@ 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. +- Must be a persistent value that never changes, 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's hard to guarantee it doesn't ever change, for example, when a person's name changes. Email addresses are @@ -66,15 +67,15 @@ the user details need to be passed to GitLab as SAML assertions. At a minimum, the user's email address *must* be specified as an assertion named `email` or `mail`. See [the assertions list](../../../integration/saml.md#assertions) for other available claims. - -NOTE: -The `username` assertion is not supported for GitLab.com SaaS integrations. +In addition to the attributes in the linked assertions list, GitLab.com supports `username` +and `nickname` attributes. ### Metadata configuration GitLab provides metadata XML that can be used to configure your identity provider. -1. Navigate to the group and select **Settings > SAML SSO**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. 1. Follow your identity provider's documentation and paste the metadata URL when it's requested. @@ -82,7 +83,8 @@ GitLab provides metadata XML that can be used to configure your identity provide After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: -1. Navigate to the group's **Settings > SAML SSO**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > SAML SSO**. 1. Find the SSO URL from your identity provider and enter it the **Identity provider single sign-on URL** field. 1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. 1. Select the access level to be applied to newly added users in the **Default membership role** field. The default access level is 'Guest'. @@ -110,7 +112,7 @@ However, users are not prompted to sign in through SSO on each visit. GitLab che has authenticated through SSO. If it's been more than 1 day since the last sign-in, GitLab prompts the user to sign in again through SSO. -We intend to add a similar SSO requirement for [API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). +We intend to add a similar SSO requirement for [API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/297389). SSO has the following effects when enabled: @@ -131,7 +133,7 @@ When SCIM updates, the user's access is immediately revoked. ## Providers -The SAML standard means that a wide range of identity providers will work with GitLab. Your identity provider may have relevant documentation. It may be generic SAML documentation, or specifically targeted for GitLab. +The SAML standard means that you can use a wide range of identity providers with GitLab. Your identity provider might have relevant documentation. It can be generic SAML documentation or specifically targeted for GitLab. When [configuring your identity 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. @@ -224,7 +226,7 @@ When a user tries to sign in with Group SSO, GitLab attempts to find or create a To link SAML to your existing GitLab.com account: -1. Sign in to your GitLab.com account. +1. Sign in to your GitLab.com account. [Reset your password](https://gitlab.com/users/password/new) if necessary. 1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group owner can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the identity provider. 1. Select **Authorize**. 1. Enter your credentials on the identity provider if prompted. @@ -265,6 +267,9 @@ convert the information to XML. An example SAML response is shown here. <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue> </saml2:Attribute> + <saml2:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.nickName</saml2:AttributeValue> + </saml2:Attribute> <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue> </saml2:Attribute> @@ -309,7 +314,7 @@ group owner, and then you can unlink the account. For example, to unlink the `MyOrg` account: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Disconnect** next to the connected account. @@ -346,8 +351,8 @@ a SAML identity provider group name to a GitLab Access Level. This can be done f To link the SAML groups from the `saml:AttributeStatement` example above: -1. Enter the value of `saml:AttributeValue` in the `SAML Group Name` field. -1. Choose the desired `Access Level`. +1. In the **SAML Group Name** box, enter the value of `saml:AttributeValue`. +1. Choose the desired **Access Level**. 1. **Save** the group link. 1. Repeat to add additional group links if desired. @@ -356,7 +361,14 @@ To link the SAML groups from the `saml:AttributeStatement` example above: If a user is a member of multiple SAML groups mapped to the same GitLab group, the user gets the highest access level from the groups. For example, if one group is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` -access. +access. + +Users granted: + +- A higher role with Group Sync are displayed as having + [direct membership](../../project/members/#display-direct-members) of the group. +- A lower or the same role with Group Sync are displayed as having + [inherited membership](../../project/members/#display-inherited-members) of the group. ### Automatic member removal @@ -480,7 +492,7 @@ If you receive a `404` during setup when using "verify configuration", make sure [SHA-1 generated fingerprint](../../../integration/saml.md#notes-on-configuring-your-identity-provider). If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configuring-your-identity-provider), they may see a 404. -As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner will need to provide the URL to users. +As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. ### Message: "SAML authentication failed: Extern UID has already been taken" @@ -502,13 +514,13 @@ Here are possible causes and solutions: | Cause | Solution | | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user will need to [link their account](#user-access-and-management). | +| When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user needs to [link their account](#user-access-and-management). | ### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" Getting both of these errors at the same time suggests the NameID capitalization provided by the identity provider didn't exactly match the previous value for that user. -This can be prevented by configuring the [NameID](#nameid) to return a consistent value. Fixing this for an individual user involves [unlinking SAML in the GitLab account](#unlinking-accounts), although this will cause group membership and to-dos to be lost. +This can be prevented by configuring the [NameID](#nameid) to return a consistent value. Fixing this for an individual user involves [unlinking SAML in the GitLab account](#unlinking-accounts), although this causes group membership and to-do items to be lost. ### Message: "Request to link SAML account must be authorized" @@ -541,7 +553,7 @@ Otherwise, to change the SAML app used for sign in, users need to [unlink the cu Many SAML terms can vary between providers. It is possible that the information you are looking for is listed under another name. -For more information, start with your identity provider's documentation. Look for their options and examples to see how they configure SAML. This can provide hints on what you'll need to configure GitLab to work with these providers. +For more information, start with your identity provider's documentation. Look for their options and examples to see how they configure SAML. This can provide hints on what you need to configure GitLab to work with these providers. It can also help to look at our [more detailed docs for self-managed GitLab](../../../integration/saml.md). SAML configuration for GitLab.com is mostly the same as for self-managed instances. diff --git a/doc/user/group/settings/img/import_panel_v14_1.png b/doc/user/group/settings/img/import_panel_v14_1.png Binary files differdeleted file mode 100644 index 28417383b6c..00000000000 --- a/doc/user/group/settings/img/import_panel_v14_1.png +++ /dev/null diff --git a/doc/user/group/settings/img/new_group_navigation_v13_1.png b/doc/user/group/settings/img/new_group_navigation_v13_1.png Binary files differdeleted file mode 100644 index 307175727c7..00000000000 --- a/doc/user/group/settings/img/new_group_navigation_v13_1.png +++ /dev/null diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 516f3504a98..3f9d94f044e 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -4,6 +4,7 @@ stage: Manage group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- + # Group import/export **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. @@ -23,9 +24,9 @@ Users with the [Owner role](../../permissions.md) for a group can enable import and export for that group: 1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > General > Visibility and access controls**. -1. Scroll to **Import sources**. -1. Enable the desired **Import sources**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. In the **Import sources** section, select the checkboxes for the sources you want. ## Important Notes @@ -65,19 +66,23 @@ For more details on the specific data persisted in a group export, see the ## Export a group +WARNING: +This feature will be [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) +in GitLab 14.6 and replaced by [GitLab Migration](../import/). + Users with the [Owner role](../../permissions.md) for a group can export the contents of that group: -1. On the top bar, select **Menu >** **Groups** and find your group. -1. On the left sidebar, select **Settings**. -1. Scroll to the **Advanced** section, and select **Export Group**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. In the **Advanced** section, select **Export Group**. 1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents) in a compressed tar archive, with contents in NDJSON format. 1. Alternatively, you can download the export from the UI: 1. Return to your group's **Settings > General** page. - 1. Scroll to the **Advanced** section, and select **Download export**. - You can also generate a new file by clicking **Regenerate export**. + 1. In the **Advanced** section, select **Download export**. + You can also generate a new file by selecting **Regenerate export**. NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). @@ -91,24 +96,18 @@ The Enterprise Edition retains some group data that isn't part of the Community ## Importing the group -1. Navigate to the New Group page, either via the `+` button in the top navigation bar, or the **New subgroup** button -on an existing group's page. - -  - -1. On the New Group page, select the **Import group**. - -  +1. Create a new group: + - On the top bar, select **New** (**{plus}**) and then **New group**. + - On an existing group's page, select the **New subgroup** button. +1. Select **Import group**. 1. Enter your group name. - 1. Accept or modify the associated group URL. - -1. Click **Choose file** - +1. Select **Choose file**. 1. Select the file that you exported in the [Export a group](#export-a-group) section. +1. To begin importing, select **Import group**. -1. Click **Import group** to begin importing. Your newly imported group page appears after the operation completes. +Your newly imported group page appears after the operation completes. ## Version history diff --git a/doc/user/group/subgroups/img/create_new_group.png b/doc/user/group/subgroups/img/create_new_group.png Binary files differdeleted file mode 100644 index 9d011ec709a..00000000000 --- a/doc/user/group/subgroups/img/create_new_group.png +++ /dev/null diff --git a/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png b/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png Binary files differdeleted file mode 100644 index 013aee6b0b4..00000000000 --- a/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png +++ /dev/null diff --git a/doc/user/group/subgroups/img/group_members_13_7.png b/doc/user/group/subgroups/img/group_members_13_7.png Binary files differdeleted file mode 100644 index ab22bcb932c..00000000000 --- a/doc/user/group/subgroups/img/group_members_13_7.png +++ /dev/null diff --git a/doc/user/group/subgroups/img/group_members_v14_4.png b/doc/user/group/subgroups/img/group_members_v14_4.png Binary files differnew file mode 100644 index 00000000000..695564a8b74 --- /dev/null +++ b/doc/user/group/subgroups/img/group_members_v14_4.png diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index aaff0574ef0..49032d0a2ef 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -73,51 +73,41 @@ subgroups, the behavior is the same as when performing these actions at the ## Creating a subgroup +Users can create subgroups if they are explicitly added as an Owner (or +Maintainer, if that setting is enabled) to an immediate parent group, even if group +creation is disabled by an administrator in their settings. + +To create a subgroup: + +1. On the top bar, select **Menu > Groups** and find the parent group. +1. In the top right, select **New subgroup**. +1. Select **Create group**. +1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) + that cannot be used as group names. +1. Select **Create group**. + +### Change who can create subgroups + To create a subgroup you must either be an Owner or a Maintainer of the group, depending on the group's setting. -By default, groups created in: +By default: -- GitLab 12.2 or later allow both Owners and Maintainers to create subgroups. -- GitLab 12.1 or earlier only allow Owners to create subgroups. +- In GitLab 12.2 or later, both Owners and Maintainers can create subgroups. +- In GitLab 12.1 or earlier, only Owners can create subgroups. -The setting can be changed for any group by: +You can change this setting: -- A group owner: +- As group owner: 1. Select the group. 1. On the left sidebar, select **Settings > General**. - 1. Expand the **Permissions, LFS, 2FA** section. -- An administrator: + 1. Expand **Permissions, LFS, 2FA**. +- As an administrator: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. 1. Select the group, and select **Edit**. -For: - -- More information, check the [permissions table](../../permissions.md#group-members-permissions). -- A list of words that are not allowed to be used as group names, see the - [reserved names](../../reserved_names.md). - -Users can always create subgroups if they are explicitly added as an Owner (or -Maintainer, if that setting is enabled) to an immediate parent group, even if group -creation is disabled by an administrator in their settings. - -To create a subgroup: - -1. In the group's dashboard click the **New subgroup** button. - -  - -1. Create a new group like you would normally do. Notice that the immediate parent group - namespace is fixed under **Group path**. The visibility level can differ from - the immediate parent group. - -  - -1. Click the **Create group** button to be redirected to the new group's - dashboard page. - -Follow the same process to create any subsequent groups. +For more information, view the [permissions table](../../permissions.md#group-members-permissions). ## Membership @@ -136,7 +126,7 @@ the **Members** page of the group the member was added. You can tell if a member has inherited the permissions from a parent group by looking at the group's **Members** page. - + From the image above, we can deduce the following things: diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 68ae5e0df2d..5c8393f30ab 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -284,9 +284,9 @@ To sort the stage table by a table column, select the table header. You can sort in ascending or descending order. To find items that spent the most time in a stage, potentially causing bottlenecks in your value stream, sort the table by the **Time** column. From there, select individual items to drill in and investigate how delays are happening. -To see which items the stage most recently, sort by the work item column on the left. +To see which items most recently exited the stage, sort by the work item column on the left. -The table displays up to 20 items at a time. If there are more than 20 items, you can use the +The table displays 20 items per page. If there are more than 20 items, you can use the **Prev** and **Next** buttons to navigate through the pages. ### Creating a value stream @@ -302,11 +302,12 @@ best practices. You can customize this flow by adding, hiding or re-ordering sta To create a value stream: -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the Value stream dropdown and select **Create new Value Stream** -1. Fill in a name for the new Value Stream - - You can [customize the stages](#creating-a-value-stream-with-stages) -1. Click the **Create Value Stream** button. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value Stream**. +1. In the top right, select the dropdown list and then **Create new Value Stream**. +1. Enter a name for the new Value Stream. + - You can [customize the stages](#creating-a-value-stream-with-stages). +1. Select **Create Value Stream**.  @@ -324,18 +325,19 @@ add stages as desired. To create a value stream with stages: -1. Go to your group and select **Analytics > Value Stream**. -1. Select the Value Stream dropdown and select **Create new Value Stream**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value Stream**. +1. In the top right, select the dropdown list and then **Create new Value Stream**. 1. Select either **Create from default template** or **Create from no template**. - - Default stages in the value stream can be hidden or re-ordered. + - You can hide or re-order default stages in the value stream.  - - New stages can be added by clicking the 'Add another stage' button. - - The name, start and end events for the stage can be selected + - You can add new stages by selecting **Add another stage**. + - You can select the name and start and end events for the stage.  -1. Select the **Create Value Stream** button to save the value stream. +1. Select **Create Value Stream**. #### Label-based stages @@ -358,8 +360,9 @@ In this example, we'd like to measure times for deployment from a staging enviro After you create a value stream, you can customize it to suit your purposes. To edit a value stream: -1. Go to your group and select **Analytics > Value Stream**. -1. Find and select the relevant value stream from the value stream dropdown. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value Stream**. +1. In the top right, select the dropdown list and then select the relevant value stream. 1. Next to the value stream dropdown, select **Edit**. The edit form is populated with the value stream details. 1. Optional: @@ -377,10 +380,11 @@ After you create a value stream, you can customize it to suit your purposes. To To delete a custom value stream: -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the Value stream dropdown and select the value stream you would like to delete. -1. Click the **Delete (name of value stream)**. -1. Click the **Delete** button to confirm. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value Stream**. +1. In the top right, select the dropdown list and then select the value stream you would like to delete. +1. Select **Delete (name of value stream)**. +1. To confirm, select **Delete**.  @@ -398,15 +402,6 @@ from the chart itself. The chart data is limited to the last 500 items. -### Disabling chart - -This chart is enabled by default. If you have a self-managed instance, an -administrator can open a Rails console and disable it with the following command: - -```ruby -Feature.disable(:cycle_analytics_scatterplot_enabled) -``` - ## Type of work - Tasks by type chart > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. @@ -422,7 +417,7 @@ select up to a total of 15 labels. ## Permissions -To access Group-level Value Stream Analytics, users must have Reporter access or above. +To access Group-level Value Stream Analytics, users must have at least the Reporter role. You can [read more about permissions](../../permissions.md) in general. diff --git a/doc/user/index.md b/doc/user/index.md index d6eaad469c1..c9f20af9668 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -13,10 +13,10 @@ Welcome to GitLab! We're glad to have you here! As a GitLab user you have access to all the features your [subscription](https://about.gitlab.com/pricing/) includes, except [GitLab administrator](../administration/index.md) -settings, unless you have admin privileges to install, configure, +settings, unless you have administrator privileges to install, configure, and upgrade your GitLab instance. -Admin privileges for [GitLab.com](https://gitlab.com/) are restricted to the GitLab team. +Administrator privileges for [GitLab.com](https://gitlab.com/) are restricted to the GitLab team. For more information on configuring GitLab self-managed instances, see the [Administrator documentation](../administration/index.md). @@ -63,7 +63,7 @@ With GitLab Enterprise Edition, you can also: - Use [Burndown Charts](project/milestones/burndown_and_burnup_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 Search](search/advanced_search.md) for faster, more advanced code search across your entire GitLab instance. - [Authenticate users with Kerberos](../integration/kerberos.md). -- [Mirror a repository](project/repository/repository_mirroring.md) from elsewhere on your local server. +- [Mirror a repository](project/repository/mirror/index.md) from elsewhere on your local server. - View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](../ci/pipelines/multi_project_pipelines.md). - [Lock files](project/file_lock.md) to prevent conflicts. - View the current health and status of each CI environment running on Kubernetes with [deploy boards](project/deploy_boards.md). @@ -78,7 +78,7 @@ There are several types of users in GitLab: - Regular users and GitLab.com users. <!-- Note: further description TBA --> - [Groups](group/index.md) of users. -- GitLab [admin area](admin_area/index.md) user. +- GitLab [administrator area](admin_area/index.md) user. - [GitLab Administrator](../administration/index.md) with full access to self-managed instances' features and settings. - [Internal users](../development/internal_users.md). diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index ada278292a9..636cb1bb457 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -63,16 +63,6 @@ You can also use the [certificate-based method](../../../project/clusters/multip but, for [security implications](#security-implications-for-clusters-connected-with-certificates), we don't recommend using this method. -## Cluster levels - -Choose your cluster's level according to its purpose: - -| Level | Purpose | -|--|--| -| [Project level](../../../project/clusters/index.md) | Use your cluster for a single project. | -| [Group level](../../../group/clusters/index.md) | Use the same cluster across multiple projects within your group. | -| [Instance level](../../../instance/clusters/index.md) **(FREE SELF)** | Use the same cluster across groups and projects within your instance. | - ## Supported cluster versions GitLab is committed to support at least two production-ready Kubernetes minor @@ -86,29 +76,42 @@ version. The range of supported versions is based on the evaluation of: GitLab supports the following Kubernetes versions, and you can upgrade your Kubernetes version to any supported version at any time: +- 1.20 (support ends on July 22, 2022) - 1.19 (support ends on February 22, 2022) - 1.18 (support ends on November 22, 2021) - 1.17 (support ends on September 22, 2021) +[Adding support to other versions of Kubernetes is managed under this epic](https://gitlab.com/groups/gitlab-org/-/epics/4827). + Some GitLab features may support versions outside the range provided here. -## View your clusters +## Cluster levels + +Choose your cluster's level according to its purpose: + +| Level | Purpose | +|--|--| +| [Project level](../../../project/clusters/index.md) | Use your cluster for a single project. | +| [Group level](../../../group/clusters/index.md) | Use the same cluster across multiple projects within your group. | +| [Instance level](../../../instance/clusters/index.md) | Use the same cluster across groups and projects within your instance. | + +### View your clusters To view the Kubernetes clusters connected to your project, -group, or instance, open the cluster's page according to the -[level](#cluster-levels) of your cluster. +group, or instance, open the cluster's page according to +your cluster's level. **Project-level clusters:** -1. Go to your project's homepage. +1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. **Group-level clusters:** -1. Go to your group's homepage. +1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Kubernetes**. -**Instance-level clusters:** **(FREE SELF)** +**Instance-level clusters:** 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Kubernetes**. diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 90044fa74e1..3c934b72886 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -26,25 +26,46 @@ You can then modify the project files according to your needs. **Steps:** 1. [Import the example project](#import-the-example-project). -1. [Add your GCP credentials to GitLab](#add-your-gcp-credentials-to-gitlab). +1. [Create your GCP and GitLab credentials](#create-your-gcp-and-gitlab-credentials). 1. [Configure your project](#configure-your-project). 1. [Deploy your cluster](#deploy-your-cluster). ## Import the example project +To create a new group-level cluster from GitLab using Infrastructure as Code, it is necessary +to create a project to manage the cluster from. In this tutorial, we import a pre-configured +sample project to help you get started. + Start by [importing the example project by URL](../../../project/import/repo_by_url.md). Use `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git` as URL. -## Add your GCP credentials to GitLab +This project provides you with the following resources: + +- A [cluster on Google Cloud Platform (GCP)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gke.tf) +with defaults for name, location, node count, and Kubernetes version. +- A [`gitlab-admin` K8s service account](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gitlab-admin.tf) with `cluster-admin` privileges. +- The new group-level cluster connected to GitLab. +- Pre-configures Terraform files: -After importing the project, you need to set up [CI environment variables](../../../../ci/variables/index.md) to associate your cluster on GCP to your group in GitLab. + ```plaintext + ├── backend.tf # State file Location Configuration + ├── gke.tf # Google GKE Configuration + ├── gitlab-admin.tf # Adding kubernetes service account + └── group_cluster.tf # Registering kubernetes cluster to GitLab `apps` Group + ``` -We advise that you [set environment variables through the GitLab UI](../../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) -so that your credentials are not exposed through the code. To do so, follow the steps below. +## Create your GCP and GitLab credentials -### Prepare your credentials on GCP +To set up your project to communicate to GCP and the GitLab API: -1. Create a [GCP service account](https://cloud.google.com/docs/authentication/getting-started) to authenticate GCP with GitLab. It needs the following roles: `Computer Network Viewer`, `Kubernetes Engine Admin`, and `Service Account User`. -1. Download the JSON file with the service account key. +1. Create a [GitLab personal access token](../../../profile/personal_access_tokens.md) with + `api` scope. The Terraform script uses it to connect the cluster to your GitLab group. Take note of the generated token. You will + need it when you [configure your project](#configure-your-project). +1. To authenticate GCP with GitLab, create a [GCP service account](https://cloud.google.com/docs/authentication/getting-started) +with following roles: `Compute Network Viewer`, `Kubernetes Engine Admin`, `Service Account User`, and `Service Account Admin`. Both User and Admin +service accounts are necessary. The User role impersonates the [default service account](https://cloud.google.com/compute/docs/access/service-accounts#default_service_account) +when [creating the node pool](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/using_gke_with_terraform#node-pool-management). +The Admin role creates a service account in the `kube-system` namespace. +1. Download the JSON file with the service account key you created in the previous step. 1. On your computer, encode the JSON file to `base64` (replace `/path/to/sa-key.json` to the path to your key): ```shell @@ -53,36 +74,38 @@ so that your credentials are not exposed through the code. To do so, follow the 1. Use the output of this command as the `BASE64_GOOGLE_CREDENTIALS` environment variable in the next step. -### Add your credentials to GitLab as environment variables +## Configure your project -1. On GitLab, from your project's sidebar, go to **Settings > CI/CD** and expand **Variables**. -1. Add your `GITLAB_TOKEN` ([personal access token](../../../profile/personal_access_tokens.md)). -1. Add the variable `BASE64_GOOGLE_CREDENTIALS` from the previous step. +**Required configuration:** -## Configure your project +Use CI/CD environment variables to configure your project as detailed below. -After authenticating with GCP, replace the project's defaults from the example -project with your own. To do so, edit the files as described below. +**Required configuration:** -Edit `gke.tf`: +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Variables**. +1. Set the variable `TF_VAR_gitlab_token` to the GitLab personal access token you just created. +1. Set the variable `BASE64_GOOGLE_CREDENTIALS` to the `base64` encoded JSON file you just created. +1. Set the variable `TF_VAR_gcp_project` to your GCP's `project` name. +1. Set the variable `TF_VAR_gitlab_group` to the name of the group you want to connect your cluster to. If your group's URL is `https://gitlab.example.com/my-example-group`, `my-example-group` is your group's name. -1. **(Required)** Replace the GCP `project` with a unique project name. -1. **(Optional)** Choose the `name` of your cluster. -1. **(Optional)** Choose the `region` and `zone` that you would like to deploy your cluster to. -1. Push the changes to your project's default branch. +**Optional configuration:** -Edit `group_cluster.tf`: +The file [`variables.tf`](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/variables.tf) +contains other variables that you can override according to your needs: -1. **(Required)**: Replace the `full_path` with the path to your group. -1. **(Optional)**: Choose your cluster base domain through `domain`. -1. **(Optional)**: Choose your environment through `environment_scope`. -1. Push the changes to your project's default branch. +- `TF_VAR_gcp_region`: Set your cluster's region. +- `TF_VAR_cluster_name`: Set your cluster's name. +- `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes. +- `TF_VAR_cluster_description`: Set a description for the cluster. We recommend setting this to `$CI_PROJECT_URL` to create a reference to your GitLab project on your GCP cluster detail page. This way you know which project was responsible for provisioning the cluster you see on the GCP dashboard. +- `TF_VAR_base_domain`: Set to the base domain to provision resources under. +- `TF_VAR_environment_scope`: Set to the environment scope for your cluster. Refer to the [GitLab Terraform provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) and the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) documentation for further resource options. ## Deploy your cluster -After adjusting the files in the previous step, manually trigger the deployment of your cluster. In GitLab: +After configuring your project, manually trigger the deployment of your cluster. In GitLab: 1. From your project's sidebar, go to **CI/CD > Pipelines**. 1. Select the dropdown icon (**{angle-down}**) next to the play icon (**{play}**). diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md new file mode 100644 index 00000000000..16ca6d02865 --- /dev/null +++ b/doc/user/infrastructure/clusters/index.md @@ -0,0 +1,66 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Kubernetes clusters **(FREE)** + +> - Project-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. +> - Group-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. +> - Instance-level clusters [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11. + +Kubernetes is a container orchestration platform to deploy applications +in a cluster without downtime and that scales as you need. + +With the GitLab integration with Kubernetes, you can: + +1. [Connect your cluster](#connect-your-cluster-to-gitlab). +1. [Manage your cluster](#manage-your-cluster). +1. [Deploy your cluster](#deploy-to-your-cluster). + +See the [Kubernetes clusters versions supported by GitLab](connect/index.md#supported-cluster-versions). + +## Connect your cluster to GitLab + +Learn how to [create new and connect existing clusters to GitLab](connect/index.md). + +## Manage your cluster + +- [Cluster Management Project](../../clusters/management_project.md): +create a project to manage your cluster's shared resources requiring +`cluster-admin` privileges such as an Ingress controller. + - [Cluster Management Project Template](../../clusters/management_project_template.md): start a cluster management project directly from a template. + - [Migrate to Cluster Management Project](../../clusters/migrating_from_gma_to_project_template.md): migrate from the deprecated GitLab Managed Apps to Cluster Management Projects. + - [GitLab Managed Apps](../../clusters/applications.md) (deprecated in favor of Cluster Management Projects): configure applications in your cluster directly from GitLab. +- [Cluster integrations](../../clusters/integrations.md): install +third-party applications into your cluster and manage them from GitLab. +- [GitLab-managed clusters](../../project/clusters/gitlab_managed_clusters.md): +enable GitLab to automatically create resources for your clusters. +- [Cost management](../../clusters/cost_management.md): see insights into your cluster's resource usage. +- [Crossplane integration](../../clusters/crossplane.md): manage your cluster's resources and cloud infrastructure with Crossplane. + +### Monitor your cluster + +- [Prometheus monitoring](../../project/integrations/prometheus_library/kubernetes.md): detect and monitor Kubernetes metrics with Prometheus. +- [NGINX monitoring](../../project/integrations/prometheus_library/nginx.md): automatically monitor NGINX Ingress. +- [Clusters health](manage/clusters_health.md): monitor your cluster's health, such as CPU and memory usage. + +### Secure your cluster + +- [Container Host Security](../../project/clusters/protect/container_host_security/index.md): monitor and block activity inside a container and enforce security policies across the cluster. +- [Container Network security](../../project/clusters/protect/container_network_security/index.md): filter traffic going in and out of the cluster and traffic between pods through a firewall with Cilium NetworkPolicies. + +## Deploy to your cluster + +- [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md): use the CI/CD Tunnel to run Kubernetes commands from different projects. +- [Inventory object](deploy/inventory_object.md): track objects applied to a cluster configured with the Kubernetes Agent. +- [Auto DevOps](../../../topics/autodevops/index.md): enable Auto DevOps +to allow GitLab automatically detect, build, test, and deploy applications. +- [Cluster environments](../../clusters/environments.md): view CI/CD environments deployed to Kubernetes clusters. +- [Canary Deployments](../../project/canary_deployments.md): deploy app updates to a small portion of the fleet with this Continuous Delivery strategy. +- [Deploy to your cluster](../../project/clusters/deploy_to_cluster.md): +deploy applications into your cluster using cluster certificates. +- [Deploy Boards](../../project/deploy_boards.md): view the current health and status of each CI/CD environment running on your cluster, and the status of deployment pods. +- [Pod logs](../../project/clusters/kubernetes_pod_logs.md): view the logs of your cluster's running pods. +- [Serverless](../../project/clusters/serverless/index.md) (deprecated): deploy Serverless applications in Kubernetes environments and cloud Function as a Service (FaaS) environments. diff --git a/doc/user/infrastructure/clusters/manage/clusters_health.md b/doc/user/infrastructure/clusters/manage/clusters_health.md new file mode 100644 index 00000000000..009945589ad --- /dev/null +++ b/doc/user/infrastructure/clusters/manage/clusters_health.md @@ -0,0 +1,14 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Clusters health **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Free in 13.2. + +When [the Prometheus cluster integration is enabled](../../../clusters/integrations.md#prometheus-cluster-integration), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. + + diff --git a/doc/user/project/clusters/img/k8s_cluster_monitoring.png b/doc/user/infrastructure/clusters/manage/img/k8s_cluster_monitoring.png Binary files differindex 0a8c5043c65..0a8c5043c65 100644 --- a/doc/user/project/clusters/img/k8s_cluster_monitoring.png +++ b/doc/user/infrastructure/clusters/manage/img/k8s_cluster_monitoring.png diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 9f28a40474e..e99dc691774 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -35,7 +35,7 @@ DevSecOps pipeline by default targeted at Kubernetes based deployments. To suppo all the GitLab features, GitLab offers a cluster management project for easy onboarding. The deploy boards provide quick insights into your cluster, including pod logs tailing. -Learn more about the [GitLab integration with Kubernetes](../project/clusters/index.md). +Learn more about the [GitLab integration with Kubernetes](clusters/index.md). ## Runbooks in GitLab diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 20cd30b6110..de09cd4845e 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Instance-level Kubernetes clusters +# Instance-level Kubernetes clusters **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11. @@ -39,4 +39,4 @@ are deployed to the Kubernetes cluster, see the documentation for ## More information For information on integrating GitLab and Kubernetes, see -[Kubernetes clusters](../../project/clusters/index.md). +[Kubernetes clusters](../../infrastructure/clusters/index.md). diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 4149307c45a..5e600b6e0d1 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -524,7 +524,7 @@ GitLab Flavored Markdown recognizes the following: | specific user | `@user_name` | | | | specific group | `@group_name` | | | | entire team | `@all` | | | -| project | `namespace/project` | | | +| project | `namespace/project>` | | | | issue | ``#123`` | `namespace/project#123` | `project#123` | | merge request | `!123` | `namespace/project!123` | `project!123` | | snippet | `$123` | `namespace/project$123` | `project$123` | @@ -955,6 +955,10 @@ Do not change to a reference style link.  +In the rare case where you need to set a specific height or width for an image, +you can use the `img` HTML tag instead of Markdown and set its `height` and +`width` parameters. + #### Videos If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#videos). diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 2787aefdeca..6e3af45df17 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -10,6 +10,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. > - Support for Composer 2.0 [added](https://gitlab.com/gitlab-org/gitlab/-/issues/259840) in GitLab Free 13.10. +WARNING: +The Composer package registry for GitLab is under development and isn't ready for production use due to +limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6817) details the remaining +work and timelines to make it production ready. + Publish [Composer](https://getcomposer.org/) packages in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -120,6 +125,7 @@ You can publish a Composer package to the Package Registry as part of your CI/CD deploy: stage: deploy script: + - apk add curl - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/composer"' ``` @@ -132,7 +138,7 @@ To view the published package, go to **Packages & Registries > Package Registry* A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` template: 1. On the left sidebar, select **Project information**. -1. Above the file list, click **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**. +1. Above the file list, select **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**. 1. From the **Apply a template** list, select **Composer**. WARNING: diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index dc08baaf731..33c48478921 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -9,6 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab Premium 12.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +WARNING: +The Conan package registry for GitLab is under development and isn't ready for production use due to +limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6816) details the remaining +work and timelines to make it production ready. + Publish Conan packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -358,7 +363,7 @@ There are two ways to remove a Conan package from the GitLab Package Registry. - From the GitLab user interface: Go to your project's **Packages & Registries > Package Registry**. Remove the - package by clicking the red trash icon. + package by selecting **Remove repository** (**{remove}**). ## Search for Conan packages in the Package Registry diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 1db2165cd5d..c39552c1edb 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -648,7 +648,11 @@ For self-managed instances, those settings can be updated in the [Rails console] ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) ``` -Alternatively, once the limits are [enabled](#enable-or-disable-cleanup-policy-limits), they are available in the [admin area](../../admin_area/index.md) **Settings > CI/CD > Container Registry**. +Alternatively, once the limits are [enabled](#enable-or-disable-cleanup-policy-limits), +they are available in the [administrator area](../../admin_area/index.md): + +1. On the top bar, select **Menu > Admin**. +1. Go to **Settings > CI/CD > Container Registry**. #### Enable or disable cleanup policy limits @@ -714,15 +718,6 @@ Check the regex patterns to ensure they are valid. GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in the cleanup policy. You can test them with the [regex101 regex tester](https://regex101.com/). View some common [regex pattern examples](#regex-pattern-examples). -## Use the Container Registry to store Helm Charts - -With the launch of [Helm v3](https://helm.sh/docs/topics/registries/), -you can use the Container Registry to store Helm Charts. However, due to the way metadata is passed -and stored by Docker, it is not possible for GitLab to parse this data and meet performance standards. -[This epic](https://gitlab.com/groups/gitlab-org/-/epics/2313) updates the architecture of the Container Registry to support Helm Charts. - -[Read more about the above challenges](https://gitlab.com/gitlab-org/gitlab/-/issues/38047#note_298842890). - ## Limitations - Moving or renaming existing Container Registry repositories is not supported @@ -911,10 +906,10 @@ these steps: while read -r LINE || [[ -n $LINE ]]; do echo ${LINE}; curl --request DELETE --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags/${LINE}"; sleep 0.1; echo; done < list_o_tags.out > delete.logs ``` -### Troubleshoot as a GitLab server admin +### Troubleshoot as a GitLab server administrator Troubleshooting the GitLab Container Registry, most of the times, requires -administrator access to the GitLab server. +you to log in to GitLab server with the Administrator role. [Read how to troubleshoot the Container Registry](../../../administration/packages/container_registry.md#troubleshooting). diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 29641380753..36d85d94161 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -12,7 +12,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: The Debian package registry for GitLab is under development and isn't ready for production use due to -limited functionality. +limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6057) details the remaining +work and timelines to make it production ready. Publish Debian packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -138,7 +139,7 @@ To install a package: 1. Configure the repository: - If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt config: + If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt configuration: ```shell echo 'machine gitlab.example.com login <username> password <your_access_token>' \ diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index ad25ec7edbf..5d482a15460 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -33,6 +33,14 @@ The following images and packages are supported. For a list of planned additions, view the [direction page](https://about.gitlab.com/direction/package/#dependency-proxy). +## Enable or disable the Dependency Proxy for a group + +To enable or disable the Dependency Proxy for a group: + +1. Go to your group's **Settings > Packages & Registries**. +1. Expand the **Dependency Proxy** section. +1. To enable the proxy, turn on **Enable Proxy**. To disable it, turn the toggle off. + ## View the Dependency Proxy To view the Dependency Proxy: @@ -66,7 +74,7 @@ has disrupted your existing Dependency Proxy usage. Because the Dependency Proxy is storing Docker images in a space associated with your group, you must authenticate against the Dependency Proxy. -Follow the [instructions for using images from a private registry](../../../ci/docker/using_docker_images.md#define-an-image-from-a-private-container-registry), +Follow the [instructions for using images from a private registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry), but instead of using `registry.example.com:5000`, use your GitLab domain with no port `gitlab.example.com`. For example, to manually log in: @@ -171,8 +179,53 @@ from the GitLab server. Blobs are kept forever on the GitLab server, and there is no hard limit on how much data can be stored. +### Using the API to clear the cache + To reclaim disk space used by image blobs that are no longer needed, use -the [Dependency Proxy API](../../../api/dependency_proxy.md). +the [Dependency Proxy API](../../../api/dependency_proxy.md) to clear the entire +cache. + +If you clear the cache, the next time a pipeline runs it must pull an image or tag from Docker Hub. + +### Cleanup policies + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294187) in GitLab Free 14.4. + +The cleanup policy is a scheduled job you can use to clear cached images that are no longer used, +freeing up additional storage space. The policies use time-to-live (TTL) logic: + +- The number of days is configured. +- All cached dependency proxy files that have not been pulled in that many days are deleted. + +Use the [GraphQL API](../../../api/graphql/reference/index.md#mutationupdatedependencyproxyimagettlgrouppolicy) +to enable and configure cleanup policies: + +```graphql +mutation { + updateDependencyProxyImageTtlGroupPolicy(input: + { + groupPath: "<your-full-group-path>", + enabled: true, + ttl: 90 + } + ) { + dependencyProxyImageTtlPolicy { + enabled + ttl + } + errors + } +} +``` + +See the [Getting started with GraphQL](../../../api/graphql/getting_started.md) +guide to learn how to make GraphQL queries. Support for enabling and configuring cleanup policies in +the UI is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340777). + +When the policy is initially enabled, the default TTL setting is 90 days. Once enabled, stale +dependency proxy files are queued for deletion each day. Deletion may not occur right away due to +processing time. If the image is pulled after the cached files are marked as expired, the expired +files are ignored and new files are downloaded and cached from the external registry. ## Docker Hub rate limits and the Dependency Proxy @@ -227,7 +280,7 @@ script: ```shell # Note, you must have jq installed to run this command -TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 | grep RateLimit +TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 | grep --ignore-case RateLimit ... ``` @@ -256,10 +309,6 @@ hub_docker_quota_check: TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 ``` -## Use the NPM Dependency Proxy for NPM packages - -For information on this, see [Dependency Proxy](../npm_registry/#dependency-proxy). - ## Troubleshooting ### Dependency Proxy Connection Failure diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 0c04c4a23d0..f17910cd46d 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -9,10 +9,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab Premium 13.1. > - It's deployed behind a feature flag, disabled by default. > - It's disabled for GitLab.com. -> - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-the-go-proxy). > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. +WARNING: +The Go package registry for GitLab is under development and isn't ready for production use due to +limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/3043) details the remaining +work and timelines to make it production ready. + With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 2d984d76b97..c88fba83dc7 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -8,6 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1. +WARNING: +The Helm chart registry for GitLab is under development and isn't ready for production use due to +limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6366) details the remaining +work and timelines to make it production ready. + Publish Helm packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -31,6 +36,10 @@ To authenticate to the Helm repository, you need either: ## Publish a package +WARNING: +The `helm-push` command is broken in Helm 3.7. For more information, see the [open issue](https://github.com/chartmuseum/helm-push/issues/109) +in the Chart Museum project. + NOTE: You can publish Helm charts with duplicate names or versions. If duplicates exist, GitLab always returns the chart with the latest version. @@ -105,7 +114,7 @@ helm install my-release project-1/mychart - `<project_id>`: the project ID (like `42`). - `<channel>`: the name of the channel (like `stable`). -If the repo has previously been added, you may need to run: +If the repository has previously been added, you may need to run: ```shell helm repo update @@ -123,3 +132,15 @@ Check the [Sidekiq log](../../../administration/logs.md#sidekiqlog) for any related errors. If you see `Validation failed: Version is invalid`, it means that the version in your `Chart.yaml` file does not follow [Helm Chart versioning specifications](https://helm.sh/docs/topics/charts/#charts-and-versioning). To fix the error, use the correct version syntax and upload the chart again. + +### `helm push` results in an error + +The `helm push` plugin is not yet supported in Helm 3.7. If you try to push a chart using +`helm push`, it produces the following error: + +```plaintext +Error: this feature has been marked as experimental and is not enabled by default. Please set HELM_EXPERIMENTAL_OCI=1 in your environment to use this feature +``` + +To continue to use the plugin, you can push an image using [curl](#use-cicd-to-publish-a-helm-package) +or downgrade your version of Helm. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 9158b5cc674..a8f1b1998ae 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -10,20 +10,31 @@ The GitLab [Package Registry](package_registry/index.md) acts as a private or pu for a variety of common package managers. You can publish and share packages, which can be easily consumed as a dependency in downstream projects. +WARNING: +Not all package manager formats are ready for production use. To view each format's status, see the +table's **Status** column. + The Package Registry supports the following formats: -| Package type | GitLab version | -| ------------ | -------------- | -| [Composer](composer_repository/index.md) | 13.2+ | -| [Conan](conan_repository/index.md) | 12.6+ | -| [Go](go_proxy/index.md) | 13.1+ | -| [Helm](helm_repository/index.md) | 14.1+ | -| [Maven](maven_repository/index.md) | 11.3+ | -| [npm](npm_registry/index.md) | 11.7+ | -| [NuGet](nuget_repository/index.md) | 12.8+ | -| [PyPI](pypi_repository/index.md) | 12.10+ | -| [Generic packages](generic_packages/index.md) | 13.5+ | -| [Ruby gems](rubygems_registry/index.md) | 13.10+ | +| Package type | GitLab version | Status | +| ------------ | -------------- |------- | +| [Maven](maven_repository/index.md) | 11.3+ | Stable | +| [npm](npm_registry/index.md) | 11.7+ | Stable | +| [NuGet](nuget_repository/index.md) | 12.8+ | Stable | +| [PyPI](pypi_repository/index.md) | 12.10+ | Stable | +| [Generic packages](generic_packages/index.md) | 13.5+ | Stable | +| [Composer](composer_repository/index.md) | 13.2+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6817) | +| [Conan](conan_repository/index.md) | 12.6+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6816) | +| [Helm](helm_repository/index.md) | 14.1+ | [Beta](https://gitlab.com/groups/gitlab-org/-/epics/6366) | +| [Debian](debian_repository/index.md) | 14.2+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/6057) | +| [Go](go_proxy/index.md) | 13.1+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/3043) | +| [Ruby gems](rubygems_registry/index.md) | 13.10+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/3200) | + +Status: + +- Alpha: behind a feature flag and not officially supported. +- Beta: several known issues that may prevent expected use. +- Stable: ready for production use. You can also use the [API](../../api/packages.md) to administer the Package Registry. @@ -40,12 +51,12 @@ guides you through the process. | CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | | Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | | CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | -| Debian | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50438) | | Opkg | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | | P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | | Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | -| RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | +| RPM | [#5932](https://gitlab.com/groups/gitlab-org/-/epics/5128) | | SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | +| Swift | [#12233](https://gitlab.com/gitlab-org/gitlab/-/issues/12233) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | <!-- vale gitlab.Spelling = YES --> diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index fe7e6a0ea46..b07ae72e273 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -370,13 +370,26 @@ in a JavaScript project. You can install a package from the scope of a project o If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. -1. Set the URL for scoped packages by running: +1. Set the URL for scoped packages. + + For [instance-level endpoints](#use-the-gitlab-endpoint-for-npm-packages) run: ```shell npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ ``` - Replace `@foo` with your scope. + - Replace `@foo` with your scope. + - Replace `gitlab.example.com` with your domain name. + + For [project-level endpoints](#use-the-gitlab-endpoint-for-npm-packages) run: + + ```shell + npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/ + ``` + + - Replace `@foo` with your scope. + - Replace `gitlab.example.com` with your domain name. + - Replace `<your_project_id>` with your project ID, found on the project's home page. 1. Ensure [authentication](#authenticate-to-the-package-registry) is configured. @@ -601,8 +614,3 @@ The GitLab npm repository supports the following commands for the npm CLI (`npm` - `npm view`: Show package metadata. - `yarn add`: Install an npm package. - `yarn update`: Update your dependencies. - -## Dependency Proxy - -The NPM Dependency Proxy for NPM packages isn't available. For more information, see -[this epic](https://gitlab.com/groups/gitlab-org/-/epics/3608). diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 40e8b74c2b6..2af6dc60078 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -77,6 +77,8 @@ To use the GitLab endpoint for NuGet Packages, choose an option: Some features such as [publishing](#publish-a-nuget-package) a package are only available on the project-level endpoint. +When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 most recent versions. + WARNING: Because of how NuGet handles credentials, the Package Registry rejects anonymous requests on the group-level endpoint. To work around this limitation, set up [authentication](#add-the-package-registry-as-a-source-for-nuget-packages). @@ -352,12 +354,12 @@ the existing package is overwritten. ## Install packages -To install a NuGet package from the Package Registry, you must first -[add a project-level or group-level endpoint](#add-the-package-registry-as-a-source-for-nuget-packages). - If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. +To install a NuGet package from the Package Registry, you must first +[add a project-level or group-level endpoint](#add-the-package-registry-as-a-source-for-nuget-packages). + ### Install a package with the NuGet CLI WARNING: diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 2a0fea6e0ef..e31bd8bd0bf 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -9,8 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in [GitLab Free](https://about.gitlab.com/pricing/) 13.10. WARNING: -The Ruby gems registry for GitLab is under development and isn't ready for production use due to -limited functionality. +The Ruby gems package registry for GitLab is under development and isn't ready for production use due to +limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/3200) details the remaining +work and timelines to make it production ready. You can publish Ruby gems in your project's Package Registry, then install the packages when you need to use them as a dependency. Although you can push gems to the registry, you cannot install diff --git a/doc/user/permissions.md b/doc/user/permissions.md index f240a9fd407..10147e7f69c 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -33,8 +33,6 @@ usernames. A GitLab administrator can configure the GitLab instance to ## Project members permissions -> The Master role was renamed to Maintainer in GitLab 11.0. - The Owner role is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects. While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, or an instance administrator, who receives all permissions. For more information, see [projects members documentation](project/members/index.md). @@ -59,23 +57,23 @@ The following table lists project permissions available for each role: | [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | | [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) **(ULTIMATE)** | | | | | ✓ | -| [CI/CD](../ci/README.md):<br>Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>View a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>View list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>View [environments](../ci/environments/index.md) | | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Cancel and retry jobs | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Create new [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Stop [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Manage CI/CD variables | | | | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Manage job triggers | | | | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Manage runners | | | | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals) | | | | ✓ | ✓ | -| [CI/CD](../ci/README.md):<br>Delete pipelines | | | | | ✓ | -| [Clusters](project/clusters/index.md):<br>View pod logs | | | ✓ | ✓ | ✓ | -| [Clusters](project/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>View a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>View list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>View [environments](../ci/environments/index.md) | | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Cancel and retry jobs | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Create new [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Stop [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Manage CI/CD variables | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Manage job triggers | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Manage runners | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals) | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Delete pipelines | | | | | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Remove a container registry image | | | ✓ | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Update container registry | | | ✓ | ✓ | ✓ | @@ -132,7 +130,7 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View project statistics | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | | [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | @@ -269,9 +267,6 @@ Find the visibility permissions for the Container Registry, as described in the ## Group members permissions -NOTE: -In GitLab 11.0, the Master role was renamed to Maintainer. - Any user can remove themselves from a group, unless they are the last Owner of the group. @@ -434,7 +429,7 @@ mentioned in the [permissions table above](#project-members-permissions) (they are unable to browse the project's repository, for example). NOTE: -To prevent a guest user from creating projects, as an admin, you can edit the +To prevent a guest user from creating projects, as an administrator, you can edit the user's profile to mark the user as [external](#external-users). Beware though that even if a user is external, if they already have Reporter or higher permissions in any project or group, they are **not** counted as a @@ -442,8 +437,6 @@ free guest user. ## Auditor users **(PREMIUM SELF)** ->[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/998) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.17. - Auditor users are given read-only access to all projects, groups, and other resources on the GitLab instance. @@ -454,7 +447,7 @@ with the permissions described on the documentation on [auditor users permission ## Users with minimal access **(PREMIUM)** ->[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. Owners can add members with a "minimal access" role to a parent group. Such users don't automatically have access to projects and subgroups underneath. To support such access, owners must explicitly add these "minimal access" users to the specific subgroups/projects. @@ -480,9 +473,6 @@ which visibility level you select on project settings. ## GitLab CI/CD permissions -NOTE: -In GitLab 11.0, the Master role was renamed to Maintainer. - GitLab CI/CD permissions rely on the role the user has in GitLab. There are four roles: @@ -513,13 +503,10 @@ instance and project. ### Job permissions -NOTE: -In GitLab 11.0, the Master role was renamed to Maintainer. - This table shows granted privileges for jobs triggered by specific types of users: -| Action | Guest, Reporter | Developer |Maintainer| Admin | +| Action | Guest, Reporter | Developer |Maintainer| Administrator | |---------------------------------------------|-----------------|-------------|----------|---------| | Run CI job | | ✓ | ✓ | ✓ | | Clone source and LFS from current project | | ✓ | ✓ | ✓ | @@ -534,8 +521,8 @@ users: | Push container images to other projects | | | | | | Push source and LFS | | | | | -1. Only if the user is not an external one -1. Only if the user is a member of the project +1. Only if the triggering user is not an external one +1. Only if the triggering user is a member of the project ## Running pipelines on protected branches @@ -555,7 +542,7 @@ for more information. ## LDAP users permissions -In GitLab 8.15 and later, LDAP user permissions can now be manually overridden by an admin user. +LDAP user permissions can be manually overridden by an administrator. Read through the documentation on [LDAP users permissions](group/index.md#manage-group-memberships-via-ldap) to learn more. ## Project aliases diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 3cc56cc47e6..ab0cae976d2 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can create users: -- Manually through the sign in page or Admin Area. +- Manually through the sign in page or Administrator Area. - Automatically through user authentication integrations. ## Create users on sign in page @@ -24,17 +24,17 @@ their own accounts by either: ## Create users in Admin Area -As an Admin user, you can manually create users: +As an Administrator user, you can manually create users: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users** (`/admin/users`). 1. Select **New user**. -You can also [create users through the API](../../../api/users.md) as an admin. +You can also [create users through the API](../../../api/users.md) as an administrator. - + - + ## Create users through authentication integrations diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 41b4e508c38..c555f5ca8cc 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -19,7 +19,7 @@ Deleting a user deletes all projects in that user namespace. As a user, to delete your own account: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. Select **Delete account**. diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 44537707db6..6fe4b457fac 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,5 +1,4 @@ --- -type: howto stage: Manage group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -35,7 +34,8 @@ still access your account if you lose your U2F / WebAuthn device. ## Enabling 2FA -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3, account email confirmation required. +> - Account email confirmation requirement [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3. [Deployed behind the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md), enabled by default. +> - Account email confirmation requirement generally available and [feature flag `ensure_verified_primary_email_for_2fa` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340151) in GitLab 14.4. There are multiple ways to enable two-factor authentication (2FA): @@ -44,11 +44,6 @@ There are multiple ways to enable two-factor authentication (2FA): In GitLab 14.3 and later, your account email must be confirmed to enable two-factor authentication. -FLAG: -On self-managed GitLab, account email confirmation requirement is enabled. To disable this -restriction, ask an administrator to -[disable the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md). - ### One-time password To enable 2FA: @@ -239,8 +234,6 @@ Feature.disable(:forti_token_cloud, User.find(<user ID>)) ### U2F device -> Introduced in [GitLab 8.9](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/). - GitLab officially only supports [YubiKey](https://www.yubico.com/products/) U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/) or [Google Titan Security Key](https://cloud.google.com/titan-security-key). diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 25f349d9272..1797307a00c 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -9,14 +9,14 @@ type: howto > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17867) in GitLab 10.8. -GitLab lists all devices that have logged into your account. This allows you to +GitLab lists all devices that have logged into your account. You can review the sessions, and revoke any you don't recognize. ## Listing all active sessions To list all active sessions: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Active Sessions**. @@ -33,7 +33,7 @@ exceeds 100, the oldest ones are deleted. To revoke an active session: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Active Sessions**. 1. Select **Revoke** next to a session. The current session cannot be revoked, as this would sign you out of GitLab. diff --git a/doc/user/profile/img/notification_global_settings_v13_12.png b/doc/user/profile/img/notification_global_settings_v13_12.png Binary files differdeleted file mode 100644 index 0998bb89778..00000000000 --- a/doc/user/profile/img/notification_global_settings_v13_12.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 24006e6f875..7f16c4e244e 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -15,25 +15,25 @@ Your profile also includes settings, which you use to customize your GitLab expe To access your profile: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select your name or username. ## Access your user settings To access your user settings: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. ## Change your password To change your password: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Password**. -1. In the **Current password** field, enter your current password. -1. In the **New password** and **Password confirmation** field, enter your new password. +1. In the **Current password** text box, enter your current password. +1. In the **New password** and **Password confirmation** text box, enter your new password. 1. Select **Save password**. If you don't know your current password, select the **I forgot my password** link. @@ -53,7 +53,7 @@ Prerequisites: To change your username: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Change username** section, enter a new username as the path. @@ -63,10 +63,10 @@ To change your username: To add new email to your account: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Emails**. -1. In the **Email** box, enter the new email. +1. In the **Email** text box, enter the new email. 1. Select **Add email address**. 1. Verify your email address with the verification email received. @@ -76,7 +76,7 @@ You can make your user profile visible to only you and GitLab administrators. To make your profile private: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. 1. Select the **Private profile** checkbox. 1. Select **Update profile settings**. @@ -107,7 +107,7 @@ They can help other users connect with you on other platforms. To add links to other accounts: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, add your information from: - Skype @@ -121,7 +121,7 @@ In the user contribution calendar graph and recent activity list, you can see yo To show private contributions: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, select the **Include private contributions on my profile** checkbox. 1. Select **Update profile settings**. @@ -135,9 +135,9 @@ your name in your profile. To specify your pronouns: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the **Pronouns** field, enter your pronouns. +1. In the **Pronouns** text box, enter your pronouns. 1. Select **Update profile settings**. ## Add your name pronunciation @@ -149,9 +149,9 @@ your name. To add your name pronunciation: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the **Pronunciation** field, enter how your name is pronounced. +1. In the **Pronunciation** text box, enter how your name is pronounced. 1. Select **Update profile settings**. ## Set your current status @@ -165,11 +165,11 @@ Your status is publicly visible even if your [profile is private](#make-your-use To set your current status: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. 1. Set the desired emoji and status message. Status messages must be plain text and 100 characters or less. They can also contain emoji codes like, `I'm on vacation :palm_tree:`. -1. Select a value from the **Clear status after** dropdown. +1. Select a value from the **Clear status after** dropdown list. 1. Select **Set status**. Alternatively, you can select **Remove status** to remove your user status entirely. You can also set your current status by [using the API](../../api/users.md#user-status). @@ -188,12 +188,12 @@ To indicate to others that you are busy, you can set an indicator. To set the busy status indicator, either: - Set it directly: - 1. In the top-right corner, select your avatar. + 1. On the top bar, in the top-right corner, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. 1. Select the **Busy** checkbox. - Set it on your profile: - 1. In the top-right corner, select your avatar. + 1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Current status** section, select the **Busy** checkbox. @@ -221,7 +221,7 @@ To set the busy status indicator, either: To set your time zone: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Time settings** section, select your time zone from the dropdown list. @@ -236,7 +236,7 @@ To change your commit email: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the **Commit email** list, select an email address. +1. In the **Commit email** dropdown list, select an email address. 1. Select **Update profile settings**. ### Use an automatically-generated private commit email @@ -246,9 +246,9 @@ so you can keep your email information private. To use a private commit email: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. -1. In the **Commit email** list, select the **Use a private email** option. +1. In the **Commit email** dropdown list, select **Use a private email**. 1. Select **Update profile settings**. Every Git-related action uses the private commit email. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index aaa311a4097..6de09f5538f 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -13,56 +13,62 @@ You can receive updates about activity in issues, merge requests, epics, and des For the tool that GitLab administrators can use to send messages to users, read [Email from GitLab](../../tools/email.md). -## Receive notifications +## Who receives notifications -You receive notifications for one of the following reasons: +When notifications are enabled for an issue, merge request, or epic, GitLab notifies you of actions +that happen there. -- You participate in an issue, merge request, epic, or design. In this context, _participate_ means - comment or edit. -- You've [enabled notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). -- You configured notifications at the [project](#project-notifications) and/or [group](#group-notifications) level. +You might receive notifications for one of the following reasons: -While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic. +- You participate in an issue, merge request, epic, or design. You become a participant when you comment + or edit, or someone mentions you. +- You've [enabled notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). +- You've configured notifications for the [project](#change-level-of-project-notifications) or [group](#group-notifications). NOTE: Administrators can block notifications, preventing them from being sent. -## Tune your notifications +## Edit notification settings Getting many notifications can be overwhelming. You can tune the notifications you receive. For example, you might want to be notified about all activity in a specific project. For other projects, you only want to be notified when you are mentioned by name. -You can tune the notifications you receive by changing your notification settings: - -- [Global notification settings](#global-notification-settings) -- [Notification scope](#notification-scope) -- [Notification levels](#notification-levels) - -## Edit notification settings - These notification settings apply only to you. They do not affect the notifications received by -anyone else in the same project or group. +anyone else. To edit your notification settings: 1. In the top-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. -1. Edit the desired notification settings. Edited settings are automatically saved and enabled. +1. Edit the desired global, group, or project notification settings. + Edited settings are automatically saved. -## Notification scope +### Notification scope -You can tune the scope of your notifications by selecting different notification levels for each project and group. +You can tune the scope of your notifications by selecting different notification levels for each +project and group. Notification scope is applied from the broadest to most specific levels: -- **Global (default)**: Your global, or _default_, notification level applies if you +- 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. -- **Group**: For each group, you can select a notification level. Your group setting - overrides your default setting. -- **Project**: For each project, you can select a notification level. Your project - setting overrides the group setting. +- Your **group** setting overrides your default setting. +- Your **project** setting overrides the group setting. + +### 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. | +| Participate | Receive notifications for threads you have participated in. | +| On mention | Receive notifications when you are [mentioned](../project/issues/issue_data_and_actions.md#mentions) in a comment. | +| Disabled | Receive no notifications. | +| Custom | Receive notifications for selected events. | ### Global notification settings @@ -72,19 +78,17 @@ different values for a project or a group. - **Notification email**: the email address your notifications are sent to. Defaults to your primary email address. - **Receive product marketing emails**: select this checkbox to receive - [periodic emails](#product-marketing-emails) about GitLab features. + [periodic emails](#opt-out-of-product-marketing-emails) about GitLab features. - **Global notification level**: the default [notification level](#notification-levels) which applies to all your notifications. - **Receive notifications about your own activity**: select this checkbox to receive notifications about your own activity. Not selected by default. - - ### Group notifications You can select a notification level and email address for each group. -#### Group notification level +#### Change level of group notifications To select a notification level for a group, use either of these methods: @@ -100,11 +104,12 @@ Or: 1. Select the notification dropdown, next to the bell icon (**{notifications}**). 1. Select the desired [notification level](#notification-levels). -#### Group notification email address +#### Change email address used for group notifications -> Introduced in GitLab 12.0 +> 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. +You can select an email address to receive notifications for each group you belong to. +You can use group notifications, for example, if you work freelance, and want to keep email about clients' projects separate. 1. In the top-right corner, select your avatar. 1. Select **Preferences**. @@ -112,9 +117,9 @@ You can select an email address to receive notifications for each group you belo 1. Locate the project in the **Groups** section. 1. Select the desired email address. -### Project notifications +### Change level of project notifications -You can select a notification level for each project to help you closely monitor activity in select projects. +To help you stay up to date, you can select a notification level for each project. To select a notification level for a project, use either of these methods: @@ -131,28 +136,20 @@ Or: 1. Select the desired [notification level](#notification-levels). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -To learn how to be notified when a new release is available, see [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4). +To learn how to be notified when a new release is available, watch [Notification for releases](https://www.youtube.com/watch?v=qyeNkGgqmH4). -### 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](../project/issues/issue_data_and_actions.md#mentions) in a comment. | -| Participate | Receive notifications for threads you have participated in. | -| Disabled | Turns off notifications. | -| Custom | Receive notifications for custom selected events. | - -### Product marketing emails +### Opt out of product marketing emails You can receive emails that teach you about various GitLab features. -This is enabled by default. +These emails are enabled by default. -To opt out, [edit your notification settings](#edit-notification-settings) and clear the -**Receive product marketing emails** checkbox. +To opt out: + +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. On the left sidebar, select **Notifications**. +1. Clear the **Receive product marketing emails** checkbox. + Edited settings are automatically saved and enabled. Disabling these emails does not disable all emails. Learn how to [opt out of all emails from GitLab](#opt-out-of-all-gitlab-emails). @@ -175,108 +172,115 @@ Users are notified of the following events: | Event | Sent to | Settings level | |------------------------------|---------------------|------------------------------| -| New release | Project members | Custom notification | -| Project moved | Project members (1) | (1) not disabled | +| New release | Project members | Custom notification. | +| Project moved | Project members | Any other than disabled. | | Email changed | User | Security email, always sent. | -| Group access level changed | User | Sent when user group access level is changed | +| Group access level changed | User | Sent when user group access level is changed. | | New email added | User | Security email, always sent. | | New SAML/SCIM user provisioned | User | Sent when a user is provisioned through SAML/SCIM. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276018) in GitLab 13.8 | | New SSH key added | User | Security email, always sent. | -| New user created | User | Sent on user creation, except for OmniAuth (LDAP)| -| Password changed | User | Security email, always sent when user changes their own password | -| Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user | -| Personal access tokens expiring soon <!-- Do not delete or lint this instance of future tense --> | User | Security email, always sent. | +| New user created | User | Sent on user creation, except for OmniAuth (LDAP). | +| Password changed | User | Security email, always sent when user changes their own password. | +| Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user. | +| Personal access tokens expiring soon | User | Security email, always sent. | | Personal access tokens have expired | User | Security email, always sent. | -| Project access level changed | User | Sent when user project access level is changed | -| SSH key has expired | User | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12 | +| Project access level changed | User | Sent when user project access level is changed. | +| SSH key has expired | User | Security email, always sent. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12._ | | Two-factor authentication disabled | User | Security email, always sent. | -| User added to group | User | Sent when user is added to group | -| User added to project | User | Sent when user is added to project | +| User added to group | User | Sent when user is added to group. | +| User added to project | User | Sent when user is added to project. | ## Notifications on issues, merge requests, and epics -To enable notifications on a specific issue, merge request, or epic, you must turn on the -**Notifications** toggle in the right sidebar. +You also receive notifications for events happening on +issues, merge requests, and epics. -- To subscribe, **turn on** if you are not a participant in the discussion, but want to receive - notifications on each update. -- To unsubscribe, **turn off** if you are receiving notifications for updates but no longer want to - receive them, unsubscribe from it. - -Turning this toggle off only unsubscribes you from updates related to this issue, merge request, or epic. -Learn how to [opt out of all emails from GitLab](#opt-out-of-all-gitlab-emails). - -Turning notifications on in an epic doesn't automatically subscribe you to the issues linked -to the epic. +### Who receives notifications on issues, merge requests, and epics -For most events, the notification is sent to: +In issues, merge requests, and epics, for most events, the notification is sent to: - Participants: - - The author and assignee of the issue/merge request. + - The author and assignee. - Authors of comments. - Anyone [mentioned](../project/issues/issue_data_and_actions.md#mentions) by username in the title - or description of the issue, merge request or epic. - - Anyone with notification level "Participating" or higher that is mentioned by their username in - any of the comments on the issue, merge request, or epic. + or description. + - Anyone mentioned by username in a comment if their notification level is "Participating" or higher. - Watchers: users with notification level "Watch". -- Subscribers: anyone who manually subscribed to the issue, merge request, or epic. -- Custom: Users with notification level "custom" who turned on notifications for any of the events in the following table. +- Subscribers: anyone who manually subscribed to notifications. +- Custom: users with notification level "Custom" who turned on notifications for a fitting type of events. NOTE: To minimize the number of notifications that do not require any action, in -[GitLab versions 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/616), eligible -approvers are no longer notified for all the activities in their projects. To receive them they have +[GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/616), eligible +approvers are no longer notified for all the activities in their projects. To turn on such notifications, they have to change their user notification settings to **Watch** instead. +### Edit notification settings for issues, merge requests, and epics + +To enable notifications on a specific issue, merge request, or epic, you must turn on the +**Notifications** toggle in the right sidebar. + +- To subscribe, **turn on** if you are not a participant in the discussion, but want to receive + notifications on each update. + + When you turn notifications on in an epic, you aren't automatically subscribed to the issues linked + to the epic. + +- To unsubscribe, **turn off** if you are receiving notifications for updates but no longer want to + receive them. + + Turning this toggle off only unsubscribes you from updates related to this issue, merge request, or epic. + Learn how to [opt out of all emails from GitLab](#opt-out-of-all-gitlab-emails). + +### Notification events on issues, merge requests, and epics + The following table presents the events that generate notifications for issues, merge requests, and epics: | Event | Sent to | |------------------------|---------| -| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | -| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected. | +| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected. | | Close epic | | | Close issue | | | Close merge request | | -| Due issue | Participants and Custom notification level with this event selected | -| Failed pipeline | The author of the pipeline | -| Fixed pipeline | The author of the pipeline. Enabled by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1 | +| Due issue | Participants and Custom notification level with this event selected. | +| Failed pipeline | The author of the pipeline. | +| Fixed pipeline | The author of the pipeline. Enabled by default. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1._ | | Merge merge request | | -| Merge when pipeline succeeds | Author, Participants, Watchers, Subscribers, and Custom notification level with this event selected. Custom notification level is ignored for Author, Watchers and Subscribers. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4 | -| Merge request [marked as ready](../project/merge_requests/drafts.md) | Watchers and participants. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15332) in GitLab 13.10 | -| New comment | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | +| Merge when pipeline succeeds | Author, Participants, Watchers, Subscribers, and Custom notification level with this event selected. Custom notification level is ignored for Author, Watchers and Subscribers. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4._ | +| Merge request [marked as ready](../project/merge_requests/drafts.md) | Watchers and participants. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15332) in GitLab 13.10._ | +| New comment | Participants, Watchers, Subscribers, and Custom notification level with this event selected. Also anyone mentioned by username in the comment, with notification level "Mention" or higher. | | New epic | | | New issue | | | New merge request | | -| Push to merge request | Participants and Custom notification level with this event selected | -| Reassign issue | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus the old assignee | -| Reassign merge request | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus the old assignee | -| Remove milestone issue | 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 | +| Push to merge request | Participants and Custom notification level with this event selected. | +| Reassign issue | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | +| Reassign merge request | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | +| Remove milestone issue | 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. | | Reopen epic | | | Reopen issue | | | Reopen merge request | | -| Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set. If the pipeline failed previously, a `Fixed pipeline` message is sent for the first successful pipeline after the failure, then a `Successful pipeline` message for any further successful pipelines. | +| Successful pipeline | The author of the pipeline, with Custom notification level for successful pipelines. If the pipeline failed previously, a "Fixed pipeline" message is sent for the first successful pipeline after the failure, and then a "Successful pipeline" message for any further successful pipelines. | If the title or description of an issue or merge request is -changed, notifications are sent to any **new** mentions by `@username` as +changed, notifications are sent to any **new** mentions by username as if they had been mentioned in the original text. -By default, you don't receive notifications for issues, merge requests, or epics created -by yourself. You only receive notifications when somebody else comments or adds changes to the ones -that you've created or mentions you, or when an issue is due soon. -To always receive notifications on your own issues and so on, you must turn on -[notifications about your own activity](#global-notification-settings). - If an open merge request becomes unmergeable due to conflict, its author is notified about the cause. If a user has also set the merge request to automatically merge when pipeline succeeds, then that user is also notified. +By default, you don't receive notifications for issues, merge requests, or epics created by yourself. +To always receive notifications on your own issues, merge requests, and so on, turn on +[notifications about your own activity](#global-notification-settings). + ## Notifications on designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217095) in GitLab 13.6. -Email notifications are sent to the participants when comments are made on a design. +Email notifications are sent to the participants when someone comments on a design. The participants are: @@ -288,7 +292,9 @@ The participants are: If you no longer wish to receive any email notifications: -1. [Go to the Notifications settings page.](#edit-notification-settings) +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. On the left sidebar, select **Notifications**. 1. Clear the **Receive product marketing emails** checkbox. 1. Set your **Global notification level** to **Disabled**. 1. Clear the **Receive notifications about your own activity** checkbox. @@ -299,40 +305,43 @@ On self-managed installations, even after doing this, your instance administrato [can still email you](../../tools/email.md). To unsubscribe, select the unsubscribe link in one of these emails. -## Filter email +## Email headers you can use to filter email + +Notification email messages include GitLab-specific headers. To better manage your notifications, +you can filter the notification emails based on the content of these headers. -Notification email messages include GitLab-specific headers. You can filter the notification emails based on the content of these headers to better manage your notifications. For example, you could filter all emails for a specific project where you are being assigned either a merge request or issue. +For example, you could filter all emails from a specific project where you are being assigned a +a merge request or an issue. The following table lists all GitLab-specific email headers: | Header | Description | |------------------------------------|-------------------------------------------------------------------------| +| `List-Id` | The path of the project in an RFC 2919 mailing list identifier. You can use it for email organization with filters. | +| `X-GitLab-(Resource)-ID` | The ID of the resource the notification is for. The resource, for example, can be `Issue`, `MergeRequest`, `Commit`, or another such resource. | +| `X-GitLab-Discussion-ID` | The ID of the thread the comment belongs to, in notification emails for comments. | | `X-GitLab-Group-Id` **(PREMIUM)** | The group's ID. Only present on notification emails for epics. | | `X-GitLab-Group-Path` **(PREMIUM)** | The group's path. Only present on notification emails for epics. | -| `X-GitLab-Project` | The name of the project the notification belongs to. | +| [`X-GitLab-NotificationReason`](#x-gitlab-notificationreason) | The reason for the notification. This can be `mentioned`, `assigned`, or `own_activity`. | +| `X-GitLab-Pipeline-Id` | The ID of the pipeline the notification is for, in notification emails for pipelines. | | `X-GitLab-Project-Id` | The project's ID. | | `X-GitLab-Project-Path` | The project's path. | -| `X-GitLab-(Resource)-ID` | The ID of the resource the notification is for. The resource, for example, can be `Issue`, `MergeRequest`, `Commit`, or another such resource. | -| `X-GitLab-Discussion-ID` | The ID of the thread the comment belongs to, in notification emails for comments. | -| `X-GitLab-Pipeline-Id` | The ID of the pipeline the notification is for, in notification emails for pipelines. | +| `X-GitLab-Project` | The name of the project the notification belongs to. | | `X-GitLab-Reply-Key` | A unique token to support reply by email. | -| `X-GitLab-NotificationReason` | The reason for the notification. This can be `mentioned`, `assigned`, or `own_activity`. | -| `List-Id` | The path of the project in an RFC 2919 mailing list identifier. This is useful for email organization with filters, for example. | ### X-GitLab-NotificationReason -The `X-GitLab-NotificationReason` header contains the reason for the notification. The value is one of the following, in order of priority: +The `X-GitLab-NotificationReason` header contains the reason for the notification. +The value is one of the following, in order of priority: - `own_activity` - `assigned` - `mentioned` -The reason for the notification is also included in the footer of the notification email. For example an email with the -reason `assigned` has this sentence in the footer: +The reason for the notification is also included in the footer of the notification email. +For example, an email with the reason `assigned` has this sentence in the footer: -- `You are receiving this email because you have been assigned an item on <configured GitLab hostname>.` - -Notification of other events is being considered for inclusion in the `X-GitLab-NotificationReason` header. For details, see this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/20689). +> You are receiving this email because you have been assigned an item on \<configured GitLab hostname>. For example, an alert notification email can have one of [the alert's](../../operations/incident_management/alerts.md) statuses: @@ -341,3 +350,6 @@ For example, an alert notification email can have one of - `alert_acknowledged` - `alert_resolved` - `alert_ignored` + +Expanding the list of events included in the `X-GitLab-NotificationReason` header is tracked in +[issue 20689](https://gitlab.com/gitlab-org/gitlab/-/issues/20689). diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 64a375c6a1d..d54edc7e6d3 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -24,14 +24,16 @@ If you find that you have to add the same badges to several projects, you may wa To add a new badge to a project: -1. Navigate to your project's **Settings > General > Badges**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under "Badge image URL" the URL of the image that should be displayed. -1. Submit the badge by clicking the **Add badge** button. +1. Select **Add badge**. After adding a badge to a project, you can see it in the list below the form. -You can edit it by clicking on the pen icon next to it or to delete it by -clicking on the trash icon. +You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by +selecting **Delete** (**{remove}**). Badges associated with a group can only be edited or deleted on the [group level](#group-badges). @@ -42,13 +44,15 @@ A common project badge presents the GitLab CI pipeline status. To add this badge to a project: -1. Navigate to your project's **Settings > General > Badges**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Badges**. 1. Under **Name**, enter _Pipeline Status_. 1. Under **Link**, enter the following URL: `https://gitlab.com/%{project_path}/-/commits/%{default_branch}` 1. Under **Badge image URL**, enter the following URL: `https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg` -1. Submit the badge by clicking the **Add badge** button. +1. Select **Add badge**. ## Group badges @@ -60,14 +64,16 @@ project, consider adding them on the [project level](#project-badges) or use To add a new badge to a group: -1. Navigate to your group's **Settings > General > Badges**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Badges**. 1. Under "Link", enter the URL that the badges should point to and under "Badge image URL" the URL of the image that should be displayed. -1. Submit the badge by clicking the **Add badge** button. +1. Select **Add badge**. After adding a badge to a group, you can see it in the list below the form. -You can edit the badge by clicking on the pen icon next to it or to delete it -by clicking on the trash icon. +You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by +selecting **Delete** (**{remove}**). Badges directly associated with a project can be configured on the [project level](#project-badges). @@ -108,7 +114,8 @@ https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg To add a new badge to a group or project with a custom image: -1. Go to your group or project and select **Settings > General**. +1. On the top bar, select **Menu** and find your group or project. +1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. 1. Under **Name**, enter the name for the badge. 1. Under **Link**, enter the URL that the badge should point to. diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index b4723294438..6d1fb0f6755 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -90,7 +90,7 @@ canary deployment is promoted to production. Here's an example setup flow from scratch: 1. Prepare an [Auto DevOps-enabled](../../topics/autodevops/index.md) project. -1. Set up a [Kubernetes Cluster](../../user/project/clusters/index.md) in your project. +1. Set up a [Kubernetes Cluster](../../user/infrastructure/clusters/index.md) in your project. 1. Install [NGINX Ingress](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx) in your cluster. 1. Set up [the base domain](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) based on the Ingress Endpoint assigned above. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index f7dd24fcfad..0db0f14b633 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,23 +4,37 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# EKS clusters (DEPRECATED) **(FREE)** +# Connect EKS clusters through cluster certificates **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. WARNING: -Use [Infrastructure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. +Use [Infrastrucure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +to create new clusters. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic Kubernetes Service (EKS). -## Add an existing EKS cluster +## Connect an existing EKS cluster -If you already have an EKS cluster and want to integrate it with GitLab, -see how to [add an existing cluster](add_existing_cluster.md). +If you already have an EKS cluster and want to connect it to GitLab, +use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). -## Create a new certificate-based EKS cluster +Alternatively, you can [connect them with cluster certificates](add_existing_cluster.md), +although this method is not recommended for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). + +## Create a new EKS cluster + +To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). + +Alternatively, you can [create new EKS clusters using cluster certificates](#how-to-create-a-new-cluster-on-eks-through-cluster-certificates-deprecated). +Although still available on the GitLab UI, this method was deprecated +in GitLab 14.0 and is scheduled for removal in GitLab 15.0. +It also has [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). + +### How to create a new cluster on EKS through cluster certificates (DEPRECATED) + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. Prerequisites: @@ -41,9 +55,10 @@ Further steps: 1. [Create a default Storage Class](#create-a-default-storage-class). 1. [Deploy the app to EKS](#deploy-the-app-to-eks). -### Create a new EKS cluster in GitLab +#### Create a new EKS cluster in GitLab -To create a new EKS cluster: +To create new a EKS cluster for your project, group, or instance, through +cluster certificates: 1. Go to your: - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 505c493de4e..3347ef9a437 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -188,7 +188,7 @@ To add a Kubernetes cluster to your project, group, or instance: ``` 1. **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. + See the [Managed clusters section](gitlab_managed_clusters.md) for more information. 1. **Project namespace** (optional) - You don't have to fill this in. By leaving it blank, GitLab creates one for you. Also: - Each project should have a unique namespace. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 78d4bce737d..0d35e89a560 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,48 +4,55 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GKE clusters (DEPRECATED) **(FREE)** - -> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. +# Connect GKE clusters through cluster certificates **(FREE)** WARNING: -Use [Infrastructure as Code](../../infrastructure/index.md) to create new clusters. The method described in this document is deprecated as of GitLab 14.0. +Use [Infrastrucure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md) +to create a cluster hosted on Google Kubernetes Engine (GKE). -Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic -Kubernetes Service (EKS). +Through GitLab, you can create new and connect existing clusters +hosted on Google Kubernetes Engine (GKE). -GitLab supports adding new and existing GKE clusters. +## Connect an existing GKE cluster -## GKE requirements +If you already have a GKE cluster and want to connect it to GitLab, +use the [GitLab Kubernetes Agent](../../clusters/agent/index.md). -Before creating your first cluster on Google GKE with GitLab integration, make sure the following -requirements are met: +Alternatively, you can [connect them with cluster certificates](add_existing_cluster.md), +altough this method is not recommended for [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). -- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) - set up with access. -- 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). +## Create a new GKE cluster from GitLab + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25925) in GitLab 12.4, all the GKE clusters provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). + +To create a new GKE cluster from GitLab, use [Infrastructure as Code](../../infrastructure/clusters/connect/new_gke_cluster.md). -## Add an existing GKE cluster +Alternatively, you can [create new GKE clusters using cluster certificates](#create-a-new-cluster-on-gke-through-cluster-certificates-deprecated). +Although still available in the GitLab UI, this method was deprecated +in GitLab 14.0 and is scheduled for removal in GitLab 15.0. +It also has [security implications](../../infrastructure/clusters/connect/index.md#security-implications-for-clusters-connected-with-certificates). -If you already have a GKE cluster and want to integrate it with GitLab, -see how to [add an existing cluster](add_existing_cluster.md). +## Create a new cluster on GKE through cluster certificates (DEPRECATED) -## Create new GKE cluster +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. -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). +Prerequisites: + +- A [Google Cloud billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) + set up with access. +- Kubernetes Engine API and related services 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). Note the following: - 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. -- Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55902), all GKE clusters +- In [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55902) and later, all GKE clusters created by GitLab are RBAC-enabled. Take a look at the [RBAC section](cluster_access.md#rbac-cluster-resources) for more information. -- Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341), the +- In [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341) and later, the cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to @@ -54,9 +61,8 @@ Note the following: explicitly requests GKE to create clusters with basic authentication enabled and a client certificate. -### Creating the cluster on GKE - -To create and add a new Kubernetes cluster to your project, group, or instance: +To create new Kubernetes clusters to your project, group, or instance, through +cluster certificates: 1. Navigate to your: - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 7bf202f6963..452f5727620 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -32,7 +32,7 @@ The resources created by GitLab differ depending on the type of cluster. Note the following about access controls: - Environment-specific resources are only created if your cluster is - [managed by GitLab](index.md#gitlab-managed-clusters). + [managed by GitLab](gitlab_managed_clusters.md). - If your cluster was created before GitLab 12.2, it uses a single namespace for all project environments. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 791dc90cad5..ac59f874244 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -4,77 +4,22 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Kubernetes clusters **(FREE)** +# Project-level Kubernetes clusters **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1 for projects. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in -> GitLab 11.6 for [groups](../../group/clusters/index.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in -> GitLab 11.11 for [instances](../../instance/clusters/index.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. -We offer extensive integrations to help you connect and manage your Kubernetes clusters from GitLab. +[Project-level Kubernetes clusters](../../infrastructure/clusters/connect/index.md#cluster-levels) +allow you to connect a Kubernetes cluster to a project in GitLab. -Read through this document to get started. +You can also [connect multiple clusters](multiple_kubernetes_clusters.md) +to a single project. -## Benefit from the GitLab-Kubernetes integration +After connecting a cluster to GitLab, you can benefit from the large number of +[GitLab features available for Kubernetes clusters](../../infrastructure/clusters/index.md) to manage and deploy to your cluster. -Using the GitLab-Kubernetes integration, you can benefit of GitLab -features such as: +## View your project-level clusters -- Create [CI/CD Pipelines](../../../ci/pipelines/index.md) to build, test, and deploy to your cluster. -- Use [Auto DevOps](#auto-devops) to automate the CI/CD process. -- Use [role-based or attribute-based access controls](cluster_access.md). -- Run serverless workloads on [Kubernetes with Knative](serverless/index.md). -- Connect GitLab to in-cluster applications using [cluster integrations](../../clusters/integrations.md). -- Use [deploy boards](../deploy_boards.md) to see the health and status of each CI [environment](../../../ci/environments/index.md) running on your Kubernetes cluster. -- Use [Canary deployments](../canary_deployments.md) to update only a portion of your fleet with the latest version of your application. -- View your [Kubernetes podlogs](kubernetes_pod_logs.md) directly in GitLab. -- Connect to your cluster through GitLab [web terminals](deploy_to_cluster.md#web-terminals-for-kubernetes-clusters). +To view project-level Kubernetes clusters: -## Supported cluster versions - -See the [Kubernetes clusters versions supported by GitLab](../../infrastructure/clusters/connect/index.md#supported-cluster-versions). - -## Connect your cluster to GitLab - -Learn how to [create new and connect existing clusters to GitLab](../../infrastructure/clusters/connect/index.md). - -## Cluster integrations - -See the available [cluster integrations](../../clusters/integrations.md) -to integrate third-party applications with your clusters through GitLab. - -## Cluster management project - -Attach a [Cluster management project](../../clusters/management_project.md) -to your cluster to manage shared resources requiring `cluster-admin` privileges for -installation, such as an Ingress controller. - -## GitLab-managed clusters - -See how to allow [GitLab to manage your cluster for you](gitlab_managed_clusters.md). - -## Auto DevOps - -You can use [Auto DevOps](../../../topics/autodevops/index.md) to automatically -detect, build, test, deploy, and monitor your applications. - -## Deploying to a Kubernetes cluster - -See how to [deploy to your Kubernetes cluster](deploy_to_cluster.md) from GitLab. - -## Monitoring your Kubernetes cluster - -Automatically detect and monitor Kubernetes metrics. Automatic monitoring of -[NGINX Ingress](../integrations/prometheus_library/nginx.md) is also supported. - -[Read more about Kubernetes monitoring](../integrations/prometheus_library/kubernetes.md) - -### Visualizing cluster health - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Free in 13.2. - -When [the Prometheus cluster integration is enabled](../../clusters/integrations.md#prometheus-cluster-integration), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. - - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 1940cf229b8..283e6c0b81c 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -57,7 +57,7 @@ to install Cilium in your Kubernetes cluster. ``` 1. Merge or push these changes to the default branch of your cluster management project, -and [GitLab CI/CD](../../../../../ci/README.md) will automatically install Cilium. +and [GitLab CI/CD](../../../../../ci/index.md) will automatically install Cilium. WARNING: Installation and removal of the Cilium requires a **manual** diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 7357fc850e5..9d623518f72 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -63,8 +63,9 @@ information. Follow this step-by-step guide to configure an executable runbook in GitLab using the components outlined above and the pre-loaded demo runbook. -1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-an-oauth-20-authentication-service-provider). -1. When [installing JupyterHub with Helm](https://zero-to-jupyterhub.readthedocs.io/en/latest/jupyterhub/installation.html), use the following values +1. Create an [OAuth application for JupyterHub](../../../../integration/oauth_provider.md). +1. When [installing JupyterHub with Helm](https://zero-to-jupyterhub.readthedocs.io/en/latest/jupyterhub/installation.html), + use the following values: ```yaml #----------------------------------------------------------------------------- diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index fb32579f40e..f6598f8846b 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -282,7 +282,7 @@ Explanation of the fields used above: |-----------|-------------| | `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh middleware. | | `envs` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are the variable contents. You may replace this with your own variables. | -| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for **all** functions in the file. The secrets are expected in INI format. | +| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for **all** functions in the file. The secrets are expected in `INI` format. | ### `functions` @@ -296,7 +296,7 @@ subsequent lines contain the function attributes. | `runtime` (optional)| The runtime to be used to execute the function. This can be a runtime alias (see [Runtime aliases](#runtime-aliases)), or it can be a full URL to a custom runtime repository. When the runtime is not specified, we assume that `Dockerfile` is present in the function directory specified by `source`. | | `description` | A short description of the function. | | `envs` | Sets an environment variable for the specific function only. | -| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for the specific function only. The secrets are expected in INI format. | +| `secrets` | Includes the contents of the Kubernetes secret as environment variables accessible to be passed as part of function execution for the specific function only. The secrets are expected in `INI` format. | ### Deployment diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 05f026cca18..6e2635b89f0 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -90,7 +90,7 @@ To display the deploy boards for a specific [environment](../../ci/environments/ 1. [Configure GitLab Runner](../../ci/runners/index.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. -1. Configure the [Kubernetes integration](clusters/index.md) in your project for the +1. Configure the [Kubernetes integration](../infrastructure/clusters/index.md) in your project for the cluster. The Kubernetes namespace is of particular note as you need it for your deployment scripts (exposed by the `KUBE_NAMESPACE` deployment variable). 1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index e9a38f91677..61dccf1cb1b 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -10,9 +10,10 @@ type: howto, reference Deploy keys allow read-only or read-write access to your repositories by importing an SSH public key into your GitLab instance. -This is useful, for example, for cloning repositories to your Continuous -Integration (CI) server. By using deploy keys, you don't have to set up a -fake user account. +Deploy keys streamline interactions between your GitLab repository and another +machine. For example, setting up a deploy key allows secure cloning of your +repositories to a Continuous Integration (CI) server without setting up a fake +user account. There are two types of deploy keys: @@ -63,11 +64,12 @@ help you access a repository, but there are some notables differences between th - Deploy keys are shareable between projects that are not related or don't even belong to the same group. Deploy tokens belong to either a project or [a group](../deploy_tokens/index.md#group-deploy-token). -- A deploy key is an SSH key you need to generate yourself on your machine. A deploy - token is generated by your GitLab instance, and is provided to users only once - (at creation time). -- A deploy key is valid as long as it's registered and enabled. Deploy tokens can - be time-sensitive, as you can control their validity by setting an expiration date to them. +- A deploy key is an SSH key you generate on the **remote machine**. A deploy + token, on the other hand, is generated by your **GitLab instance**, and is + provided to users only once (at creation time). +- A deploy key is valid as long as it's registered and enabled. Deploy tokens + can be time-sensitive, as you can control their validity by setting an + expiration date to them. - You can't log in to a registry with deploy keys, or perform read / write operations on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token). - You need an SSH key pair to use deploy keys, but not deploy tokens. @@ -115,9 +117,9 @@ project, and if you then update the access level for this key from `read-only` t ### Public deploy keys -Public deploy keys allow `read-only` or `read-write` -access to any repository in your GitLab instance. This is useful for integrating -repositories to secure, shared services, such as CI/CD. +Public deploy keys allow `read-only` or `read-write` access to any repository in +your GitLab instance. This allows for the integration of your repositories to +secure, shared services, such as CI/CD. Instance administrators can add public deploy keys: @@ -125,32 +127,37 @@ Instance administrators can add public deploy keys: 1. On the left sidebar, select **Deploy Keys**. 1. Select **New deploy key**. - Make sure your new key has a meaningful title, as it is the primary way for project - maintainers and owners to identify the correct public deploy key to add. For example, - if the key gives access to a SaaS CI/CD instance, use the name of that service - in the key name if that is all the key is used for. +Make sure your new key has a meaningful title. This title is the primary +way for project maintainers and owners to identify the correct public deploy key +to add to a repository or project. For example, the key you set up might be +intended to give access to a SaaS CI/CD instance. In this case use the name of +that service in the key title if that is all the key is used for.  -After adding a key, it's available to any shared systems. Project maintainers -or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. +After adding a key, it's available to any shared system. Users with a maintainer role or +higher can [authorize a public deploy key](#project-deploy-keys) to start using +it with the project. NOTE: -The **Publicly accessible deploy keys** tab within Project's CI/CD settings only appears -if there is at least one Public deploy key configured. +The **Publicly accessible deploy keys** tab in a Project's CI/CD +settings only appears if there is at least one Public deploy key configured. -Public deploy keys can provide greater security compared to project deploy keys, as -the administrator of the target integrated system is the only one who needs to know the key value, -or configure it. +Public deploy keys can provide greater security compared to project deploy keys. +This is because the administrator of the target integrated system is the only +entity who needs to know or configure the key value. -When creating a Public deploy key, determine whether or not it can be defined for -very narrow usage, such as just a specific service, or if it needs to be defined for -broader usage, such as full `read-write` access for all services. +When creating a Public deploy key, consider what scope and permissions are +required for it across the entire GitLab instance. For very narrow usage, such +as a single specific service, a `read-only` deploy key tied to this service is +best. If the service entails broader usage across the instance, a +deploy key with full `read-write` access is more appropriate. WARNING: -Adding a public deploy key does not immediately expose any repository to it. Public -deploy keys enable access from other systems, but access is not given to any project -until a project maintainer chooses to make use of it. +Adding a public deploy key **does not** immediately expose any repository +to the remote machine. Access to a project is only given when a project +maintainer chooses to make use of a deploy key in the project's +configuration. ## How to disable deploy keys @@ -162,22 +169,29 @@ can remove or disable a deploy key for a project repository: 1. Select the **{remove}** or **{cancel}** button. NOTE: -If anything relies on the removed deploy key, it will stop working once removed. +Any service that relies on a deploy key stops working after that key is removed. -If the key is **publicly accessible**, it will be removed from the project, but still available under **Publicly accessible deploy keys**. +If the key is **publicly accessible**, it is removed from the project, but can +still be found under **Publicly accessible deploy keys**. -If the key is **privately accessible** and only in use by this project, it will deleted. +If the key is **privately accessible** and only in use by this project, it is +deleted entirely from GitLab on removal. -If the key is **privately accessible** and in use by other projects, it will be removed from the project, but still available under **Privately accessible deploy keys**. +If the key is **privately accessible** and also in use by other projects, it is +removed from the project, but still available under **Privately accessible +deploy keys**. ## Troubleshooting ### Deploy key cannot push to a protected branch -If the owner of this deploy key doesn't have access to a [protected -branch](../protected_branches.md), then this deploy key doesn't have access to -the branch either. In addition to this, choosing the **No one** value in -[the "Allowed to push" section](../protected_branches.md#configure-a-protected-branch) -means that no users **and** no services using deploy keys can push to that selected branch. +There are a few scenarios where a deploy key will fail to push to a [protected +branch](../protected_branches.md). -Refer to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) for more information. +- The owner associated to a deploy key does not have access to the protected branch. +- The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. +- **No one** is selected in [the "Allowed to push" section](../protected_branches.md#configure-a-protected-branch) of the protected branch. + +All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. + +We recommend you create a service account, and associate a deploy key to the service account, for projects using deploy keys. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 1798aa0c1c6..483de3b21bd 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -2,12 +2,10 @@ stage: Release group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto --- # Deploy tokens -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) in GitLab 10.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** in GitLab 12.9. > - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** in GitLab 12.10.1. @@ -59,8 +57,8 @@ following table along with GitLab version it was introduced in: | Scope | Description | Introduced in GitLab Version | |--------------------------|-------------|------------------------------| -| `read_repository` | Allows read-access to the repository through `git clone` | 10.7 | -| `read_registry` | Allows read-access to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | 10.7 | +| `read_repository` | Allows read-access to the repository through `git clone` | -- | +| `read_registry` | Allows read-access to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | -- | | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | 12.10 | | `read_package_registry` | Allows read access to the package registry. | 13.0 | | `write_package_registry` | Allows write access to the package registry. | 13.0 | @@ -185,8 +183,6 @@ To pull images from the Dependency Proxy, you must: ### GitLab deploy token -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18414) in GitLab 10.8. - There's a special case when it comes to deploy tokens. If a user creates one named `gitlab-deploy-token`, the username and token of the deploy token is automatically exposed to the CI/CD jobs as CI/CD variables: `CI_DEPLOY_USER` @@ -203,3 +199,18 @@ NOTE: The special handling for the `gitlab-deploy-token` deploy token is not implemented for group deploy tokens. To make the group-level deploy token available for CI/CD jobs, the `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD` variables should be set under **Settings** to the name and token of the group deploy token respectively. + +## Troubleshooting + +### Group deploy tokens and LFS + +A bug +[prevents Group Deploy Tokens from cloning LFS objects](https://gitlab.com/gitlab-org/gitlab/-/issues/235398). +If you receive `404 Not Found` errors and this error, +use a Project Deploy Token to work around the bug: + +```plaintext +api error: Repository or object not found: +https://<URL-with-token>.git/info/lfs/objects/batch +Check that it exists and that you have proper access to it +``` diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 5ffde38b348..db8c6f24063 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -49,7 +49,7 @@ This process allows you to lock single files or file extensions and it is done through the command line. It doesn't require GitLab paid subscriptions. Git LFS is well known for tracking files to reduce the storage of -Git repositories, but it can also be user for [locking files](https://github.com/git-lfs/git-lfs/wiki/File-Locking). +Git repositories, but it can also be used for [locking files](https://github.com/git-lfs/git-lfs/wiki/File-Locking). This is the method used for Exclusive File Locks. ### Install Git LFS diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 7ccdb632c19..2715804b37a 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -126,6 +126,6 @@ Feature.disable(:bitbucket_server_user_mapping_by_username) If the GUI-based import tool does not work, you can try to: - Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) Bitbucket server endpoint. -- Set up [Repository Mirroring](../repository/repository_mirroring.md), which provides verbose error output. +- Set up [Repository Mirroring](../repository/mirror/index.md), which provides verbose error output. See the [troubleshooting](bitbucket.md#troubleshooting) section for [Bitbucket](bitbucket.md). diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 9364ac4f954..3bbc70b4337 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Manage group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -10,30 +9,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import your projects from Gitea to GitLab with minimal effort. NOTE: -This requires Gitea `v1.0.0` or newer. +This requires Gitea `v1.0.0` or later. The Gitea importer can import: -- Repository description (GitLab 8.15+) -- Git repository data (GitLab 8.15+) -- Issues (GitLab 8.15+) -- Pull requests (GitLab 8.15+) -- Milestones (GitLab 8.15+) -- Labels (GitLab 8.15+) +- Repository description +- Git repository data +- Issues +- Pull requests +- Milestones +- Labels When importing, repository public access is retained. If a repository is private in Gitea, it's created as private in GitLab as well. ## How it works -Since Gitea is currently not an OAuth provider, author/assignee cannot be mapped -to users in your GitLab instance. This means that the project creator (most of -the times the current user that started the import process) is set as the author, -but a reference on the issue about the original Gitea author is kept. +Because Gitea isn't an OAuth provider, author/assignee can't be mapped to users +in your GitLab instance. This means the project creator (usually the user that +started the import process) is set as the author. A reference, however, is kept +on the issue about the original Gitea author. -The importer creates any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository is imported under the user's -namespace that started the import process. +The importer creates any new namespaces (groups) if they don't exist. If the +namespace is taken, the repository is imported under the user's namespace +that started the import process. ## Import your Gitea repositories @@ -41,7 +40,7 @@ The importer page is visible when you create a new project.  -Click the **Gitea** link and the import authorization process starts. +Select the **Gitea** link to start the import authorization process.  @@ -52,13 +51,13 @@ GitLab access your repositories: 1. Go to `https://your-gitea-instance/user/settings/applications` (replace `your-gitea-instance` with the host of your Gitea instance). -1. Click **Generate New Token**. +1. Select **Generate New Token**. 1. Enter a token description. -1. Click **Generate Token**. +1. Select **Generate Token**. 1. Copy the token hash. 1. Go back to GitLab and provide the token to the Gitea importer. -1. Hit the **List Your Gitea Repositories** button and wait while GitLab reads - your repositories' information. Once done, you are taken to the importer +1. Select **List Your Gitea Repositories** and wait while GitLab reads + your repositories' information. After it's done, GitLab displays the importer page to select the repositories to import. ### Select which repositories to import @@ -66,19 +65,19 @@ GitLab access your repositories: After you've authorized access to your Gitea repositories, you are redirected to the Gitea importer page. -From there, you can see the import statuses of your Gitea repositories. +From there, you can view the import statuses of your Gitea repositories: -- Those that are being imported show a _started_ status, -- those already successfully imported are green with a _done_ status, -- whereas those that are not yet imported have an **Import** button on the +- Those that are being imported show a _started_ status. +- Those already successfully imported are green with a _done_ status. +- Those that aren't yet imported have an **Import** button on the right side of the table. You also can: -- Import all your Gitea projects in one go by hitting **Import all projects** in - the upper left corner. -- Filter projects by name. If filter is applied, hitting **Import all projects** - only imports matched projects. +- Import all of your Gitea projects in one go by selecting **Import all projects** + in the upper left corner. +- Filter projects by name. If filter is applied, selecting **Import all projects** + imports only matched projects.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 4443ae902fb..eff733b0b3d 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -162,7 +162,7 @@ your GitHub repositories are listed. ## Mirror a repository and share pipeline status -Depending on your GitLab tier, [repository mirroring](../repository/repository_mirroring.md) can be set up to keep +Depending on your GitLab tier, [repository mirroring](../repository/mirror/index.md) can be set up to keep your imported repository 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/import/index.md b/doc/user/project/import/index.md index 65e1eafa477..887eb546148 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -47,7 +47,7 @@ information, see [the import notes](../settings/import_export.md#important-notes NOTE: When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md) will be used. Creating users with the API is limited to self-managed instances as it requires -administrator access. +the Administrator role. To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). Migrate the assets in this order: diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 8c81af418a0..f3173736e9b 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Workspace info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -31,7 +31,7 @@ Projects include the following [features](https://about.gitlab.com/features/): from changing history or pushing code without review. - [Protected tags](protected_tags.md): Control who has permission to create tags and prevent accidental updates or deletions. - - [Repository mirroring](repository/repository_mirroring.md) + - [Repository mirroring](repository/mirror/index.md) - [Signing commits](repository/gpg_signed_commits/index.md): Use GNU Privacy Guard (GPG) to sign your commits. - [Deploy tokens](deploy_tokens/index.md): Manage access to the repository and Container Registry. - [Web IDE](web_ide/index.md) @@ -81,7 +81,7 @@ Projects include the following [features](https://about.gitlab.com/features/): browse, and download job artifacts. - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (how jobs fetch your repository), timeout (the maximum amount of time a job can run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline visibility, and more. - - [Kubernetes cluster integration](clusters/index.md): Connect your GitLab project + - [Kubernetes cluster integration](../infrastructure/clusters/index.md): Connect your GitLab project with a Kubernetes cluster. - [Feature Flags](../../operations/feature_flags.md): Ship different features by dynamically toggling functionality. **(PREMIUM)** diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index e1e926da19b..963fca34827 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Asana service **(FREE)** +# Asana integration **(FREE)** -This service adds commit messages as comments to Asana tasks. +This integration adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with `#` (for example, `#987654`). Every task ID found gets the commit comment added to it. @@ -23,7 +23,7 @@ You can use either of these words: - `closed` - `closing` -See also the [Asana service API documentation](../../../api/services.md#asana). +See also the [Asana integration API documentation](../../../api/integrations.md#asana). ## Setup diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 4908d21e764..3177aaefb75 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -18,7 +18,7 @@ and is automatically configured on [GitHub import](../../../integration/github.m ## Configuration -This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) +This integration requires a [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo:status` access granted. Complete these steps on GitHub: diff --git a/doc/user/project/integrations/img/slack_setup.png b/doc/user/project/integrations/img/slack_setup.png Binary files differindex 8acae659fb4..d8aedf84be5 100644 --- a/doc/user/project/integrations/img/slack_setup.png +++ b/doc/user/project/integrations/img/slack_setup.png diff --git a/doc/user/project/integrations/img/unify_circuit_configuration.png b/doc/user/project/integrations/img/unify_circuit_configuration.png Binary files differdeleted file mode 100644 index adba065347f..00000000000 --- a/doc/user/project/integrations/img/unify_circuit_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/webhook_logs.png b/doc/user/project/integrations/img/webhook_logs.png Binary files differindex 24bb593c7d0..05d068fd119 100644 --- a/doc/user/project/integrations/img/webhook_logs.png +++ b/doc/user/project/integrations/img/webhook_logs.png diff --git a/doc/user/project/integrations/img/webhook_testing.png b/doc/user/project/integrations/img/webhook_testing.png Binary files differindex acfebf473b9..27836556acc 100644 --- a/doc/user/project/integrations/img/webhook_testing.png +++ b/doc/user/project/integrations/img/webhook_testing.png diff --git a/doc/user/project/integrations/img/zentao_product_id.png b/doc/user/project/integrations/img/zentao_product_id.png Binary files differdeleted file mode 100644 index a91b4c3f82d..00000000000 --- a/doc/user/project/integrations/img/zentao_product_id.png +++ /dev/null diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 8027cc1c61e..1ff558b569b 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -16,7 +16,7 @@ separately configured [Mattermost Notifications Service](mattermost.md). ## Prerequisites -Mattermost [3.4 or later](https://mattermost.com/blog/category/releases/) is required. +Mattermost [3.4 or later](https://mattermost.com/blog/category/platform/releases/) is required. GitLab provides different methods of configuring Mattermost slash commands, depending on your configuration: diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index a6f739c6408..2c154467115 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -32,7 +32,7 @@ Click on the service links to see further configuration instructions and details | [Bugzilla](bugzilla.md) | Use Bugzilla as the issue tracker. | **{dotted-circle}** No | | Buildkite | Run CI/CD pipelines with Buildkite. | **{check-circle}** Yes | | Campfire | Connect to chat. | **{dotted-circle}** No | -| [Confluence Workspace](../../../api/services.md#confluence-service) | Replace the link to the internal wiki with a link to a Confluence Cloud Workspace. | **{dotted-circle}** No | +| [Confluence Workspace](../../../api/integrations.md#confluence-integration) | Replace the link to the internal wiki with a link to a Confluence Cloud Workspace. | **{dotted-circle}** No | | [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No | | [Datadog](../../../integration/datadog.md) | Trace your GitLab pipelines with Datadog. | **{check-circle}** Yes | | [Discord Notifications](discord_notifications.md) | Send notifications about project events to a Discord channel. | **{dotted-circle}** No | @@ -40,7 +40,7 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Send commits and diff of each push by email. | **{dotted-circle}** No | | [EWM](ewm.md) | Use IBM Engineering Workflow Management as the issue tracker. | **{dotted-circle}** No | | [External wiki](../wiki/index.md#link-an-external-wiki) | Link an external wiki. | **{dotted-circle}** No | -| [Flowdock](../../../api/services.md#flowdock) | Send notifications from GitLab to Flowdock flows. | **{dotted-circle}** No | +| [Flowdock](../../../api/integrations.md#flowdock) | Send notifications from GitLab to Flowdock flows. | **{dotted-circle}** No | | [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | | [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat.| **{dotted-circle}** No | | [irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | @@ -59,10 +59,9 @@ Click on the service links to see further configuration instructions and details | [Slack application](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | | [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in workspace. | **{dotted-circle}** No | -| [Unify Circuit](unify_circuit.md) | Receive events notifications. | **{dotted-circle}** No | +| [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | -| [ZenTao](zentao.md) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | ## Push hooks limit @@ -84,22 +83,7 @@ Read more about [Project integration management](../../admin_area/settings/proje ## Troubleshooting integrations -Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. GitLab stores details of service hook requests made within the last 2 days. To view details of the requests, go to that integration's configuration page. - -The **Recent Deliveries** section lists the details of each request made within the last 2 days: - -- HTTP status code (green for 200-299 codes, red for the others, `internal error` for failed deliveries) -- Triggered event -- URL to which the request was sent -- Elapsed time of the request -- Relative time in which the request was made - -To view more information about the request's execution, click the respective **View details** link. -On the details page, you can see the request headers and body sent and received by GitLab. - -To repeat a delivery using the same data, click **Resend Request**. - - +Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. Learn more about [troubleshooting service hooks](webhooks.md#troubleshoot-webhooks). ### Uninitialized repositories diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index d464007dd5e..93a3490e4b6 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -29,7 +29,7 @@ Read more about the [Source Commits endpoint](https://www.pivotaltracker.com/help/api/rest/v5#Source_Commits) in the Pivotal Tracker API documentation. -See also the [Pivotal Tracker service API documentation](../../../api/services.md#pivotal-tracker). +See also the [Pivotal Tracker integration API documentation](../../../api/integrations.md#pivotal-tracker). ## Set up Pivotal Tracker diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index acae0793e19..680f787c83c 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -75,7 +75,7 @@ service account can be found at Google's documentation for 1. (Optional) In **Google IAP Service Account JSON**, provide the contents of the Service Account credentials file that is authorized to access the Prometheus resource. The JSON key `token_credential_uri` is discarded to prevent - [Server-side Request Forgery (SSRF)](https://www.hackerone.com/blog-How-To-Server-Side-Request-Forgery-SSRF). + [Server-side Request Forgery (SSRF)](https://www.hackerone.com/application-security/how-server-side-request-forgery-ssrf). 1. Click **Save changes**.  diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index ea0119f2e94..429df7f7e27 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -12,7 +12,7 @@ GitLab has support for automatically detecting and monitoring Kubernetes metrics ## Requirements -The [Prometheus](../prometheus.md) and [Kubernetes](../../clusters/index.md) +The [Prometheus](../prometheus.md) and [Kubernetes](../../../infrastructure/clusters/index.md) integration services must be enabled. ## Metrics supported diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index d1fe58390fe..6478011b730 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -38,6 +38,8 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. +To isolate and display only relevant metrics for a given environment, GitLab needs a method to +detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. +In this case, the `ingress` label must include the value `<CI_ENVIRONMENT_SLUG>`. If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 066a2f83753..cddb72a83b2 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Slack slash commands **(FREE SELF)** -> Introduced in GitLab 8.15. - If you want to control and view GitLab content while you're working in Slack, you can use Slack slash commands. To use Slack slash commands, you must configure both Slack and GitLab. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 2e166e87ff5..814c64d8140 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -6,29 +6,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Unify Circuit service **(FREE)** -The Unify Circuit service sends notifications from GitLab to the conversation for which the webhook was created. +The Unify Circuit service sends notifications from GitLab to a Circuit conversation. -## On Unify Circuit +## Set up Unify Circuit service -1. Open the conversation in which you want to see the notifications. -1. From the conversation menu, select **Configure Webhooks**. -1. Click **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally - define an avatar. -1. Click **SAVE** and copy the **Webhook URL** of your webhook. +In Unify Circuit, [add a webhook](https://www.circuit.com/unifyportalfaqdetail?articleId=164448) and +copy its URL. -For more information, see the [Unify Circuit documentation for configuring incoming webhooks](https://www.circuit.com/unifyportalfaqdetail?articleId=164448). +In GitLab: -## On GitLab - -When you have the **Webhook URL** for your Unify Circuit conversation webhook, you can set up the GitLab service. - -1. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings, i.e. **Project > Settings > Integrations**. -1. Select the **Unify Circuit** integration to configure it. -1. Ensure that the **Active** toggle is enabled. -1. Check the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. +1. Go to the [Integrations page](overview.md#accessing-integrations) in your project's settings. +1. Select **Unify Circuit**. +1. Turn on the **Active** toggle. +1. Select the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. -1. Configure the remaining options and click `Save changes`. - -Your Unify Circuit conversation now starts receiving GitLab event notifications as configured. +1. Select the **Notify only broken pipelines** checkbox to notify only on failures. +1. In the **Branches to be notified** dropdown, select which types of branches to send notifications for. +1. Select `Save changes` or optionally select **Test settings**. - +Your Unify Circuit conversation now starts receiving GitLab event notifications. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md new file mode 100644 index 00000000000..9b07e6322bc --- /dev/null +++ b/doc/user/project/integrations/webhook_events.md @@ -0,0 +1,1669 @@ +--- +stage: Ecosystem +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Webhook events **(FREE)** + +You can configure a [webhook](webhooks.md) in your project that triggers when +an event occurs. The following events are supported. + +## Push events + +Triggered when you push to the repository except when pushing tags. + +NOTE: +When more than 20 commits are pushed at once, the `commits` webhook +attribute only contains the newest 20 for performance reasons. Loading +detailed commit data is expensive. Note that despite only 20 commits being +present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. + +NOTE: +If a branch creation push event is generated without new commits being introduced, the +`commits` attribute in the payload is empty. + +Also, if a single push includes changes for more than three (by default, depending on +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +branches, this hook isn't executed. + +**Request header**: + +```plaintext +X-Gitlab-Event: Push Hook +``` + +**Payload example:** + +```json +{ + "object_kind": "push", + "event_name": "push", + "before": "95790bf891e76fee5e1747ab589903a6a1f80f22", + "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "ref": "refs/heads/master", + "checkout_sha": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "user_id": 4, + "user_name": "John Smith", + "user_username": "jsmith", + "user_email": "john@example.com", + "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80", + "project_id": 15, + "project":{ + "id": 15, + "name":"Diaspora", + "description":"", + "web_url":"http://example.com/mike/diaspora", + "avatar_url":null, + "git_ssh_url":"git@example.com:mike/diaspora.git", + "git_http_url":"http://example.com/mike/diaspora.git", + "namespace":"Mike", + "visibility_level":0, + "path_with_namespace":"mike/diaspora", + "default_branch":"master", + "homepage":"http://example.com/mike/diaspora", + "url":"git@example.com:mike/diaspora.git", + "ssh_url":"git@example.com:mike/diaspora.git", + "http_url":"http://example.com/mike/diaspora.git" + }, + "repository":{ + "name": "Diaspora", + "url": "git@example.com:mike/diaspora.git", + "description": "", + "homepage": "http://example.com/mike/diaspora", + "git_http_url":"http://example.com/mike/diaspora.git", + "git_ssh_url":"git@example.com:mike/diaspora.git", + "visibility_level":0 + }, + "commits": [ + { + "id": "b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327", + "message": "Update Catalan translation to e38cb41.\n\nSee https://gitlab.com/gitlab-org/gitlab for more information", + "title": "Update Catalan translation to e38cb41.", + "timestamp": "2011-12-12T14:27:31+02:00", + "url": "http://example.com/mike/diaspora/commit/b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327", + "author": { + "name": "Jordi Mallach", + "email": "jordi@softcatala.org" + }, + "added": ["CHANGELOG"], + "modified": ["app/controller/application.rb"], + "removed": [] + }, + { + "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "message": "fixed readme", + "title": "fixed readme", + "timestamp": "2012-01-03T23:36:29+02:00", + "url": "http://example.com/mike/diaspora/commit/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "author": { + "name": "GitLab dev user", + "email": "gitlabdev@dv6700.(none)" + }, + "added": ["CHANGELOG"], + "modified": ["app/controller/application.rb"], + "removed": [] + } + ], + "total_commits_count": 4 +} +``` + +## Tag events + +Triggered when you create (or delete) tags to the repository. + +NOTE: +If a single push includes changes for more than three (by default, depending on +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +tags, this hook is not executed. + +**Request header**: + +```plaintext +X-Gitlab-Event: Tag Push Hook +``` + +**Payload example:** + +```json +{ + "object_kind": "tag_push", + "event_name": "tag_push", + "before": "0000000000000000000000000000000000000000", + "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", + "ref": "refs/tags/v1.0.0", + "checkout_sha": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", + "user_id": 1, + "user_name": "John Smith", + "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80", + "project_id": 1, + "project":{ + "id": 1, + "name":"Example", + "description":"", + "web_url":"http://example.com/jsmith/example", + "avatar_url":null, + "git_ssh_url":"git@example.com:jsmith/example.git", + "git_http_url":"http://example.com/jsmith/example.git", + "namespace":"Jsmith", + "visibility_level":0, + "path_with_namespace":"jsmith/example", + "default_branch":"master", + "homepage":"http://example.com/jsmith/example", + "url":"git@example.com:jsmith/example.git", + "ssh_url":"git@example.com:jsmith/example.git", + "http_url":"http://example.com/jsmith/example.git" + }, + "repository":{ + "name": "Example", + "url": "ssh://git@example.com/jsmith/example.git", + "description": "", + "homepage": "http://example.com/jsmith/example", + "git_http_url":"http://example.com/jsmith/example.git", + "git_ssh_url":"git@example.com:jsmith/example.git", + "visibility_level":0 + }, + "commits": [], + "total_commits_count": 0 +} +``` + +## Issue events + +Triggered when a new issue is created or an existing issue was updated/closed/reopened. + +**Request header**: + +```plaintext +X-Gitlab-Event: Issue Hook +``` + +**Available `object_attributes.action`:** + +- `open` +- `close` +- `reopen` +- `update` + +**Payload example:** + +```json +{ + "object_kind": "issue", + "event_type": "issue", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" + }, + "project": { + "id": 1, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlabhq/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", + "namespace":"GitlabHQ", + "visibility_level":20, + "path_with_namespace":"gitlabhq/gitlab-test", + "default_branch":"master", + "ci_config_path": null, + "homepage":"http://example.com/gitlabhq/gitlab-test", + "url":"http://example.com/gitlabhq/gitlab-test.git", + "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "http_url":"http://example.com/gitlabhq/gitlab-test.git" + }, + "object_attributes": { + "id": 301, + "title": "New API: create/update/delete file", + "assignee_ids": [51], + "assignee_id": 51, + "author_id": 51, + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "updated_by_id": 1, + "last_edited_at": null, + "last_edited_by_id": null, + "relative_position": 0, + "description": "Create new API for manipulations with repository", + "milestone_id": null, + "state_id": 1, + "confidential": false, + "discussion_locked": true, + "due_date": null, + "moved_to_id": null, + "duplicated_to_id": null, + "time_estimate": 0, + "total_time_spent": 0, + "time_change": 0, + "human_total_time_spent": null, + "human_time_estimate": null, + "human_time_change": null, + "weight": null, + "iid": 23, + "url": "http://example.com/diaspora/issues/23", + "state": "opened", + "action": "open", + "labels": [{ + "id": 206, + "title": "API", + "color": "#ffffff", + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "template": false, + "description": "API related issues", + "type": "ProjectLabel", + "group_id": 41 + }] + }, + "repository": { + "name": "Gitlab Test", + "url": "http://example.com/gitlabhq/gitlab-test.git", + "description": "Aut reprehenderit ut est.", + "homepage": "http://example.com/gitlabhq/gitlab-test" + }, + "assignees": [{ + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + }], + "assignee": { + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + }, + "labels": [{ + "id": 206, + "title": "API", + "color": "#ffffff", + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "template": false, + "description": "API related issues", + "type": "ProjectLabel", + "group_id": 41 + }], + "changes": { + "updated_by_id": { + "previous": null, + "current": 1 + }, + "updated_at": { + "previous": "2017-09-15 16:50:55 UTC", + "current": "2017-09-15 16:52:00 UTC" + }, + "labels": { + "previous": [{ + "id": 206, + "title": "API", + "color": "#ffffff", + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "template": false, + "description": "API related issues", + "type": "ProjectLabel", + "group_id": 41 + }], + "current": [{ + "id": 205, + "title": "Platform", + "color": "#123123", + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "template": false, + "description": "Platform related issues", + "type": "ProjectLabel", + "group_id": 41 + }] + } + } +} +``` + +NOTE: +`assignee` and `assignee_id` keys are deprecated and now show the first assignee only. + +## Comment events + +Triggered when a new comment is made on commits, merge requests, issues, and code snippets. +The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The +payload also includes information about the target of the comment. For example, +a comment on an issue includes the specific issue information under the `issue` key. +Valid target types: + +- `commit` +- `merge_request` +- `issue` +- `snippet` + +### Comment on commit + +**Request header**: + +```plaintext +X-Gitlab-Event: Note Hook +``` + +**Payload example:** + +```json +{ + "object_kind": "note", + "event_type": "note", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" + }, + "project_id": 5, + "project":{ + "id": 5, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlabhq/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", + "namespace":"GitlabHQ", + "visibility_level":20, + "path_with_namespace":"gitlabhq/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlabhq/gitlab-test", + "url":"http://example.com/gitlabhq/gitlab-test.git", + "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "http_url":"http://example.com/gitlabhq/gitlab-test.git" + }, + "repository":{ + "name": "Gitlab Test", + "url": "http://example.com/gitlab-org/gitlab-test.git", + "description": "Aut reprehenderit ut est.", + "homepage": "http://example.com/gitlab-org/gitlab-test" + }, + "object_attributes": { + "id": 1243, + "note": "This is a commit comment. How does this work?", + "noteable_type": "Commit", + "author_id": 1, + "created_at": "2015-05-17 18:08:09 UTC", + "updated_at": "2015-05-17 18:08:09 UTC", + "project_id": 5, + "attachment":null, + "line_code": "bec9703f7a456cd2b4ab5fb3220ae016e3e394e3_0_1", + "commit_id": "cfe32cf61b73a0d5e9f13e774abde7ff789b1660", + "noteable_id": null, + "system": false, + "st_diff": { + "diff": "--- /dev/null\n+++ b/six\n@@ -0,0 +1 @@\n+Subproject commit 409f37c4f05865e4fb208c771485f211a22c4c2d\n", + "new_path": "six", + "old_path": "six", + "a_mode": "0", + "b_mode": "160000", + "new_file": true, + "renamed_file": false, + "deleted_file": false + }, + "url": "http://example.com/gitlab-org/gitlab-test/commit/cfe32cf61b73a0d5e9f13e774abde7ff789b1660#note_1243" + }, + "commit": { + "id": "cfe32cf61b73a0d5e9f13e774abde7ff789b1660", + "message": "Add submodule\n\nSigned-off-by: Example User \u003cuser@example.com.com\u003e\n", + "timestamp": "2014-02-27T10:06:20+02:00", + "url": "http://example.com/gitlab-org/gitlab-test/commit/cfe32cf61b73a0d5e9f13e774abde7ff789b1660", + "author": { + "name": "Example User", + "email": "user@example.com" + } + } +} +``` + +### Comment on merge request + +**Request header**: + +```plaintext +X-Gitlab-Event: Note Hook +``` + +**Payload example:** + +```json +{ + "object_kind": "note", + "event_type": "note", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" + }, + "project_id": 5, + "project":{ + "id": 5, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" + }, + "repository":{ + "name": "Gitlab Test", + "url": "http://localhost/gitlab-org/gitlab-test.git", + "description": "Aut reprehenderit ut est.", + "homepage": "http://example.com/gitlab-org/gitlab-test" + }, + "object_attributes": { + "id": 1244, + "note": "This MR needs work.", + "noteable_type": "MergeRequest", + "author_id": 1, + "created_at": "2015-05-17 18:21:36 UTC", + "updated_at": "2015-05-17 18:21:36 UTC", + "project_id": 5, + "attachment": null, + "line_code": null, + "commit_id": "", + "noteable_id": 7, + "system": false, + "st_diff": null, + "url": "http://example.com/gitlab-org/gitlab-test/merge_requests/1#note_1244" + }, + "merge_request": { + "id": 7, + "target_branch": "markdown", + "source_branch": "master", + "source_project_id": 5, + "author_id": 8, + "assignee_id": 28, + "title": "Tempora et eos debitis quae laborum et.", + "created_at": "2015-03-01 20:12:53 UTC", + "updated_at": "2015-03-21 18:27:27 UTC", + "milestone_id": 11, + "state": "opened", + "merge_status": "cannot_be_merged", + "target_project_id": 5, + "iid": 1, + "description": "Et voluptas corrupti assumenda temporibus. Architecto cum animi eveniet amet asperiores. Vitae numquam voluptate est natus sit et ad id.", + "position": 0, + "source":{ + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" + }, + "target": { + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" + }, + "last_commit": { + "id": "562e173be03b8ff2efb05345d12df18815438a4b", + "message": "Merge branch 'another-branch' into 'master'\n\nCheck in this test\n", + "timestamp": "2015-04-08T21: 00:25-07:00", + "url": "http://example.com/gitlab-org/gitlab-test/commit/562e173be03b8ff2efb05345d12df18815438a4b", + "author": { + "name": "John Smith", + "email": "john@example.com" + } + }, + "work_in_progress": false, + "assignee": { + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + } + } +} +``` + +### Comment on issue + +**Request header**: + +```plaintext +X-Gitlab-Event: Note Hook +``` + +**Payload example:** + +```json +{ + "object_kind": "note", + "event_type": "note", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" + }, + "project_id": 5, + "project":{ + "id": 5, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" + }, + "repository":{ + "name":"diaspora", + "url":"git@example.com:mike/diaspora.git", + "description":"", + "homepage":"http://example.com/mike/diaspora" + }, + "object_attributes": { + "id": 1241, + "note": "Hello world", + "noteable_type": "Issue", + "author_id": 1, + "created_at": "2015-05-17 17:06:40 UTC", + "updated_at": "2015-05-17 17:06:40 UTC", + "project_id": 5, + "attachment": null, + "line_code": null, + "commit_id": "", + "noteable_id": 92, + "system": false, + "st_diff": null, + "url": "http://example.com/gitlab-org/gitlab-test/issues/17#note_1241" + }, + "issue": { + "id": 92, + "title": "test", + "assignee_ids": [], + "assignee_id": null, + "author_id": 1, + "project_id": 5, + "created_at": "2015-04-12 14:53:17 UTC", + "updated_at": "2015-04-26 08:28:42 UTC", + "position": 0, + "branch_name": null, + "description": "test", + "milestone_id": null, + "state": "closed", + "iid": 17, + "labels": [ + { + "id": 25, + "title": "Afterpod", + "color": "#3e8068", + "project_id": null, + "created_at": "2019-06-05T14:32:20.211Z", + "updated_at": "2019-06-05T14:32:20.211Z", + "template": false, + "description": null, + "type": "GroupLabel", + "group_id": 4 + }, + { + "id": 86, + "title": "Element", + "color": "#231afe", + "project_id": 4, + "created_at": "2019-06-05T14:32:20.637Z", + "updated_at": "2019-06-05T14:32:20.637Z", + "template": false, + "description": null, + "type": "ProjectLabel", + "group_id": null + } + ] + } +} +``` + +NOTE: +`assignee_id` field is deprecated and now shows the first assignee only. + +NOTE: +`event_type` is set to `confidential_note` for confidential issues. + +### Comment on code snippet + +**Request header**: + +```plaintext +X-Gitlab-Event: Note Hook +``` + +**Payload example:** + +```json +{ + "object_kind": "note", + "event_type": "note", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" + }, + "project_id": 5, + "project":{ + "id": 5, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" + }, + "repository":{ + "name":"Gitlab Test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "description":"Aut reprehenderit ut est.", + "homepage":"http://example.com/gitlab-org/gitlab-test" + }, + "object_attributes": { + "id": 1245, + "note": "Is this snippet doing what it's supposed to be doing?", + "noteable_type": "Snippet", + "author_id": 1, + "created_at": "2015-05-17 18:35:50 UTC", + "updated_at": "2015-05-17 18:35:50 UTC", + "project_id": 5, + "attachment": null, + "line_code": null, + "commit_id": "", + "noteable_id": 53, + "system": false, + "st_diff": null, + "url": "http://example.com/gitlab-org/gitlab-test/snippets/53#note_1245" + }, + "snippet": { + "id": 53, + "title": "test", + "content": "puts 'Hello world'", + "author_id": 1, + "project_id": 5, + "created_at": "2015-04-09 02:40:38 UTC", + "updated_at": "2015-04-09 02:40:38 UTC", + "file_name": "test.rb", + "expires_at": null, + "type": "ProjectSnippet", + "visibility_level": 0 + } +} +``` + +## Merge request events + +Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch. + +**Request header**: + +```plaintext +X-Gitlab-Event: Merge Request Hook +``` + +**Available `object_attributes.action`:** + +- `open` +- `close` +- `reopen` +- `update` +- `approved` +- `unapproved` +- `merge` + +**Payload example:** + +```json +{ + "object_kind": "merge_request", + "event_type": "merge_request", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", + "email": "admin@example.com" + }, + "project": { + "id": 1, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlabhq/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", + "namespace":"GitlabHQ", + "visibility_level":20, + "path_with_namespace":"gitlabhq/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlabhq/gitlab-test", + "url":"http://example.com/gitlabhq/gitlab-test.git", + "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "http_url":"http://example.com/gitlabhq/gitlab-test.git" + }, + "repository": { + "name": "Gitlab Test", + "url": "http://example.com/gitlabhq/gitlab-test.git", + "description": "Aut reprehenderit ut est.", + "homepage": "http://example.com/gitlabhq/gitlab-test" + }, + "object_attributes": { + "id": 99, + "target_branch": "master", + "source_branch": "ms-viewport", + "source_project_id": 14, + "author_id": 51, + "assignee_id": 6, + "title": "MS-Viewport", + "created_at": "2013-12-03T17:23:34Z", + "updated_at": "2013-12-03T17:23:34Z", + "milestone_id": null, + "state": "opened", + "merge_status": "unchecked", + "target_project_id": 14, + "iid": 1, + "description": "", + "source": { + "name":"Awesome Project", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/awesome_space/awesome_project", + "avatar_url":null, + "git_ssh_url":"git@example.com:awesome_space/awesome_project.git", + "git_http_url":"http://example.com/awesome_space/awesome_project.git", + "namespace":"Awesome Space", + "visibility_level":20, + "path_with_namespace":"awesome_space/awesome_project", + "default_branch":"master", + "homepage":"http://example.com/awesome_space/awesome_project", + "url":"http://example.com/awesome_space/awesome_project.git", + "ssh_url":"git@example.com:awesome_space/awesome_project.git", + "http_url":"http://example.com/awesome_space/awesome_project.git" + }, + "target": { + "name":"Awesome Project", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/awesome_space/awesome_project", + "avatar_url":null, + "git_ssh_url":"git@example.com:awesome_space/awesome_project.git", + "git_http_url":"http://example.com/awesome_space/awesome_project.git", + "namespace":"Awesome Space", + "visibility_level":20, + "path_with_namespace":"awesome_space/awesome_project", + "default_branch":"master", + "homepage":"http://example.com/awesome_space/awesome_project", + "url":"http://example.com/awesome_space/awesome_project.git", + "ssh_url":"git@example.com:awesome_space/awesome_project.git", + "http_url":"http://example.com/awesome_space/awesome_project.git" + }, + "last_commit": { + "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "message": "fixed readme", + "timestamp": "2012-01-03T23:36:29+02:00", + "url": "http://example.com/awesome_space/awesome_project/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", + "author": { + "name": "GitLab dev user", + "email": "gitlabdev@dv6700.(none)" + } + }, + "work_in_progress": false, + "url": "http://example.com/diaspora/merge_requests/1", + "action": "open", + "assignee": { + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + } + }, + "labels": [{ + "id": 206, + "title": "API", + "color": "#ffffff", + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "template": false, + "description": "API related issues", + "type": "ProjectLabel", + "group_id": 41 + }], + "changes": { + "updated_by_id": { + "previous": null, + "current": 1 + }, + "updated_at": { + "previous": "2017-09-15 16:50:55 UTC", + "current":"2017-09-15 16:52:00 UTC" + }, + "labels": { + "previous": [{ + "id": 206, + "title": "API", + "color": "#ffffff", + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "template": false, + "description": "API related issues", + "type": "ProjectLabel", + "group_id": 41 + }], + "current": [{ + "id": 205, + "title": "Platform", + "color": "#123123", + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "template": false, + "description": "Platform related issues", + "type": "ProjectLabel", + "group_id": 41 + }] + } + } +} +``` + +## Wiki Page events + +Triggered when a wiki page is created, updated or deleted. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Wiki Page Hook +``` + +**Payload example**: + +```json +{ + "object_kind": "wiki_page", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "email": "admin@example.com" + }, + "project": { + "id": 1, + "name": "awesome-project", + "description": "This is awesome", + "web_url": "http://example.com/root/awesome-project", + "avatar_url": null, + "git_ssh_url": "git@example.com:root/awesome-project.git", + "git_http_url": "http://example.com/root/awesome-project.git", + "namespace": "root", + "visibility_level": 0, + "path_with_namespace": "root/awesome-project", + "default_branch": "master", + "homepage": "http://example.com/root/awesome-project", + "url": "git@example.com:root/awesome-project.git", + "ssh_url": "git@example.com:root/awesome-project.git", + "http_url": "http://example.com/root/awesome-project.git" + }, + "wiki": { + "web_url": "http://example.com/root/awesome-project/-/wikis/home", + "git_ssh_url": "git@example.com:root/awesome-project.wiki.git", + "git_http_url": "http://example.com/root/awesome-project.wiki.git", + "path_with_namespace": "root/awesome-project.wiki", + "default_branch": "master" + }, + "object_attributes": { + "title": "Awesome", + "content": "awesome content goes here", + "format": "markdown", + "message": "adding an awesome page to the wiki", + "slug": "awesome", + "url": "http://example.com/root/awesome-project/-/wikis/awesome", + "action": "create" + } +} +``` + +## Pipeline events + +In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) +and later, the pipeline webhook returns only the latest jobs. + +Triggered on status change of Pipeline. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Pipeline Hook +``` + +**Payload example**: + +```json +{ + "object_kind": "pipeline", + "object_attributes":{ + "id": 31, + "ref": "master", + "tag": false, + "sha": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", + "before_sha": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", + "source": "merge_request_event", + "status": "success", + "stages":[ + "build", + "test", + "deploy" + ], + "created_at": "2016-08-12 15:23:28 UTC", + "finished_at": "2016-08-12 15:26:29 UTC", + "duration": 63, + "variables": [ + { + "key": "NESTOR_PROD_ENVIRONMENT", + "value": "us-west-1" + } + ] + }, + "merge_request": { + "id": 1, + "iid": 1, + "title": "Test", + "source_branch": "test", + "source_project_id": 1, + "target_branch": "master", + "target_project_id": 1, + "state": "opened", + "merge_status": "can_be_merged", + "url": "http://192.168.64.1:3005/gitlab-org/gitlab-test/merge_requests/1" + }, + "user":{ + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "user_email@gitlab.com" + }, + "project":{ + "id": 1, + "name": "Gitlab Test", + "description": "Atque in sunt eos similique dolores voluptatem.", + "web_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test", + "avatar_url": null, + "git_ssh_url": "git@192.168.64.1:gitlab-org/gitlab-test.git", + "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", + "namespace": "Gitlab Org", + "visibility_level": 20, + "path_with_namespace": "gitlab-org/gitlab-test", + "default_branch": "master" + }, + "commit":{ + "id": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", + "message": "test\n", + "timestamp": "2016-08-12T17:23:21+02:00", + "url": "http://example.com/gitlab-org/gitlab-test/commit/bcbb5ec396a2c0f828686f14fac9b80b780504f2", + "author":{ + "name": "User", + "email": "user@gitlab.com" + } + }, + "builds":[ + { + "id": 380, + "stage": "deploy", + "name": "production", + "status": "skipped", + "created_at": "2016-08-12 15:23:28 UTC", + "started_at": null, + "finished_at": null, + "when": "manual", + "manual": true, + "allow_failure": false, + "user":{ + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" + }, + "runner": null, + "artifacts_file":{ + "filename": null, + "size": null + }, + "environment": { + "name": "production", + "action": "start", + "deployment_tier": "production" + } + }, + { + "id": 377, + "stage": "test", + "name": "test-image", + "status": "success", + "created_at": "2016-08-12 15:23:28 UTC", + "started_at": "2016-08-12 15:26:12 UTC", + "finished_at": null, + "when": "on_success", + "manual": false, + "allow_failure": false, + "user":{ + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" + }, + "runner": { + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "active": true, + "runner_type": "instance_type", + "is_shared": true, + "tags": [ + "linux", + "docker", + "shared-runner" + ] + }, + "artifacts_file":{ + "filename": null, + "size": null + }, + "environment": null + }, + { + "id": 378, + "stage": "test", + "name": "test-build", + "status": "success", + "created_at": "2016-08-12 15:23:28 UTC", + "started_at": "2016-08-12 15:26:12 UTC", + "finished_at": "2016-08-12 15:26:29 UTC", + "when": "on_success", + "manual": false, + "allow_failure": false, + "user":{ + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" + }, + "runner": { + "id":380987, + "description":"shared-runners-manager-6.gitlab.com", + "active":true, + "runner_type": "instance_type", + "is_shared": true, + "tags": [ + "linux", + "docker" + ] + }, + "artifacts_file":{ + "filename": null, + "size": null + }, + "environment": null + }, + { + "id": 376, + "stage": "build", + "name": "build-image", + "status": "success", + "created_at": "2016-08-12 15:23:28 UTC", + "started_at": "2016-08-12 15:24:56 UTC", + "finished_at": "2016-08-12 15:25:26 UTC", + "when": "on_success", + "manual": false, + "allow_failure": false, + "user":{ + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" + }, + "runner": { + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "active": true, + "runner_type": "instance_type", + "is_shared": true, + "tags": [ + "linux", + "docker" + ] + }, + "artifacts_file":{ + "filename": null, + "size": null + }, + "environment": null + }, + { + "id": 379, + "stage": "deploy", + "name": "staging", + "status": "created", + "created_at": "2016-08-12 15:23:28 UTC", + "started_at": null, + "finished_at": null, + "when": "on_success", + "manual": false, + "allow_failure": false, + "user":{ + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "email": "admin@example.com" + }, + "runner": null, + "artifacts_file":{ + "filename": null, + "size": null + }, + "environment": { + "name": "staging", + "action": "start", + "deployment_tier": "staging" + } + } + ] +} +``` + +## Job events + +Triggered on status change of a job. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Job Hook +``` + +**Payload example**: + +```json +{ + "object_kind": "build", + "ref": "gitlab-script-trigger", + "tag": false, + "before_sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", + "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", + "build_id": 1977, + "build_name": "test", + "build_stage": "test", + "build_status": "created", + "build_created_at": "2021-02-23T02:41:37.886Z", + "build_started_at": null, + "build_finished_at": null, + "build_duration": null, + "build_allow_failure": false, + "build_failure_reason": "script_failure", + "pipeline_id": 2366, + "project_id": 380, + "project_name": "gitlab-org/gitlab-test", + "user": { + "id": 3, + "name": "User", + "email": "user@gitlab.com", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + }, + "commit": { + "id": 2366, + "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", + "message": "test\n", + "author_name": "User", + "author_email": "user@gitlab.com", + "status": "created", + "duration": null, + "started_at": null, + "finished_at": null + }, + "repository": { + "name": "gitlab_test", + "description": "Atque in sunt eos similique dolores voluptatem.", + "homepage": "http://192.168.64.1:3005/gitlab-org/gitlab-test", + "git_ssh_url": "git@192.168.64.1:gitlab-org/gitlab-test.git", + "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", + "visibility_level": 20 + }, + "runner": { + "active": true, + "runner_type": "project_type", + "is_shared": false, + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "tags": [ + "linux", + "docker" + ] + }, + "environment": null +} +``` + +Note that `commit.id` is the ID of the pipeline, not the ID of the commit. + +## Deployment events + +Triggered when a deployment: + +- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.) +- Succeeds +- Fails +- Is cancelled + +**Request Header**: + +```plaintext +X-Gitlab-Event: Deployment Hook +``` + +**Payload example**: + +```json +{ + "object_kind": "deployment", + "status": "success", + "status_changed_at":"2021-04-28 21:50:00 +0200", + "deployment_id": 15, + "deployable_id": 796, + "deployable_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/jobs/796", + "environment": "staging", + "project": { + "id": 30, + "name": "test-deployment-webhooks", + "description": "", + "web_url": "http://10.126.0.2:3000/root/test-deployment-webhooks", + "avatar_url": null, + "git_ssh_url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", + "git_http_url": "http://10.126.0.2:3000/root/test-deployment-webhooks.git", + "namespace": "Administrator", + "visibility_level": 0, + "path_with_namespace": "root/test-deployment-webhooks", + "default_branch": "master", + "ci_config_path": "", + "homepage": "http://10.126.0.2:3000/root/test-deployment-webhooks", + "url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", + "ssh_url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", + "http_url": "http://10.126.0.2:3000/root/test-deployment-webhooks.git" + }, + "short_sha": "279484c0", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "email": "admin@example.com" + }, + "user_url": "http://10.126.0.2:3000/root", + "commit_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/commit/279484c09fbe69ededfced8c1bb6e6d24616b468", + "commit_title": "Add new file" +} +``` + +Note that `deployable_id` is the ID of the CI job. + +## Group member events **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. + +Member events are triggered when: + +- A user is added as a group member +- The access level of a user has changed +- The expiration date for user access has been updated +- A user has been removed from the group + +### Add member to group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Payload example**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-11T04:57:22Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Guest", + "group_plan": null, + "expires_at": "2020-12-14T00:00:00Z", + "event_name": "user_add_to_group" +} +``` + +### Update member access level or expiration date + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Payload example**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-12T08:48:19Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Developer", + "group_plan": null, + "expires_at": "2020-12-20T00:00:00Z", + "event_name": "user_update_for_group" +} +``` + +### Remove member from group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Payload example**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-12T08:52:34Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Guest", + "group_plan": null, + "expires_at": "2020-12-14T00:00:00Z", + "event_name": "user_remove_from_group" +} +``` + +## Subgroup events **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260419) in GitLab 13.9. + +Subgroup events are triggered when: + +- A [subgroup is created in a group](#subgroup-created-in-a-group) +- A [subgroup is removed from a group](#subgroup-removed-from-a-group) + +### Subgroup created in a group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Subgroup Hook +``` + +**Payload example**: + +```json +{ + + "created_at": "2021-01-20T09:40:12Z", + "updated_at": "2021-01-20T09:40:12Z", + "event_name": "subgroup_create", + "name": "subgroup1", + "path": "subgroup1", + "full_path": "group1/subgroup1", + "group_id": 10, + "parent_group_id": 7, + "parent_name": "group1", + "parent_path": "group1", + "parent_full_path": "group1" + +} +``` + +### Subgroup removed from a group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Subgroup Hook +``` + +**Payload example**: + +```json +{ + + "created_at": "2021-01-20T09:40:12Z", + "updated_at": "2021-01-20T09:40:12Z", + "event_name": "subgroup_destroy", + "name": "subgroup1", + "path": "subgroup1", + "full_path": "group1/subgroup1", + "group_id": 10, + "parent_group_id": 7, + "parent_name": "group1", + "parent_path": "group1", + "parent_full_path": "group1" + +} +``` + +NOTE: +Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group) + +## Feature Flag events + +Triggered when a feature flag is turned on or off. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Feature Flag Hook +``` + +**Payload example**: + +```json +{ + "object_kind": "feature_flag", + "project": { + "id": 1, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlabhq/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", + "namespace":"GitlabHQ", + "visibility_level":20, + "path_with_namespace":"gitlabhq/gitlab-test", + "default_branch":"master", + "ci_config_path": null, + "homepage":"http://example.com/gitlabhq/gitlab-test", + "url":"http://example.com/gitlabhq/gitlab-test.git", + "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "http_url":"http://example.com/gitlabhq/gitlab-test.git" + }, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "email": "admin@example.com" + }, + "user_url": "http://example.com/root", + "object_attributes": { + "id": 6, + "name": "test-feature-flag", + "description": "test-feature-flag-description", + "active": true + } +} +``` + +## Release events + +Triggered when a release is created or updated. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Release Hook +``` + +**Available `object_attributes.action`:** + +- `create` +- `update` + +**Payload example**: + +```json +{ + "id": 1, + "created_at": "2020-11-02 12:55:12 UTC", + "description": "v1.0 has been released", + "name": "v1.1", + "released_at": "2020-11-02 12:55:12 UTC", + "tag": "v1.1", + "object_kind": "release", + "project": { + "id": 2, + "name": "release-webhook-example", + "description": "", + "web_url": "https://example.com/gitlab-org/release-webhook-example", + "avatar_url": null, + "git_ssh_url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "git_http_url": "https://example.com/gitlab-org/release-webhook-example.git", + "namespace": "Gitlab", + "visibility_level": 0, + "path_with_namespace": "gitlab-org/release-webhook-example", + "default_branch": "master", + "ci_config_path": null, + "homepage": "https://example.com/gitlab-org/release-webhook-example", + "url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "ssh_url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "http_url": "https://example.com/gitlab-org/release-webhook-example.git" + }, + "url": "https://example.com/gitlab-org/release-webhook-example/-/releases/v1.1", + "action": "create", + "assets": { + "count": 5, + "links": [ + { + "id": 1, + "external": true, + "link_type": "other", + "name": "Changelog", + "url": "https://example.net/changelog" + } + ], + "sources": [ + { + "format": "zip", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.zip" + }, + { + "format": "tar.gz", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar.gz" + }, + { + "format": "tar.bz2", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar.bz2" + }, + { + "format": "tar", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar" + } + ] + }, + "commit": { + "id": "ee0a3fb31ac16e11b9dbb596ad16d4af654d08f8", + "message": "Release v1.1", + "title": "Release v1.1", + "timestamp": "2020-10-31T14:58:32+11:00", + "url": "https://example.com/gitlab-org/release-webhook-example/-/commit/ee0a3fb31ac16e11b9dbb596ad16d4af654d08f8", + "author": { + "name": "Example User", + "email": "user@example.com" + } + } +} +``` diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 44225ac2921..0891d48c038 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -6,1802 +6,226 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Webhooks **(FREE)** -Project webhooks allow you to trigger a percent-encoded URL if, for example, new code is pushed or -a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab sends a POST request with data -to the webhook URL. - -You usually need to set up your own [webhook receiver](#example-webhook-receiver) -to receive information from GitLab and send it to another app, according to your requirements. -We already have a [built-in receiver](slack.md) -for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. - -## Overview - -[Webhooks](https://en.wikipedia.org/wiki/Webhook) are "_user-defined HTTP -callbacks_". They are usually triggered by some -event, such as pushing code to a repository or a comment being posted to a blog. -When that event occurs, the source app makes an HTTP request to the URI -configured for the webhook. The action taken may be anything. -Common uses are to trigger builds with continuous integration systems or to -notify bug tracking systems. - -Webhooks can be used to update an external issue tracker, trigger CI jobs, -update a backup mirror, or even deploy to your production server. - -Webhooks are available: - -- Per project, at a project's **Settings > Webhooks** menu. **(FREE)** -- Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** - -GitLab.com enforces various [webhook limits](../../../user/gitlab_com/index.md#webhooks), including: - -- The maximum number of webhooks and their size, both per project, and per group. -- The number of webhook calls per minute. - -## Possible uses for webhooks - -- You can set up a webhook in GitLab to send a notification to +[Webhooks](https://en.wikipedia.org/wiki/Webhook) are custom HTTP callbacks +that you define. They are usually triggered by an +event, such as pushing code to a repository or posting a comment on a blog. +When the event occurs, the source app makes an HTTP request to the URI +configured for the webhook. The action to take may be anything. For example, +you can use webhooks to: + +- Trigger continuous integration (CI) jobs, update external issue trackers, + update a backup mirror, or deploy to your production server. +- Send a notification to [Slack](https://api.slack.com/incoming-webhooks) every time a job fails. -- You can [integrate with Twilio to be notified via SMS](https://www.datadoghq.com/blog/send-alerts-sms-customizable-webhooks-twilio/) - every time an issue is created for a specific project or group within GitLab -- You can use them to [automatically assign labels to merge requests](https://about.gitlab.com/blog/2016/08/19/applying-gitlab-labels-automatically/). - -## Webhook endpoint tips - -If you are writing your own endpoint (web server) to receive -GitLab webhooks, keep in mind the following: - -- Your endpoint should send its HTTP response as fast as possible. If the response takes longer than - the configured timeout, GitLab decides the hook failed and retries it. For information on - customizing this timeout, see - [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). -- Your endpoint should ALWAYS return a valid HTTP response. If you do - not do this then GitLab thinks the hook failed and retries it. - Most HTTP libraries take care of this for you automatically but if - you are writing a low-level hook this is important to remember. -- GitLab ignores the HTTP status code returned by your endpoint. - -## Secret token - -If you specify a secret token, it is sent with the hook request in the -`X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify -that the request is legitimate. - -## SSL verification - -By default, the SSL certificate of the webhook endpoint is verified based on -an internal list of Certificate Authorities. This means the certificate cannot -be self-signed. - -You can turn this off in the webhook settings in your GitLab projects. - -## Branch filtering - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20338) in GitLab 11.3. - -Push events can be filtered by branch using a branch name or wildcard pattern -to limit which push events are sent to your webhook endpoint. By default the -field is blank causing all push events to be sent to your webhook endpoint. - -## Events - -Below are described the supported events. - -### Push events - -Triggered when you push to the repository except when pushing tags. - -NOTE: -When more than 20 commits are pushed at once, the `commits` webhook -attribute only contains the newest 20 for performance reasons. Loading -detailed commit data is expensive. Note that despite only 20 commits being -present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. - -NOTE: -If a branch creation push event is generated without new commits being introduced, the -`commits` attribute in the payload is empty. - -Also, if a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) -branches, this hook isn't executed. - -**Request header**: - -```plaintext -X-Gitlab-Event: Push Hook -``` - -**Payload example:** - -```json -{ - "object_kind": "push", - "before": "95790bf891e76fee5e1747ab589903a6a1f80f22", - "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "ref": "refs/heads/master", - "checkout_sha": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "user_id": 4, - "user_name": "John Smith", - "user_username": "jsmith", - "user_email": "john@example.com", - "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80", - "project_id": 15, - "project":{ - "id": 15, - "name":"Diaspora", - "description":"", - "web_url":"http://example.com/mike/diaspora", - "avatar_url":null, - "git_ssh_url":"git@example.com:mike/diaspora.git", - "git_http_url":"http://example.com/mike/diaspora.git", - "namespace":"Mike", - "visibility_level":0, - "path_with_namespace":"mike/diaspora", - "default_branch":"master", - "homepage":"http://example.com/mike/diaspora", - "url":"git@example.com:mike/diaspora.git", - "ssh_url":"git@example.com:mike/diaspora.git", - "http_url":"http://example.com/mike/diaspora.git" - }, - "repository":{ - "name": "Diaspora", - "url": "git@example.com:mike/diaspora.git", - "description": "", - "homepage": "http://example.com/mike/diaspora", - "git_http_url":"http://example.com/mike/diaspora.git", - "git_ssh_url":"git@example.com:mike/diaspora.git", - "visibility_level":0 - }, - "commits": [ - { - "id": "b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327", - "message": "Update Catalan translation to e38cb41.\n\nSee https://gitlab.com/gitlab-org/gitlab for more information", - "title": "Update Catalan translation to e38cb41.", - "timestamp": "2011-12-12T14:27:31+02:00", - "url": "http://example.com/mike/diaspora/commit/b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327", - "author": { - "name": "Jordi Mallach", - "email": "jordi@softcatala.org" - }, - "added": ["CHANGELOG"], - "modified": ["app/controller/application.rb"], - "removed": [] - }, - { - "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "message": "fixed readme", - "title": "fixed readme", - "timestamp": "2012-01-03T23:36:29+02:00", - "url": "http://example.com/mike/diaspora/commit/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "author": { - "name": "GitLab dev user", - "email": "gitlabdev@dv6700.(none)" - }, - "added": ["CHANGELOG"], - "modified": ["app/controller/application.rb"], - "removed": [] - } - ], - "total_commits_count": 4 -} -``` +- [Integrate with Twilio to be notified via SMS](https://www.datadoghq.com/blog/send-alerts-sms-customizable-webhooks-twilio/) + every time an issue is created for a specific project or group in GitLab. +- [Automatically assign labels to merge requests](https://about.gitlab.com/blog/2016/08/19/applying-gitlab-labels-automatically/). -### Tag events +You can configure your GitLab project or [group](#group-webhooks) to trigger +a percent-encoded webhook URL when an event occurs. For example, when new code +is pushed or a new issue is created. +The webhook listens for specific [events](#events) and +GitLab sends a POST request with data to the webhook URL. -Triggered when you create (or delete) tags to the repository. - -NOTE: -If a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) -tags, this hook is not executed. +Usually, you set up your own [webhook receiver](#create-an-example-webhook-receiver) +to receive information from GitLab and send it to another app, according to your requirements. +We have a [built-in receiver](slack.md) +for sending [Slack](https://api.slack.com/incoming-webhooks) notifications per project. -**Request header**: +GitLab.com enforces [webhook limits](../../../user/gitlab_com/index.md#webhooks), +including: -```plaintext -X-Gitlab-Event: Tag Push Hook -``` +- The maximum number of webhooks and their size, both per project and per group. +- The number of webhook calls per minute. -**Payload example:** - -```json -{ - "object_kind": "tag_push", - "before": "0000000000000000000000000000000000000000", - "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", - "ref": "refs/tags/v1.0.0", - "checkout_sha": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", - "user_id": 1, - "user_name": "John Smith", - "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80", - "project_id": 1, - "project":{ - "id": 1, - "name":"Example", - "description":"", - "web_url":"http://example.com/jsmith/example", - "avatar_url":null, - "git_ssh_url":"git@example.com:jsmith/example.git", - "git_http_url":"http://example.com/jsmith/example.git", - "namespace":"Jsmith", - "visibility_level":0, - "path_with_namespace":"jsmith/example", - "default_branch":"master", - "homepage":"http://example.com/jsmith/example", - "url":"git@example.com:jsmith/example.git", - "ssh_url":"git@example.com:jsmith/example.git", - "http_url":"http://example.com/jsmith/example.git" - }, - "repository":{ - "name": "Example", - "url": "ssh://git@example.com/jsmith/example.git", - "description": "", - "homepage": "http://example.com/jsmith/example", - "git_http_url":"http://example.com/jsmith/example.git", - "git_ssh_url":"git@example.com:jsmith/example.git", - "visibility_level":0 - }, - "commits": [], - "total_commits_count": 0 -} -``` +## Group webhooks **(PREMIUM)** -### Issue events +You can configure a webhook for a group to ensure all projects in the group +receive the same webhook settings. -Triggered when a new issue is created or an existing issue was updated/closed/reopened. +## Configure a webhook -**Request header**: +You can configure a webhook for a group or a project. -```plaintext -X-Gitlab-Event: Issue Hook -``` +1. In your project or group, on the left sidebar, select **Settings > Webhooks**. +1. In **URL**, enter the URL of the webhook endpoint. + The URL must be percentage-encoded, if necessary. +1. In **Secret token**, enter the [secret token](#validate-payloads-by-using-a-secret-token) to validate payloads. +1. In the **Trigger** section, select the [events](webhook_events.md) to trigger the webhook. +1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](#verify-an-ssl-certificate). +1. Select **Add webhook**. -**Available `object_attributes.action`:** - -- `open` -- `close` -- `reopen` -- `update` - -**Payload example:** - -```json -{ - "object_kind": "issue", - "event_type": "issue", - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", - "email": "admin@example.com" - }, - "project": { - "id": 1, - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlabhq/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", - "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", - "namespace":"GitlabHQ", - "visibility_level":20, - "path_with_namespace":"gitlabhq/gitlab-test", - "default_branch":"master", - "ci_config_path": null, - "homepage":"http://example.com/gitlabhq/gitlab-test", - "url":"http://example.com/gitlabhq/gitlab-test.git", - "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", - "http_url":"http://example.com/gitlabhq/gitlab-test.git" - }, - "object_attributes": { - "id": 301, - "title": "New API: create/update/delete file", - "assignee_ids": [51], - "assignee_id": 51, - "author_id": 51, - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "updated_by_id": 1, - "last_edited_at": null, - "last_edited_by_id": null, - "relative_position": 0, - "description": "Create new API for manipulations with repository", - "milestone_id": null, - "state_id": 1, - "confidential": false, - "discussion_locked": true, - "due_date": null, - "moved_to_id": null, - "duplicated_to_id": null, - "time_estimate": 0, - "total_time_spent": 0, - "time_change": 0, - "human_total_time_spent": null, - "human_time_estimate": null, - "human_time_change": null, - "weight": null, - "iid": 23, - "url": "http://example.com/diaspora/issues/23", - "state": "opened", - "action": "open", - "labels": [{ - "id": 206, - "title": "API", - "color": "#ffffff", - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "template": false, - "description": "API related issues", - "type": "ProjectLabel", - "group_id": 41 - }] - }, - "repository": { - "name": "Gitlab Test", - "url": "http://example.com/gitlabhq/gitlab-test.git", - "description": "Aut reprehenderit ut est.", - "homepage": "http://example.com/gitlabhq/gitlab-test" - }, - "assignees": [{ - "name": "User1", - "username": "user1", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" - }], - "assignee": { - "name": "User1", - "username": "user1", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" - }, - "labels": [{ - "id": 206, - "title": "API", - "color": "#ffffff", - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "template": false, - "description": "API related issues", - "type": "ProjectLabel", - "group_id": 41 - }], - "changes": { - "updated_by_id": { - "previous": null, - "current": 1 - }, - "updated_at": { - "previous": "2017-09-15 16:50:55 UTC", - "current": "2017-09-15 16:52:00 UTC" - }, - "labels": { - "previous": [{ - "id": 206, - "title": "API", - "color": "#ffffff", - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "template": false, - "description": "API related issues", - "type": "ProjectLabel", - "group_id": 41 - }], - "current": [{ - "id": 205, - "title": "Platform", - "color": "#123123", - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "template": false, - "description": "Platform related issues", - "type": "ProjectLabel", - "group_id": 41 - }] - } - } -} -``` +## Test a webhook -NOTE: -`assignee` and `assignee_id` keys are deprecated and now show the first assignee only. +You can trigger a webhook manually, to ensure it's working properly. -### Comment events +For example, to test `push events`, your project should have at least one commit. The webhook uses this commit in the webhook. -Triggered when a new comment is made on commits, merge requests, issues, and code snippets. -The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The -payload also includes information about the target of the comment. For example, -a comment on an issue includes the specific issue information under the `issue` key. -Valid target types: +To test a webhook: -- `commit` -- `merge_request` -- `issue` -- `snippet` +1. In your project, on the left sidebar, select **Settings > Webhooks**. +1. Scroll down to the list of configured webhooks. +1. From the **Test** dropdown list, select the type of event to test. -#### Comment on commit + -**Request header**: +## Create an example webhook receiver -```plaintext -X-Gitlab-Event: Note Hook -``` +To test how GitLab webhooks work, you can use +an echo script running in a console session. For the following script to +work you must have Ruby installed. -**Payload example:** - -```json -{ - "object_kind": "note", - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", - "email": "admin@example.com" - }, - "project_id": 5, - "project":{ - "id": 5, - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlabhq/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", - "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", - "namespace":"GitlabHQ", - "visibility_level":20, - "path_with_namespace":"gitlabhq/gitlab-test", - "default_branch":"master", - "homepage":"http://example.com/gitlabhq/gitlab-test", - "url":"http://example.com/gitlabhq/gitlab-test.git", - "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", - "http_url":"http://example.com/gitlabhq/gitlab-test.git" - }, - "repository":{ - "name": "Gitlab Test", - "url": "http://example.com/gitlab-org/gitlab-test.git", - "description": "Aut reprehenderit ut est.", - "homepage": "http://example.com/gitlab-org/gitlab-test" - }, - "object_attributes": { - "id": 1243, - "note": "This is a commit comment. How does this work?", - "noteable_type": "Commit", - "author_id": 1, - "created_at": "2015-05-17 18:08:09 UTC", - "updated_at": "2015-05-17 18:08:09 UTC", - "project_id": 5, - "attachment":null, - "line_code": "bec9703f7a456cd2b4ab5fb3220ae016e3e394e3_0_1", - "commit_id": "cfe32cf61b73a0d5e9f13e774abde7ff789b1660", - "noteable_id": null, - "system": false, - "st_diff": { - "diff": "--- /dev/null\n+++ b/six\n@@ -0,0 +1 @@\n+Subproject commit 409f37c4f05865e4fb208c771485f211a22c4c2d\n", - "new_path": "six", - "old_path": "six", - "a_mode": "0", - "b_mode": "160000", - "new_file": true, - "renamed_file": false, - "deleted_file": false - }, - "url": "http://example.com/gitlab-org/gitlab-test/commit/cfe32cf61b73a0d5e9f13e774abde7ff789b1660#note_1243" - }, - "commit": { - "id": "cfe32cf61b73a0d5e9f13e774abde7ff789b1660", - "message": "Add submodule\n\nSigned-off-by: Example User \u003cuser@example.com.com\u003e\n", - "timestamp": "2014-02-27T10:06:20+02:00", - "url": "http://example.com/gitlab-org/gitlab-test/commit/cfe32cf61b73a0d5e9f13e774abde7ff789b1660", - "author": { - "name": "Example User", - "email": "user@example.com" - } - } -} -``` +1. Save the following file as `print_http_body.rb`: -#### Comment on merge request + ```ruby + require 'webrick' -**Request header**: + server = WEBrick::HTTPServer.new(:Port => ARGV.first) + server.mount_proc '/' do |req, res| + puts req.body + end -```plaintext -X-Gitlab-Event: Note Hook -``` + trap 'INT' do + server.shutdown + end + server.start + ``` -**Payload example:** - -```json -{ - "object_kind": "note", - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", - "email": "admin@example.com" - }, - "project_id": 5, - "project":{ - "id": 5, - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlab-org/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", - "namespace":"Gitlab Org", - "visibility_level":10, - "path_with_namespace":"gitlab-org/gitlab-test", - "default_branch":"master", - "homepage":"http://example.com/gitlab-org/gitlab-test", - "url":"http://example.com/gitlab-org/gitlab-test.git", - "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "http_url":"http://example.com/gitlab-org/gitlab-test.git" - }, - "repository":{ - "name": "Gitlab Test", - "url": "http://localhost/gitlab-org/gitlab-test.git", - "description": "Aut reprehenderit ut est.", - "homepage": "http://example.com/gitlab-org/gitlab-test" - }, - "object_attributes": { - "id": 1244, - "note": "This MR needs work.", - "noteable_type": "MergeRequest", - "author_id": 1, - "created_at": "2015-05-17 18:21:36 UTC", - "updated_at": "2015-05-17 18:21:36 UTC", - "project_id": 5, - "attachment": null, - "line_code": null, - "commit_id": "", - "noteable_id": 7, - "system": false, - "st_diff": null, - "url": "http://example.com/gitlab-org/gitlab-test/merge_requests/1#note_1244" - }, - "merge_request": { - "id": 7, - "target_branch": "markdown", - "source_branch": "master", - "source_project_id": 5, - "author_id": 8, - "assignee_id": 28, - "title": "Tempora et eos debitis quae laborum et.", - "created_at": "2015-03-01 20:12:53 UTC", - "updated_at": "2015-03-21 18:27:27 UTC", - "milestone_id": 11, - "state": "opened", - "merge_status": "cannot_be_merged", - "target_project_id": 5, - "iid": 1, - "description": "Et voluptas corrupti assumenda temporibus. Architecto cum animi eveniet amet asperiores. Vitae numquam voluptate est natus sit et ad id.", - "position": 0, - "source":{ - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlab-org/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", - "namespace":"Gitlab Org", - "visibility_level":10, - "path_with_namespace":"gitlab-org/gitlab-test", - "default_branch":"master", - "homepage":"http://example.com/gitlab-org/gitlab-test", - "url":"http://example.com/gitlab-org/gitlab-test.git", - "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "http_url":"http://example.com/gitlab-org/gitlab-test.git" - }, - "target": { - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlab-org/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", - "namespace":"Gitlab Org", - "visibility_level":10, - "path_with_namespace":"gitlab-org/gitlab-test", - "default_branch":"master", - "homepage":"http://example.com/gitlab-org/gitlab-test", - "url":"http://example.com/gitlab-org/gitlab-test.git", - "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "http_url":"http://example.com/gitlab-org/gitlab-test.git" - }, - "last_commit": { - "id": "562e173be03b8ff2efb05345d12df18815438a4b", - "message": "Merge branch 'another-branch' into 'master'\n\nCheck in this test\n", - "timestamp": "2015-04-08T21: 00:25-07:00", - "url": "http://example.com/gitlab-org/gitlab-test/commit/562e173be03b8ff2efb05345d12df18815438a4b", - "author": { - "name": "John Smith", - "email": "john@example.com" - } - }, - "work_in_progress": false, - "assignee": { - "name": "User1", - "username": "user1", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" - } - } -} -``` +1. Choose an unused port (for example, `8000`) and start the script: -#### Comment on issue + ```shell + ruby print_http_body.rb 8000 + ``` -**Request header**: +1. In GitLab, add your webhook receiver as `http://my.host:8000/`. -```plaintext -X-Gitlab-Event: Note Hook -``` +1. Select **Test**. You should see something like this in the console: -**Payload example:** - -```json -{ - "object_kind": "note", - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", - "email": "admin@example.com" - }, - "project_id": 5, - "project":{ - "id": 5, - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlab-org/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", - "namespace":"Gitlab Org", - "visibility_level":10, - "path_with_namespace":"gitlab-org/gitlab-test", - "default_branch":"master", - "homepage":"http://example.com/gitlab-org/gitlab-test", - "url":"http://example.com/gitlab-org/gitlab-test.git", - "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "http_url":"http://example.com/gitlab-org/gitlab-test.git" - }, - "repository":{ - "name":"diaspora", - "url":"git@example.com:mike/diaspora.git", - "description":"", - "homepage":"http://example.com/mike/diaspora" - }, - "object_attributes": { - "id": 1241, - "note": "Hello world", - "noteable_type": "Issue", - "author_id": 1, - "created_at": "2015-05-17 17:06:40 UTC", - "updated_at": "2015-05-17 17:06:40 UTC", - "project_id": 5, - "attachment": null, - "line_code": null, - "commit_id": "", - "noteable_id": 92, - "system": false, - "st_diff": null, - "url": "http://example.com/gitlab-org/gitlab-test/issues/17#note_1241" - }, - "issue": { - "id": 92, - "title": "test", - "assignee_ids": [], - "assignee_id": null, - "author_id": 1, - "project_id": 5, - "created_at": "2015-04-12 14:53:17 UTC", - "updated_at": "2015-04-26 08:28:42 UTC", - "position": 0, - "branch_name": null, - "description": "test", - "milestone_id": null, - "state": "closed", - "iid": 17, - "labels": [ - { - "id": 25, - "title": "Afterpod", - "color": "#3e8068", - "project_id": null, - "created_at": "2019-06-05T14:32:20.211Z", - "updated_at": "2019-06-05T14:32:20.211Z", - "template": false, - "description": null, - "type": "GroupLabel", - "group_id": 4 - }, - { - "id": 86, - "title": "Element", - "color": "#231afe", - "project_id": 4, - "created_at": "2019-06-05T14:32:20.637Z", - "updated_at": "2019-06-05T14:32:20.637Z", - "template": false, - "description": null, - "type": "ProjectLabel", - "group_id": null - } - ] - } -} -``` + ```plaintext + {"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>} + example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 + - -> / + ``` NOTE: -`assignee_id` field is deprecated and now shows the first assignee only. - -#### Comment on code snippet - -**Request header**: - -```plaintext -X-Gitlab-Event: Note Hook -``` - -**Payload example:** - -```json -{ - "object_kind": "note", - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", - "email": "admin@example.com" - }, - "project_id": 5, - "project":{ - "id": 5, - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlab-org/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", - "namespace":"Gitlab Org", - "visibility_level":10, - "path_with_namespace":"gitlab-org/gitlab-test", - "default_branch":"master", - "homepage":"http://example.com/gitlab-org/gitlab-test", - "url":"http://example.com/gitlab-org/gitlab-test.git", - "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", - "http_url":"http://example.com/gitlab-org/gitlab-test.git" - }, - "repository":{ - "name":"Gitlab Test", - "url":"http://example.com/gitlab-org/gitlab-test.git", - "description":"Aut reprehenderit ut est.", - "homepage":"http://example.com/gitlab-org/gitlab-test" - }, - "object_attributes": { - "id": 1245, - "note": "Is this snippet doing what it's supposed to be doing?", - "noteable_type": "Snippet", - "author_id": 1, - "created_at": "2015-05-17 18:35:50 UTC", - "updated_at": "2015-05-17 18:35:50 UTC", - "project_id": 5, - "attachment": null, - "line_code": null, - "commit_id": "", - "noteable_id": 53, - "system": false, - "st_diff": null, - "url": "http://example.com/gitlab-org/gitlab-test/snippets/53#note_1245" - }, - "snippet": { - "id": 53, - "title": "test", - "content": "puts 'Hello world'", - "author_id": 1, - "project_id": 5, - "created_at": "2015-04-09 02:40:38 UTC", - "updated_at": "2015-04-09 02:40:38 UTC", - "file_name": "test.rb", - "expires_at": null, - "type": "ProjectSnippet", - "visibility_level": 0 - } -} -``` - -### Merge request events - -Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch. - -**Request header**: - -```plaintext -X-Gitlab-Event: Merge Request Hook -``` - -**Available `object_attributes.action`:** - -- `open` -- `close` -- `reopen` -- `update` -- `approved` -- `unapproved` -- `merge` - -**Payload example:** - -```json -{ - "object_kind": "merge_request", - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon", - "email": "admin@example.com" - }, - "project": { - "id": 1, - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlabhq/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", - "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", - "namespace":"GitlabHQ", - "visibility_level":20, - "path_with_namespace":"gitlabhq/gitlab-test", - "default_branch":"master", - "homepage":"http://example.com/gitlabhq/gitlab-test", - "url":"http://example.com/gitlabhq/gitlab-test.git", - "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", - "http_url":"http://example.com/gitlabhq/gitlab-test.git" - }, - "repository": { - "name": "Gitlab Test", - "url": "http://example.com/gitlabhq/gitlab-test.git", - "description": "Aut reprehenderit ut est.", - "homepage": "http://example.com/gitlabhq/gitlab-test" - }, - "object_attributes": { - "id": 99, - "target_branch": "master", - "source_branch": "ms-viewport", - "source_project_id": 14, - "author_id": 51, - "assignee_id": 6, - "title": "MS-Viewport", - "created_at": "2013-12-03T17:23:34Z", - "updated_at": "2013-12-03T17:23:34Z", - "milestone_id": null, - "state": "opened", - "merge_status": "unchecked", - "target_project_id": 14, - "iid": 1, - "description": "", - "source": { - "name":"Awesome Project", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/awesome_space/awesome_project", - "avatar_url":null, - "git_ssh_url":"git@example.com:awesome_space/awesome_project.git", - "git_http_url":"http://example.com/awesome_space/awesome_project.git", - "namespace":"Awesome Space", - "visibility_level":20, - "path_with_namespace":"awesome_space/awesome_project", - "default_branch":"master", - "homepage":"http://example.com/awesome_space/awesome_project", - "url":"http://example.com/awesome_space/awesome_project.git", - "ssh_url":"git@example.com:awesome_space/awesome_project.git", - "http_url":"http://example.com/awesome_space/awesome_project.git" - }, - "target": { - "name":"Awesome Project", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/awesome_space/awesome_project", - "avatar_url":null, - "git_ssh_url":"git@example.com:awesome_space/awesome_project.git", - "git_http_url":"http://example.com/awesome_space/awesome_project.git", - "namespace":"Awesome Space", - "visibility_level":20, - "path_with_namespace":"awesome_space/awesome_project", - "default_branch":"master", - "homepage":"http://example.com/awesome_space/awesome_project", - "url":"http://example.com/awesome_space/awesome_project.git", - "ssh_url":"git@example.com:awesome_space/awesome_project.git", - "http_url":"http://example.com/awesome_space/awesome_project.git" - }, - "last_commit": { - "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "message": "fixed readme", - "timestamp": "2012-01-03T23:36:29+02:00", - "url": "http://example.com/awesome_space/awesome_project/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "author": { - "name": "GitLab dev user", - "email": "gitlabdev@dv6700.(none)" - } - }, - "work_in_progress": false, - "url": "http://example.com/diaspora/merge_requests/1", - "action": "open", - "assignee": { - "name": "User1", - "username": "user1", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" - } - }, - "labels": [{ - "id": 206, - "title": "API", - "color": "#ffffff", - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "template": false, - "description": "API related issues", - "type": "ProjectLabel", - "group_id": 41 - }], - "changes": { - "updated_by_id": { - "previous": null, - "current": 1 - }, - "updated_at": { - "previous": "2017-09-15 16:50:55 UTC", - "current":"2017-09-15 16:52:00 UTC" - }, - "labels": { - "previous": [{ - "id": 206, - "title": "API", - "color": "#ffffff", - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "template": false, - "description": "API related issues", - "type": "ProjectLabel", - "group_id": 41 - }], - "current": [{ - "id": 205, - "title": "Platform", - "color": "#123123", - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "template": false, - "description": "Platform related issues", - "type": "ProjectLabel", - "group_id": 41 - }] - } - } -} -``` - -### Wiki Page events - -Triggered when a wiki page is created, updated or deleted. - -**Request Header**: - -```plaintext -X-Gitlab-Event: Wiki Page Hook -``` - -**Payload example**: - -```json -{ - "object_kind": "wiki_page", - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", - "email": "admin@example.com" - }, - "project": { - "id": 1, - "name": "awesome-project", - "description": "This is awesome", - "web_url": "http://example.com/root/awesome-project", - "avatar_url": null, - "git_ssh_url": "git@example.com:root/awesome-project.git", - "git_http_url": "http://example.com/root/awesome-project.git", - "namespace": "root", - "visibility_level": 0, - "path_with_namespace": "root/awesome-project", - "default_branch": "master", - "homepage": "http://example.com/root/awesome-project", - "url": "git@example.com:root/awesome-project.git", - "ssh_url": "git@example.com:root/awesome-project.git", - "http_url": "http://example.com/root/awesome-project.git" - }, - "wiki": { - "web_url": "http://example.com/root/awesome-project/-/wikis/home", - "git_ssh_url": "git@example.com:root/awesome-project.wiki.git", - "git_http_url": "http://example.com/root/awesome-project.wiki.git", - "path_with_namespace": "root/awesome-project.wiki", - "default_branch": "master" - }, - "object_attributes": { - "title": "Awesome", - "content": "awesome content goes here", - "format": "markdown", - "message": "adding an awesome page to the wiki", - "slug": "awesome", - "url": "http://example.com/root/awesome-project/-/wikis/awesome", - "action": "create" - } -} -``` - -### Pipeline events - -In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) -and later, the pipeline webhook returns only the latest jobs. - -Triggered on status change of Pipeline. - -**Request Header**: - -```plaintext -X-Gitlab-Event: Pipeline Hook -``` - -**Payload example**: - -```json -{ - "object_kind": "pipeline", - "object_attributes":{ - "id": 31, - "ref": "master", - "tag": false, - "sha": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", - "before_sha": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", - "source": "merge_request_event", - "status": "success", - "stages":[ - "build", - "test", - "deploy" - ], - "created_at": "2016-08-12 15:23:28 UTC", - "finished_at": "2016-08-12 15:26:29 UTC", - "duration": 63, - "variables": [ - { - "key": "NESTOR_PROD_ENVIRONMENT", - "value": "us-west-1" - } - ] - }, - "merge_request": { - "id": 1, - "iid": 1, - "title": "Test", - "source_branch": "test", - "source_project_id": 1, - "target_branch": "master", - "target_project_id": 1, - "state": "opened", - "merge_status": "can_be_merged", - "url": "http://192.168.64.1:3005/gitlab-org/gitlab-test/merge_requests/1" - }, - "user":{ - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - "email": "user_email@gitlab.com" - }, - "project":{ - "id": 1, - "name": "Gitlab Test", - "description": "Atque in sunt eos similique dolores voluptatem.", - "web_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test", - "avatar_url": null, - "git_ssh_url": "git@192.168.64.1:gitlab-org/gitlab-test.git", - "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", - "namespace": "Gitlab Org", - "visibility_level": 20, - "path_with_namespace": "gitlab-org/gitlab-test", - "default_branch": "master" - }, - "commit":{ - "id": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", - "message": "test\n", - "timestamp": "2016-08-12T17:23:21+02:00", - "url": "http://example.com/gitlab-org/gitlab-test/commit/bcbb5ec396a2c0f828686f14fac9b80b780504f2", - "author":{ - "name": "User", - "email": "user@gitlab.com" - } - }, - "builds":[ - { - "id": 380, - "stage": "deploy", - "name": "production", - "status": "skipped", - "created_at": "2016-08-12 15:23:28 UTC", - "started_at": null, - "finished_at": null, - "when": "manual", - "manual": true, - "allow_failure": false, - "user":{ - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - "email": "admin@example.com" - }, - "runner": null, - "artifacts_file":{ - "filename": null, - "size": null - }, - "environment": { - "name": "production", - "action": "start", - "deployment_tier": "production" - } - }, - { - "id": 377, - "stage": "test", - "name": "test-image", - "status": "success", - "created_at": "2016-08-12 15:23:28 UTC", - "started_at": "2016-08-12 15:26:12 UTC", - "finished_at": null, - "when": "on_success", - "manual": false, - "allow_failure": false, - "user":{ - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - "email": "admin@example.com" - }, - "runner": { - "id": 380987, - "description": "shared-runners-manager-6.gitlab.com", - "active": true, - "runner_type": "instance_type", - "is_shared": true, - "tags": [ - "linux", - "docker", - "shared-runner" - ] - }, - "artifacts_file":{ - "filename": null, - "size": null - }, - "environment": null - }, - { - "id": 378, - "stage": "test", - "name": "test-build", - "status": "success", - "created_at": "2016-08-12 15:23:28 UTC", - "started_at": "2016-08-12 15:26:12 UTC", - "finished_at": "2016-08-12 15:26:29 UTC", - "when": "on_success", - "manual": false, - "allow_failure": false, - "user":{ - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - "email": "admin@example.com" - }, - "runner": { - "id":380987, - "description":"shared-runners-manager-6.gitlab.com", - "active":true, - "runner_type": "instance_type", - "is_shared": true, - "tags": [ - "linux", - "docker" - ] - }, - "artifacts_file":{ - "filename": null, - "size": null - }, - "environment": null - }, - { - "id": 376, - "stage": "build", - "name": "build-image", - "status": "success", - "created_at": "2016-08-12 15:23:28 UTC", - "started_at": "2016-08-12 15:24:56 UTC", - "finished_at": "2016-08-12 15:25:26 UTC", - "when": "on_success", - "manual": false, - "allow_failure": false, - "user":{ - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - "email": "admin@example.com" - }, - "runner": { - "id": 380987, - "description": "shared-runners-manager-6.gitlab.com", - "active": true, - "runner_type": "instance_type", - "is_shared": true, - "tags": [ - "linux", - "docker" - ] - }, - "artifacts_file":{ - "filename": null, - "size": null - }, - "environment": null - }, - { - "id": 379, - "stage": "deploy", - "name": "staging", - "status": "created", - "created_at": "2016-08-12 15:23:28 UTC", - "started_at": null, - "finished_at": null, - "when": "on_success", - "manual": false, - "allow_failure": false, - "user":{ - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - "email": "admin@example.com" - }, - "runner": null, - "artifacts_file":{ - "filename": null, - "size": null - }, - "environment": { - "name": "staging", - "action": "start", - "deployment_tier": "staging" - } - } - ] -} -``` - -### Job events - -Triggered on status change of a job. - -**Request Header**: - -```plaintext -X-Gitlab-Event: Job Hook -``` - -**Payload example**: - -```json -{ - "object_kind": "build", - "ref": "gitlab-script-trigger", - "tag": false, - "before_sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", - "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", - "build_id": 1977, - "build_name": "test", - "build_stage": "test", - "build_status": "created", - "build_created_at": "2021-02-23T02:41:37.886Z", - "build_started_at": null, - "build_finished_at": null, - "build_duration": null, - "build_allow_failure": false, - "build_failure_reason": "script_failure", - "pipeline_id": 2366, - "project_id": 380, - "project_name": "gitlab-org/gitlab-test", - "user": { - "id": 3, - "name": "User", - "email": "user@gitlab.com", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - }, - "commit": { - "id": 2366, - "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", - "message": "test\n", - "author_name": "User", - "author_email": "user@gitlab.com", - "status": "created", - "duration": null, - "started_at": null, - "finished_at": null - }, - "repository": { - "name": "gitlab_test", - "description": "Atque in sunt eos similique dolores voluptatem.", - "homepage": "http://192.168.64.1:3005/gitlab-org/gitlab-test", - "git_ssh_url": "git@192.168.64.1:gitlab-org/gitlab-test.git", - "git_http_url": "http://192.168.64.1:3005/gitlab-org/gitlab-test.git", - "visibility_level": 20 - }, - "runner": { - "active": true, - "runner_type": "project_type", - "is_shared": false, - "id": 380987, - "description": "shared-runners-manager-6.gitlab.com", - "tags": [ - "linux", - "docker" - ] - }, - "environment": null -} -``` - -Note that `commit.id` is the ID of the pipeline, not the ID of the commit. - -### Deployment events - -Triggered when a deployment: - -- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.) -- Succeeds -- Fails -- Is cancelled - -**Request Header**: - -```plaintext -X-Gitlab-Event: Deployment Hook -``` - -**Payload example**: - -```json -{ - "object_kind": "deployment", - "status": "success", - "status_changed_at":"2021-04-28 21:50:00 +0200", - "deployment_id": 15, - "deployable_id": 796, - "deployable_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/jobs/796", - "environment": "staging", - "project": { - "id": 30, - "name": "test-deployment-webhooks", - "description": "", - "web_url": "http://10.126.0.2:3000/root/test-deployment-webhooks", - "avatar_url": null, - "git_ssh_url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", - "git_http_url": "http://10.126.0.2:3000/root/test-deployment-webhooks.git", - "namespace": "Administrator", - "visibility_level": 0, - "path_with_namespace": "root/test-deployment-webhooks", - "default_branch": "master", - "ci_config_path": "", - "homepage": "http://10.126.0.2:3000/root/test-deployment-webhooks", - "url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", - "ssh_url": "ssh://vlad@10.126.0.2:2222/root/test-deployment-webhooks.git", - "http_url": "http://10.126.0.2:3000/root/test-deployment-webhooks.git" - }, - "short_sha": "279484c0", - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "email": "admin@example.com" - }, - "user_url": "http://10.126.0.2:3000/root", - "commit_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/commit/279484c09fbe69ededfced8c1bb6e6d24616b468", - "commit_title": "Add new file" -} -``` - -Note that `deployable_id` is the ID of the CI job. - -### Group member events **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. - -Member events are triggered when: - -- A user is added as a group member -- The access level of a user has changed -- The expiration date for user access has been updated -- A user has been removed from the group - -#### Add member to group - -**Request Header**: - -```plaintext -X-Gitlab-Event: Member Hook -``` - -**Payload example**: - -```json -{ - "created_at": "2020-12-11T04:57:22Z", - "updated_at": "2020-12-11T04:57:22Z", - "group_name": "webhook-test", - "group_path": "webhook-test", - "group_id": 100, - "user_username": "test_user", - "user_name": "Test User", - "user_email": "testuser@webhooktest.com", - "user_id": 64, - "group_access": "Guest", - "group_plan": null, - "expires_at": "2020-12-14T00:00:00Z", - "event_name": "user_add_to_group" -} -``` - -#### Update member access level or expiration date - -**Request Header**: - -```plaintext -X-Gitlab-Event: Member Hook -``` - -**Payload example**: - -```json -{ - "created_at": "2020-12-11T04:57:22Z", - "updated_at": "2020-12-12T08:48:19Z", - "group_name": "webhook-test", - "group_path": "webhook-test", - "group_id": 100, - "user_username": "test_user", - "user_name": "Test User", - "user_email": "testuser@webhooktest.com", - "user_id": 64, - "group_access": "Developer", - "group_plan": null, - "expires_at": "2020-12-20T00:00:00Z", - "event_name": "user_update_for_group" -} -``` - -#### Remove member from group - -**Request Header**: - -```plaintext -X-Gitlab-Event: Member Hook -``` - -**Payload example**: - -```json -{ - "created_at": "2020-12-11T04:57:22Z", - "updated_at": "2020-12-12T08:52:34Z", - "group_name": "webhook-test", - "group_path": "webhook-test", - "group_id": 100, - "user_username": "test_user", - "user_name": "Test User", - "user_email": "testuser@webhooktest.com", - "user_id": 64, - "group_access": "Guest", - "group_plan": null, - "expires_at": "2020-12-14T00:00:00Z", - "event_name": "user_remove_from_group" -} -``` - -### Subgroup events **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260419) in GitLab 13.9. - -Subgroup events are triggered when: - -- A [subgroup is created in a group](#subgroup-created-in-a-group) -- A [subgroup is removed from a group](#subgroup-removed-from-a-group) - -#### Subgroup created in a group - -**Request Header**: - -```plaintext -X-Gitlab-Event: Subgroup Hook -``` - -**Payload example**: - -```json -{ - - "created_at": "2021-01-20T09:40:12Z", - "updated_at": "2021-01-20T09:40:12Z", - "event_name": "subgroup_create", - "name": "subgroup1", - "path": "subgroup1", - "full_path": "group1/subgroup1", - "group_id": 10, - "parent_group_id": 7, - "parent_name": "group1", - "parent_path": "group1", - "parent_full_path": "group1" - -} -``` - -#### Subgroup removed from a group - -**Request Header**: - -```plaintext -X-Gitlab-Event: Subgroup Hook -``` - -**Payload example**: - -```json -{ - - "created_at": "2021-01-20T09:40:12Z", - "updated_at": "2021-01-20T09:40:12Z", - "event_name": "subgroup_destroy", - "name": "subgroup1", - "path": "subgroup1", - "full_path": "group1/subgroup1", - "group_id": 10, - "parent_group_id": 7, - "parent_name": "group1", - "parent_path": "group1", - "parent_full_path": "group1" +You may need to [allow requests to the local network](../../../security/webhooks.md) for this +receiver to be added. -} -``` +## Validate payloads by using a secret token -NOTE: -Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group) +You can specify a secret token to validate received payloads. +The token is sent with the hook request in the +`X-Gitlab-Token` HTTP header. Your webhook endpoint can check the token to verify +that the request is legitimate. -### Feature Flag events +## Verify an SSL certificate -Triggered when a feature flag is turned on or off. +By default, the SSL certificate of the webhook endpoint is verified based on +an internal list of Certificate Authorities. This means the certificate cannot +be self-signed. -**Request Header**: +You can turn off SSL verification in the [webhook settings](#configure-a-webhook) +in your GitLab projects. -```plaintext -X-Gitlab-Event: Feature Flag Hook -``` +## Filter push events by branch -**Payload example**: - -```json -{ - "object_kind": "feature_flag", - "project": { - "id": 1, - "name":"Gitlab Test", - "description":"Aut reprehenderit ut est.", - "web_url":"http://example.com/gitlabhq/gitlab-test", - "avatar_url":null, - "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", - "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", - "namespace":"GitlabHQ", - "visibility_level":20, - "path_with_namespace":"gitlabhq/gitlab-test", - "default_branch":"master", - "ci_config_path": null, - "homepage":"http://example.com/gitlabhq/gitlab-test", - "url":"http://example.com/gitlabhq/gitlab-test.git", - "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", - "http_url":"http://example.com/gitlabhq/gitlab-test.git" - }, - "user": { - "id": 1, - "name": "Administrator", - "username": "root", - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "email": "admin@example.com" - }, - "user_url": "http://example.com/root", - "object_attributes": { - "id": 6, - "name": "test-feature-flag", - "description": "test-feature-flag-description", - "active": true - } -} -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20338) in GitLab 11.3. -### Release events +Push events can be filtered by branch using a branch name or wildcard pattern +to limit which push events are sent to your webhook endpoint. By default, +all push events are sent to your webhook endpoint. You can configure branch filtering +in the [webhook settings](#configure-a-webhook) in your project. -Triggered when a release is created or updated. +## HTTP responses for your endpoint -**Request Header**: +If you are writing your own endpoint (web server) to receive +GitLab webhooks, keep in mind the following: -```plaintext -X-Gitlab-Event: Release Hook -``` +- Your endpoint should send its HTTP response as fast as possible. If the response + takes longer than the configured timeout, GitLab assumes the hook failed and retries it. + To customize the timeout, see + [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). +- Your endpoint should ALWAYS return a valid HTTP response. If not, + GitLab assumes the hook failed and retries it. + Most HTTP libraries take care of the response for you automatically but if + you are writing a low-level hook, this is important to remember. +- GitLab ignores the HTTP status code returned by your endpoint. -**Available `object_attributes.action`:** - -- `create` -- `update` - -**Payload example**: - -```json -{ - "id": 1, - "created_at": "2020-11-02 12:55:12 UTC", - "description": "v1.0 has been released", - "name": "v1.1", - "released_at": "2020-11-02 12:55:12 UTC", - "tag": "v1.1", - "object_kind": "release", - "project": { - "id": 2, - "name": "release-webhook-example", - "description": "", - "web_url": "https://example.com/gitlab-org/release-webhook-example", - "avatar_url": null, - "git_ssh_url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", - "git_http_url": "https://example.com/gitlab-org/release-webhook-example.git", - "namespace": "Gitlab", - "visibility_level": 0, - "path_with_namespace": "gitlab-org/release-webhook-example", - "default_branch": "master", - "ci_config_path": null, - "homepage": "https://example.com/gitlab-org/release-webhook-example", - "url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", - "ssh_url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", - "http_url": "https://example.com/gitlab-org/release-webhook-example.git" - }, - "url": "https://example.com/gitlab-org/release-webhook-example/-/releases/v1.1", - "action": "create", - "assets": { - "count": 5, - "links": [ - { - "id": 1, - "external": true, - "link_type": "other", - "name": "Changelog", - "url": "https://example.net/changelog" - } - ], - "sources": [ - { - "format": "zip", - "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.zip" - }, - { - "format": "tar.gz", - "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar.gz" - }, - { - "format": "tar.bz2", - "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar.bz2" - }, - { - "format": "tar", - "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar" - } - ] - }, - "commit": { - "id": "ee0a3fb31ac16e11b9dbb596ad16d4af654d08f8", - "message": "Release v1.1", - "title": "Release v1.1", - "timestamp": "2020-10-31T14:58:32+11:00", - "url": "https://example.com/gitlab-org/release-webhook-example/-/commit/ee0a3fb31ac16e11b9dbb596ad16d4af654d08f8", - "author": { - "name": "Example User", - "email": "user@example.com" - } - } -} -``` +## How image URLs are displayed in the webhook body -## Image URL rewriting +> Introduced in GitLab 11.2. -From GitLab 11.2, simple image references are rewritten to use an absolute URL -in webhooks. So if an image, merge request, comment, or wiki page has this in -its description: +Relative image references are rewritten to use an absolute URL +in the body of a webhook. +For example, if an image, merge request, comment, or wiki page includes the +following image reference: ```markdown  ``` -It appears in the webhook body as follows assuming that: +If: - GitLab is installed at `gitlab.example.com`. - The project is at `example-group/example-project`. +The reference is rewritten in the webhook body as follows: + ```markdown  ``` -This doesn't rewrite URLs that already are pointing to HTTP, HTTPS, or -protocol-relative URLs. It also doesn't rewrite image URLs using advanced -Markdown features, like link labels. +Image URLs are not rewritten if: -## Testing webhooks +- They already point to HTTP, HTTPS, or + protocol-relative URLs. +- They use advanced Markdown features like link labels. -You can trigger the webhook manually. Sample data from the project is used. -For example, for triggering `Push Events` your project should have at least one commit. +## Events - +For more information about supported events for Webhooks, go to [Webhook events](webhook_events.md). ## Troubleshoot webhooks -GitLab stores each perform of the webhook. -You can find records for last 2 days in "Recent Deliveries" section on the edit page of each webhook. +GitLab records the history of each webhook request. +You can view requests made in the last 2 days in the **Recent events** table. - +To view the table: -In this section you can see: +1. In your project, on the left sidebar, select **Settings > Webhooks**. +1. Scroll down to the webhooks. +1. Select **Edit** for the webhook you want to view. -- HTTP status code (green for `200-299` codes, red for the others, `internal error` for failed deliveries). -- Triggered event. -- A time when the event was called. -- Elapsed time of the request. +The table includes the following details about each request: -If you need more information about execution, you can click `View details` link. -On this page, you can see data that GitLab sends (request headers and body) and data that it received (response headers and body). +- HTTP status code (green for `200`-`299` codes, red for the others, and `internal error` for failed deliveries) +- Triggered event +- Elapsed time of the request +- Relative time for when the request was made -From this page, you can repeat delivery with the same data by clicking `Resend Request` button. + NOTE: -This history is unavailable for Group-level webhooks. For more information, read +The **Recent events** table is unavailable for group-level webhooks. For more information, read [issue #325642](https://gitlab.com/gitlab-org/gitlab/-/issues/325642). +Each webhook event has a corresponding **Details** page. This page details the data that GitLab sent (request headers and body) and received (response headers and body). +To view the **Details** page, select **View details** for the webhook event. + +To repeat the delivery with the same data, select **Resend Request**. + NOTE: -If URL or secret token of the webhook were updated, data is delivered to the new address. +If you update the URL or secret token of the webhook, data is delivered to the new address. ### Webhook fails or multiple webhook requests are triggered -When GitLab sends a webhook, it expects a response in 10 seconds by default. If it does not receive -one, it retries the webhook. If the endpoint doesn't send its HTTP response within those 10 seconds, -GitLab may decide the hook failed and retry it. +When GitLab sends a webhook, it expects a response in 10 seconds by default. +If the endpoint doesn't send an HTTP response in those 10 seconds, +GitLab may assume the webhook failed and retry it. -If your webhooks are failing or you are receiving multiple requests, you can try changing the -default value. You can do this by uncommenting or adding the following setting to your -`/etc/gitlab/gitlab.rb` file: +If your webhooks are failing or you are receiving multiple requests, +you can try changing the default timeout value. +In your `/etc/gitlab/gitlab.rb` file, uncomment or add the following setting: ```ruby gitlab_rails['webhook_timeout'] = 10 @@ -1809,48 +233,11 @@ gitlab_rails['webhook_timeout'] = 10 ### Unable to get local issuer certificate -When SSL verification is enabled, this error indicates that GitLab isn't able to verify the SSL certificate of the webhook endpoint. -Typically, this is because the root certificate isn't issued by a trusted certification authority as +When SSL verification is enabled, you might get an error that GitLab cannot +verify the SSL certificate of the webhook endpoint. +Typically, this error occurs because the root certificate isn't +issued by a trusted certification authority as determined by [CAcert.org](http://www.cacert.org/). -Should that not be the case, consider using [SSL Checker](https://www.sslshopper.com/ssl-checker.html) to identify faults. -Missing intermediate certificates are a common point of verification failure. - -## Example webhook receiver - -If you want to see GitLab webhooks in action for testing purposes you can use -a simple echo script running in a console session. For the following script to -work you need to have Ruby installed. - -Save the following file as `print_http_body.rb`: - -```ruby -require 'webrick' - -server = WEBrick::HTTPServer.new(:Port => ARGV.first) -server.mount_proc '/' do |req, res| - puts req.body -end - -trap 'INT' do - server.shutdown -end -server.start -``` - -Pick an unused port (for example, `8000`) and start the script: `ruby print_http_body.rb -8000`. Then add your server as a webhook receiver in GitLab as -`http://my.host:8000/`. - -When you press 'Test' in GitLab, you should see something like this in the -console: - -```plaintext -{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>} -example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 -- -> / -``` - -NOTE: -You may need to [allow requests to the local network](../../../security/webhooks.md) for this -receiver to be added. +If that is not the case, consider using [SSL Checker](https://www.sslshopper.com/ssl-checker.html) to identify faults. +Missing intermediate certificates are common causes of verification failure. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md deleted file mode 100644 index ab8a7829139..00000000000 --- a/doc/user/project/integrations/zentao.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -stage: Ecosystem -group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments ---- - -# ZenTao product integration **(PREMIUM)** - -[ZenTao](https://www.zentao.net/) is a web-based project management platform. - -## Configure ZenTao - -This integration requires a ZenTao API secret key. - -Complete these steps in ZenTao: - -1. Go to your **Admin** page and select **Develop > Application**. -1. Select **Add Application**. -1. Under **Name** and **Code**, enter a name and a code for the new secret key. -1. Under **Account**, select an existing account name. -1. Select **Save**. -1. Copy the generated key to use in GitLab. - -## Configure GitLab - -Complete these steps in GitLab: - -1. Go to your project and select **Settings > Integrations**. -1. Select **ZenTao**. -1. Turn on the **Active** toggle under **Enable Integration**. -1. Provide the ZenTao configuration information: - - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). - - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. - - **ZenTao API token**: Use the key you generated when you [configured ZenTao](#configure-zentao). - - **ZenTao Product ID**: To display issues from a single ZenTao product in a given GitLab project. The Product ID can be found in the ZenTao product page under **Settings > Overview**. - -  - -1. To verify the ZenTao connection is working, select **Test settings**. -1. Select **Save changes**. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 4d1805e3d31..8a599608f71 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -203,17 +203,13 @@ When visiting a board, issues appear ordered in any list. You're able to change that order by dragging the issues. The changed order is saved, so that anybody who visits the same board later sees the reordering, with some exceptions. -The first time an issue appears in any board (that is, the first time a user -loads a board containing that issue), it is ordered in relation to other issues in that list. -The order is done according to [label priority](labels.md#label-priority). +When an issue is created, the system assigns a relative order value that is greater than the maximum value +of that issue's project or root group. This means the issue will be at the bottom of any issue list that +it appears in. -At this point, that issue is assigned a relative order value by the system, -with respect to the other issues in the list. Any time -you drag and reorder the issue, its relative order value changes accordingly. - -Also, any time that issue appears in any board, the ordering is done according to -the updated relative order value. It's only the first -time an issue appears that it takes from the priority order mentioned above. If a user in your GitLab instance +Any time you drag and reorder the issue, its relative order value changes accordingly. +Then, any time that issue appears in any board, the ordering is done according to +the updated relative order value. If a user in your GitLab instance drags issue `A` above issue `B`, the ordering is maintained when these two issues are subsequently loaded in any board in the same instance. This could be a different project board or a different group board, for example. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 7f2713b81e6..37c00bf0efa 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,21 +1,21 @@ --- stage: Plan group: Product Planning -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Design Management **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -> - Support for SVGs was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. -> - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab Premium 12.2. +> - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab Premium 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. -Design Management allows you to upload design assets (wireframes, mockups, etc.) -to GitLab issues and keep them stored in one single place, accessed by the Design +Design Management allows you to upload design assets (including wireframes and mockups) +to GitLab issues and keep them stored in a single place, accessed by the Design Management's page within an issue, giving product designers, product managers, and engineers a -way to collaborate on designs over one single source of truth. +way to collaborate on designs over a single source of truth. -You can easily share mock-ups of designs with your team, or visual regressions can be easily +You can share mock-ups of designs with your team, or visual regressions can be viewed and addressed. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -36,10 +36,11 @@ to be enabled: and enable **Git Large File Storage**. Design Management also requires that projects are using -[hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). Since - GitLab 10.0, newly created projects use hashed storage by default. A GitLab administrator can verify the storage type of a -project by navigating to **Admin Area > Projects** and then selecting the project in question. -A project can be identified as hashed-stored if its *Gitaly relative path* contains `@hashed`. +[hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). +Newly created projects use hashed storage by default. A GitLab administrator +can verify the storage type of a project by going to **Admin Area > Projects** +and then selecting the project in question. A project can be identified as +hashed-stored if its *Gitaly relative path* contains `@hashed`. If the requirements are not met, the **Designs** tab displays a message to the user. @@ -74,8 +75,8 @@ and connect to GitLab through a personal access token. The details are explained ## The Design Management section -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2, Designs are displayed directly on the issue description rather than on a separate tab. -> - New display's feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) in GitLab 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2. Designs are displayed directly in the issue description instead of a separate tab. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) for new displays in GitLab 13.4. You can find to the **Design Management** section in the issue description: @@ -83,22 +84,26 @@ You can find to the **Design Management** section in the issue description: ## Adding designs +> - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.9. +> - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.9. +> - Copy and paste uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. + To upload Design images, drag files from your computer and drop them in the Design Management section, -or click **upload** to select images from your file browser: +or select **click to upload** to select images from your file browser:  -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, -you can drag and drop designs onto the dedicated drop zone to upload them. +You can drag and drop designs onto the dedicated drop zone to upload them.  -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) -in GitLab 12.10, you can also copy images from your file system and -paste them directly on the GitLab Design page as a new design. +You can also copy images from your file system and paste them directly on the +GitLab Design page as a new design. -On macOS you can also take a screenshot and immediately copy it to -the clipboard by simultaneously clicking <kbd>Control</kbd> + <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>3</kbd>, and then paste it as a design. +On macOS, you can take a screenshot and immediately copy it to the clipboard +by simultaneously pressing <kbd>Control</kbd> + <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>3</kbd>, +and then paste it as a design. Copy-and-pasting has some limitations: @@ -108,24 +113,24 @@ Copy-and-pasting has some limitations: - Copy/pasting designs is not supported on Internet Explorer. Designs with the same filename as an existing uploaded design create a new version -of the design, and replaces the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design also creates a new version, -provided the filenames are the same. +of the design, and replaces the previous version. Dropping a design on an +existing uploaded design creates a new version if the filenames are the same. ### Skipped designs Designs with the same filename as an existing uploaded design _and_ whose content has not changed are skipped. -This means that no new version of the design is created. When designs are skipped, you are made aware via a warning +This means that no new version of the design is created. When designs are skipped, you are made aware by a warning message on the Issue. ## Viewing designs -Images on the Design Management page can be enlarged by clicking on them. -You can navigate through designs by clicking on the navigation buttons on the +Images on the Design Management page can be enlarged by selecting them. +You can navigate through designs by selecting the navigation buttons on the top-right corner or with <kbd>Left</kbd>/<kbd>Right</kbd> keyboard buttons. The number of discussions on a design — if any — is listed to the right -of the design filename. Clicking on this number enlarges the design -just like clicking anywhere else on the design. +of the design filename. Selecting this number enlarges the design, +similar to clicking or tapping anywhere else in the design. When a design is added or modified, an icon is displayed on the item to help summarize changes between versions. @@ -137,27 +142,29 @@ to help summarize changes between versions. ### Exploring designs by zooming -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab Premium 12.7. +> - Drag to move a zoomed image [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. Designs can be explored in greater detail by zooming in and out of the image. Control the amount of zoom with the `+` and `-` buttons at the bottom of the image. While zoomed, you can still [start new discussions](#starting-discussions-on-designs) on the image, and see any existing ones. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10, while zoomed in, -you can click-and-drag on the image to move around it. +While zoomed in, you can drag the image to move around it.  ## Deleting designs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab Premium 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. There are two ways to delete designs: manually delete them individually, or select a few of them to delete at once, as shown below. -To delete a single design, click it to view it enlarged, -then click the trash icon on the top right corner and confirm -the deletion by clicking the **Delete** button on the modal window: +To delete a single design, select it to view it enlarged, +then select the trash icon on the top right corner and confirm +the deletion by selecting **Delete** in the window:  @@ -166,7 +173,7 @@ first select the designs you want to delete:  -Once selected, click the **Delete selected** button to confirm the deletion: +Select **Delete selected** to confirm the deletion:  @@ -183,14 +190,16 @@ You can change the order of designs by dragging them to a new position. ## Starting discussions on designs -When a design is uploaded, you can start a discussion by clicking on +> - Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. + +When a design is uploaded, you can start a discussion by selecting the image on the exact location you would like the discussion to be focused on. A pin is added to the image, identifying the discussion's location.  -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8, -you can adjust a pin's position by dragging it around the image. This is useful +You can adjust a pin's position by dragging it around the image. This is useful for when your design layout has changed between revisions, or if you need to move an existing pin to add a new one in its place. @@ -198,7 +207,7 @@ Different discussions have different pin numbers:  -From GitLab 12.5 on, new discussions are outputted to the issue activity, +In GitLab 12.5 and later, new discussions are output to the issue activity, so that everyone involved can participate in the discussion. ## Resolve Design threads @@ -209,20 +218,20 @@ Discussion threads can be resolved on Designs. There are two ways to resolve/unresolve a Design thread: -1. You can mark a thread as resolved or unresolved by clicking the checkmark icon for **Resolve thread** in the top-right corner of the first comment of the discussion: +1. You can mark a thread as resolved or unresolved by selecting the checkmark icon for **Resolve thread** in the top-right corner of the first comment of the discussion: -  +  1. Design threads can also be resolved or unresolved in their threads by using a checkbox. - When replying to a comment, there is a checkbox that you can click in order to resolve or unresolve - the thread once published: + When replying to a comment, you can select or clear a checkbox to resolve or unresolve + the thread after publishing: -  +  Resolving a discussion thread also marks any pending to-do items related to notes inside the thread as done. This is applicable only for to-do items owned by the user triggering the action. -Note that your resolved comment pins disappear from the Design to free up space for new discussions. +Your resolved comment pins disappear from the Design to free up space for new discussions. However, if you need to revisit or find a resolved discussion, all of your resolved threads are available in the **Resolved Comment** area at the bottom of the right sidebar. @@ -231,19 +240,19 @@ available in the **Resolved Comment** area at the bottom of the right sidebar. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. -Add a to-do item for a design by clicking **Add a to do** on the design sidebar: +Add a to-do item for a design by selecting **Add a to do** on the design sidebar:  ## Referring to designs in Markdown -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in **GitLab 13.1**. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258662) in **GitLab 13.5** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in GitLab 13.1. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258662) in GitLab 13.5. We support referring to designs in [Markdown](../../markdown.md), which is available throughout the application, including in merge request and issue descriptions, in discussions and comments, and in wiki pages. -At present, full URL references are supported. For example, if we refer to a design +Full URL references are supported. For example, if we refer to a design somewhere with: ```markdown diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 5b8dd617ab9..94a5fdc3f0f 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -15,7 +15,7 @@ the issue can view the due date. When creating an issue, select the **Due date** field to make a calendar appear for choosing the date. To remove the date, select the date -text and delete it. The date is related to the server's timezone, not the timezone of +text and delete it. The date is related to the server's time zone, not the time zone of the user setting the due date.  @@ -45,7 +45,7 @@ Due dates also appear in your [to-do list](../../todos.md). The day before an open issue is due, an email is sent to all participants of the issue. Like the due date, the "day before the due date" is determined by the -server's timezone. +server's time zone. Issues with due dates can also be exported as an iCalendar feed. The URL of the feed can be added to calendar applications. The feed is accessible by selecting diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 7033b90b736..a2fa044be6b 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -212,7 +212,7 @@ that are not in status **closed** from one project to another. To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. -We do also recommend [creating a backup](../../../raketasks/backup_restore.md#back-up-gitlab) before +We do also recommend [creating a backup](../../../raketasks/backup_restore.md) before attempting any changes in the console. ```ruby diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 43d6ab2070d..e9cbe012110 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -156,8 +156,6 @@ to the project: ## Scoped labels **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. - Scoped labels allow teams to use the label feature to annotate issues, merge requests and epics with mutually exclusive labels. This can enable more complicated workflows by preventing certain labels from being used together. @@ -180,6 +178,19 @@ For example: 1. GitLab automatically removes the `priority::low` label, as an issue should not have two priority labels at the same time. +### Filter by scoped labels + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12285) in GitLab 14.4. + +To filter issue, merge request, or epic lists for ones with labels that belong to a given scope, enter +`<scope>::*` in the searched label name. + +For example, filtering by the `platform::*` label returns issues that have `platform::iOS`, +`platform::Android`, or `platform::Linux` labels. + +NOTE: +This is not available on the [issues or merge requests dashboard pages](../search/index.md#issues-and-merge-requests). + ### Workflows with scoped labels Suppose you wanted a custom field in issues to track the operating system platform @@ -228,14 +239,14 @@ to label notifications for the project only, or the whole group. ## Label priority -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14189) in GitLab 8.9. -> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. - Labels can have relative priorities, which are used in the **Label priority** and **Priority** sort orders of issues and merge request list pages. Prioritization for both group and project labels happens at the project level, and cannot be done from the group label list. +NOTE: +Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. + From the project label list page, star a label to indicate that it has a priority.  diff --git a/doc/user/project/members/img/project_members_filter_direct_v13_9.png b/doc/user/project/members/img/project_members_filter_direct_v13_9.png Binary files differdeleted file mode 100644 index 50115ee4052..00000000000 --- a/doc/user/project/members/img/project_members_filter_direct_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_filter_direct_v14_4.png b/doc/user/project/members/img/project_members_filter_direct_v14_4.png Binary files differnew file mode 100644 index 00000000000..79cee06bc30 --- /dev/null +++ b/doc/user/project/members/img/project_members_filter_direct_v14_4.png diff --git a/doc/user/project/members/img/project_members_filter_inherited_v13_9.png b/doc/user/project/members/img/project_members_filter_inherited_v13_9.png Binary files differdeleted file mode 100644 index 433003fe58b..00000000000 --- a/doc/user/project/members/img/project_members_filter_inherited_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_filter_inherited_v14_4.png b/doc/user/project/members/img/project_members_filter_inherited_v14_4.png Binary files differnew file mode 100644 index 00000000000..ce2a0ebf088 --- /dev/null +++ b/doc/user/project/members/img/project_members_filter_inherited_v14_4.png diff --git a/doc/user/project/members/img/project_members_search_v13_9.png b/doc/user/project/members/img/project_members_search_v13_9.png Binary files differdeleted file mode 100644 index 67280d11dca..00000000000 --- a/doc/user/project/members/img/project_members_search_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_search_v14_4.png b/doc/user/project/members/img/project_members_search_v14_4.png Binary files differnew file mode 100644 index 00000000000..8c52c5788d4 --- /dev/null +++ b/doc/user/project/members/img/project_members_search_v14_4.png diff --git a/doc/user/project/members/img/project_members_sort_v13_9.png b/doc/user/project/members/img/project_members_sort_v13_9.png Binary files differdeleted file mode 100644 index 47abe18ba49..00000000000 --- a/doc/user/project/members/img/project_members_sort_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_sort_v14_4.png b/doc/user/project/members/img/project_members_sort_v14_4.png Binary files differnew file mode 100644 index 00000000000..20834b9307e --- /dev/null +++ b/doc/user/project/members/img/project_members_sort_v14_4.png diff --git a/doc/user/project/members/img/project_members_v13_9.png b/doc/user/project/members/img/project_members_v13_9.png Binary files differdeleted file mode 100644 index 3b48c752c6a..00000000000 --- a/doc/user/project/members/img/project_members_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_v14_4.png b/doc/user/project/members/img/project_members_v14_4.png Binary files differnew file mode 100644 index 00000000000..0a235e91d28 --- /dev/null +++ b/doc/user/project/members/img/project_members_v14_4.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 8a70b74fcc1..f9788ef18ec 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -87,7 +87,7 @@ A success message is displayed and the new members are now displayed in the list When your project belongs to a group, group members inherit their role from the group. - + In this example: @@ -140,7 +140,7 @@ You can filter and sort members in a project. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press Enter. - + ### Display direct members @@ -148,19 +148,19 @@ You can filter and sort members in a project. 1. In the **Filter members** box, select `Membership` `=` `Direct`. 1. Press Enter. - + ### Search You can search for members by name, username, or email. - + ### Sort You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. - + ## Request access to a project diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index e1149b85cd5..abca140411a 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Workspace info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 7e168fb239a..b422982c0e7 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -154,7 +154,7 @@ become eligible approvers in the project. To enable this merge request approval 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Locate **Any eligible user** and select the number of approvals required: +1. Locate **Eligible users** and select the number of approvals required:  @@ -225,7 +225,7 @@ approval rule for certain branches: 1. Go to your project and select **Settings**. 1. Expand **Merge request (MR) approvals**. 1. Select a **Target branch**: - - To protect all branches, select **Any branch**. + - To protect all branches, select **All branches**. - To select a specific branch, select it from the list:  diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index ebd07f30f52..1c56e91ed6b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval settings **(FREE)** +# Merge request approval settings **(PREMIUM)** You can configure the settings for [merge request approvals](index.md) to ensure the approval rules meet your use case. You can also configure @@ -30,7 +30,7 @@ In this section of general settings, you can configure the following settings: | [Require user password to approve](#require-user-password-to-approve) | Force potential approvers to first authenticate with a password. | | [Remove all approvals when commits are added to the source branch](#remove-all-approvals-when-commits-are-added-to-the-source-branch) | When enabled, remove all existing approvals on a merge request when more changes are added to it. | -## Prevent approval by author **(PREMIUM)** +## Prevent approval by author > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. > - Moved to GitLab Premium in 13.9. @@ -52,7 +52,7 @@ this setting, unless you configure one of these options: at the instance level, you can't edit this setting at the project or individual merge request levels. -## Prevent approvals by users who add commits **(PREMIUM)** +## Prevent approvals by users who add commits > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. > - Moved to GitLab Premium in 13.9. @@ -126,13 +126,29 @@ merge request could introduce a vulnerability. To learn more, see [Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). -## Code coverage check approvals **(PREMIUM)** +## Code coverage check approvals You can require specific approvals if a merge request would result in a decline in code test coverage. To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). +## Merge request approval settings cascading + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md). On GitLab.com, this feature is not available. +You should not use this feature for production environments + +You can also enforce merge request approval settings: + +- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups on an instance and, therefore, all + projects. +- On a [top-level group](../../../group/index.md#group-approval-rules), which apply to all subgroups and projects. + +If the settings are inherited by a group or project, they cannot be overridden by the group or project that inherited them. + ## Related links - [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 6df84dd1dd1..ff2e6acf123 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -11,11 +11,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w Merge requests in a public repository are also public, even when the merge request is created for a [confidential issue](../issues/confidential_issues.md). To avoid leaking confidential information when working on a confidential issue, -create your merge request from a private fork. +create your merge request from a private fork in the same namespace. Roles are inherited from parent groups. If you create your private fork in the -same group or subgroup as the original (public) repository, developers receive -the same permissions in your fork. This inheritance ensures: +same namespace (same group or subgroup) as the original (public) repository, +developers receive the same permissions in your fork. This inheritance ensures: - Developer users have the needed permissions to view confidential issues and resolve them. - You do not need grant individual users access to your fork. @@ -24,13 +24,17 @@ The [security practices for confidential merge requests](https://gitlab.com/gitl ## Create a confidential merge request -WARNING: -To create a confidential merge request, you must create a private fork. This fork -may expose confidential information, if you create your fork in another namespace -that may have other members. - Branches are public by default. To protect the confidentiality of your work, you -must create your changes in a private fork. +must create your branches and merge requests in the same namespace, but downstream +in a private fork. If you create your private fork in the same namespace as the +public repository, your fork inherits the permissions of the upstream public repository. +Users with the Developer role in the upstream public repository inherit those upstream +permissions in your downstream private fork without action by you. These users can +immediately push code to branches in your private fork to help fix the confidential issue. + +WARNING: +Your private fork may expose confidential information, if you create it in a different +namespace than the upstream repository. The two namespaces may not contain the same users. Prerequisites: @@ -56,16 +60,15 @@ To create a confidential merge request: branches must be available in your selected fork. 1. Select **Create**. -If you created a branch in your private fork, users with the Developer role in the -public repository can push code to that branch in your private fork to fix the -confidential issue. +This merge request targets your private fork, not the public upstream project. +Your branch, merge requests, and commits remain in your private fork. This prevents +prematurely revealing confidential information. -As your merge request targets your private fork, not the public upstream project, -your branch, merge request, and commits do not enter the public repository. This -prevents prematurely revealing confidential information. +Open a merge request +[from your fork to the upstream repository](../repository/forking_workflow.md#merging-upstream) when: -To make a confidential commit public, open a merge request from the private fork -to the public upstream project. +- You are satisfied the problem is resolved in your private fork. +- You are ready to make the confidential commits public. ## Related links diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 72fcd7f36b0..cee4df1f61e 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -50,8 +50,9 @@ Learn the various ways to [create a merge request](creating_merge_requests.md). ## What you can do with merge requests When you start a new merge request, you can immediately include the following -options, or add them later by clicking the **Edit** button on the merge -request's page at the top-right side: +options. You can also add them later by either selecting **Edit** on the merge +request's page at the top-right side, or by using +[keyboard shortcuts for merge requests](../../shortcuts.md#issues-and-merge-requests): - [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. - Set a [milestone](../milestones/index.md) to track time-sensitive changes. @@ -74,8 +75,10 @@ After you have created the merge request, you can also: - Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). -Many of these can be set when pushing changes from the command line, -with [Git push options](../push_options.md). +Many of these options can be set: + +- From the merge request page, with [keyboard shortcuts](../../shortcuts.md#issues-and-merge-requests). +- When pushing changes from the command line, with [Git push options](../push_options.md). See also other [features associated to merge requests](reviews/index.md#associated-features). diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index b7e055ca749..2c062c2c592 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -40,14 +40,18 @@ important parts of the merge request: ## View merge requests -You can view merge requests for a specific project, or for all projects in a group: +To view a list of merge requests: -- **Specific project**: Go to your project and select **Merge requests**. +- **Merge requests for a project**: Go to your project and select **Merge requests**, or use + the <kbd>g</kbd> + <kbd>m</kbd> [keyboard shortcut](../../shortcuts.md) from a page in your project. - **All projects in a group**: Go to your group and select **Merge requests**. If your group contains subgroups, this view also displays merge requests from the subgroup projects. GitLab displays a count of open merge requests in the left sidebar, but [caches the value](reviews/index.md#cached-merge-request-count) for groups with a large number of open merge requests. +- **Merge requests assigned to you**: On any GitLab page, select **Merge requests** + in the top bar, or use the <kbd>Shift</kbd> + <kbd>m</kbd> + [global keyboard shortcut](../../shortcuts.md). GitLab displays open merge requests, with tabs to filter the list by open and closed status: @@ -153,3 +157,4 @@ For a web developer writing a webpage for your company's website: - [Review a merge request](reviews/index.md) - [Authorization for merge requests](authorization_for_merge_requests.md) - [Testing and reports](testing_and_reports_in_merge_requests.md) +- [GitLab keyboard shortcuts](../../shortcuts.md) diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index dbf3b0180e6..e6f84f1c357 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -158,7 +158,7 @@ Multiline comments display the comment's line numbers above the body of the comm Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. -When bulk editing merge requests in a project, you can edit the following attributes: +When bulk-editing merge requests in a project, you can edit the following attributes: - Status (open/closed) - Assignee @@ -211,6 +211,8 @@ These features are associated with merge requests: 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 a merge request. +- [Keyboard shortcuts](../../../shortcuts.md#issues-and-merge-requests): + Access and modify specific parts of a merge request with keyboard commands. ## Troubleshooting diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 4027ec08234..ac1cd57fb99 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -33,9 +33,8 @@ which generates a commit in the merge request authored by the user that suggeste  -1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, - you can opt to add a custom commit message to describe your change. If you don't - specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions). +1. Optionally specify a custom commit message for individual suggestions (GitLab 13.9 and later) to + describe your change. If you don't specify it, the default commit message is used.  @@ -118,6 +117,7 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. +> - Custom commit messages for batch suggestions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) in GitLab 14.4. You can apply multiple suggestions at once to reduce the number of commits added to your branch to address your reviewers' requests. @@ -134,7 +134,10 @@ to your branch to address your reviewers' requests.  -1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**: +1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**. You + can optionally specify a custom commit message for [batch suggestions](#batch-suggestions) + (GitLab 14.4 and later) to describe your change. If you don't specify it, the default commit + message is used.  diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 399d7958bbf..08b82462187 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -93,7 +93,7 @@ for doesn't appear immediately. The search box requires **three** alphanumeric characters to be entered for the search to begin. If you want the status check to be applied to **all** merge requests, -you can select the **Any branch** option. +you can select the **All branches** option. ## Delete a status check diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 813e3c1c9ce..b36510c2df8 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -177,8 +177,6 @@ coverage-jdk11: # convert report from jacoco to cobertura, using relative project path - python /opt/cover2cover.py target/site/jacoco/jacoco.xml $CI_PROJECT_DIR/src/main/java/ > target/site/cobertura.xml needs: ["test-jdk11"] - dependencies: - - test-jdk11 artifacts: reports: cobertura: target/site/cobertura.xml @@ -215,8 +213,6 @@ coverage-jdk11: # convert report from jacoco to cobertura, using relative project path - python /opt/cover2cover.py build/jacoco/jacoco.xml $CI_PROJECT_DIR/src/main/java/ > build/cobertura.xml needs: ["test-jdk11"] - dependencies: - - test-jdk11 artifacts: reports: cobertura: build/cobertura.xml @@ -235,7 +231,8 @@ run tests: image: python:3 script: - pip install pytest pytest-cov - - pytest --cov=src/ tests.py + - coverage run -m pytest + - coverage report - coverage xml artifacts: reports: 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 51f1ec96c22..27487003697 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 @@ -26,7 +26,7 @@ and steps below. - A custom domain name `example.com` or subdomain `subdomain.example.com`. - Access to your domain's server control panel to set up DNS records: - A DNS A or CNAME record pointing your domain to GitLab Pages server. - - A DNS TXT record to verify your domain's ownership. + - A DNS `TXT` record to verify your domain's ownership. ### Steps @@ -48,7 +48,7 @@ Click **Create New Domain**. #### 2. Get the verification code After you add a new domain to Pages, the verification code prompts you. Copy the values from GitLab -and paste them in your domain's control panel as a TXT record on the next step. +and paste them in your domain's control panel as a `TXT` record on the next step.  @@ -76,7 +76,7 @@ Root domains (`example.com`) require: | From | DNS Record | To | | --------------------------------------------- | ---------- | --------------- | | `example.com` | A | `35.185.44.232` | -| `_gitlab-pages-verification-code.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | For projects on GitLab.com, this IP is `35.185.44.232`. For projects living in other GitLab instances (CE or EE), please contact @@ -104,7 +104,7 @@ Subdomains (`subdomain.example.com`) require: | From | DNS Record | To | | ------------------------------------------------------- | ---------- | --------------------- | | `subdomain.example.com` | CNAME | `namespace.gitlab.io` | -| `_gitlab-pages-verification-code.subdomain.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.subdomain.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | Note that, whether it's a user or a project website, the `CNAME` should point to your Pages domain (`namespace.gitlab.io`), @@ -121,15 +121,15 @@ They require: - A DNS A record for the domain. - A DNS CNAME record for the subdomain. -- A DNS TXT record for each. +- A DNS `TXT` record for each. | From | DNS Record | To | | ------------------------------------------------- | ---------- | ---------------------- | | `example.com` | A | `35.185.44.232` | -| `_gitlab-pages-verification-code.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | |---------------------------------------------------+------------+------------------------| | `www.example.com` | CNAME | `namespace.gitlab.io` | -| `_gitlab-pages-verification-code.www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | If you're using Cloudflare, check [Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare). @@ -196,15 +196,15 @@ For a root domain: | From | DNS Record | To | | ------------------------------------------------- | ---------- | ---------------------- | -| `example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -| `_gitlab-pages-verification-code.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | For a subdomain: | From | DNS Record | To | | ------------------------------------------------- | ---------- | ---------------------- | -| `www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -| `_gitlab-pages-verification-code.www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | ### Adding more domain aliases @@ -290,8 +290,6 @@ Sublime Text, Atom, Dreamweaver, Brackets, etc). ## Force HTTPS for GitLab Pages websites -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28857) in GitLab 10.7. - To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your website through HTTP are automatically redirected to HTTPS through 301. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index 5b7f6454ef7..21f2dd51f70 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -35,7 +35,7 @@ with financial transactions. <!-- vale gitlab.Spelling = NO --> -Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): +Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [Internet Security Research Group (ISRG)](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): <!-- vale gitlab.rulename = YES --> diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 385a4fafa7d..283ed0b61b9 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -7,14 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80) in GitLab Enterprise Edition 8.3. -> - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173) in GitLab Enterprise Edition 8.5. -> - [Ported](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/14605) to GitLab Community Edition in GitLab 8.17. -> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30548) in GitLab 11.8. -> - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. - -With GitLab Pages, you can publish static websites -directly from a repository in GitLab. +With GitLab Pages, you can publish static websites directly from a repository +in GitLab. <div class="row"> <div class="col-md-9"> @@ -32,11 +26,11 @@ directly from a repository in GitLab. <div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="middle display-block"></div> </div> -To publish a website with Pages, you can use any SSG, -like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also +To publish a website with Pages, you can use any static site generator, +like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. You can also publish any website written directly in plain HTML, CSS, and JavaScript. -Pages does **not** support dynamic server-side processing, for instance, as `.php` and `.asp` requires. +Pages does not support dynamic server-side processing, for instance, as `.php` and `.asp` requires. Learn more about [static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). @@ -45,18 +39,18 @@ Learn more about To create a GitLab Pages website: | Document | Description | -| -------- | ----------- | -| [Create a `.gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | +|----------|-------------| +| [Create a `.gitlab-ci.yml` file from scratch](getting_started/pages_from_scratch.md) | Add a Pages site to an existing project. Learn how to create and configure your own CI file. | | [Use a `.gitlab-ci.yml` template](getting_started/pages_ci_cd_template.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. | -| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | -| [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | +| [Fork a sample project](getting_started/pages_forked_sample_project.md) | Create a new project with Pages already configured by forking a sample project. | +| [Use a project template](getting_started/pages_new_project_template.md) | Create a new project with Pages already configured by using a template. | To update a GitLab Pages website: | Document | Description | -| -------- | ----------- | +|----------|-------------| | [GitLab Pages domain names, URLs, and base URLs](getting_started_part_one.md) | Learn about GitLab Pages default domains. | -| [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ. | +| [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, and FAQ. | | [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Custom domains and subdomains, DNS records, and SSL/TLS certificates. | | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | | [Redirects](redirects.md) | Set up HTTP redirects to forward one page to another. | @@ -64,7 +58,7 @@ To update a GitLab Pages website: Learn more and see examples: | Document | Description | -| -------- | ----------- | +|----------|-------------| | [Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | Static versus dynamic site overview. | | [Modern static site generators](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) | SSG overview. | | [Build any SSG site with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | Use SSGs for GitLab Pages. | @@ -74,7 +68,7 @@ Learn more and see examples: To use GitLab Pages, you must create a project in GitLab to upload your website's files to. These projects can be either public, internal, or private. -GitLab always deploys your website from a very specific folder called `public` in your +GitLab always deploys your website from a specific folder called `public` in your repository. When you create a new project in GitLab, a [repository](../repository/index.md) becomes available automatically. @@ -87,7 +81,7 @@ GitLab Pages website. You can either use the GitLab [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 -need administrator access to your domain's registrar (or control panel) to set it up with Pages. +must have the Administrator role in your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. @@ -95,24 +89,21 @@ The following diagrams show the workflows you might follow to get started with P ## Access to your Pages site -If you're using GitLab Pages default domain (`.gitlab.io`), -your website is automatically secure and available under -HTTPS. If you're using your own custom domain, you can -optionally secure it with SSL/TLS certificates. +If you're using GitLab Pages default domain (`.gitlab.io`), your website is +automatically secure and available under HTTPS. If you're using your own custom +domain, you can optionally secure it with SSL/TLS certificates. If you're using GitLab.com, your website is publicly available to the internet. To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). -If you're using a self-managed instance (Free, Premium, or Ultimate), -your websites are published on your own server, according to the -[Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, -who can make them public or internal. +If you're using a self-managed instance, your websites are published on your +own server, according to the [Pages settings](../../../administration/pages/index.md) +chosen by your sysadmin, who can make them public or internal. ## Pages examples -There are some great examples of GitLab Pages websites built for -specific reasons. These examples can teach you advanced techniques -to use and adapt to your own needs: +These GitLab Pages website examples can teach you advanced techniques to use +and adapt for your own needs: - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/blog/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/). - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/). @@ -122,27 +113,27 @@ to use and adapt to your own needs: ## Administer GitLab Pages for self-managed instances -If you are running a self-managed instance of GitLab (GitLab Community Edition and Enterprise Editions), +If you are running a self-managed instance of GitLab, [follow the administration steps](../../../administration/pages/index.md) to configure Pages. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) about how to get started with GitLab Pages administration. ## Security for GitLab Pages -If your username is `foo`, your GitLab Pages website is located at `foo.gitlab.io`. -GitLab allows usernames to contain a `.`, so a user named `bar.foo` could create -a GitLab Pages website `bar.foo.gitlab.io` that effectively is a subdomain of your -`foo.gitlab.io` website. Be careful if you use JavaScript to set cookies for your website. +If your username is `example`, your GitLab Pages website is located at `example.gitlab.io`. +GitLab allows usernames to contain a `.`, so a user named `bar.example` could create +a GitLab Pages website `bar.example.gitlab.io` that effectively is a subdomain of your +`example.gitlab.io` website. Be careful if you use JavaScript to set cookies for your website. The safe way to manually set cookies with JavaScript is to not specify the `domain` at all: ```javascript -// Safe: This cookie is only visible to foo.gitlab.io +// Safe: This cookie is only visible to example.gitlab.io document.cookie = "key=value"; -// Unsafe: This cookie is visible to foo.gitlab.io and its subdomains, +// Unsafe: This cookie is visible to example.gitlab.io and its subdomains, // regardless of the presence of the leading dot. -document.cookie = "key=value;domain=.foo.gitlab.io"; -document.cookie = "key=value;domain=foo.gitlab.io"; +document.cookie = "key=value;domain=.example.gitlab.io"; +document.cookie = "key=value;domain=example.gitlab.io"; ``` This issue doesn't affect users with a custom domain, or users who don't set any diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 94656c91e98..45c2f1aaf04 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -118,7 +118,7 @@ pages: paths: - public only: - - master + - main ``` ### `.gitlab-ci.yml` for a static site generator @@ -133,7 +133,7 @@ the `pages` job with the [`only` parameter](../../../ci/yaml/index.md#only--exce whenever a new commit is pushed to a branch used specifically for your pages. -That way, you can have your project's code in the `master` branch and use an +That way, you can have your project's code in the `main` branch and use an orphan branch (let's name it `pages`) to host your static generator site. You can create a new empty branch like this: @@ -163,7 +163,7 @@ pages: - pages ``` -See an example that has different files in the [`master` branch](https://gitlab.com/pages/jekyll-branched/tree/master) +See an example that has different files in the [`main` branch](https://gitlab.com/pages/jekyll-branched/tree/main) and the source files for Jekyll are in a [`pages` branch](https://gitlab.com/pages/jekyll-branched/tree/pages) which also includes `.gitlab-ci.yml`. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index c17133e72cf..305bbb2ded0 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -61,7 +61,7 @@ time as pushing changes: | Push option | Description | Introduced in version | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------- | | `merge_request.create` | Create a new merge request for the pushed branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | -| `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | +| `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch or upstream project, such as: `git push -o merge_request.target=project_path/branch` | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | | `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | | `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 52b59d70302..45a83394c41 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -103,7 +103,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | | `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | | `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | -| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8003)| +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8103)| | `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | | `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | | `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 49b5ec2ca60..9e4d621dbc6 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -218,7 +218,7 @@ To set a deploy freeze window in the UI, complete these steps: 1. Scroll to **Deploy freezes**. 1. Click **Expand** to see the deploy freeze table. 1. Click **Add deploy freeze** to open the deploy freeze modal. -1. Enter the start time, end time, and timezone of the desired deploy freeze period. +1. Enter the start time, end time, and time zone of the desired deploy freeze period. 1. Click **Add deploy freeze** in the modal. 1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**) and remove it by selecting the delete button (**{remove}**).  diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index a1ea929bb49..5cd025f017d 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -11,8 +11,9 @@ When you create a new [project](../../index.md), GitLab creates a default branch in the repository. A default branch has special configuration options not shared by other branches: +- It cannot be deleted. - It's [initially protected](../../protected_branches.md#protected-branches) against - accidental deletion and forced pushes. + forced pushes. - When a merge request uses an [issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically) to close an issue, the work is merged into this branch. @@ -97,7 +98,7 @@ Ensure they understand the scope of this change includes references to the old branch name in related code and scripts. When changing the default branch name for an existing repository, you should preserve -the history of your default branch by renaming it, instead of deleting it. This example +the history of your default branch by renaming it, instead of creating a new branch. This example renames a Git repository's (`example`) default branch. 1. On your local command line, navigate to your `example` repository, and ensure @@ -195,3 +196,32 @@ To fix the problem: ``` 1. In GitLab, [change the default branch](#change-the-default-branch-name-for-a-project) to the one you intend to use. + +### Query GraphQL for default branches + +You can use a [GraphQL query](../../../../api/graphql/index.md) +to retrieve the default branches for all projects in a group. + +To return all projects in a single page of results, replace `GROUPNAME` with the +full path to your group. GitLab returns the first page of results. If `hasNextPage` +is `true`, you can request the next page by replacing the `null` in `after: null` +with the value of `endCursor`: + +```graphql +{ + group(fullPath: "GROUPNAME") { + projects(after: null) { + pageInfo { + hasNextPage + endCursor + } + nodes { + name + repository { + rootRef + } + } + } + } +} +``` diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 91858ff9a65..351daaaca3b 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: concepts, howto --- # Branches **(FREE)** @@ -57,8 +56,6 @@ To compare branches in a repository: ## Delete merged branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6449) in GitLab 8.14. -  This feature allows merged branches to be deleted in bulk. Only branches that @@ -83,8 +80,6 @@ Search results appear in the following order: ## Branch filter search box -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22166) in GitLab 11.5. -  This feature allows you to search and select branches quickly. Search results appear in the following order: diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 33ab5f6580d..bf4ef21e31b 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -52,7 +52,7 @@ of the fork must manually change the visibility. Issue ## Repository mirroring -You can use [repository mirroring](repository_mirroring.md) to keep your fork synced with the original repository. You can also use `git remote add upstream` to achieve the same result. +You can use [repository mirroring](mirror/index.md) to keep your fork synced with the original repository. You can also use `git remote add upstream` to achieve the same result. The main difference is that with repository mirroring, your remote fork is automatically kept up-to-date. diff --git a/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png Binary files differindex 20d76797977..df5e803d77a 100644 --- a/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png +++ b/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png Binary files differindex 150ec3ebf90..732173d9c1b 100644 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png +++ b/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png Binary files differindex 326605baaab..bbdb9bca199 100644 --- a/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png +++ b/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png Binary files differindex 4a4c1f8cd11..1a92555457a 100644 --- a/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png +++ b/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png b/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png Binary files differindex d0bdefaa437..5a5562ed38c 100644 --- a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png +++ b/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png diff --git a/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png b/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png Binary files differindex 1b2fa59726a..ad949aae8ce 100644 --- a/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png +++ b/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md new file mode 100644 index 00000000000..c4254655fcc --- /dev/null +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -0,0 +1,171 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' +--- + +# Bidirectional mirroring **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. + +WARNING: +Bidirectional mirroring may cause conflicts. + +Bidirectional [mirroring](index.md) configures two repositories to both pull from, +and push to, each other. There is no guarantee that either repository can update +without errors. + +## Reduce conflicts in bidirectional mirroring + +If you configure bidirectional mirroring, prepare your repositories for +conflicts. Configure them to reduce conflicts, and how to settle them when they occur: + +- [Mirror only protected branches](index.md#mirror-only-protected-branches). Rewriting + any mirrored commit on either remote causes conflicts and mirroring to fail. +- [Protect the branches](../../protected_branches.md) you want to mirror on both + remotes to prevent conflicts caused by rewriting history. +- Reduce mirroring delay with a [push event webhook](../../integrations/webhook_events.md#push-events). + Bidirectional mirroring creates a race condition where commits made close together + to the same branch cause conflicts. Push event webhooks can help mitigate the race + condition. Push mirroring from GitLab is rate limited to once per minute when only + push mirroring protected branches. +- Prevent conflicts [using a pre-receive hook](#prevent-conflicts-by-using-a-pre-receive-hook). + +## Configure a webhook to trigger an immediate pull to GitLab + +A [push event webhook](../../integrations/webhook_events.md#push-events) in the downstream +instance can help reduce race conditions by syncing changes more frequently. + +Prerequisites: + +- You have configured the [push](push.md#set-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) +and [pull](pull.md#pull-from-a-remote-repository) mirrors in the upstream GitLab instance. + +To create the webhook in the downstream instance: + +1. Create a [personal access token](../../../profile/personal_access_tokens.md) with `API` scope. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Webhooks**. +1. Add the webhook **URL**, which (in this case) uses the + [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) + request to trigger an immediate pull after a repository update: + + ```plaintext + https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> + ``` + +1. Select **Push Events**. +1. Select **Add Webhook**. + +To test the integration, select **Test** and confirm GitLab doesn't return an error message. + +## Prevent conflicts by using a pre-receive hook + +WARNING: +This solution negatively affects the performance of Git push operations, because +they are proxied to the upstream Git repository. + +In this configuration, one Git repository acts as the authoritative upstream, and +the other as downstream. This server-side `pre-receive` hook accepts a push only +after first pushing the commit to the upstream repository. Install this hook on +your downstream repository. + +For example: + +```shell +#!/usr/bin/env bash + +# --- Assume only one push mirror target +# Push mirroring remotes are named `remote_mirror_<id>`. +# This line 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 + allowlist=$(expr "$branch" : "\(master\)") + + case "$refname" in + refs/heads/*) + branch=$(expr "$refname" : "refs/heads/\(.*\)") + + if [ "$allowlist" = "$branch" ]; then + # handle https://git-scm.com/docs/git-receive-pack#_quarantine_environment + unset GIT_QUARANTINE_PATH + 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. It is possible for some refs + # to succeed, and others to fail. This results in a failed push. + while read oldrev newrev refname + do + proxy_push $oldrev $newrev $refname + done +fi +``` + +This sample has a few limitations: + +- It may not work for your use case without modification: + - It doesn't regard different types of authentication mechanisms for the mirror. + - It doesn't work with forced updates (rewriting history). + - Only branches that match the `allowlist` patterns are proxy pushed. +- The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` + is seen as a ref update, and Git displays warnings about it. + +## Mirror with Perforce Helix via Git Fusion **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. + +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). GitLab can use the Perforce Helix +interface to bidirectionally mirror projects. It can help when migrating from Perforce Helix +to GitLab, if overlapping Perforce Helix workspaces cannot be migrated simultaneously. + +If you mirror with Perforce Helix, mirror only protected branches. Perforce Helix +rejects any pushes that rewrite history. Only the fewest number of branches should be mirrored +due to the performance limitations of Git Fusion. + +When you configure mirroring with Perforce Helix by using Git Fusion, we recommend these Git Fusion +settings: + +- Disable `change-pusher`. Otherwise, every commit is rewritten as being committed + by the mirroring account, rather than mapping to existing Perforce Helix users or the `unknown_git` user. +- Use the `unknown_git` user as the commit author, if the GitLab user doesn't 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). + +## Related topics + +- [Configure server hooks](../../../../administration/server_hooks.md) on a GitLab server. diff --git a/doc/user/project/repository/img/repository_mirroring_copy_ssh_public_key_button.png b/doc/user/project/repository/mirror/img/repository_mirroring_copy_ssh_public_key_button.png Binary files differindex e20dae09a4d..e20dae09a4d 100644 --- a/doc/user/project/repository/img/repository_mirroring_copy_ssh_public_key_button.png +++ b/doc/user/project/repository/mirror/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/mirror/img/repository_mirroring_force_update.png Binary files differindex 1e6dcb9ea08..1e6dcb9ea08 100644 --- a/doc/user/project/repository/img/repository_mirroring_force_update.png +++ b/doc/user/project/repository/mirror/img/repository_mirroring_force_update.png diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md new file mode 100644 index 00000000000..4532a80c2f5 --- /dev/null +++ b/doc/user/project/repository/mirror/index.md @@ -0,0 +1,224 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' +--- + +# Repository mirroring **(FREE)** + +Repository mirroring allows for the mirroring of repositories to and from external sources. You +can use it to mirror branches, tags, and commits between repositories. It helps you use +a repository outside of GitLab. + +A repository mirror at GitLab updates automatically. You can also manually trigger an update: + +- At most once every five minutes on GitLab.com. +- According to a [limit set by the administrator](../../../../administration/instance_limits.md#pull-mirroring-interval) + on self-managed instances. + +There are two kinds of repository mirroring supported by GitLab: + +- [Push](push.md): for mirroring a GitLab repository to another location. +- [Pull](pull.md): for mirroring a repository from another location to GitLab. + +When the mirror repository is updated, all new branches, tags, and commits are visible in the +project's activity feed. + +Users with the [Maintainer role](../../../permissions.md) for the project can also force an +immediate update, unless: + +- The mirror is already being updated. +- The [limit for pull mirroring interval seconds](../../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed after its last update. + +For security reasons, the URL to the original repository is only displayed to users with the +[Maintainer role](../../../permissions.md) or the [Owner role](../../../permissions.md) for the mirrored +project. + +## Use cases + +The following are some possible use cases for repository mirroring: + +- You migrated to GitLab but still must keep your project in another source. In that case, you + can set it up to mirror to GitLab (pull) and all the essential history of commits, tags, + and branches are available in your GitLab instance. **(PREMIUM)** +- 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. +- You are a GitLab self-managed user for privacy reasons and your instance is closed to the public, + but you still have certain software components that you want open sourced. In this case, utilizing + GitLab to be your primary repository which is closed from the public, and using push mirroring to a + GitLab.com repository that's public, allows you to open source specific projects and contribute back + to the open source community. + +## Mirror only protected branches **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. + +Based on the mirror direction that you choose, you can opt to mirror only the +[protected branches](../../protected_branches.md) in the mirroring project, +either from or to your remote repository. For pull mirroring, non-protected branches in +the mirroring project are not mirrored and can diverge. + +To use this option, check the **Only mirror protected branches** box when +creating a repository mirror. **(PREMIUM)** + +## SSH authentication + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. + +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 (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](../../deploy_keys/index.md). + +To get started: + +1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. +1. Enter an `ssh://` URL for mirroring. + +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 select the: + +- **Detect host keys** button, GitLab fetches 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 must 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://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) +- [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/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 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: + +```shell +$ 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: +You must exclude `-E md5` for some older versions of SSH. + +When mirroring the repository, GitLab checks 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 must also 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 selecting the **Copy SSH public key** button. + + + +You then must 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](../../../project/deploy_keys/index.md). +- If the other repository is hosted elsewhere, you must 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 must change the key at any time, you can remove and re-add the mirror +to generate a new key. Update the other repository with the new +key to keep the mirror running. + +NOTE: +The generated keys are stored in the GitLab database, not in the file system. Therefore, +SSH public key authentication for mirrors cannot be used in a pre-receive hook. + +## Force an update **(FREE)** + +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. + + + +## Resources + +- Configure a [Pull Mirroring Interval](../../../../administration/instance_limits.md#pull-mirroring-interval) +- [Disable mirrors for a project](../../../admin_area/settings/visibility_and_access_controls.md#enable-project-mirroring) +- [Secrets file and mirroring](../../../../raketasks/backup_restore.md#when-the-secrets-file-is-lost) + +## Troubleshooting + +Should an error occur during a push, GitLab displays 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 a "13:Received RST_STREAM with error code 2" message 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. + +### 4:Deadline Exceeded + +When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you +must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. + +### Connection blocked because server only allows public key authentication + +As the error indicates, the connection is getting blocked between GitLab and the remote repository. Even if a +[TCP Check](../../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) is successful, +you must check any networking components in the route from GitLab to the remote Server to ensure there's no blockage. + +For example, we've seen this error when a Firewall was performing a `Deep SSH Inspection` on outgoing packets. + +### Could not read username: terminal prompts disabled + +If you receive this error after creating a new project using +[GitLab CI/CD for external repositories](../../../../ci/ci_cd_for_external_repos/): + +```plaintext +"2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': terminal prompts disabled\n": exit status 128." +``` + +Check if the repository owner is specified in the URL of your mirrored repository: + +1. Go to your project. +1. On the left sidebar, select **Settings > Repository**. +1. Select **Mirroring repositories**. +1. If no repository owner is specified, delete and add the URL again in this format: + + ```plaintext + https://**<repo_owner>**@bitbucket.org/<accountname>/<reponame>.git + ``` + +The repository owner is needed for Bitbucket to connect to the repository for mirroring. + +### Pull mirror is missing LFS files + +In some cases, pull mirroring does not transfer LFS files. This issue occurs when: + +- You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. + There is [an issue to fix this for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). +- You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. + This was [fixed in GitLab 14.0.6](https://gitlab.com/gitlab-org/gitlab/-/issues/335123). +- You mirror an external repository using object storage. + There is [an issue to fix this](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md new file mode 100644 index 00000000000..d1943cbfd71 --- /dev/null +++ b/doc/user/project/repository/mirror/pull.md @@ -0,0 +1,121 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' +--- + +# Pull from a remote repository **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. + +You can use the GitLab interface to browse the content and activity of a repository, +even if it isn't hosted on GitLab. Create a pull [mirror](index.md) to copy the +branches, tags, and commits from an upstream repository to yours. + +Unlike [push mirrors](push.md), pull mirrors retrieve changes from an upstream (remote) +repository on a scheduled basis. To prevent the mirror from diverging from the upstream +repository, don't push commits directly to the downstream mirror. Push commits to +the upstream repository instead. Changes in the remote repository are pulled into the GitLab repository, either: + +- Automatically in a certain period of time. Self-managed instances can + configure [pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval). +- When an administrator [force-updates the mirror](index.md#force-an-update). +- When an [API call triggers an update](#trigger-an-update-by-using-the-api). + +By default, if any branch or tag on the downstream pull mirror diverges from the +local repository, GitLab stops updating the branch. This prevents data loss. +Deleted branches and tags in the upstream repository are not reflected in the +downstream repository. + +## How pull mirroring works + +After you configure a GitLab repository as a pull mirror: + +1. GitLab adds the repository to a queue. +1. Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on: + - Available capacity, determined by Sidekiq settings. For GitLab.com, read + [GitLab.com Sidekiq settings](../../../gitlab_com/index.md#sidekiq). + - How many mirrors are already in the queue and due for updates. Being due depends + on when the repository mirror was last updated, and how many times updates have been retried. +1. Sidekiq becomes available to process updates, mirrors are updated. If the update process: + - **Succeeds**: An update is enqueued again with at least a 30 minute wait. + - **Fails**: The update is attempted again later. After 14 failures, a mirror is marked as a + [hard failure](#hard-failure) and is no longer enqueued for updates. A branch diverging + from its upstream counterpart can cause failures. To prevent branches from + diverging, configure [Overwrite diverged branches](#overwrite-diverged-branches) when + you create your mirror. + +## Configure pull mirroring + +Prerequisite: + +- If your remote repository is on GitHub and you have + [two-factor authentication (2FA) configured](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa), + create a [personal access token for GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) + with the `repo` scope. If 2FA is enabled, this personal access + token serves as your GitHub password. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. Enter the **Git repository URL**. Include the username + in the URL, if required: `https://MYUSERNAME@github.com/GROUPNAME/PROJECTNAME.git` +1. In **Mirror direction**, select **Pull**. +1. In **Authentication method**, select your authentication method. +1. Select any of the options you need: + - [**Overwrite diverged branches**](#overwrite-diverged-branches) + - [**Trigger pipelines for mirror updates**](#trigger-pipelines-for-mirror-updates) + - **Only mirror protected branches** +1. To save the configuration, select **Mirror repository**. + +### Overwrite diverged branches + +> Moved to GitLab Premium in 13.9. + +To always update your local branches with remote versions, even if they have +diverged from the remote, select **Overwrite diverged branches** when you +create a mirror. + +WARNING: +For mirrored branches, enabling this option results in the loss of local changes. + +### Trigger pipelines for mirror updates + +> Moved to GitLab Premium in 13.9. + +If this option is enabled, pipelines trigger when branches or tags are +updated from the remote repository. Depending on the activity of the remote +repository, this may greatly increase the load on your CI runners. Only enable +this feature if you know they can handle the load. CI uses the credentials +assigned when you set up pull mirroring. + +## Trigger an update by using the API + +> Moved to GitLab Premium in 13.9. + +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), +updates are pulled immediately. + +For more information, read +[Start the pull mirroring process for a project](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). + +## Hard failure + +> Moved to GitLab Premium in 13.9. + +After 14 consecutive unsuccessful retries, the mirroring process is marked as a hard failure +and mirroring attempts stop. This failure is visible in either the: + +- Project's main dashboard. +- Pull mirror settings page. + +You can resume the project mirroring again by [forcing an update](index.md#force-an-update). + +## Related topics + +- Configure [pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) + on self-managed instances. +- Configure [pull mirroring through the API](../../../../api/projects.md#configure-pull-mirroring-for-a-project). diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md new file mode 100644 index 00000000000..498b8d063a9 --- /dev/null +++ b/doc/user/project/repository/mirror/push.md @@ -0,0 +1,197 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' +--- + +# Push mirroring **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in GitLab 13.5: LFS support over HTTPS. + +A _push mirror_ is a downstream repository that [mirrors](index.md) the commits made +to the upstream repository. Push mirrors passively receive copies of the commits made to the +upstream repository. To prevent the mirror from diverging from the upstream +repository, don't push commits directly to the downstream mirror. Push commits to +the upstream repository instead. + +While [pull mirroring](pull.md) periodically retrieves updates from the upstream repository, +push mirrors only receive changes when: + +- Commits are pushed to the upstream GitLab repository. +- An administrator [force-updates the mirror](index.md#force-an-update). + +When you push a change to the upstream repository, the push mirror receives it: + +- Within five minutes. +- Within one minute, if you enabled **Only mirror protected branches**. + +In the case of a diverged branch, an error displays in the **Mirroring repositories** +section. + +## Configure push mirroring + +To set up push mirroring for an existing project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. Enter a repository URL. +1. In the **Mirror direction** dropdown list, select **Push**. +1. Select an **Authentication method**. + You can authenticate with either a password or an [SSH key](index.md#ssh-authentication). +1. Select **Only mirror protected branches**, if necessary. +1. Select **Keep divergent refs**, if desired. +1. To save the configuration, select **Mirror repository**. + +### Configure push mirrors through the API + +You can also create and modify project push mirrors through the +[remote mirrors API](../../../../api/remote_mirrors.md). + +## Keep divergent refs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. + +By default, if any ref (branch or tag) on the remote (downstream) mirror diverges from the +local repository, the upstream repository overwrites any changes on the remote: + +1. A repository mirrors `main` and `develop` branches to a remote. +1. A new commit is added to `develop` on the remote mirror. +1. The next push updates the remote mirror to match the upstream repository. +1. The new commit added to `develop` on the remote mirror is lost. + +If **Keep divergent refs** is selected, the changes are handled differently: + +1. Updates to the `develop` branch on the remote mirror are skipped. +1. The `develop` branch on the remote mirror preserves the commit that does not + exist on the upstream repository. Any refs that exist in the remote mirror, + but not the upstream, are left untouched. +1. The update is marked failed. + +After you create a mirror, you can only modify the value of **Keep divergent refs** +through the [remote mirrors API](../../../../api/remote_mirrors.md). + +## Set up a push mirror from GitLab to GitHub + +To configure a mirror from GitLab to GitHub: + +1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) + with `public_repo` selected. +1. Enter a **Git repository URL** with this format: + `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. +1. For **Password**, enter your GitHub personal access token. +1. Select **Mirror repository**. + +The mirrored repository is listed. For example: + +```plaintext +https://*****:*****@github.com/<your_github_group>/<your_github_project>.git +``` + +The repository pushes shortly thereafter. To force a push, select **Update now** (**{retry}**). + +## Set up a push mirror from GitLab to AWS CodeCommit + +AWS CodeCommit push mirroring is the best way to connect GitLab repositories to +AWS CodePipeline. GitLab is not yet supported as one of their Source Code Management (SCM) providers. +Each new AWS CodePipeline needs significant AWS infrastructure setup. It also +requires an individual pipeline per branch. + +If AWS CodeDeploy is the final step of a CodePipeline, you can, instead combine +these tools to create a deployment: + +- GitLab CI/CD pipelines. +- The AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. + +NOTE: +GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. + +To set up a mirror from GitLab to AWS CodeCommit: + +1. In the AWS IAM console, create an IAM user. +1. Add the following least privileges permissions for repository mirroring as an **inline policy**. + + The Amazon Resource Names (ARNs) must explicitly include the region and account. This IAM policy + grants privilege for mirroring access to two sample repositories. These permissions have + been tested to be the minimum (least privileged) required for mirroring: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "MinimumGitLabPushMirroringPermissions", + "Effect": "Allow", + "Action": [ + "codecommit:GitPull", + "codecommit:GitPush" + ], + "Resource": [ + "arn:aws:codecommit:us-east-1:111111111111:MyDestinationRepo", + "arn:aws:codecommit:us-east-1:111111111111:MyDemo*" + ] + } + ] + } + ``` + +1. After the user is created, select the AWS IAM user name. +1. Select the **Security credentials** tab. +1. Under **HTTPS Git credentials for AWS CodeCommit**, select **Generate credentials**. + + NOTE: + This Git user ID and password is specific to communicating with CodeCommit. Do + not confuse it with the IAM user ID or AWS keys of this user. + +1. Copy or download the special Git HTTPS user ID and password. +1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository. +1. Open your new repository, and then select **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). +1. In GitLab, open the repository to be push-mirrored. +1. On the left sidebar, select **Settings > Repository**, and then expand **Mirroring repositories**. +1. Fill in the **Git repository URL** field using this format: + + ```plaintext + https://<your_aws_git_userid>@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> + ``` + + Replace `<your_aws_git_userid>` with the AWS **special HTTPS Git user ID** + from the IAM Git credentials created earlier. Replace `<your_codecommit_repo>` + with the name of your repository in CodeCommit. + +1. For **Mirror direction**, select **Push**. +1. For **Authentication method**, select **Password**. Fill in the **Password** box + with the special IAM Git clone user ID **password** created earlier in AWS. +1. Leave the option **Only mirror protected branches** for CodeCommit. It pushes more + frequently (from every five minutes to every minute). + + CodePipeline requires individual pipeline setups for named branches you want + to have a AWS CI setup for. Because feature branches with dynamic names are unsupported, + configuring **Only mirror protected branches** doesn't cause flexibility problems + with CodePipeline integration. You must also protect all the named branches you + want to build CodePipelines for. + +1. Select **Mirror repository**. You should see the mirrored repository appear: + + ```plaintext + https://*****:*****@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> + ``` + +To test mirroring by forcing a push, select **Update now** (the half-circle arrows). +If **Last successful update** shows a date, you have configured mirroring correctly. +If it isn't working correctly, a red `error` tag appears, and shows the error message as hover text. + +## Set 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 `write_repository` scope. +1. On the source GitLab instance: + 1. Enter the **Git repository URL** using this format: + `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. + 1. Enter the **Password**. Use the GitLab personal access token created on the + destination GitLab instance. + 1. Select **Mirror repository**. + +## Related topics + +- [Remote mirrors API](../../../../api/remote_mirrors.md). diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 81429ea5384..0094e0b1b15 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -63,6 +63,12 @@ To purge files from a GitLab repository: git clone --bare --mirror /path/to/project.bundle ``` +1. Navigate to the `project.git` directory: + + ```shell + cd project.git + ``` + 1. Using `git filter-repo`, purge any files from the history of your repository. Because we are trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us which internal refs to remove. diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 5a02a35fce1..8fbe5aec6a3 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -1,635 +1,9 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' +redirect_to: 'mirror/index.md' +remove_date: '2022-03-22' --- -# Repository mirroring **(FREE)** +This document was moved to [another location](mirror/index.md). -Repository mirroring allows for the mirroring of repositories to and from external sources. You -can use it to mirror branches, tags, and commits between repositories. It helps you use -a repository outside of GitLab. - -A repository mirror at GitLab updates automatically. You can also manually trigger an update: - -- At most once every five minutes on GitLab.com. -- According to a [limit set by the administrator](../../../administration/instance_limits.md#pull-mirroring-interval) - on self-managed instances. - -There are two kinds of repository mirroring supported by GitLab: - -- [Push](#push-to-a-remote-repository): for mirroring a GitLab repository to another location. -- [Pull](#pull-from-a-remote-repository): for mirroring a repository from another location to GitLab. - -When the mirror repository is updated, all new branches, tags, and commits are visible in the -project's activity feed. - -Users with the [Maintainer role](../../permissions.md) for the project can also force an -immediate update, unless: - -- The mirror is already being updated. -- The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. - -For security reasons, the URL to the original repository is only displayed to users with the -[Maintainer role](../../permissions.md) or the [Owner role](../../permissions.md) for the mirrored -project. - -## 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 set it up to mirror to GitLab (pull) and all the essential history of commits, tags, - and branches are available in your GitLab instance. **(PREMIUM)** -- 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. -- You are a GitLab self-managed user for privacy reasons and your instance is closed to the public, - but you still have certain software components that you want open sourced. In this case, utilizing - GitLab to be your primary repository which is closed from the public, and using push mirroring to a - GitLab.com repository that's public, allows you to open source specific projects and contribute back - to the open source community. - -## Push to a remote repository - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in GitLab 13.5: LFS support over HTTPS. - -For an existing project, you can set up push mirroring as follows: - -1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. -1. Enter a repository URL. -1. In the **Mirror direction** dropdown, select **Push**. -1. Select an authentication method from the **Authentication method** dropdown. - You can authenticate with either a password or an [SSH key](#ssh-authentication). -1. Select the **Only mirror protected branches** checkbox, if necessary. -1. Select the **Keep divergent refs** checkbox, if desired. -1. Select **Mirror repository** to save the configuration. - -When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the -mirror diverging. - -Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. -The mirrored repository receives all changes only when: - -- Commits are pushed to GitLab. -- A [forced update](#force-an-update) 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, an error displays in the **Mirroring repositories** -section. - -### Configure push mirrors through the API - -You can also create and modify project push mirrors through the -[remote mirrors API](../../../api/remote_mirrors.md). - -### Keep divergent refs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0. - -By default, if any ref (branch or tag) on the remote mirror has diverged from the local repository, the local differences are forced to the remote. - -For example, if a repository has `main` and `develop` branches that -have been mirrored to a remote, and then a new commit is added to `develop` on -the remote mirror. The next push updates all of the references on the remote mirror to match -the local repository, and the new commit added to the remote `develop` branch is lost. - -With the **Keep divergent refs** option enabled, the `develop` branch is -skipped, causing only `main` to be updated. The mirror status -reflects that `develop` has diverged and was skipped, and be marked as a -failed update. Refs that exist in the mirror repository but not in the local -repository are left untouched. - -NOTE: -After the mirror is created, this option can only be modified via the [API](../../../api/remote_mirrors.md). - -### Set up a push mirror from GitLab to GitHub - -To set up a mirror from GitLab to GitHub, you need to follow these steps: - -1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) 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. Select **Mirror repository**. - -The mirrored repository is listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. - -The repository pushes shortly thereafter. To force a push, select the **Update now** (**{retry}**) button. - -### Set up a push mirror from GitLab to AWS CodeCommit - -AWS CodeCommit push mirroring is the best way to connect GitLab repositories to -AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. - -Each new AWS CodePipeline needs significant AWS infrastructure setup. It also -requires an individual pipeline per branch. - -If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage -GitLab CI/CD pipelines and use the AWS CLI in the final job in `.gitlab-ci.yml` -to deploy to CodeDeploy. - -NOTE: -GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. - -To set up a mirror from GitLab to AWS CodeCommit: - -1. In the AWS IAM console, create an IAM user. -1. Add the following least privileges permissions for repository mirroring as an "inline policy". - - The Amazon Resource Names (ARNs) must explicitly include the region and account. The IAM policy - below grants privilege for mirroring access to two sample repositories. These permissions have - been tested to be the minimum (least privileged) required for mirroring: - - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "MinimumGitLabPushMirroringPermissions", - "Effect": "Allow", - "Action": [ - "codecommit:GitPull", - "codecommit:GitPush" - ], - "Resource": [ - "arn:aws:codecommit:us-east-1:111111111111:MyDestinationRepo", - "arn:aws:codecommit:us-east-1:111111111111:MyDemo*" - ] - } - ] - } - ``` - -1. After the user was created, select the AWS IAM user name. -1. Select the **Security credentials** tab. -1. Under **HTTPS Git credentials for AWS CodeCommit** select **Generate credentials**. - - NOTE: - This Git user ID and password is specific to communicating with CodeCommit. Do - not confuse it with the IAM user ID or AWS keys of this user. - -1. Copy or download special Git HTTPS user ID and password. -1. In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository. -1. Open your new repository, and then select **Clone URL > Clone HTTPS** (not **Clone HTTPS (GRC)**). -1. In GitLab, open the repository to be push-mirrored. -1. Go to **Settings > Repository**, and then expand **Mirroring repositories**. -1. Fill in the **Git repository URL** field using this format: - - ```plaintext - https://<your_aws_git_userid>@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> - ``` - - Replace `<your_aws_git_userid>` with the AWS **special HTTPS Git user ID** from the IAM Git - credentials created earlier. Replace `<your_codecommit_repo>` with the name of your repository in CodeCommit. - -1. For **Mirror direction**, select **Push**. -1. For **Authentication method**, select **Password** and fill in the **Password** field with the special IAM Git clone user ID **password** created earlier in AWS. -1. The option **Only mirror protected branches** should be good for CodeCommit as it pushes more - frequently (from every five minutes to every minute). - CodePipeline requires individual pipeline setups for named branches you wish to have a AWS CI setup for. Because feature branches that have dynamic names are unsupported, configuring **Only mirror protected branches** doesn't cause flexibility problems with CodePipeline integration as long as you are also willing to protect all the named branches you want to build CodePipelines for. - -1. Select **Mirror repository**. You should see the mirrored repository appear: - - ```plaintext - https://*****:*****@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo> - ``` - -To test mirroring by forcing a push, select the half-circle arrows button (hover text is **Update now**). -If **Last successful update** shows a date, you have configured mirroring correctly. -If it isn't working correctly, a red `error` tag appears and shows the error message as hover text. - -### Set 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 `write_repository` 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 the **Password** field with the GitLab personal access token created on the destination GitLab instance. - 1. Select **Mirror repository**. - -## Pull from a remote repository **(PREMIUM)** - -> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in GitLab 11.11. -> - Moved to GitLab Premium in 13.9. - -You can set up a repository to automatically have its branches, tags, and commits updated from an -upstream repository. - -If a repository you're interested in is located on a different server, and you want -to browse its content and its activity using the GitLab interface, you can configure -mirror pulling: - -1. If your remote repository is on GitHub and you have - [two-factor authentication (2FA) configured](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa), - create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). - with the `repo` scope. If 2FA is enabled, this personal access - token serves as your GitHub password. -1. In your project, go to **Settings > Repository**, and then expand the - **Mirroring repositories** section. -1. In the **Git repository URL** field, enter a repository URL. Include the username - in the URL if required: `https://MYUSERNAME@github.com/group/PROJECTNAME.git` -1. In the **Mirror direction** dropdown, select **Pull**. -1. In the **Authentication method** dropdown, select your authentication method. -1. Select from the following checkboxes, if needed: - - **Overwrite diverged branches** - - **Trigger pipelines for mirror updates** - - **Only mirror protected branches** -1. Select **Mirror repository** 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 remote repository. -Changes pushed to the remote repository are pulled into the GitLab repository, either: - -- Automatically in a certain period of time. -- When a [forced update](#force-an-update) is initiated. - -WARNING: -If you do manually update a branch in the GitLab repository, the branch becomes diverged from -upstream, and GitLab no longer automatically updates this branch to prevent any changes from being lost. -Deleted branches and tags in the upstream repository are not reflected in the GitLab repository. - -### How it works - -After 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 is enqueued again with at least a 30 minute wait. -- **Fails**: (For example, a branch diverged from upstream.), The update attempted again later. Mirrors can fail - up to 14 times before they are no longer enqueued for updates. - -### Overwrite diverged branches **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -You can choose to always update your local branches with remote versions, even if they have -diverged from the remote. - -WARNING: -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. - -### Trigger pipelines for mirror updates **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -If this option is enabled, pipelines trigger when branches or tags are -updated from the remote repository. Depending on the activity of the remote -repository, this may greatly increase the load on your CI runners. Only enable -this if you know they can handle the load. CI uses the credentials -assigned when you set up pull mirroring. - -### Hard failure **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -After 14 consecutive unsuccessful retries, the mirroring process is marked as a hard failure -and mirroring attempts stop. This failure is visible in either the: - -- Project's main dashboard. -- Pull mirror settings page. - -You can resume the project mirroring again by [forcing an update](#force-an-update). - -### Trigger an update using the API **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -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), -updates are 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). - -## Mirror only protected branches **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -Based on the mirror direction that you choose, you can opt to mirror only the -[protected branches](../protected_branches.md) in the mirroring project, -either from or to your remote repository. For pull mirroring, non-protected branches in -the mirroring project are not mirrored and can diverge. - -To use this option, check the **Only mirror protected branches** box when -creating a repository mirror. **(PREMIUM)** - -## SSH authentication - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. - -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 (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](../deploy_keys/index.md). - -To get started: - -1. In your project, go to **Settings > Repository**, and then expand the **Mirroring repositories** section. -1. Enter an `ssh://` URL for mirroring. - -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 select the: - -- **Detect host keys** button, GitLab fetches 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://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) -- [GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/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 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: - -```shell -$ 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: -You may need to exclude `-E md5` for some older versions of SSH. - -When mirroring the repository, GitLab checks 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 must also 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 selecting 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](../../project/deploy_keys/index.md). -- 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. Update the other repository with the new -key to keep the mirror running. - -NOTE: -The generated keys are stored in the GitLab database, not in the file system. Therefore, -SSH public key authentication for mirrors cannot be used in a pre-receive hook. - -## Force an update **(FREE)** - -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 **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -WARNING: -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 updates correctly. If you set up a repository for -bidirectional mirroring, you should prepare for the likely conflicts by deciding who resolves -them and how. - -Rewriting any mirrored commit on either remote causes conflicts and mirroring to fail. This can -be prevented by [mirroring only protected branches](#mirror-only-protected-branches). - -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. - -### Configure a webhook to trigger an immediate pull to GitLab - -Assuming you have already configured the [push](#set-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) -and [pull](#pull-from-a-remote-repository) mirrors in the upstream GitLab instance, to trigger an -immediate pull as suggested above, you must configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) -in the downstream instance. - -To do this: - -1. Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. -1. In your project, go to **Settings > Webhooks**. -1. Add the webhook URL which (in this case) uses the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) - request to trigger an immediate pull after updates to the repository. - - ```plaintext - https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> - ``` - -1. Ensure the **Push Events** checkbox is selected. -1. Select **Add Webhook** to save the webhook. - -To test the integration, select the **Test** button and confirm GitLab doesn't return an error message. - -### Prevent conflicts using a pre-receive hook - -WARNING: -The solution proposed negatively affects the performance of -Git push operations because they are 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 -is installed on the downstream repository. - -Read about [configuring Server hooks](../../../administration/server_hooks.md) on the GitLab server. - -A sample `pre-receive` hook is provided below. - -```shell -#!/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 - allowlist=$(expr "$branch" : "\(master\)") - - case "$refname" in - refs/heads/*) - branch=$(expr "$refname" : "refs/heads/\(.*\)") - - if [ "$allowlist" = "$branch" ]; then - unset GIT_QUARANTINE_PATH # handle https://git-scm.com/docs/git-receive-pack#_quarantine_environment - 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 -``` - -Note that this sample has a few limitations: - -- This example may not work verbatim for your use case and might need modification. - - It doesn't regard different types of authentication mechanisms for the mirror. - - It doesn't work with forced updates (rewriting history). - - Only branches that match the `allowlist` patterns are proxy pushed. -- The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` - is seen as a ref update, and Git displays warnings about it. - -### Mirror with Perforce Helix via Git Fusion **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -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 can help you 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 -rejects 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 is 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 is used as the commit author if the GitLab user doesn't 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 displays 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 a "13:Received RST_STREAM with error code 2" message 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. - -### 4:Deadline Exceeded - -When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you -may need to update your mirroring username and password to ensure that `%40` characters are replaced with `@`. - -### Connection blocked because server only allows public key authentication - -As the error indicates, the connection is getting blocked between GitLab and the remote repository. Even if a -[TCP Check](../../../administration/raketasks/maintenance.md#check-tcp-connectivity-to-a-remote-site) is successful, -you must check any networking components in the route from GitLab to the remote Server to ensure there's no blockage. - -For example, we've seen this error when a Firewall was performing a `Deep SSH Inspection` on outgoing packets. - -### Could not read username: terminal prompts disabled - -If you receive this error after creating a new project using -[GitLab CI/CD for external repositories](../../../ci/ci_cd_for_external_repos/): - -```plaintext -"2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org': terminal prompts disabled\n": exit status 128." -``` - -Check if the repository owner is specified in the URL of your mirrored repository: - -1. Go to your project. -1. On the left sidebar, select **Settings > Repository**. -1. Select **Mirroring repositories**. -1. If no repository owner is specified, delete and add the URL again in this format: - - ```plaintext - https://**<repo_owner>**@bitbucket.org/<accountname>/<reponame>.git - ``` - -The repository owner is needed for Bitbucket to connect to the repository for mirroring. - -### Pull mirror is missing LFS files - -In some cases, pull mirroring does not transfer LFS files. This issue occurs when: - -- You use an SSH repository URL. The workaround is to use an HTTPS repository URL instead. - There is [an issue to fix this for SSH URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/11997). -- You're using GitLab 14.0 or older, and the source repository is a public Bitbucket URL. - This was [fixed in GitLab 14.0.6](https://gitlab.com/gitlab-org/gitlab/-/issues/335123). -- You mirror an external repository using object storage. - There is [an issue to fix this](https://gitlab.com/gitlab-org/gitlab/-/issues/335495). +<!-- This redirect file can be deleted after <2022-03-22>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 3be3b1682bb..661bd3e0598 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -7,8 +7,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Requirements Management **(ULTIMATE)** +NOTE: +In 14.4, Requirements was moved under **Issues**. + > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. > - The ability to add and edit a requirement's long description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224622) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. +> - [Moved under Issues](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70748) in 14.4 With requirements, you can set criteria to check your products against. They can be based on users, stakeholders, system, software, or anything else you find important to capture. @@ -38,7 +42,7 @@ Users with Reporter or higher [permissions](../../permissions.md) can create req To create a requirement: -1. In a project, go to **Requirements**. +1. In a project, go to **Issues > Requirements**. 1. Select **New requirement**. 1. Enter a title and description and select **Create requirement**. @@ -107,7 +111,7 @@ You can search for a requirement from the requirements list page based on the fo To search for a requirement: -1. In a project, go to **Requirements > List**. +1. In a project, go to **Issues > Requirements > List**. 1. Select the **Search or filter results** field. A dropdown menu appears. 1. Select the requirement author or status from the dropdown or enter plain text to search by requirement title. 1. Press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -222,7 +226,7 @@ Before you import your file: To import requirements: -1. In a project, go to **Requirements**. +1. In a project, go to **Issues > Requirements**. - If the project already has existing requirements, select the import icon (**{import}**) in the top right. - For a project without any requirements, select **Import CSV** in the middle of the page. @@ -281,7 +285,7 @@ Users with Reporter or higher [permissions](../../permissions.md) can export req To export requirements: -1. In a project, go to **Requirements**. +1. In a project, go to **Issues > Requirements**. 1. In the top right, select the **Export as CSV** icon (**{export}**). A confirmation modal appears. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 69215e03f28..6c3bf731cf8 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -141,6 +141,11 @@ The following items are **not** exported: - Merge Request Approvers - Repository size limits +These content rules also apply to creating projects from templates on the +[group](../../group/custom_project_templates.md) +or [instance](../../admin_area/custom_project_templates.md) +levels, because the same export and import mechanisms are used. + NOTE: For more details on the specific data persisted in a project export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file. @@ -221,6 +226,15 @@ GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) ## Troubleshooting +### Project fails to import due to mismatch + +If the [shared runners enablement](../../../ci/runners/runners_scope.md#enable-shared-runners) +does not match between the exported project, and the project import, the project fails to import. +Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and either: + +- Ensure shared runners are enabled in both the source and destination projects. +- Disable shared runners on the parent group when you import the project. + ### Import workaround for large repositories [Maximum import size limitations](#import-the-project) @@ -258,7 +272,7 @@ reduce the repository size for another import attempt. git gc --prune=now --aggressive # Prepare recreating an importable file - git bundle create ../project.bundle smaller-tmp-main + git bundle create ../project.bundle <default-branch-name> cd .. mv project/ ../"$EXPORT"-project cd .. @@ -276,3 +290,29 @@ reduce the repository size for another import attempt. its [default branch](../repository/branches/default.md), and delete the temporary, `smaller-tmp-main` branch, and the local, temporary data. + +### Manually execute export steps + +Exports sometimes fail without giving enough information to troubleshoot. In these cases, it can be +helpful to [execute the export process manually within rails](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/uncategorized/project-export.md#export-a-project-via-rails-console). +Execute each line individually, rather than pasting the entire block at once, so you can see any +errors each command returns. + +```shell +u = User.find_by_username('someuser') +p = Project.find_by_full_path('some/project') +e = Projects::ImportExport::ExportService.new(p,u) + +e.send(:version_saver).send(:save) +e.send(:avatar_saver).send(:save) +e.send(:project_tree_saver).send(:save) +e.send(:uploads_saver).send(:save) +e.send(:wiki_repo_saver).send(:save) +e.send(:lfs_saver).send(:save) +e.send(:snippets_repo_saver).send(:save) +e.send(:design_repo_saver).send(:save) + +s = Gitlab::ImportExport::Saver.new(exportable: p, shared:p.import_export_shared) +s.send(:compress_and_save) +s.send(:save_upload) +``` diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 8b159a75451..30def6ae80f 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Workspace info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, index, howto --- @@ -39,17 +39,19 @@ You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#li > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. -You can create a framework label to identify that your project has certain compliance requirements -or needs additional oversight. +You can create a compliance framework label to identify that your project has certain compliance +requirements or needs additional oversight. The label can optionally apply +[compliance pipeline configuration](#compliance-pipeline-configuration). Group owners can create, edit, and delete compliance frameworks: -1. Go to the group's **Settings** > **General**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings** > **General**. 1. Expand the **Compliance frameworks** section. -Compliance frameworks created can then be assigned to any number of projects using: +Compliance frameworks created can then be assigned to projects within the group using: -- The project settings page inside the group or subgroups. +- The GitLab UI, using the project settings page. - In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) and later, using the [GraphQL API](../../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework). @@ -64,24 +66,32 @@ read-only view to discourage this behavior. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. -Group owners can use the compliance pipeline configuration to define compliance requirements -such as scans or tests, and enforce them in individual projects. +Group owners can use compliance pipeline configuration to add additional pipeline configuration to +projects to define compliance requirements such as scans or tests. -The [custom compliance framework](#compliance-frameworks) feature allows group owners to specify the location -of a compliance pipeline configuration stored and managed in a dedicated project, distinct from a developer's project. +[Compliance frameworks](#compliance-frameworks) allow group owners to specify the location of +compliance pipeline configuration stored and managed in dedicated projects, separate from regular +projects. -When you set up the compliance pipeline configuration field, use the -`file@group/project` format. For example, you can configure -`.compliance-gitlab-ci.yml@compliance-group/compliance-project`. -This field is inherited by projects where the compliance framework label is applied. The result -forces the project to run the compliance configurations. +When you set up the compliance framework, use the **Compliance pipeline configuration** box to link +the compliance framework to specific CI/CD configuration. Use the +`path/file.y[a]ml@group-name/project-name` format. For example: -When a project with a custom label executes a pipeline, it begins by evaluating the compliance pipeline configuration. -The custom pipeline configuration can then execute any included individual project configuration. +- `.compliance-ci.yml@gitlab-org/gitlab`. +- `.compliance-ci.yaml@gitlab-org/gitlab`. -The user running the pipeline in the project should at least have Reporter access to the compliance project. +This configuration is inherited by projects where the compliance framework label is applied. The +result forces projects with the label to run the compliance CI/CD configuration in addition to +the project's own CI/CD configuration. When a project with a compliance framework label executes a +pipeline, it evaluates configuration in the following order: -Example `.compliance-gitlab-ci.yml` +1. Compliance pipeline configuration. +1. Project-specific pipeline configuration. + +The user running the pipeline in the project must at least have the Reporter role on the compliance +project. + +Example `.compliance-gitlab-ci.yml`: ```yaml # Allows compliance team to control the ordering and interweaving of stages/jobs. @@ -94,10 +104,10 @@ stages: - deploy - post-compliance -variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml +variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml FOO: sast -sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml +sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml variables: FOO: sast image: ruby:2.6 @@ -144,10 +154,10 @@ audit trail: after_script: - "# No after scripts." -include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) +include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) project: '$CI_PROJECT_PATH' file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch. + ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch. ``` ##### Ensure compliance jobs are always run @@ -182,6 +192,20 @@ cannot change them: This ensures that your job uses the settings you intend and that they are not overridden by project-level pipelines. +##### Avoid parent and child pipelines + +Compliance pipelines start on the run of _every_ pipeline in a relevant project. This means that if a pipeline in the relevant project +triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. + +Therefore, in projects with compliance frameworks, we recommend replacing +[parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md) with the following: + +- Direct [`include`](../../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. +- Child pipelines placed in another project that are run using the [trigger API](../../../ci/triggers/) rather than the parent-child + pipeline feature. + +This alternative ensures the compliance pipeline does not re-start the parent pipeline. + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 010a63b7957..71cf0c03549 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -26,7 +26,7 @@ and from merge requests: 1. Select **Edit in Web IDE** to open the editor. - *When viewing a merge request* - 1. Go to your merge request, and select the **Overview** tab. - 1. Scroll to the widgets area, after the merge request description. + 1. Scroll to the widgets section, after the merge request description. 1. Select **Edit in Web IDE** if it is visible. 1. If **Edit in Web IDE** is not visible: 1. Select the **(angle-down)** next to **Open in Gitpod**. @@ -231,7 +231,7 @@ left. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. To switch between your authored and assigned merge requests, click the -dropdown in the top of the sidebar to open a list of merge requests. You need to commit or discard all your changes before switching to a different merge +dropdown in the top of the sidebar to open a list of merge requests. You must commit or discard all your changes before switching to a different merge request. ## Switching branches @@ -240,7 +240,7 @@ request. To switch between branches of the current project repository, click the dropdown in the top of the sidebar to open a list of branches. -You need to commit or discard all your changes before switching to a +You must commit or discard all your changes before switching to a different branch. ## Markdown editing @@ -324,7 +324,7 @@ An example `package.json`: WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. GitLab.com shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), -so you would need to use your own private runner to make use of this feature. +so you must use your own private runner to make use of this feature. [Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) give the project [Maintainers](../../permissions.md#project-members-permissions) @@ -333,14 +333,14 @@ GitLab, including through the Web IDE. ### Runner configuration -Some things need to be configured in the runner for the interactive web terminal +Some things must be configured in the runner for the interactive web terminal to work: - The runner needs to have [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). This section requires at least a `session_timeout` value (which defaults to 1800 seconds) and a `listen_address` value. If `advertise_address` is not defined, `listen_address` is used. -- If you are using a reverse proxy with your GitLab instance, web terminals need to be +- If you are using a reverse proxy with your GitLab instance, web terminals must be [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE SELF)** If you have the terminal open and the job has finished with its tasks, the @@ -355,7 +355,7 @@ The [File Sync](#file-syncing-to-web-terminal) feature is supported on Kubernete ### Web IDE configuration file -In order to enable the Web IDE terminals you need to create the file +To enable the Web IDE terminals you must create the file `.gitlab/.gitlab-webide.yml` inside the repository's root. This file is fairly similar to the [CI configuration file](../../../ci/yaml/index.md) syntax but with some restrictions: @@ -456,7 +456,7 @@ terminal: ``` - The `webide-file-sync` executable must start **after** the project - directory is available. This is why we need to add `sleep 5` to the `command`. + directory is available. This is why we must add `sleep 5` to the `command`. See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/-/issues/7) for more information. - `$CI_PROJECT_DIR` is a diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index d0a1f485fa8..e2a8167b14c 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -13,8 +13,14 @@ in each GitLab project. Every wiki is a separate Git repository, so you can crea wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). To access the wiki for a project or group, go to the page for your project or group -and, in the left sidebar, select **Wiki**. If **Wiki** is not listed in the -left sidebar, a project administrator has [disabled it](#enable-or-disable-a-project-wiki). +and either: + +- In the left sidebar, select **Wiki**. +- On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> + [wiki keyboard shortcut](../../shortcuts.md). + +If **Wiki** is not listed in the left sidebar of your project, a project administrator +has [disabled it](#enable-or-disable-a-project-wiki). GitLab wikis support Markdown, RDoc, AsciiDoc, and Org for content. Wiki pages written in Markdown support all [Markdown features](../../markdown.md), @@ -130,8 +136,9 @@ may not be able to check out the wiki locally afterward. You need at least the [Developer role](../../permissions.md) to edit a wiki page: 1. Go to your project or group and select **Wiki**. -1. Go to the page you want to edit. -1. Select the edit icon (**{pencil}**). +1. Go to the page you want to edit, and either: + - Use the <kbd>e</kbd> wiki [keyboard shortcut](../../shortcuts.md#wiki-pages). + - Select the edit icon (**{pencil}**). 1. Edit the content. 1. Select **Save changes**. @@ -142,7 +149,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need at least the [Maintainer role](../../permissions.md) to delete a wiki page: +You need at least the [Developer role](../../permissions.md) to delete a wiki page: 1. Go to your project or group and select **Wiki**. 1. Go to the page you want to delete. @@ -355,3 +362,4 @@ For the status of the ongoing development for CommonMark and GitLab Flavored Mar - [Project wikis API](../../../api/wikis.md) - [Group repository storage moves API](../../../api/group_repository_storage_moves.md) - [Group wikis API](../../../api/group_wikis.md) +- [Wiki keyboard shortcuts](../../shortcuts.md#wiki-pages) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 32bb202767a..11b570f19e5 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Workspace info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- @@ -165,7 +165,7 @@ To push a new project: As project creation permissions can have many factors, contact your GitLab administrator if you're unsure. -1. If you want to push using SSH, ensure you have [created a SSH key](../../ssh/README.md) and +1. If you want to push using SSH, ensure you have [created a SSH key](../../ssh/index.md) and [added it to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). 1. Push with one of the following methods. Replace `gitlab.example.com` with the domain name of the machine that hosts your Git repository, `namespace` with the name of @@ -187,6 +187,12 @@ You can view your new project at `https://gitlab.example.com/namespace/myproject Your project's visibility is set to **Private** by default, but you can change it in your [project's settings](../../public_access/public_access.md#change-project-visibility)). +This feature does not work for project paths that have previously been in use and +[renamed](settings/index.md#renaming-a-repository). A redirect exists over the previous project path +that causes push attempts to redirect requests to the renamed project location, instead of creating +a new project. To create a new project, use the [Web UI](#create-a-project) or the +[Projects API](../../api/projects.md#create-project). + ## Fork a project A fork is a copy of an original repository that you put in another namespace diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index bf9abcca640..203b1c9e93a 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Manage +group: Workspace info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 37e89dd54db..f46c5428248 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -39,7 +39,7 @@ These shortcuts are available in most areas of GitLab: | <kbd>Shift</kbd> + <kbd>s</kbd> | Go to your Snippets page. | | <kbd>s</kbd> / <kbd>/</kbd> | Put cursor in the search bar. | | <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>m</kbd> | Go to your [Merge requests](project/merge_requests/index.md) page. | | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to your To-Do List page. | | <kbd>p</kbd> + <kbd>b</kbd> | Show or hide the Performance Bar. | | <kbd>g</kbd> + <kbd>x</kbd> | Toggle between [GitLab](https://gitlab.com/) and [GitLab Next](https://next.gitlab.com/) (GitLab SaaS only). | @@ -77,17 +77,17 @@ relatively quickly to work, and they take you to another page in the project. | <kbd>g</kbd> + <kbd>i</kbd> | Go to the project issues list (**Issues > List**). | | <kbd>i</kbd> | Go to the New Issue page (**Issues**, select **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>m</kbd> | Go to the project [merge requests](project/merge_requests/index.md) 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 (**Monitor > Metrics**). | | <kbd>g</kbd> + <kbd>e</kbd> | Go to the project environments (**Deployments > Environments**). | | <kbd>g</kbd> + <kbd>k</kbd> | Go to the project Kubernetes cluster integration page (**Infrastructure > Kubernetes clusters**). 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. | +| <kbd>g</kbd> + <kbd>w</kbd> | Go to the [project wiki](project/wiki/index.md) (**Wiki**), if enabled. | ### Issues and merge requests -These shortcuts are available when viewing issues and merge requests: +These shortcuts are available when viewing issues and [merge requests](project/merge_requests/index.md): | Keyboard shortcut | Description | |------------------------------|-------------| diff --git a/doc/user/todos.md b/doc/user/todos.md index f0601db0300..9a985664ed1 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -7,8 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # To-Do List **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2817) in GitLab 8.5. - Your *To-Do List* is a chronological list of items waiting for your input. The items are known as *to-do items*. @@ -67,8 +65,6 @@ You can manually add an item to your To-Do List. ## Create a to-do item by directly addressing someone -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7926) in GitLab 9.0. - You can create a to-do item by directly addressing someone at the start of a line. For example, in the following comment: diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 07a5eda8cfb..5a48353c9d4 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -5,7 +5,7 @@ group: Utilization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Storage usage quota **(FREE SAAS)** +# Storage usage quota **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in GitLab 12.0. > - Moved to GitLab Free. @@ -18,29 +18,27 @@ you must purchase additional storage. For more details, see [Excess storage usag ## View storage usage -To help manage storage, a namespace's owner can view: +You can view storage usage for your project or [namespace](../user/group/#namespaces). -- Total storage used in the namespace -- Total storage used per project +1. Go to your project or namespace: + - For a project, on the top bar, select **Menu > Projects** and find your project. + - For a namespace, enter the URL in your browser's toolbar. +1. From the left sidebar, select **Settings > Usage Quotas**. +1. Select the **Storage** tab. -To view storage usage, from the namespace's page go to **Settings > Usage Quotas** and select the -**Storage** tab. The Usage Quotas statistics are updated every 90 minutes. +The statistics are displayed. Select any title to view details. The information on this page +is updated every 90 minutes. -If your namespace shows `N/A` as the total storage usage, push a commit to any project in that -namespace to trigger a recalculation. - -A stacked bar graph shows the proportional storage used for the namespace, including a total per -storage item. Click on each project's title to see a breakdown per storage item. +If your namespace shows `N/A`, push a commit to any project in the +namespace to recalculate the storage. ## Storage usage statistics -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247831) in GitLab 13.7. -> - It's [deployed behind a feature flag](../user/feature_flags.md), enabled by default. -> - It's enabled on GitLab SaaS. -> - It's recommended for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68898) project-level graph in GitLab 14.4 [with a flag](../administration/feature_flags.md) named `project_storage_ui`. Disabled by default. +> - Enabled on GitLab.com in GitLab 14.4. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `project_storage_ui`. On GitLab.com, this feature is available. The following storage usage statistics are available to an owner: diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 2ce30c645d5..d75d91f087d 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -6,24 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Workspace -Workspace will be above the [top-level namespaces](../group/index.md#namespaces) for you to manage everything you can do as a GitLab administrator, including: +Workspace will be above the [top-level namespaces](../group/index.md#namespaces) for you to manage +everything you do as a GitLab administrator, including: - Defining and applying settings to all of your groups, subgroups, and projects. - Aggregating data from all your groups, subgroups, and projects. -The functionality in the [Admin Area](../admin_area/index.md) of self-managed installations will be split up and go to: +Our goal is to reach feature parity between SaaS and self-managed installations, with all +[Admin Area settings](/ee/user/admin_area/settings/) moving to either: -1. Groups (available in the Workspace, Top-level group namespaces, and Sub-groups) -1. Hardware Controls (for functionality that does not apply to groups) - -Our goal is to reach feature parity between SaaS and Self-Managed installations, with all [Admin Area settings](/ee/user/admin_area/settings/) moving to either: - -- Workspace (contains features relevant to both GitLab-managed and self-managed installations) with a dedicated Settings menu available within the left navigation bar. -- Hardware controls (only contains features relative to Self-Managed installations, with one per installation). +- Groups. Available in the Workspace, top-level group namespaces, and sub-groups. +- Hardware Controls. For functionality that does not apply to groups, Hardware Controls are only + applicable to self-managed installations. There is one Hardware Controls section per installation. NOTE: Workspace is currently in development. +## Demo: New hierarchy concept for groups and projects for epics + +The following demo introduces the new hierarchy concept for groups and projects for epics. + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/embed/fE74lsG_8yM">Consolidating groups and projects update (2021-08-23)</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/fE74lsG_8yM" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + ## Concept previews The following provide a preview to the Workspace concept. |
