diff options
Diffstat (limited to 'doc/user')
181 files changed, 2543 insertions, 1673 deletions
diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index de2856c2320..847f687d051 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -16,7 +16,7 @@ when you go to **New project > Create from template** and select the **Instance* Every project in the group, but not its subgroups, can be selected when a new project is created, based on the user's access permissions: -- Public projects can be selected by any signed-in user as a template for a new project, +- Public projects can be selected by any authenticated user as a template for a new project, if all enabled [project features](../project/settings/index.md#configure-project-visibility-features-and-permissions) except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. The same applies to internal projects. diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index c9b6a077c73..559aae63da5 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -135,8 +135,7 @@ For each user, the following are listed: 1. Date of account creation 1. Date of last activity -To edit a user, select the **Edit** button in that user's -row. To delete the user, or delete the user and their contributions, select the cog dropdown list in +To edit a user, in the user's row, select **Edit**. To delete the user, or delete the user and their contributions, select the cog dropdown list in that user's row, and select the desired option. To change the sort order: @@ -256,9 +255,7 @@ To access the Groups page: 1. On the left sidebar, select **Overview > Groups**. For each group, the page displays their name, description, size, number of projects in the group, -number of members, and whether the group is private, internal, or public. To edit a group, select -the **Edit** button in that group's row. To delete the group, select the **Delete** button in -that group's row. +number of members, and whether the group is private, internal, or public. To edit a group, in the group's row, select **Edit**. To delete the group, in the group's row, select **Delete**. To change the sort order, select the sort dropdown list and select the desired order. The default sort order is by **Last created**. @@ -300,33 +297,32 @@ The assigned topics are visible only to everyone with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. -### Administering Jobs +### Administering Gitaly servers -You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. +You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** +page. For more details, see [Gitaly](../../administration/gitaly/index.md). -To access the Jobs page: +To access the **Gitaly Servers** page: 1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. -1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** - tab to list only jobs of that status. +1. On the left sidebar, select **Overview > Gitaly Servers**. -For each job, the following details are listed: +For each Gitaly server, the following details are listed: -| Field | Description | -|----------|-------------| -| Status | Job status, either **passed**, **skipped**, or **failed**. | -| Job | Includes links to the job, branch, and the commit that started the job. | -| Pipeline | Includes a link to the specific pipeline. | -| Project | Name of the project, and organization, to which the job belongs. | -| Runner | Name of the CI runner assigned to execute the job. | -| Stage | Stage that the job is declared in a `.gitlab-ci.yml` file. | -| Name | Name of the job specified in a `.gitlab-ci.yml` file. | -| Timing | Duration of the job, and how long ago the job completed. | -| Coverage | Percentage of tests coverage. | +| Field | Description | +|----------------|-------------| +| Storage | Repository storage | +| Address | Network address on which the Gitaly server is listening | +| Server version | Gitaly version | +| Git version | Version of Git installed on the Gitaly server | +| Up to date | Indicates if the Gitaly server version is the latest version available. A green dot indicates the server is up to date. | + +## CI/CD section ### Administering runners +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/340859) from **Overview > Runners** to **CI/CD > Runners** in GitLab 15.8. + You can administer all runners in the GitLab instance from the Admin Area's **Runners** page. See [GitLab Runner](https://docs.gitlab.com/runner/) for more information. @@ -380,25 +376,32 @@ For each runner, the following attributes are listed: You can also edit, pause, or remove each runner. -### Administering Gitaly servers +### Administering Jobs -You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** -page. For more details, see [Gitaly](../../administration/gitaly/index.md). +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/386311) from **Overview > Jobs** to **CI/CD > Jobs** in GitLab 15.8. -To access the **Gitaly Servers** page: +You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. + +To access the Jobs page: 1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Overview > Gitaly Servers**. +1. On the left sidebar, select **CI/CD > Jobs**. All jobs are listed, in descending order of job ID. +1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** + tab to list only jobs of that status. -For each Gitaly server, the following details are listed: +For each job, the following details are listed: -| Field | Description | -|----------------|-------------| -| Storage | Repository storage | -| Address | Network address on which the Gitaly server is listening | -| Server version | Gitaly version | -| Git version | Version of Git installed on the Gitaly server | -| Up to date | Indicates if the Gitaly server version is the latest version available. A green dot indicates the server is up to date. | +| Field | Description | +|----------|-------------| +| Status | Job status, either **passed**, **skipped**, or **failed**. | +| Job | Includes links to the job, branch, and the commit that started the job. | +| Pipeline | Includes a link to the specific pipeline. | +| Project | Name of the project, and organization, to which the job belongs. | +| Runner | Name of the CI runner assigned to execute the job. | +| Stage | Stage that the job is declared in a `.gitlab-ci.yml` file. | +| Name | Name of the job specified in a `.gitlab-ci.yml` file. | +| Timing | Duration of the job, and how long ago the job completed. | +| Coverage | Percentage of tests coverage. | ## Monitoring section diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md index 9c35a8c1269..29e43476819 100644 --- a/doc/user/admin_area/license_file.md +++ b/doc/user/admin_area/license_file.md @@ -75,7 +75,7 @@ and issue creation. Your instance becomes read-only and an expiration message displays to all administrators. You have a 14-day grace period before this occurs. -To resume functionality, [renew your subscription](../../subscriptions/self_managed/index.md#renew-a-subscription). +To resume functionality, [renew your subscription](../../subscriptions/self_managed/index.md#renew-subscription-manually). If the license has been expired for more than 30 days, you must purchase a [new subscription](../../subscriptions/self_managed/index.md) to resume functionality. @@ -187,7 +187,7 @@ License.current.data #### Check if a project feature is available on the instance -Features listed in <https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/license.rb>. +Features listed in [`features.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/gitlab_subscriptions/features.rb). ```ruby License.current.feature_available?(:jira_dev_panel_integration) @@ -195,7 +195,7 @@ License.current.feature_available?(:jira_dev_panel_integration) #### Check if a project feature is available in a project -Features listed in [`license.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/license.rb). +Features listed in [`features.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/models/gitlab_subscriptions/features.rb). ```ruby p = Project.find_by_full_path('<group>/<project>') diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index c0daf029b1f..3d96eaf793f 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -142,7 +142,7 @@ A deactivated user: - Cannot access Git repositories or the API. - Does not receive any notifications from GitLab. -- Does not be able to use [slash commands](../../integration/slash_commands.md). +- Cannot use [slash commands](../../integration/slash_commands.md). - Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). Personal projects, and group and user history of the deactivated user are left intact. @@ -223,7 +223,7 @@ 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 `ban_user_feature_flag`. On GitLab.com, this feature is available to GitLab.com administrators only. -GitLab administrators can ban and unban users. Banned users are blocked, and their issues are hidden. +GitLab administrators can ban and unban users. Banned users are blocked, and their issues and merge requests are hidden. The banned user's comments are still displayed. Hiding a banned user's comments is [tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327356). ### Ban a user diff --git a/doc/user/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md index f700b8b1ea3..66d1173058e 100644 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ b/doc/user/admin_area/reporting/git_abuse_rate_limit.md @@ -4,12 +4,12 @@ group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Git abuse rate limit (administration) **(ULTIMATE SELF)** +# Git abuse rate limit (administration) **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `git_abuse_rate_limit_feature_flag`. Disabled by default. 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 `git_abuse_rate_limit_feature_flag`. On GitLab.com, this feature is not available. +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 `git_abuse_rate_limit_feature_flag`. On GitLab.com, this feature is available. Git abuse rate limiting is a feature to automatically [ban users](../moderate_users.md#ban-and-unban-users) who download or clone more than a specified number of repositories in any project in the instance within a given time frame. Banned users cannot sign in to the instance and cannot access any non-public group via HTTP or SSH. diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index b235b812416..7f678344955 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -102,7 +102,8 @@ to find tokens more quickly, or for use with automation tools. The default prefix is `glpat-` but administrators can change it. -[Project access tokens](../../project/settings/project_access_tokens.md) also inherit this prefix. +[Project access tokens](../../project/settings/project_access_tokens.md) and +[group access tokens](../../group/settings/group_access_tokens.md) also inherit this prefix. ### Set a prefix @@ -291,6 +292,16 @@ By default, new users can create top-level groups. GitLab administrators can pre 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Clear the **Allow new users to create top-level groups** checkbox. +## Set profiles of new users to private by default + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231301) in GitLab 15.8. + +By default, newly created users have a public profile. GitLab administrators can set new users to have a private profile by default: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. Select the **Make new users' profiles private by default** checkbox. + ## Troubleshooting ### 413 Request Entity Too Large diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 81e51aaef37..7c869c9b8fe 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -52,7 +52,7 @@ you can assign that runner to other projects. To enable a specific runner for more than one project: 1. On the top bar, select **Main menu > Admin**. -1. From the left sidebar, select **Overview > Runners**. +1. From the left sidebar, select **CI/CD > Runners**. 1. Select the runner you want to edit. 1. In the top right, select **Edit** (**{pencil}**). 1. Under **Restrict projects for this runner**, search for a project. @@ -188,7 +188,7 @@ For the value set for GitLab.com, see [Scheduled job archiving](../../gitlab_com ## Protect CI/CD variables by default To set all new [CI/CD variables](../../../ci/variables/index.md) as -[protected](../../../ci/variables/index.md#protected-cicd-variables) by default: +[protected](../../../ci/variables/index.md#protect-a-cicd-variable) by default: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 8d0fef398af..07d3ae83d74 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -27,7 +27,7 @@ You can now see the message on `/help`. NOTE: By default, `/help` is visible to unauthenticated users. However, if the [**Public** visibility level](visibility_and_access_controls.md#restrict-visibility-levels) -is restricted, `/help` is visible only to signed-in users. +is restricted, `/help` is visible only to authenticated users. ## Add a help message to the sign-in page diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index bf07c5b2808..026782ae83b 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -13,7 +13,7 @@ type: reference In hosted systems, enterprises often have a need to share their own templates across teams. This feature allows an administrator to pick a project to be the instance-wide collection of file templates. These templates are then exposed to -all users [via the web editor](../../project/repository/web_editor.md#template-dropdowns) +all users through the [Web Editor](../../project/repository/web_editor.md) while the project remains secure. ## Configuration @@ -28,7 +28,7 @@ To select a project to serve as the custom template repository: 1. Add custom templates to the selected repository. After you add templates, you can use them for the entire instance. -They are available in the [Web Editor's dropdown list](../../project/repository/web_editor.md#template-dropdowns) +They are available in the [Web Editor](../../project/repository/web_editor.md) and through the [API settings](../../../api/settings.md). ## Supported file types and locations diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 6ec3d082114..d663238a88c 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -68,7 +68,7 @@ For more information, see the [list of settings that can be accessed through API Open the [Rails console](../../../administration/operations/rails_console.md) and run the following: ```ruby -::Gitlab::CurrentSettings.update!(admin_mode true) +::Gitlab::CurrentSettings.update!(admin_mode: true) ``` #### Use the UI to enable Admin Mode @@ -115,6 +115,9 @@ authentication steps. We may address these limitations in the future. For more information see the following epic: [Admin Mode for GitLab Administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158). +Also, when GitLab Geo is enabled, you can't view the replication status of projects and designs while +on a secondary node. A fix is proposed when projects ([issue 367926](https://gitlab.com/gitlab-org/gitlab/-/issues/367926)) and designs ([issue 355660](https://gitlab.com/gitlab-org/gitlab/-/issues/355660)) move to the new Geo framework. + ### Troubleshooting Admin Mode If necessary, you can disable **Admin Mode** as an administrator by using one of these two methods: diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 9a02e50b23f..85927bad8ad 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -29,7 +29,7 @@ For each update to the terms, a new version is stored. When a user accepts or de GitLab records which version they accepted or declined. Existing users must accept the terms on their next GitLab interaction. -If a signed-in user declines the terms, they are signed out. +If an authenticated user declines the terms, they are signed out. When enabled, it adds a mandatory checkbox to the sign up page for new users: diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 8d2ae72ba69..4f6e727f673 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index df60268a8bf..8b9f09d9df5 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -48,7 +48,7 @@ tier. Users can continue to access the features in a paid tier without sharing u ### Features available in 14.4 and later - [Repository size limit](../settings/account_and_limit_settings.md#repository-size-limit). -- [Group access restriction by IP address](../../group/access_and_permissions.md#restrict-access-to-groups-by-ip-address). +- [Group access restriction by IP address](../../group/access_and_permissions.md#restrict-group-access-by-ip-address). NOTE: Registration is not yet required for participation, but may be added in a future milestone. @@ -67,7 +67,7 @@ Registration is not yet required for participation, but may be added in a future 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`) -for all signed-in users, and on the Admin Area pages. The statuses are: +for all authenticated users, and on the Admin Area pages. The statuses are: - Green: You are running the latest version of GitLab. - Orange: An updated version of GitLab is available. 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 4da0f5da3f4..5ca942a42bb 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -118,7 +118,7 @@ To set the default [visibility levels for new projects](../../public_access.md): 1. Select the desired default project visibility: - **Private** - Project access must be granted explicitly to each user. If this project is part of a group, access is granted to members of the group. - - **Internal** - The project can be accessed by any logged in user except external users. + - **Internal** - The project can be accessed by any authenticated user except external users. - **Public** - The project can be accessed without any authentication. 1. Select **Save changes**. @@ -146,7 +146,7 @@ To set the default visibility levels for new groups: 1. Expand the **Visibility and access controls** section. 1. Select the desired default group visibility: - **Private** - The group and its projects can only be viewed by members. - - **Internal** - The group and any internal projects can be viewed by any logged in user except external users. + - **Internal** - The group and any internal projects can be viewed by any authenticated user except external users. - **Public** - The group and any public projects can be viewed without any authentication. 1. Select **Save changes**. @@ -163,7 +163,7 @@ To restrict visibility levels for projects, snippets, and selected pages: 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. If you restrict the **Public** level: - - User profiles are only visible to logged in users via the Web interface. + - User profiles are only visible to authenticated users via the Web interface. - User attributes via the GraphQL API are: - Not visible in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88020). - Only visible to authenticated users between [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33195) and GitLab 15.0. @@ -192,7 +192,25 @@ To enable the export of 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. -1. Select **Project export enabled**. +1. Scroll to **Project export**. +1. Select the **Enabled** checkbox. +1. Select **Save changes**. + +## Enable migration of groups and projects by direct transfer + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. + +You can enable migration of groups by direct transfer. To also migrate projects with the groups, you must enable the +[`bulk_import_projects` feature flag](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). + +To enable migration of groups by direct transfer: + +1. Sign in to GitLab as a user with Administrator access level. +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Scroll to **Allow migrating GitLab groups and projects by direct transfer**. +1. Select the **Enabled** checkbox. 1. Select **Save changes**. ## Configure enabled Git access protocols @@ -280,7 +298,7 @@ work in every repository. They can only be re-enabled by an administrator user o > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87579) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `group_ip_restrictions_allow_global`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) in GitLab 15.4. [Feature flag `group_ip_restrictions_allow_global`](https://gitlab.com/gitlab-org/gitlab/-/issues/366445) removed. -Administrators can set IP address ranges to be combined with [group-level IP restrictions](../../group/access_and_permissions.md#restrict-access-to-groups-by-ip-address). +Administrators can set IP address ranges to be combined with [group-level IP restrictions](../../group/access_and_permissions.md#restrict-group-access-by-ip-address). Use globally-allowed IP addresses to allow aspects of the GitLab installation to work even when group-level IP address restrictions are set. diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index fba0d0e98ff..9ac949f05b4 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -24,7 +24,7 @@ For software leaders, tracking velocity alongside quality metrics ensures they'r For an overview, see <a href="https://www.youtube.com/watch?v=1BrcMV6rCDw">GitLab Speed Run: DORA metrics in GitLab One DevOps Platform</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/1BrcMV6rCDw" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/1BrcMV6rCDw" frameborder="0" allowfullscreen> </iframe> </figure> ## DORA Metrics dashboard in Value Stream Analytics diff --git a/doc/user/analytics/img/devops_metrics_comparison_v15_8.png b/doc/user/analytics/img/devops_metrics_comparison_v15_8.png Binary files differnew file mode 100644 index 00000000000..3a52d9e0781 --- /dev/null +++ b/doc/user/analytics/img/devops_metrics_comparison_v15_8.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 38d92180c7d..774063810f3 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -51,6 +51,14 @@ The following analytics features are available for users to create personalized Be sure to review the documentation page for this feature for GitLab tier requirements. +## Value streams management + +You can use the following analytics features to analyze and visualize the performance of your projects and groups: + +- [Value stream analytics for projects](value_stream_analytics.md) +- [Value stream analytics for groups](../group/value_stream_analytics/index.md) +- [Value streams dashboard](value_streams_dashboard.md) + ## Definitions We use the following terms to describe GitLab analytics: diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md new file mode 100644 index 00000000000..1de26749deb --- /dev/null +++ b/doc/user/analytics/value_streams_dashboard.md @@ -0,0 +1,61 @@ +--- +stage: Plan +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Value Streams Dashboard **(PREMIUM)** + +> Introduced in GitLab 15.8 as a Closed [Beta](../../policy/alpha-beta-support.md#beta-features) feature. + +You can leave feedback on dashboard bugs or functionality in [issue 381787](https://gitlab.com/gitlab-org/gitlab/-/issues/381787). + +This feature is not ready for production use. + +The Value Streams Dashboard is a customizable dashboard to enable decision-makers to identify trends, patterns, and opportunities for digital transformation improvements. +This page is a work in progress, and we're updating the information as we add more features. +For more information, see the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). + +## Initial use case + +Our initial use case is focused on providing the ability to compare software delivery metrics. +This comparison can help decision-makers understand whether projects and groups are improving. + +The beta version of the Value Streams Dashboard includes the following metrics: + +- [DORA metrics](dora_metrics.md) +- [Value Stream Analytics (VSA) - flow metrics](value_stream_analytics.md) + +The Value Streams Dashboard allows you to: + +- Aggregate data records from different APIs. +- Track software performance (DORA) and flow of value (VSA) across the organization. + +## DevOps metrics comparison + +The DevOps metrics comparison displays DORA4 and flow metrics for a group or project in the +month-to-date, last month, the month before, and the past 180 days. + +This visualization helps you get a high-level custom view over multiple DevOps metrics and +understand whether they're improving month over month. You can compare the performance between +groups, projects, and teams at a glance. This visualization helps you identify the teams and projects +that are the largest value contributors, overperforming, or underperforming. + + + +You can also drill down the metrics for further analysis. +When you hover over a metric, a tooltip displays an explanation of the metric and a link to the related documentation page. + +## Customize the dashboard widgets + +You can customize the Value Streams Dashboard and configure what subgroups and projects to include in the page. + +A view can display maximum four subgroups or projects. + +To display multiple subgroups and projects, specify their path as a URL parameter. + +For example, the parameter `query=gitlab-org/gitlab-foss,gitlab-org/gitlab,gitlab-org/gitlab-design,gitlab-org/gitlab-docs` displays three separate widgets, one each for the: + +- `gitlab-org` group +- `gitlab-ui` project +- `gitlab-org/plan-stage` subgroup diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index e4ca512bdc6..31322419902 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -917,7 +917,7 @@ provide a script that performs an authentication flow or calculates the token. is an authentication method built into the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) +We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#for-a-project) for the password (for example, `TEST_API_PASSWORD`), and set it to be masked. You can create CI/CD variables from the GitLab project's page at **Settings > CI/CD**, in the **Variables** section. Because of the [limitations on masked variables](../../../ci/variables/index.md#mask-a-cicd-variable), @@ -965,7 +965,7 @@ outgoing HTTP requests. Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: -1. [Create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables), +1. [Create a CI/CD variable](../../../ci/variables/index.md#for-a-project), for example `TEST_API_BEARERAUTH`, with the value `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the @@ -1321,7 +1321,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#add-a-cicd-variable-to-an-instance): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui): ```yaml stages: diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index e198f967eea..fc06b50b03d 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -81,7 +81,7 @@ To enable container scanning in your pipeline, you need the following: - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the 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) +- [Build and push](../../packages/container_registry/build_and_push_images.md#use-gitlab-cicd) the Docker image to your project's container registry. - If you're using a third-party container registry, you might need to provide authentication credentials through the `CS_REGISTRY_USER` and `CS_REGISTRY_PASSWORD` [configuration variables](#available-cicd-variables). @@ -425,7 +425,7 @@ container_scanning: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. ### Vulnerability allowlisting **(ULTIMATE)** @@ -637,7 +637,7 @@ container_scanning: CS_IMAGE: "gcr.io/path-to-you-registry/image:tag" ``` -Before you commit this configuration, [add a CI/CD variable](../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) +Before you commit this configuration, [add a CI/CD variable](../../../ci/variables/index.md#for-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: diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index c04c07f561d..71c842ca277 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -159,16 +159,9 @@ the default option of one corpus per job. The corpus registry uses the package registry to store the project's corpuses. Corpuses stored in the registry are hidden to ensure data integrity. -In the GitLab UI, with corpus management you can: - -- View details of the corpus registry. -- Download a corpus. -- Delete a corpus. -- Create a new corpus. - When you download a corpus, the file is named `artifacts.zip`, regardless of the filename used when the corpus was initially uploaded. This file contains only the corpus, which is different to the -artifacts files you can download from the CI/CD pipeline. +artifacts files you can download from the CI/CD pipeline. Also, a project member with a Reporter or above privilege can download the corpus using the direct download link. ### View details of the corpus registry diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index d4f91639dbc..d5ba92f399c 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -110,7 +110,7 @@ dast: ``` Do **not** define `DAST_USERNAME` and `DAST_PASSWORD` in the YAML job definition file as this could present a security risk. Instead, create them as masked CI/CD variables using the GitLab UI. -See [Custom CI/CI variables](../../../ci/variables/index.md#custom-cicd-variables) for more information. +See [Custom CI/CI variables](../../../ci/variables/index.md#for-a-project) for more information. ### Configuration for a multi-step login form @@ -136,7 +136,7 @@ dast: ``` Do **not** define `DAST_USERNAME` and `DAST_PASSWORD` in the YAML job definition file as this could present a security risk. Instead, create them as masked CI/CD variables using the GitLab UI. -See [Custom CI/CI variables](../../../ci/variables/index.md#custom-cicd-variables) for more information. +See [Custom CI/CI variables](../../../ci/variables/index.md#for-a-project) for more information. ### Configuration for Single Sign-On (SSO) diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 7377f31d0ce..96480bcb6a5 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -7,11 +7,8 @@ type: reference, howto # DAST browser-based analyzer **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12. - -WARNING: -This product is in an early-access stage and is considered a [beta](../../../policy/alpha-beta-support.md#beta-features) -feature. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12 as a Beta feature. +> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/9023) in GitLab 15.7 (GitLab DAST v3.0.50). WARNING: Do not run DAST scans against a production server. Not only can it perform *any* function that @@ -173,7 +170,7 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_ADVERTISE_SCAN` | boolean | `true` | 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_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/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_ACTION_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action. | -| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | +| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. Headers set using `DAST_REQUEST_HEADERS` are added to every request made to these hostnames. | | `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | | `DAST_BROWSER_CRAWL_GRAPH` | boolean | `true` | Set to `true` to generate an SVG graph of navigation paths visited during crawl phase of the scan. | | `DAST_BROWSER_DEVTOOLS_LOG` | string | `Default:messageAndBody,truncate:2000` | Set to log protocol messages between DAST and the Chromium browser. | | @@ -193,7 +190,8 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/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_NAVIGATION_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another. | | `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_PAGE_READY_SELECTOR` | selector | `css:#page-is-ready` | Selector that when detected as visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. | +| `DAST_BROWSER_PAGE_LOADING_SELECTOR` | selector | `css:#page-is-loading` | Selector that when is no longer visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Cannot be used with `DAST_BROWSER_PAGE_READY_SELECTOR` | +| `DAST_BROWSER_PAGE_READY_SELECTOR` | selector | `css:#page-is-ready` | Selector that when detected as visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Cannot be used with `DAST_BROWSER_PAGE_LOADING_SELECTOR` | | `DAST_BROWSER_SCAN` | boolean | `true` | Required to be `true` to run a browser-based scan. | | `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or user actions. | | `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://pkg.go.dev/time#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis. | @@ -203,8 +201,8 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_PATHS` | string | `/page1.html,/category1/page3.html` | Set to a comma-separated list of URL paths relative to `DAST_WEBSITE` for DAST to scan. | | `DAST_PATHS_FILE` | string | `/builds/project/urls.txt` | Set to a file path containing a list of URL paths relative to `DAST_WEBSITE` for DAST to scan. The file must be plain text with one path per line. | | `DAST_PKCS12_CERTIFICATE_BASE64` | string | `ZGZkZ2p5NGd...` | The PKCS12 certificate used for sites that require Mutual TLS. Must be encoded as base64 text. | -| `DAST_PKCS12_PASSWORD` | string | `password` | The password of the certificate used in `DAST_PKCS12_CERTIFICATE_BASE64`. Create sensitive [custom CI/CI variables](../../../ci/variables/index.md#custom-cicd-variables) using the GitLab UI. | -| `DAST_REQUEST_HEADERS` | string | `Cache-control:no-cache` | Set to a comma-separated list of request header names and values. Headers are added to every request made to `DAST_BROWSER_ALLOWED_HOSTS` by DAST. | +| `DAST_PKCS12_PASSWORD` | string | `password` | The password of the certificate used in `DAST_PKCS12_CERTIFICATE_BASE64`. Create sensitive [custom CI/CI variables](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui) using the GitLab UI. | +| `DAST_REQUEST_HEADERS` | string | `Cache-control:no-cache` | Set to a comma-separated list of request header names and values. | | `DAST_SKIP_TARGET_CHECK` | boolean | `true` | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. | | `DAST_TARGET_AVAILABILITY_TIMEOUT` | number | `60` | Time limit in seconds to wait for target availability. | | `DAST_WEBSITE` | URL | `https://example.com` | The URL of the website to scan. | diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 63276eba871..4c324033140 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -828,7 +828,7 @@ provide a script that performs an authentication flow or calculates the token. is an authentication method built into the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables) +We recommended that you [create a CI/CD variable](../../../ci/variables/index.md#for-a-project) for the password (for example, `TEST_API_PASSWORD`), and set it to be masked. You can create CI/CD variables from the GitLab project's page at **Settings > CI/CD**, in the **Variables** section. Because of the [limitations on masked variables](../../../ci/variables/index.md#mask-a-cicd-variable), @@ -876,7 +876,7 @@ outgoing HTTP requests. Follow these steps to provide the Bearer token with `DAST_API_OVERRIDES_ENV`: -1. [Create a CI/CD variable](../../../ci/variables/index.md#custom-cicd-variables), +1. [Create a CI/CD variable](../../../ci/variables/index.md#for-a-project), for example `TEST_API_BEARERAUTH`, with the value `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the @@ -1271,7 +1271,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#add-a-cicd-variable-to-an-instance): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui): ```yaml stages: @@ -1528,7 +1528,7 @@ variables: ### Example: Using a masked CI/CD variable -The following `.gitlab-ci.yml` sample assumes the [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable) `SECRET_REQUEST_HEADERS_BASE64` is defined as a [group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#add-a-cicd-variable-to-an-instance). The value of `SECRET_REQUEST_HEADERS_BASE64` is set to `WC1BQ01FLVNlY3JldDogc31jcnt0ISwgWC1BQ01FLVRva2VuOiA3MDVkMTZmNWUzZmI=`, which is the Base64-encoded text version of `X-ACME-Secret: s3cr3t!, X-ACME-Token: 705d16f5e3fb`. Then, it can be used as follows: +The following `.gitlab-ci.yml` sample assumes the [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable) `SECRET_REQUEST_HEADERS_BASE64` is defined as a [group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui). The value of `SECRET_REQUEST_HEADERS_BASE64` is set to `WC1BQ01FLVNlY3JldDogc31jcnt0ISwgWC1BQ01FLVRva2VuOiA3MDVkMTZmNWUzZmI=`, which is the Base64-encoded text version of `X-ACME-Secret: s3cr3t!, X-ACME-Token: 705d16f5e3fb`. Then, it can be used as follows: ```yaml stages: diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index e4466dffd56..d13c4cecdf4 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -7,17 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning Analyzers **(ULTIMATE)** -Dependency Scanning relies on underlying third-party tools that are wrapped into -what we call "Analyzers". An analyzer is a -[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) -that wraps a particular tool to: - -- Expose its detection logic. -- Handle its execution. -- Convert its output to the common format. - -This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common). - Dependency Scanning supports the following official analyzers: - [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) @@ -27,8 +16,6 @@ Dependency Scanning supports the following official analyzers: The analyzers are published as Docker images, which Dependency Scanning uses to launch dedicated containers for each analysis. -The Dependency Scanning analyzers' current major version number is 2. - Dependency Scanning is pre-configured with a set of **default images** that are maintained by GitLab, but users can also integrate their own **custom images**. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index a4957c96db4..8106201cb99 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -198,13 +198,13 @@ table.supported-languages ul { <tr> <td rowspan="2">Java</td> <td rowspan="2"> - 8, - 11, + 8 LTS, + 11 LTS, 13<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, 14<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, 15<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, 16<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, - or 17 + or 17 LTS </td> <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-2">2</a></b></sup></td> <td> @@ -295,7 +295,7 @@ table.supported-languages ul { <li> <a id="notes-regarding-supported-languages-and-package-managers-1"></a> <p> - This version of Java is not supported by the FIPS-enabled image of <code>gemnasium-maven</code>. + Support for these versions of Java is deprecated and is planned to be removed in the GitLab 16.0 release. Additionally, these versions of Java are not supported by the FIPS-enabled image of <code>gemnasium-maven</code>. Official support is limited to LTS versions only. Although it may be possible to use Dependency Scanning with other versions by building a custom dependency scanning image, this approach is not officially supported by GitLab. </p> </li> <li> @@ -353,16 +353,16 @@ GitLab analyzers obtain dependency information using one of the following two me The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: -| Package Manager | Supported File Format Versions | Tested Versions | -| ------ | ------ | ------ | -| Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | -| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock) | -| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | -| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | -| npm | v1, v2 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4) | -| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | -| Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v3/qa/fixtures/python-poetry/default/poetry.lock) | +| Package Manager | Supported File Format Versions | Tested Versions | +| ------ | ------ | ------ | +| Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | +| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | +| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | +| NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | +| npm | v1, v2, v3 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | +| yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | +| Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | <!-- markdownlint-disable MD044 --> <ol> @@ -383,21 +383,27 @@ To support the following package managers, the GitLab analyzers proceed in two s 1. Execute the package manager or a specific task, to export the dependency information. 1. Parse the exported dependency information. -| Package Manager | Pre-installed Versions | Tested Versions | -| ------ | ------ | ------ | -| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L443-447), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L449-453), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L455-459), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L461-465), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L467-471), [1.5.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L473-477), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L479-483) | -| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L95-97) | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L95-97) | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.26.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L319-323), [6.7](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L286-288)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [6.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L331-335), [7.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.28.1/spec/image_spec.rb#L300-302)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L224-247) | -| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L77-91) | -| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L168-191)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L143-166) | -| Go | [1.17](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/7dc7a892b564abfcb160189f46b2ae6415e0dffa/build/gemnasium/alpine/Dockerfile#L88-91) | [1.17](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/7dc7a892b564abfcb160189f46b2ae6415e0dffa/build/gemnasium/alpine/Dockerfile#L88-91)<sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> | +| Package Manager | Pre-installed Versions | Tested Versions | +| ------ | ------ | ------ | +| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L445-449), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L451-455), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L457-461), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L463-467), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L469-473), [1.5.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L475-479), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L481-485) | +| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L95-97)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | +| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L314-319), [6.7](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L321-326), [6.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L328-333), [7.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L335-339) | +| setuptools | [58.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17) | [>= 65.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/spec/gemnasium-python_image_spec.rb#L249-271) | +| pip | [22.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L88-102) | +| Pipenv | [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/requirements.txt#L13) | [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L186-210)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L161-183) | +| Go | [1.18](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91) | [1.18](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91)<sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> | <!-- markdownlint-disable MD044 --> <ol> <li> <a id="exported-dependency-information-notes-1"></a> <p> + This test uses the default version of <code>maven</code> specified by the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3">.tool-versions</a> file. + </p> + </li> + <li> + <a id="exported-dependency-information-notes-2"></a> + <p> Different versions of Java require different versions of Gradle. The versions of Gradle listed in the above table are pre-installed in the analyzer image. The version of Gradle used by the analyzer depends on whether your project uses a <code>gradlew</code> (Gradle wrapper) file or not: @@ -423,12 +429,6 @@ To support the following package managers, the GitLab analyzers proceed in two s </ul> </li> <li> - <a id="exported-dependency-information-notes-2"></a> - <p> - These tests confirm that if a <code>gradlew</code> file does not exist, the version of <code>Gradle</code> pre-installed in the analyzer image is used. - </p> - </li> - <li> <a id="exported-dependency-information-notes-3"></a> <p> This test confirms that if a <code>Pipfile.lock</code> file is found, it will be used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. @@ -654,7 +654,7 @@ The following variables are used for configuring specific analyzers (used for a | `DS_INCLUDE_DEV_DEPENDENCIES` | `gemnasium` | `"true"` | When set to `"false"`, development dependencies and their vulnerabilities are not reported. Only NPM and Poetry projects are supported. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227861) in GitLab 15.1. | | `GOOS` | `gemnasium` | `"linux"` | The operating system for which to compile Go code. | | `GOARCH` | `gemnasium` | `"amd64"` | The architecture of the processor for which to compile Go code. | -| `GOFLAGS` | `gemansium` | | The flags passed to the `go build` tool. | +| `GOFLAGS` | `gemnasium` | | The flags passed to the `go build` tool. | | `GOPRIVATE` | `gemnasium` | | A list of glob patterns and prefixes to be fetched from source. Read the Go private modules [documentation](https://go.dev/ref/mod#private-modules) for more information. | #### Other variables @@ -662,7 +662,7 @@ The following variables are used for configuring specific analyzers (used for a The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they will work. This is a large list, many of which we may be unaware of, and as such is not documented. For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs, -set it as a [custom CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) +set it as a [CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) file like this: ```yaml @@ -697,7 +697,7 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. ### Using private Maven repositories diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 1c14c529523..24448dc9668 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -221,8 +221,8 @@ For example, you might need to avoid a regression in a later release. To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable in your CI/CD configuration file after you include the [`SAST-IaC.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST-IaC.gitlab-ci.yml). -Only set this variable within a specific job. -If you set it [at the top level](../../../ci/variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +Only set this variable in a specific job. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. You can set the tag to: diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 6629c798cfa..a623b819b08 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -126,7 +126,7 @@ To enable all GitLab Security scanning tools, with default settings, enable - [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance) - [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning) -While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customizing-gitlab-ciyml). +While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customize-gitlab-ciyml). ## Security scanning without Auto DevOps @@ -290,7 +290,7 @@ to pass a username and password. You can set it under your project's settings so that your credentials aren't exposed in `.gitlab-ci.yml`. If the username is `myuser` and the password is `verysecret` then you would -[set the following variable](../../ci/variables/index.md#custom-cicd-variables) +[set the following variable](../../ci/variables/index.md#for-a-project) under your project's settings: | Type | Key | Value | @@ -580,7 +580,7 @@ to the GitLab server and visible in job logs. This message is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload), and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Check the entire job log for such messages. If you don't find these messages, retry the failed job after -setting `SECURE_LOG_LEVEL: "debug"` as a [custom CI/CD variable](../../ci/variables/index.md#custom-cicd-variables). +setting `SECURE_LOG_LEVEL: "debug"` as a [custom CI/CD variable](../../ci/variables/index.md#for-a-project). This provides extra information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 05e56560f95..6976956758d 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -151,7 +151,7 @@ GitLab.com. To do so, set the CI/CD variable `SECURE_ANALYZERS_PREFIX` with the project [container registry](../../packages/container_registry/index.md). You can set this variable in the projects' `.gitlab-ci.yml`, or -in the GitLab UI at the project or group level. See the [GitLab CI/CD variables page](../../../ci/variables/index.md#custom-cicd-variables) +in the GitLab UI at the project or group level. See the [GitLab CI/CD variables page](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui) for more information. #### Variables @@ -227,7 +227,7 @@ these steps: The AutoDevOps templates leverage the `SECURE_ANALYZERS_PREFIX` variable to identify the location of analyzer images. This variable is discussed above in [Using the secure bundle created](#using-the-secure-bundle-created). Ensure that you set this variable to the correct value for where you loaded the analyzer images. - You could consider doing this with a project CI/CD variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) + You could consider doing this with a project CI/CD variable or by [modifying](../../../topics/autodevops/customize.md#customize-gitlab-ciyml) the `.gitlab-ci.yml` file directly. Once these steps are complete, GitLab has local copies of the Secure analyzers and is set up to use diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 5df910efb15..6bf3532f95e 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -17,7 +17,7 @@ job is fully executed. The following video gives you an overview of GitLab scan See the video: <a href="https://youtu.be/w5I9gcUgr9U">Overview of GitLab Scan Result Policies</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/w5I9gcUgr9U" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/w5I9gcUgr9U" frameborder="0" allowfullscreen> </iframe> </figure> ## Scan result policy editor @@ -70,7 +70,7 @@ the following sections and tables provide an alternative. ## `scan_finding` rule type -This rule enforces the defined actions based on the information provided. +This rule enforces the defined actions based on security scan findings. | Field | Type | Possible values | Description | |------------|------|-----------------|-------------| @@ -79,7 +79,19 @@ This rule enforces the defined actions based on the information provided. | `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. | | `vulnerabilities_allowed` | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. | -| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | The vulnerability states for this rule to consider when the target branch is set to the default branch. The `newly_detected` state considers all newly detected vulnerabilities regardless of their status or dismissal. The other states consider findings that match the selected state and already exist in the default branch. | +| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities that are both `Detected` or `Dismissed` within the merge request itself where the vulnerabilities do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline, and necessary security scans are complete.<br><br> • Detected<br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | + +## `license_finding` rule type + +This rule enforces the defined actions based on license findings. + +| Field | Type | Possible values | Description | +|------------|------|-----------------|-------------| +| `type` | `string` | `license_finding` | The rule's type. | +| `branches` | `array` of `string` | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. | +| `match_on_inclusion` | `boolean` | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | +| `license_types` | `array` of `string` | license types | License types to match on, for example `BSD` or `MIT`. | +| `license_states` | `array` of `string` | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. | ## `require_approval` action type diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index e83825636bf..efbbf447845 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -73,7 +73,7 @@ GitLab maintains the analyzer and writes detection rules for it. If you use the [GitLab-managed CI/CD template](index.md#configuration), the Semgrep-based analyzer operates alongside other language-specific analyzers. It runs with GitLab-managed detection rules that mimic the other analyzers' detection rules. -Work to remove language-specific analyzers and replace them with the Semgrep-based analyzer is tracked in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/5245). +Work to remove language-specific analyzers and replace them with the Semgrep-based analyzer is tracked in [epic 5245](https://gitlab.com/groups/gitlab-org/-/epics/5245). In case of duplicate findings, the [analyzer order](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/reports/security/scanner.rb#L15) determines which analyzer's findings are preferred. You can choose to disable the other analyzers early and use Semgrep-based scanning for supported languages before the default behavior changes. If you do so: diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index 3d8ad6c8bf6..aec7158d2e4 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -385,7 +385,7 @@ rules: pattern: print("Hello World") message: | Unauthorized use of Hello World. - severity: CRITICAL + severity: ERROR languages: - python ``` diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 94719224254..c4352f45704 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -105,7 +105,6 @@ Check the [SAST direction page](https://about.gitlab.com/direction/secure/static | React | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 13.10 | | Ruby | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 13.9 | | Ruby on Rails | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 10.3 | -| Scala (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with GitLab-managed rules | 15.7 | | Scala<sup>2</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.0 (SBT) & 11.9 (Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | TypeScript<sup>3</sup> | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | @@ -232,18 +231,23 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Configuration +SAST scanning runs in your CI/CD pipeline. +When you add the GitLab-managed CI/CD template to your pipeline, the right [SAST analyzers](analyzers.md) automatically scan your code and save results as [SAST report artifacts](../../../ci/yaml/artifacts_reports.md#artifactsreportssast). + To configure SAST for a project you can: - Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast), provided by [Auto DevOps](../../../topics/autodevops/index.md). -- [Configure SAST manually](#configure-sast-manually). +- [Configure SAST in your CI/CD YAML](#configure-sast-in-your-cicd-yaml). - [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). -### Configure SAST manually +You can enable SAST across many projects by [enforcing scan execution](../index.md#enforce-scan-execution). + +### Configure SAST in your CI/CD YAML -To enable SAST you must [include](../../../ci/yaml/index.md#includetemplate) -the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) -provided as a part of your GitLab installation. +To enable SAST, you [include](../../../ci/yaml/index.md#includetemplate) +the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml). +The template is provided as a part of your GitLab installation. Add the following to your `.gitlab-ci.yml` file: @@ -257,34 +261,16 @@ your project's source code for possible vulnerabilities. The results are saved as a [SAST report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportssast) -that you can later download and analyze. Due to implementation limitations, we -always take the latest SAST artifact available. +that you can later download and analyze. +When downloading, you always receive the most recent SAST artifact available. ### Configure SAST in the UI You can enable and configure SAST in the UI, either with default settings, or with customizations. The method you can use depends on your GitLab license tier. -- [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). **(ULTIMATE)** - -### Configure SAST in the UI with default settings - -> [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 - -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. - -To enable and configure SAST with default settings: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance** > **Configuration**. -1. In the SAST section, select **Configure with a merge request**. -1. Review and merge the merge request to enable SAST. - -Pipelines now include a SAST job. +- [Configure SAST in the UI with default settings only](#configure-sast-in-the-ui-with-default-settings-only). ### Configure SAST in the UI with customizations **(ULTIMATE)** @@ -315,6 +301,24 @@ To enable and configure SAST with customizations: Pipelines now include a SAST job. +### Configure SAST in the UI with default settings only + +> [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 + +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. + +To enable and configure SAST with default settings: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance** > **Configuration**. +1. In the SAST section, select **Configure with a merge request**. +1. Review and merge the merge request to enable SAST. + +Pipelines now include a SAST job. + ### Overriding SAST jobs WARNING: @@ -346,7 +350,7 @@ To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/ in your CI/CD configuration file after you include the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml). Only set this variable within a specific job. -If you set it [at the top level](../../../ci/variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. You can set the tag to: @@ -529,7 +533,7 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. #### Docker images @@ -602,7 +606,7 @@ flags are added to the scanner's CLI options. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18193) in GitLab 12.5. In addition to the aforementioned SAST configuration CI/CD variables, -all [custom variables](../../../ci/variables/index.md#custom-cicd-variables) are propagated +all [custom variables](../../../ci/variables/index.md#define-a-cicd-variable-in-the-ui) are propagated to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. @@ -761,7 +765,7 @@ variables: ### Pipeline errors related to changes in the GitLab-managed CI/CD template -The [GitLab-managed SAST CI/CD template](#configure-sast-manually) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: +The [GitLab-managed SAST CI/CD template](#configure-sast-in-your-cicd-yaml) controls which [analyzer](analyzers.md) jobs run and how they're configured. While using the template, you might experience a job failure or other pipeline error. For example, you might: - See an error message like `'<your job>' needs 'spotbugs-sast' job, but 'spotbugs-sast' is not in any previous stage` when you view an affected pipeline. - Experience another type of unexpected issue with your CI/CD pipeline configuration. @@ -775,12 +779,12 @@ include: If your GitLab instance has limited network connectivity, you can also download the file and host it elsewhere. -We recommend that you only use this solution temporarily and that you return to [the standard template](#configure-sast-manually) as soon as possible. +We recommend that you only use this solution temporarily and that you return to [the standard template](#configure-sast-in-your-cicd-yaml) as soon as possible. ### Errors in a specific analyzer job GitLab SAST [analyzers](analyzers.md) are released as container images. -If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](#configure-sast-manually) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](#pinning-to-minor-image-version). +If you're seeing a new error that doesn't appear to be related to [the GitLab-managed SAST CI/CD template](#configure-sast-in-your-cicd-yaml) or changes in your own project, you can try [pinning the affected analyzer to a specific older version](#pinning-to-minor-image-version). Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. @@ -895,3 +899,7 @@ to reconfigure, using the new and improved job definition default values. include: - template: Security/SAST.gitlab-ci.yml ``` + +### MobSF job fails with error message `Reading from Info.plist` + +This error happens when `Info.plist` file is missing a `CFBundleIdentifier` key and string value. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index 9c74467bce5..e026c663854 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w FLAG: By default, auto revocation of GitLab personal access tokens is not available. To opt-in on GitLab.com -during the [Beta period](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga), please +during the [Beta period](../../../policy/alpha-beta-support.md#beta-features), please [let us know by completing this form](https://docs.google.com/forms/d/e/1FAIpQLSdRbFhvA5jvI-Rt_Qnl1PQ1znOXKK8m6lRtmM0uva4upetKvQ/viewform). GitLab supports running post-processing hooks after detecting a secret. These diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index e86f9ff4673..22ef3ed8a1b 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -204,6 +204,8 @@ To enable security training for vulnerabilities in your project: 1. On the tab bar, select **Vulnerability Management**. 1. To enable a security training provider, turn on the toggle. +Security training uses content from third-party vendors. You must have an internet connection to use this feature. + ## View security training for a vulnerability > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 2a66549f9cb..304bbaee256 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -141,7 +141,7 @@ deploy: You can assign different agents to separate Auto DevOps jobs. For instance, Auto DevOps can use one agent for `staging` jobs, and another agent for `production` jobs. -To use multiple agents, define an [environment-scoped CI/CD variable](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) +To use multiple agents, define an [environment-scoped CI/CD variable](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) for each agent. For example: 1. Define two variables named `KUBE_CONTEXT`. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 6b5f58f8f76..a44d1e9685b 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -229,3 +229,13 @@ This error occurs when the GitLab agent tries to update an object and the object - Add the required annotations manually. - Delete the object and let the agent recreate it. - Change your [`inventory_policy`](../../infrastructure/clusters/deploy/inventory_object.md#inventory_policy-options) setting. + +## Parse error during installation + +When you install the agent, you might encounter an error that states: + +```shell +Error: parse error at (gitlab-agent/templates/observability-secret.yaml:1): unclosed action +``` + +This error is typically caused by an incompatible version of Helm. To resolve the issue, ensure that you are using a version of Helm [compatible with your version of Kubernetes](index.md#supported-cluster-versions). diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index d9a9981d211..37d742e2b08 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -84,9 +84,9 @@ Here is an example of a policy which enables operational container scanning with The keys for a schedule rule are: -- cadence (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run -- agents:<agent-name> (required): The name of the agent to use for scanning -- agents:<agent-name>:namespaces (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned +- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run +- `agents:<agent-name>` (required): The name of the agent to use for scanning +- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned NOTE: Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index a8d874ed608..6f7fdc46ad4 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -25,7 +25,7 @@ If you **have not yet** used the agent to connect your cluster with GitLab: 1. [Create a project from the cluster management project template](#create-a-project-based-on-the-cluster-management-project-template). 1. [Configure the project for the agent](agent/install/index.md). 1. In your project's settings, create an - [environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) named `$KUBE_CONTEXT` + [environment variable](../../ci/variables/index.md#for-a-project) named `$KUBE_CONTEXT` and set the value to `path/to/agent-configuration-project:your-agent-name`. 1. [Configure the files](#configure-the-project) as needed. @@ -37,7 +37,7 @@ If you have already configured the agent and connected a cluster with GitLab: 1. In the project where you configured your agent, [grant the agent access to the new project](agent/ci_cd_workflow.md#authorize-the-agent). 1. In the new project, create an - [environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) named `$KUBE_CONTEXT` + [environment variable](../../ci/variables/index.md#for-a-project) named `$KUBE_CONTEXT` and set the value to `path/to/agent-configuration-project:your-agent-name`. 1. In the new project, [configure the files](#configure-the-project) as needed. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 34434ef046a..cf9fac6b25d 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -388,7 +388,7 @@ source "https://gems.example.com" You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1.html) -[variable](../../../ci/variables/index.md#custom-cicd-variables) +[variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. ### Configuring Cargo projects @@ -412,7 +412,7 @@ To supply a custom root certificate to complete TLS verification, do one of the - Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) - [variable](../../../ci/variables/index.md#custom-cicd-variables) + [variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. ### Configuring Composer projects @@ -445,7 +445,7 @@ For example: You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) -[variable](../../../ci/variables/index.md#custom-cicd-variables) +[variable](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) in the job definition. ### Configuring Conan projects @@ -508,7 +508,7 @@ example: } ``` -If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/index.md#protected-cicd-variables) +If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/index.md#protect-a-cicd-variable) following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). #### Custom root certificates for Conan diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 2d1aeaa1c07..8c4fb6f1334 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -46,6 +46,10 @@ To enable customer relations management in a group or subgroup: ### View contacts linked to a group +Prerequisites: + +- You must have at least the Reporter role for the project. + To view a group's contacts: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -55,6 +59,10 @@ To view a group's contacts: ### Create a contact +Prerequisites: + +- You must have at least the Developer role for the project. + To create a contact: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -68,6 +76,10 @@ contacts using the GraphQL API. ### Edit a contact +Prerequisites: + +- You must have at least the Developer role for the project. + To edit an existing contact: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -98,6 +110,10 @@ To change the state of a contact: ### View organizations +Prerequisites: + +- You must have at least the Reporter role for the project. + To view a group's organizations: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -107,6 +123,10 @@ To view a group's organizations: ### Create an organization +Prerequisites: + +- You must have at least the Developer role for the project. + To create an organization: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -120,6 +140,10 @@ organizations using the GraphQL API. ### Edit an organization +Prerequisites: + +- You must have at least the Developer role for the project. + To edit an existing organization: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -138,6 +162,10 @@ issues are linked to contacts matching the email addresses in the sender and CC ### View issues linked to a contact +Prerequisites: + +- You must have at least the Reporter role for the project. + To view a contact's issues, select a contact from the issue sidebar, or: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -146,6 +174,10 @@ To view a contact's issues, select a contact from the issue sidebar, or: ### View issues linked to an organization +Prerequisites: + +- You must have at least the Reporter role for the project. + To view an organization's issues: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -154,6 +186,10 @@ To view an organization's issues: ### View contacts linked to an issue +Prerequisites: + +- You must have at least the Reporter role for the project. + You can view contacts associated with an issue in the right sidebar. To view a contact's details, hover over the contact's name. @@ -166,6 +202,10 @@ API. ### Add or remove issue contacts +Prerequisites: + +- You must have at least the Reporter role for the project. + ### Add contacts to an issue To add [active](#change-the-state-of-a-contact) contacts to an issue use the `/add_contacts [contact:address@example.com]` diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 1e791662a45..44e13f70f2e 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -7,6 +7,11 @@ type: reference, howto # Comments and threads **(FREE)** +> - Paginated merge request discussions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default. +> - Paginated merge request discussions [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2. +> - Paginated merge request discussions [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.3. +> - Paginated merge request discussions [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370075) in GitLab 15.8. Feature flag `paginated_mr_discussions` removed. + GitLab encourages communication through comments, threads, and [code suggestions](../project/merge_requests/reviews/suggestions.md). @@ -357,19 +362,3 @@ with a new push. Threads are now resolved if a push makes a diff section outdated. Threads on lines that don't change and top-level resolvable threads are not resolved. - -## Display paginated merge request discussions - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340172) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.2. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/364497) in GitLab 15.3. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature -per project or for your entire instance, ask an administrator to -[disable the feature flag](../../administration/feature_flags.md) named `paginated_mr_discussions`. -On GitLab.com, this feature is available. - -A merge request can have many discussions. Loading them all in a single request -can be slow. To improve the performance of loading discussions, they are split into multiple -pages, loading sequentially. diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index 4f569098d4d..181eb00bb50 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -6,9 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Free user limit **(FREE SAAS)** -A five-user limit applies to top-level [namespaces](namespace/index.md) with private visibility on GitLab SaaS. This limit is being rolled out gradually, and impacted users will be notified in GitLab.com at least 60 days before the limit is applied. - -When the five-user limit is applied, top-level private namespaces exceeding the user limit are placed in a read-only state. These namespaces cannot write new data to repositories, Git Large File Storage (LFS), packages, or registries. +A five-user limit applies to newly created top-level namespaces with +private visibility on GitLab SaaS. For existing namespaces, this limit +is being rolled out gradually. Impacted users are notified in +GitLab.com at least 60 days before the limit is applied. + +When the five-user limit is applied, top-level private namespaces +exceeding the user limit are placed in a read-only state. These +namespaces cannot write new data to repositories, Git Large File +Storage (LFS), packages, or registries. For the full list of restricted +actions, see [Read-only namespaces](read_only_namespaces.md). ## Manage members in your namespace diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index a7358db54df..4629f33f088 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -56,7 +56,7 @@ To change the permitted Git access protocols for a group: 1. Choose the permitted protocols from **Enabled Git access protocols**. 1. Select **Save changes**. -## Restrict access to groups by IP address **(PREMIUM)** +## Restrict group access by IP address **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. @@ -66,16 +66,32 @@ address. This group-level setting applies to: - The GitLab UI, including subgroups, projects, and issues. - [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. +- In self-managed installations of GitLab 15.1 and later, you can also configure +[globally-allowed IP address ranges](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) +at the group level. Administrators can combine restricted access by IP address with [globally-allowed IP addresses](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges). +To restrict group access by IP address: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. In the **Restrict access by IP address** text box, enter a list of IPv4 or IPv6 + address ranges in CIDR notation. This list: + - Has no limit on the number of IP address ranges. + - Has a size limit of 1 GB. + - Applies to both SSH or HTTP authorized IP address ranges. You cannot split + this list by type of authorization. +1. Select **Save changes**. + ### Security implications -You should consider some security implications before configuring IP address restrictions. +Keep in mind that restricting group access by IP address has the following implications: - Administrators and group owners can access group settings from any IP address, regardless of IP restriction. However: - - Groups owners cannot access projects belonging to the group when accessing from a disallowed IP address. + - Group owners can access the subgroups, but not the projects belonging to the group or subgroups, when accessing from a disallowed IP address. - Administrators can access projects belonging to the group when accessing from a disallowed IP address. Access to projects includes cloning code from them. - Users can still see group and project names and hierarchies. Only the following are restricted: @@ -84,30 +100,11 @@ You should consider some security implications before configuring IP address res - When you register a runner, it is not bound by the IP restrictions. When the runner requests a new job or an update to a job's state, it is also not bound by the IP restrictions. But when the running CI/CD job sends Git requests from a restricted IP address, the IP restriction prevents code from being cloned. -- Users may still see some events from the IP restricted groups and projects on their dashboard. Activity may include +- Users might still see some events from the IP-restricted groups and projects on their dashboard. Activity might include push, merge, issue, or comment events. - IP access restrictions for Git operations via SSH are supported only on GitLab SaaS. IP access restrictions applied to self-managed instances block SSH completely. -### Restrict group access by IP address - -To restrict group access by IP address: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. In the **Restrict access by IP address** field, enter a list of IPv4 or IPv6 - address ranges in CIDR notation. This list: - - Has no limit on the number of IP address ranges. - - Has a size limit of 1 GB. - - Applies to both SSH or HTTP authorized IP address ranges. You cannot split - this list by type of authorization. -1. Select **Save changes**. - -In self-managed installations of GitLab 15.1 and later, you can also configure -[globally-allowed IP address ranges](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) -at the group level. - ## Restrict group access by domain **(PREMIUM)** > - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. @@ -170,11 +167,13 @@ To prevent sharing outside of the group's hierarchy: ## Prevent a project from being shared with groups -Prevent projects in a group from -[sharing a project with another group](../project/members/share_project_with_groups.md) -to enable tighter control over project access. +[Sharing a project with another group](../project/members/share_project_with_groups.md) +increases the number of users who can invite yet more members to the project. +Each (sub)group can be an additional source of access permissions, +which can be confusing and difficult to control. -To prevent a project from being shared with other groups: +To restrict the permission to invite project members to a single source, +prevent a project from being shared with other groups: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. @@ -302,4 +301,4 @@ If a user sees a 404 when they would normally expect access, and the problem is - `json.message`: `'Attempting to access IP restricted group'` - `json.allowed`: `false` -In viewing the log entries, compare the `remote.ip` with the list of [allowed IP addresses](#restrict-access-to-groups-by-ip-address) for the group. +In viewing the log entries, compare `remote.ip` with the list of [allowed IP addresses](#restrict-group-access-by-ip-address) for the group. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 62f5a3ba54f..cb760217487 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -111,7 +111,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. [Mor When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific CI/CD variables](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) +[environment-specific CI/CD variables](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) work. While evaluating which environment matches the environment scope of a diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 0e976cec866..9f40f9e84bf 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -25,9 +25,9 @@ Group owners can create, edit, and delete compliance frameworks: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375036) in GitLab 15.6. -Group owners can set a default compliance framework. The default framework is applied to all the new projects -that are created within that group. It does not affect the framework applied to the existing projects. The default -framework cannot be deleted. +Group owners can set a default compliance framework. The default framework is applied to all the new and imported +projects that are created within that group. It does not affect the framework applied to the existing projects. The +default framework cannot be deleted. A compliance framework that is set to default has a **default** label. @@ -237,7 +237,7 @@ can be configured to be: Generally, if a value in a compliance job: - Is set, it cannot be changed or overridden by project-level configurations. -- Is not set, a project-level configuration may set. +- Is not set, a project-level configuration may be set. Either might be wanted or not depending on your use case. diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 547e64df7c5..2716db27037 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -9,12 +9,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in GitLab 11.6. -When you create a project, you can [choose from a list of templates](../project/working_with_projects.md#create-a-project). +When you create a project, you can [choose from a list of templates](../project/index.md#create-a-project). These templates, for things like GitLab Pages or Ruby, populate the new project with a copy of the files contained in the template. This information is identical to the information used by [GitLab project import/export](../project/settings/import_export.md) and can help you start a new project more quickly. -You can [customize the list](../project/working_with_projects.md#create-a-project) of available templates, so +You can [customize the list](../project/index.md#create-a-project) of available templates, so that all projects in your group have the same list. To do this, you populate a subgroup with the projects you want to use as templates. @@ -40,7 +40,7 @@ Projects in nested subgroups are not included in the template list. ## Which projects are available as templates -- Public and internal projects can be selected by any signed-in user as a template for a new project, +- Public and internal projects can be selected by any authenticated user as a template for a new project, if all [project features](../project/settings/index.md#configure-project-visibility-features-and-permissions) except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. - Private projects can be selected only by users who are members of the projects. diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 4049ac2e9a1..63bf1a4471c 100644 --- a/doc/user/group/epics/linked_epics.md +++ b/doc/user/group/epics/linked_epics.md @@ -20,9 +20,11 @@ To manage linked epics through our API, visit the [epic links API documentation] ## Add a linked epic +> Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8. + Prerequisites: -- You must have at least the Reporter role for both groups. +- You must have at least the Guest role for both groups. - For GitLab SaaS: the epic that you're editing must be in a group on GitLab Ultimate. The epics you're linking can be in a group on a lower tier. @@ -59,9 +61,11 @@ The linked epics are then displayed on the epic grouped by relationship. ## Remove a linked epic +> Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/381308) from Reporter to Guest in GitLab 15.8. + Prerequisites: -- You must have at least the Reporter role for the epic's group. +- You must have at least the Guest role for the epic's group. To remove a linked epic, in the **Linked epics** section of an epic, select **Remove** (**{close}**) next to diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 8e7b6fd82ad..fa8f96952b3 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -341,6 +341,8 @@ automatically added to the epic. #### Add an existing issue to an epic +> Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. + You can add existing issues to an epic, including issues in a project from a [different group hierarchy](index.md#child-issues-from-different-group-hierarchies). Newly added issues appear at the top of the list of issues in the **Epics and Issues** tab. @@ -350,8 +352,7 @@ current parent. Prerequisites: -- You must be able to [view the epic](#who-can-view-an-epic). -- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). +- You must have at least the Guest role for the issue's project and the epic's group. To add an existing issue to an epic: @@ -368,13 +369,14 @@ To add an existing issue to an epic: #### Create an issue from an epic +> Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. + Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts. Prerequisites: -- You must be able to [view the epic](#who-can-view-an-epic). -- You must have at least the Reporter role for the project. +- You must have at least the Guest role for the issue's project and the epic's group. To create an issue from an epic: @@ -388,13 +390,14 @@ The new issue is assigned to the epic. ### Remove an issue from an epic +> Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. + You can remove issues from an epic when you're on the epic's details page. After you remove an issue from an epic, the issue is no longer associated with this epic. Prerequisites: -- You must have at least the Reporter role for the epic's group. -- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). +- You must have at least the Guest role for the issue's project and the epic's group. To remove an issue from an epic: @@ -406,14 +409,15 @@ To remove an issue from an epic: ### Reorder issues assigned to an epic -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9367) in GitLab 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9367) in GitLab 12.5. +> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. New issues appear at the top of the list in the **Epics and Issues** tab. You can reorder the list of issues by dragging them. Prerequisites: -- You must have at least the Reporter role for the epic's group. +- You must have at least the Guest role for the issue's project and the epic's group. To reorder issues assigned to an epic: @@ -422,15 +426,15 @@ To reorder issues assigned to an epic: ### Move issues between epics **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33039) in GitLab 13.0. +> - Minimum required role for the project [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382506) from Reporter to Guest in GitLab 15.8. New issues appear at the top of the list in the **Epics and Issues** tab. You can move issues from one epic to another. Prerequisites: -- You must have at least the Reporter role for the epic's group. -- You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). +- You must have at least the Guest role for the issue's project and the epic's group. To move an issue to another epic: diff --git a/doc/user/group/import/img/bulk_imports_v14_1.png b/doc/user/group/import/img/bulk_imports_v14_1.png Binary files differdeleted file mode 100644 index fb419c1df6c..00000000000 --- a/doc/user/group/import/img/bulk_imports_v14_1.png +++ /dev/null diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 9a671ff6679..c264b5ceaf8 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -26,20 +26,16 @@ If you migrate from GitLab.com to self-managed GitLab, an administrator can crea > - Group items [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 for project resources [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6. +> - New application setting `bulk_import_enabled` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. `bulk_import` feature flag removed. FLAG: -On self-managed GitLab, by default [migrating group items](#migrated-group-items) is available. To hide the -feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `bulk_import`. -On self-managed GitLab, by default [migrating project items](#migrated-project-items) is not available. To show +On self-managed GitLab, by default [migrating group items](#migrated-group-items) is not available. To show the +feature, ask an administrator to [enable it in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer). +Also on self-managed GitLab, by default [migrating project items](#migrated-project-items-beta) is not available. To show this feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named -`bulk_import_projects`. On GitLab.com, migration of both groups and projects is available. +`bulk_import_projects`. The feature is not ready for production use. On GitLab.com, migration of both groups and projects is available. -Prerequisites: - -- Network connection between instances or GitLab.com. Must support HTTPS. -- Owner role on the top-level group to migrate. - -You can import top-level groups to: +You can migrate top-level groups to: - Another top-level group. - The subgroup of any existing top-level group. @@ -47,15 +43,34 @@ You can import top-level groups to: You can migrate: -- By direct transfer using either the UI or the [API](../../../api/bulk_imports.md). +- By direct transfer through either the UI or the [API](../../../api/bulk_imports.md). - Many groups at once. +- With projects (in [Beta](../../../policy/alpha-beta-support.md#beta-features) and not ready for production use) or + without projects. -When migrating a top-level group to GitLab.com, all its subgroups and projects are migrated too. +When you migrate a group by direct transfer, you can also migrate subgroups and projects. When you migrate a group: + +- To GitLab.com, all its subgroups and projects are migrated too. +- To a self-managed instance, migrating project items is not available by default. An administrator must + [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. + +WARNING: +Migrating subgroups and projects this way is in [Beta](../../../policy/alpha-beta-support.md#beta-features) and is not +ready for production use. Not all group and project resources are imported. See list of migrated resources below: - [Migrated group items](#migrated-group-items). -- [Migrated project items](#migrated-project-items). +- [Migrated project items](#migrated-project-items-beta). + +Prerequisites: + +- Network connection between instances or GitLab.com. Must support HTTPS. +- Both GitLab instances have [migration enabled in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) + by an instance administrator. +- Owner role on the top-level source group to migrate from. +- At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. ### Preparation @@ -94,16 +109,19 @@ Create the group you want to import to and connect the source: ### Select the groups to import +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385689) in GitLab 15.8, option to import groups with or without projects. + After you have authorized access to the source GitLab instance, you are redirected to the GitLab group importer page. The top-level groups on the connected source instance you have the Owner role for are listed. 1. By default, the proposed group namespaces match the names as they exist in source instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. -1. Next to the groups you want to import, select **Import**. +1. Next to the groups you want to import, select either: + - **Import with projects**. Importing groups with projects is in [Beta](../../../policy/alpha-beta-support.md#beta-features). This feature is not ready for production use. + - **Import without projects**. + - **Import** on self-managed GitLab, when the `bulk_import_projects` feature flag is disabled and the feature is not available. 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. - - ### Group import history You can view all groups migrated by you by direct transfer listed on the group import history page. This list includes: @@ -155,19 +173,25 @@ Group items that are migrated to the target instance include: Any other items are **not** migrated. -### Migrated project items +### Migrated project items (beta) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6. FLAG: -On self-managed GitLab, migrating project resources when migrating groups is not available by default. To make it available ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. On GitLab.com, groups are migrated with all their projects by default. +On self-managed GitLab, migrating project resources when migrating groups is not available by default. +To make it available ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named +`bulk_import_projects`. On GitLab.com, groups are migrated with all their projects by default. The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file for projects lists many of the items imported when migrating projects using group migration. View this file in the branch for your version of GitLab to see the list of items relevant to you. For example, [`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). +WARNING: +Migrating projects when migrating groups by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features) +and is not ready for production use. + Project items that are migrated to the target instance include: - Projects ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4) @@ -390,7 +414,7 @@ You can also export a group [using the API](../../../api/group_import_export.md) 1. Create a new group: - On the top bar, select **Create new…** (**{plus-square}**) and then **New group**. - - On an existing group's page, select the **New subgroup** button. + - On an existing group's page, select **New subgroup**. 1. Select **Import group**. 1. Enter your group name. 1. Accept or modify the associated group URL. @@ -405,7 +429,7 @@ The maximum import file size can be set by the administrator, default is `0` (un As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area](../../admin_area/settings/account_and_limit_settings.md). -Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. +Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to 0 in GitLab 13.8. ### Rate limits diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 62659938d91..db01358d899 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -25,7 +25,7 @@ For more information about creating and managing your groups, see [Manage groups Like projects, a group can be configured to limit the visibility of it to: - Anonymous users. -- All signed-in users. +- All authenticated users. - Only explicit group members. The restriction for [visibility levels](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 414b80d0f1d..a755447c47c 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -213,7 +213,7 @@ To avoid this problem, GitLab administrators can [ensure removed users cannot in There are two different ways to add a new project to a group: -- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/working_with_projects.md#create-a-project). +- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md#create-a-project). - While you are creating a project, select a group from the dropdown list.  diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index 1cf3a9dbe7d..a5515079294 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -4,12 +4,12 @@ group: Anti-Abuse info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Git abuse rate limit **(ULTIMATE SELF)** +# Git abuse rate limit **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. Disabled by default. 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 `limit_unique_project_downloads_per_namespace_user`. On GitLab.com, this feature is not available. +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 `limit_unique_project_downloads_per_namespace_user`. On GitLab.com, this feature is available. Git abuse rate limiting is a feature to automatically ban users who download or clone more than a specified number of repositories in a group or any of its subgroups within a given time frame. Banned users cannot access the main group or any of its non-public subgroups via HTTP or SSH. Access to unrelated groups is unaffected. @@ -31,6 +31,10 @@ If automatic banning is enabled, users with the Owner role for the main group re ## Unban a user +Prerequisites: + +- You must have the Owner role. + 1. On the left sidebar, select **Group information > Members**. 1. Select the **Banned** tab. 1. For the account you want to unban, select **Unban**. diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 80d145fc6bb..65c4d68f743 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -27,19 +27,40 @@ You must include the SAML configuration block on all Sidekiq nodes in addition t - Use SAML Group Sync. - Have multiple GitLab nodes, for example in a distributed or highly available architecture. +NOTE: +SAML Group Sync is only supported for the [SAML provider named `saml`](../../../integration/saml.md#configure-gitlab-to-use-multiple-saml-idps). +As a result, SAML Group Sync only supports a single SAML provider. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). + WARNING: To prevent users being accidentally removed from the GitLab group, follow these instructions closely before enabling Group Sync in GitLab. -To configure SAML Group Sync: - -1. Configure the identity Provider: - - For self-managed GitLab, see the [SAML OmniAuth Provider documentation](../../../integration/saml.md). - - For GitLab.com, see the [SAML SSO for GitLab.com groups documentation](index.md). - -1. Capture [a SAML response](troubleshooting.md#saml-debugging-tools) during the sign-in process to confirm your SAML identity provider sends an attribute statement: - - For self-managed GitLab, with the same name as the value of the `groups_attribute` setting. - - For GitLab.com, named `Groups` or `groups`. +To configure SAML Group Sync for self-managed GitLab instances: + +1. Configure the [SAML OmniAuth Provider](../../../integration/saml.md). +1. Ensure your SAML identity provider sends an attribute statement with the same name as the value of the `groups_attribute` setting. See the following attribute statement example for reference: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "saml", + label: "Provider name", # optional label for login button, defaults to "Saml", + groups_attribute: 'Groups', + args: { + assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", + idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", + idp_sso_target_url: "https://login.example.com/idp", + issuer: "https://gitlab.example.com", + name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" + } + } + ] + ``` + +To configure SAML Group Sync for GitLab.com instances: + +1. See [SAML SSO for GitLab.com groups](index.md). +1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`. NOTE: The value for `Groups` or `groups` in the SAML response may be either the group name or an ID. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index bd10560e138..1275e3a21e4 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -157,7 +157,7 @@ When the transparent SSO enforcement feature flag is enabled, SSO is enforced as | Public | Off | Enforced | Not enforced | Not enforced | | Public | On | Enforced | Enforced | Not enforced | -An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. +An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API and GitLab Pages activities. SSO enforcement has the following effects when enabled: @@ -370,7 +370,11 @@ On subsequent visits, you should be able to go [sign in to GitLab.com with SAML] ### Change NameID for one or more users -If the NameID changes for one or more users, they need to reconnect their SAML account. +> Update of SAML identities using the SAML API [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5. + +Group owners can update the SAML identities for their group members using the [SAML API](../../../api/saml.md). + +Alternatively, ask the users to reconnect their SAML account. 1. Ask relevant users to [unlink their account from the group](#unlinking-accounts). 1. Ask relevant users to [link their account to the new SAML app](#linking-saml-to-your-existing-gitlabcom-account). diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 18af39f4271..8c30c246566 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -15,7 +15,7 @@ GitLab SAML SSO SCIM doesn't support updating users. When SCIM is enabled for a GitLab group, membership of that group is synchronized between GitLab and an identity provider. -The [internal GitLab SCIM API](../../../development/internal_api/index.md#scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). +The [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). ## Configure GitLab @@ -121,7 +121,7 @@ attributes and modify them accordingly. In particular, the `objectId` source att target attribute. If a mapping is not listed in the table, use the Azure Active Directory defaults. For a list of required attributes, -refer to the [internal SCIM API](../../../development/internal_api/index.md#scim-api) documentation. +refer to the [internal group SCIM API](../../../development/internal_api/index.md#group-scim-api) documentation. ### Configure Okta diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index f8075e62ecc..a42d3f8fd03 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -52,7 +52,7 @@ You can use one of the following to troubleshoot SAML: - A [quick start guide to start a Docker container](../../../administration/troubleshooting/test_environments.md#saml) with a plug and play SAML 2.0 identity provider if you only require a SAML provider. - A local environment by - [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#group-saml-on-a-self-managed-gitlab-instance). + [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#configure-group-saml-sso-on-a-self-managed-instance). ## Verify configuration @@ -233,6 +233,13 @@ If you receive a `404` during setup when using "verify configuration", make sure If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](index.md#configure-your-identity-provider), they may see a 404. As outlined in the [user access section](index.md#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. +If all users are receiving a `404` after signing in to the identity provider (IdP), verify the `assertion_consumer_service_url`: + +- In the GitLab configuration by [matching it to the HTTPS endpoint of GitLab](../../../integration/saml.md#configure-saml-support-in-gitlab). +- As the `Assertion Consumer Service URL` or equivalent when setting up the SAML app on your IdP. + +For configuration examples for some of the common providers, see the [example group SAML and SCIM configurations](example_saml_config.md). + ### 500 error after login **(FREE SELF)** If you see a "500 error" in GitLab when you are redirected back from the SAML @@ -281,3 +288,12 @@ this means: A GitLab group Owner can use the [SAML API](../../../api/saml.md) to update the user's SAML `extern_uid`. The `extern_uid` value must match the Name ID value sent by the SAML identity provider (IdP). Depending on the IdP configuration this may be a generated unique ID, an email address, or other value. + +## Message: "The member's email address is not linked to a SAML account" **(PREMIUM SAAS)** + +This error appears when you try to invite a user to a GitLab.com group (or subgroup or project within a group) that has [SAML SSO enforcement](index.md#sso-enforcement) enabled. + +If you see this message after trying to invite a user to a group: + +1. Ensure the user has been [added to the SAML identity provider](index.md#user-access-and-management). +1. Ask the user to [link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account), if they have one. Otherwise, ask the user to create a GitLab.com account by [accessing GitLab.com through the identity provider's dashboard](index.md#user-access-and-management), or by [signing up manually](https://gitlab.com/users/sign_up) and linking SAML to their new account. diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index 22562c51e9e..939ed804a99 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -100,7 +100,7 @@ Changing the SAML or SCIM configuration or provider can cause the following prob GitLab.com administrators can search for SCIM requests in the `api_json.log` using the `pubsub-rails-inf-gprd-*` index in [Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html#using-kibana). Use the following filters based -on the internal [SCIM API](../../../development/internal_api/index.md#scim-api): +on the internal [group SCIM API](../../../development/internal_api/index.md#group-scim-api): - `json.path`: `/scim/v2/groups/<group-path>` - `json.params.value`: `<externalId>` diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 95c8e60af5d..f8d3456648d 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -66,16 +66,16 @@ In the hierarchy list, public groups with a private subgroup have an expand opti for all users that indicate there is a subgroup. When users who are not direct or inherited members of the private subgroup select expand (**{chevron-down}**), the nested subgroup does not display. -If you prefer to keep information about the presence of nested subgroups private, we advise that you only -add private subgroups to private parent groups. +If you prefer to keep information about the presence of nested subgroups private, we advise that you +add private subgroups only to private parent groups. ## Create a subgroup Prerequisites: -- You must either: - - Have at least the Maintainer role for a group to create subgroups for it. - - Have the [role determined by a setting](#change-who-can-create-subgroups). These users can create +- You must have either: + - At least the Maintainer role for a group to create subgroups for it. + - The [role determined by a setting](#change-who-can-create-subgroups). These users can create subgroups even if group creation is [disabled by an Administrator](../../admin_area/index.md#prevent-a-user-from-creating-groups) in the user's settings. @@ -92,8 +92,9 @@ To create a subgroup: ### Change who can create subgroups -To create a subgroup, you must have at least the Maintainer role on the group, depending on the group's setting. By -default: +Prerequisite: + +- You must have at least the Maintainer role on the group, depending on the group's setting. To change who can create subgroups on a group: @@ -120,11 +121,11 @@ There is a bug that causes some pages in the parent group to be accessible by su When you add a member to a group, that member is also added to all subgroups. The user's permissions are inherited from the group's parent. -Subgroup members can: +Subgroup members can be: -1. Be [direct members](../../project/members/index.md#add-users-to-a-project) of the subgroup. -1. [Inherit membership](../../project/members/index.md#inherited-membership) of the subgroup from the subgroup's parent group. -1. Be a member of a group that was [shared with the subgroup's top-level group](../manage.md#share-a-group-with-another-group). +1. [Direct members](../../project/members/index.md#add-users-to-a-project) of the subgroup. +1. [Inherited members](../../project/members/index.md#inherited-membership) of the subgroup from the subgroup's parent group. +1. Members of a group that was [shared with the subgroup's top-level group](../manage.md#share-a-group-with-another-group). ```mermaid flowchart RL diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 1c02ca59e3d..8635b4567ef 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -119,10 +119,10 @@ In GitLab 13.9 and later, deployment frequency metrics are calculated based on w In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on when the deployment was created. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/embed/wQU-mWvNSiI">DORA metrics and value stream analytics</a>. + See the video: <a href="https://www.youtube.com/watch?v=wQU-mWvNSiI">DORA metrics and value stream analytics</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/wQU-mWvNSiI" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/wQU-mWvNSiI" frameborder="0" allowfullscreen> </iframe> </figure> ### How value stream analytics aggregates data diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 8a5c32150c9..cefa8885bfe 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -60,6 +60,53 @@ To create a GitLab agent for Kubernetes: 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. 1. GitLab provides an address for the agent server (KAS), which you will also need later. +## Set up AWS credentials + +Set up your AWS credentials when you want to authenticate AWS with GitLab. + +1. Create an [IAM User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) or [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html). +1. Make sure that your IAM user or role has the appropriate permissions for your project. For this example project, you must have the permissions shown below. You can expand this when you set up your own project. + + ```json + // IAM custom Policy definition + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:*", + "eks:*", + "elasticloadbalancing:*", + "autoscaling:*", + "cloudwatch:*", + "logs:*", + "kms:DescribeKey", + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:CreateInstanceProfile", + "iam:CreateRole", + "iam:CreateServiceLinkedRole", + "iam:GetRole", + "iam:ListAttachedRolePolicies", + "iam:ListRolePolicies", + "iam:ListRoles", + "iam:PassRole", + // required for destroy step + "iam:DetachRolePolicy", + "iam:ListInstanceProfilesForRole", + "iam:DeleteRole" + ], + "Resource": "*" + } + ] + } + ``` + +1. [Create an access key for the user or role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). +1. Save your access key and secret. You need these to authenticate AWS with GitLab. + ## Configure your project Use CI/CD environment variables to configure your project. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index 4c68ec42712..3084cc28c9b 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -35,7 +35,7 @@ These values can be specified using [CI/CD variables](../../../../../ci/variable The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `CI_SERVER_URL` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `gitlabUrl:` in `applications/gitlab-runner/values.yaml.gotmpl`. -The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../../../../ci/variables/index.md#protected-cicd-variables) and [masked variable](../../../../../ci/variables/index.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml.gotmpl` file. +The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../../../../ci/variables/index.md#protect-a-cicd-variable) and [masked variable](../../../../../ci/variables/index.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml.gotmpl` file. You can customize the installation of GitLab Runner by defining `applications/gitlab-runner/values.yaml.gotmpl` file in your cluster diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md new file mode 100644 index 00000000000..8be949c40cd --- /dev/null +++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md @@ -0,0 +1,137 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# GitLab Terraform helpers **(FREE)** + +GitLab provides two helpers to ease your integration with the [GitLab-managed Terraform State](terraform_state.md). + +- The `gitlab-terraform` script, which is a thin wrapper around the `terraform` command. +- The `terraform-images` container images, which include the `gitlab-terraform` script and `terraform` itself. + +Both helpers are maintained in the [Terraform Images](https://gitlab.com/gitlab-org/terraform-images) +project. + +## `gitlab-terraform` + +The `gitlab-terraform` script is a thin wrapper around the `terraform` command. + +Run `gitlab-terraform` in a CI/CD pipeline to set up the necessary environment +variables to connect to the [GitLab-managed Terraform State](terraform_state.md) backend. + +### Source (but do not run) the helper script + +When the `gitlab-terraform` script is sourced, it +configures the environment for a `terraform` call, but does not +actually run `terraform`. You can source the script when you need to do +extra steps to prepare your environment, or to use alternative +tools like `terragrunt`. + +To source the script, execute: + +```shell +source $(which gitlab-terraform) +``` + +Some shells, like BusyBox, do not support the case +of another script sourcing your script. For more information, see [this Stack Overflow thread](https://stackoverflow.com/a/28776166). +To resolve this issue, you should use `bash`, `zsh` or `ksh`, or source `gitlab-terraform` directly +from the shell. + +### Commands + +You can run `gitlab-terraform` with the following commands. + +| Command | Forwards command line? | Implicit init? | Description | +|------------------------------|------------------------|-----------------------|--------------------------------------------------------------------------------------------------------| +| `gitlab-terraform apply` | Yes | Yes | Runs `terraform apply`. | +| `gitlab-terraform destroy` | Yes | Yes | Runs `terraform destroy`. | +| `gitlab-terraform fmt` | Yes | No | Runs `terraform fmt` in check mode. | +| `gitlab-terraform init` | Yes | Not applicable | Runs `terraform init`. | +| `gitlab-terraform plan` | Yes | Yes | Runs `terraform plan` and produces a `plan.cache` file. | +| `gitlab-terraform plan-json` | No | No | Converts a `plan.cache` file into a GitLab Terraform report for a [MR integration](mr_integration.md). | +| `gitlab-terraform validate` | Yes | Yes (without backend) | Runs `terraform validate`. | +| `gitlab-terraform -- <cmd>` | Yes | No | Runs `terraform <cmd>`, even if it is wrapped. | +| `gitlab-terraform <cmd>` | Yes | No | Runs `terraform <cmd>`, if the command is not wrapped. | + +### Generic variables + +When you run `gitlab-terraform`, these variables are configured. + +| Variable | Default | Description | +|----------------------|--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `TF_ROOT` | Not set | Root of the Terraform configuration. If set, it is used as the Terraform `-chdir` argument value. All read and written files are relative to the given configuration root. | +| `TF_CLI_CONFIG_FILE` | `$HOME/.terraformrc` | Location of the [Terraform configuration file](https://developer.hashicorp.com/terraform/cli/config/config-file). | +| `TF_IN_AUTOMATION` | `true` | Set to `true` to indicate that Terraform commands are automated. | +| `TF_GITLAB_SOURCED` | `false` | Set to `true` if `gitlab-terraform` [was sourced](#source-but-do-not-run-the-helper-script). | +| `TF_PLAN_CACHE` | `$TF_ROOT/plan.cache` or `$PWD/plan.cache` | Location of the plan cache file. If `TF_ROOT` is not set, then its path is relative to the current working directory (`$PWD`). | +| `TF_PLAN_JSON` | `$TF_ROOT/plan.json` or `$PWD/plan.json` | Location of the plan JSON file for [MR integration](mr_integration.md). If `TF_ROOT` is not set, then its path is relative to the current working directory (`$PWD`). | +| `DEBUG_OUTPUT` | `"false"` | If set to `"true"` every statement is logged with `set -x`. | + +### GitLab-managed Terraform state variables + +When you run `gitlab-terraform`, these variables are configured. + +| Variable | Default | Description | +|--------------------------|-------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `TF_STATE_NAME` | Not set | If `TF_ADDRESS` is not set, and `TF_STATE_NAME` is provided, then the value of `TF_STATE_NAME` is used as [GitLab-managed Terraform State](terraform_state.md) name. | +| `TF_ADDRESS` | Terraform State API URL for `$TF_STATE_NAME` | Used as default for [`TF_HTTP_ADDRESS`](https://developer.hashicorp.com/terraform/language/settings/backends/http#address). Uses `TF_STATE_NAME` as [GitLab-managed Terraform State](terraform_state.md) name by default. | +| `TF_USERNAME` | [`$GITLAB_USER_LOGIN`](../../../ci/variables/predefined_variables.md) or `gitlab-ci-token` if `$TF_PASSWORD` is not set | Used as default for [`TF_HTTP_USERNAME`](https://developer.hashicorp.com/terraform/language/settings/backends/http#username). | +| `TF_PASSWORD` | [`$CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md) | Used as default for [`TF_HTTP_PASSWORD`](https://developer.hashicorp.com/terraform/language/settings/backends/http#password). | +| `TF_HTTP_ADDRESS` | `$TF_ADDRESS` | [Address to the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#address). | +| `TF_HTTP_LOCK_ADDRESS` | `$TF_ADDRESS/lock` | [Address to the Terraform backend lock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#lock_address). | +| `TF_HTTP_LOCK_METHOD` | `POST` | [Method to use for the Terraform backend lock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#lock_method). | +| `TF_HTTP_UNLOCK_ADDRESS` | `$TF_ADDRESS/lock` | [Address to the Terraform backend unlock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#unlock_address). | +| `TF_HTTP_UNLOCK_METHOD` | `DELETE` | [Method to use for the Terraform backend unlock endpoint](https://developer.hashicorp.com/terraform/language/settings/backends/http#unlock_method). | +| `TF_HTTP_USERNAME` | `$TF_USERNAME` | [Username to authenticate with the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#username). | +| `TF_HTTP_PASSWORD` | `$TF_PASSWORD` | [Password to authenticate with the Terraform backend](https://developer.hashicorp.com/terraform/language/settings/backends/http#password). | +| `TF_HTTP_RETRY_WAIT_MIN` | `5` | [Minimum time in seconds to wait](https://developer.hashicorp.com/terraform/language/settings/backends/http#retry_wait_min) between HTTP request attempts to the Terraform backend. | + +### Command variables + +When you run `gitlab-terraform`, these variables are configured. + +| Variable | Default | Description | +|--------------------------|----------|-------------------------------------------------------------------------------------------| +| `TF_IMPLICIT_INIT` | `true` | If `true`, an implicit `terraform init` runs before the wrapped commands that require it. | +| `TF_INIT_NO_RECONFIGURE` | `false` | If `true`, the implicit `terraform init` runs without `-reconfigure`. | +| `TF_INIT_FLAGS` | Not set | Additional `terraform init` flags. | + +### Terraform input variables + +When you run `gitlab-terraform`, these Terraform input variables are set automatically. +For more information about the default values, see [Predefined variables](../../../ci/variables/predefined_variables.md). + +| Variable | Default | +|-------------------------------|-------------------------| +| `TF_VAR_CI_JOB_ID` | `$CI_JOB_ID` | +| `TF_VAR_CI_COMMIT_SHA` | `$CI_COMMIT_SHA` | +| `TF_VAR_CI_JOB_STAGE` | `$CI_JOB_STAGE` | +| `TF_VAR_CI_PROJECT_ID` | `$CI_PROJECT_ID` | +| `TF_VAR_CI_PROJECT_NAME` | `$CI_PROJECT_NAME` | +| `TF_VAR_CI_PROJECT_NAMESPACE` | `$CI_PROJECT_NAMESPACE` | +| `TF_VAR_CI_PROJECT_PATH` | `$CI_PROJECT_PATH` | +| `TF_VAR_CI_PROJECT_URL` | `$CI_PROJECT_URL` | + +## Terraform images + +The `gitlab-terraform` helper script and `terraform` itself are provided in container images +under `registry.gitlab.com/gitlab-org/terraform-images/`. You can use these images to configure +and manage your integration. + +The following images are provided: + +| Image name | Tag | Description | +|-------------------------------|-----------------------------|--------------------------------------------------------------------------------| +| `stable` | `latest` | Latest `terraform-images` release bundled with the latest Terraform release. | +| `releases/$TERRAFORM_VERSION` | `latest` | Latest `terraform-images` release bundled with a specific Terraform release. | +| `releases/$TERRAFORM_VERSION` | `$TERRAFORM_IMAGES_VERSION` | Specific `terraform-images` release bundled with a specific Terraform release. | + +For supported combinations, see [the `terraform-images` container registry](https://gitlab.com/gitlab-org/terraform-images/container_registry). + +## Related topics + +- [Terraform CI/CD templates](index.md) +- [Terraform template recipes](terraform_template_recipes.md) diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index fc86210ed56..eb6a8db0c05 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -82,7 +82,9 @@ To configure GitLab CI/CD as a backend: The output from the above `terraform` commands should be viewable in the job logs. -The `gitlab-terraform` CLI is a wrapper around the `terraform` CLI. You can [view the source code of `gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images/-/blob/master/src/bin/gitlab-terraform.sh) if you're interested. +The `gitlab-terraform` CLI is a wrapper around the `terraform` CLI. For more information, +see [GitLab Terraform helpers](gitlab_terraform_helpers.md), +or [view the source code of `gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images/-/blob/master/src/bin/gitlab-terraform.sh). If you prefer to call the `terraform` commands explicitly, you can override the template, and instead, use it as reference for what you can achieve. diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index ab2c8c1c48a..0d1b56ae979 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -181,3 +181,51 @@ deploy: ``` For an example repository, see the [GitLab Terraform template usage project](https://gitlab.com/gitlab-org/configure/examples/terraform-template-usage). + +## Deploy Terraform to multiple environments + +You can run pipelines in multiple environments, each with a unique Terraform state. + +```yaml +stages: + - validate + - test + - build + - deploy + +include: + - template: Terraform/Base.latest.gitlab-ci.yml + - template: Jobs/SAST-IaC.latest.gitlab-ci.yml + +variables: + # x prevents TF_STATE_NAME from beeing empty for non environment jobs like validate + # wait for https://gitlab.com/groups/gitlab-org/-/epics/7437 to use variable defaults + TF_STATE_NAME: x${CI_ENVIRONMENT_NAME} + TF_CLI_ARGS_plan: "-var-file=vars/${CI_ENVIRONMENT_NAME}.tfvars" + +fmt: + extends: .terraform:fmt +validate: + extends: .terraform:validate + +plan dev: + extends: .terraform:build + environment: + name: dev +plan prod: + extends: .terraform:build + environment: + name: prod + +apply dev: + extends: .terraform:deploy + environment: + name: dev + +apply prod: + extends: .terraform:deploy + environment: + name: prod +``` + +This configuration is modified from the [base GitLab template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml). diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index ad1821fbe10..2aa1e5d3284 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -110,7 +110,7 @@ If you don't set `TF_STATE_NAME` or `TF_ADDRESS` in your job, the job fails with To resolve this, ensure that either `TF_ADDRESS` or `TF_STATE_NAME` is accessible in the job that returned the error: -1. Configure the [CI/CD environment scope](../../../ci/variables/index.md#add-a-cicd-variable-to-a-project) for the job. +1. Configure the [CI/CD environment scope](../../../ci/variables/index.md#for-a-project) for the job. 1. Set the job's [environment](../../../ci/yaml/index.md#environment), matching the environment scope from the previous step. ### Error refreshing state: HTTP remote state endpoint requires auth diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index eb703328270..88430df0d67 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -33,7 +33,7 @@ GitLab tries to match clusters in the following order: - Instance-level clusters. To be selected, the cluster must be enabled and -match the [environment selector](../../../ci/environments/index.md#scope-environments-with-specs). +match the [environment selector](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable). ## Cluster environments **(PREMIUM)** diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 17b91eb9483..d29369f142c 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -343,6 +343,9 @@ backslash <code>\</code>. Otherwise the diff highlight does not render corre ### Math +> - LaTeX-compatible fencing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21757) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. Enabled on GitLab.com. +> - LaTeX-compatible fencing [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371180) in GitLab 15.8. Feature flag `markdown_dollar_math` removed. + [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#math). Math written in LaTeX syntax is rendered with [KaTeX](https://github.com/KaTeX/KaTeX). @@ -350,8 +353,10 @@ _KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX. This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). -Math written between dollar signs with backticks (``$`...`$``) is rendered -inline with the text. Math written in a [code block](#code-spans-and-blocks) with +Math written between dollar signs with backticks (``$`...`$``) or single dollar signs (`$...$`) +is rendered inline with the text. + +Math written between double dollar signs (`$$...$$`) or in a [code block](#code-spans-and-blocks) with the language declared as `math` is rendered on a separate line: ````markdown @@ -362,6 +367,14 @@ This math is on a separate line: ```math a^2+b^2=c^2 ``` + +This math is on a separate line: $$a^2+b^2=c^2$$ + +This math is on a separate line: + +$$ +a^2+b^2=c^2 +$$ ```` This math is inline: $`a^2+b^2=c^2`$. @@ -372,25 +385,6 @@ This math is on a separate line: a^2+b^2=c^2 ``` -#### LaTeX-compatible fencing - -> Introduced in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. Enabled on GitLab.com. - -[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#latex-compatible-fencing). - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, -ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `markdown_dollar_math`. -On GitLab.com, this feature is available. -The feature is not ready for production use. - -Math written between dollar signs (`$...$`) is rendered -inline with the text. Math written between double dollar signs (`$$...$$`) is rendered -on a separate line: - -````markdown -This math is inline: $a^2+b^2=c^2$. - This math is on a separate line: $$a^2+b^2=c^2$$ This math is on a separate line: @@ -398,10 +392,6 @@ This math is on a separate line: $$ a^2+b^2=c^2 $$ -```` - -<!-- Uncomment the example below when the flag is enabled on GitLab.com --> -<!-- This math is inline: $a^2+b^2=c^2$. This math is on a separate line: $$a^2+b^2=c^2$$ @@ -409,7 +399,7 @@ This math is on a separate line: $$ a^2+b^2=c^2 -$$ --> +$$ ### Task lists @@ -1668,7 +1658,7 @@ Watch the following video walkthrough of this feature: See the video: <a href="https://www.youtube.com/watch?v=12yWKw1AdKY">Demo: JSON Tables in Markdown</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/12yWKw1AdKY" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/12yWKw1AdKY" frameborder="0" allowfullscreen> </iframe> </figure> The `items` attribute is a list of objects representing the data points. diff --git a/doc/user/namespace/index.md b/doc/user/namespace/index.md index 7d26600cc38..7463b8f1099 100644 --- a/doc/user/namespace/index.md +++ b/doc/user/namespace/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -35,3 +35,10 @@ To determine whether you're viewing a group or personal namespace, you can view | A user named `alex`. | `https://gitlab.example.com/alex` | `alex` | | A group named `alex-team`. | `https://gitlab.example.com/alex-team` | `alex-team` | | A group named `alex-team` with a subgroup named `marketing`. | `https://gitlab.example.com/alex-team/marketing` | `alex-team/marketing` | + +## Naming limitations for namespaces + +When choosing a name for your namespace, keep in mind the [character limitations](../reserved_names.md#limitations-on-project-and-group-names) and [reserved group names](../reserved_names.md#reserved-group-names). + +NOTE: +If your namespace contains a `.`, you will encounter issues with the validation of your SSL certificates and the source path when [publishing Terraform modules](../packages/terraform_module_registry/index.md#publish-a-terraform-module). diff --git a/doc/user/okrs.md b/doc/user/okrs.md new file mode 100644 index 00000000000..0b6bffa97ce --- /dev/null +++ b/doc/user/okrs.md @@ -0,0 +1,254 @@ +--- +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 +--- + +# Objectives and key results (OKR) **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103355) in GitLab 15.6 [with a flag](../administration/feature_flags.md) named `okrs_mvc`. Disabled by default. + +WARNING: +OKRs are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). +For the OKR feature roadmap, see [epic 7864](https://gitlab.com/groups/gitlab-org/-/epics/7864). + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `okrs_mvc`. +The feature is not ready for production use. + +Use objectives and key results to align your workforce towards common goals and track the progress. +Set a big goal with an objective and use [child objectives and key results](#child-objectives-and-key-results) +to measure the big goal's completion. + +The objective and the key result in GitLab share many features. In the documentation, the term +**OKR** refers to either an objective or a key result. + +OKRs are a type of work item, a step towards [default issue types](https://gitlab.com/gitlab-org/gitlab/-/issues/323404) +in GitLab. +For the roadmap of migrating [issues](project/issues/index.md) and [epics](group/epics/index.md) +to work items and adding custom work item types, see +[epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or the +[Plan direction page](https://about.gitlab.com/direction/plan/). + +## Create an objective + +Prerequisites: + +- You must have at least the Guest role for the project. + +To create an objective: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues**. +1. In the top right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. +1. Select **New objective** again. +1. Enter the objective title. +1. Select **Create objective**. + +To create a key result, [add it as a child](#add-a-child-key-result) to an existing objective. + +## View an objective + +Prerequisites: + +- You must have at least the Guest role for the project. + +To view an objective: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues**. +1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) +for `Type = objective`. +1. Select the title of an objective from the list. + +## View a key result + +Prerequisites: + +- You must have at least the Guest role for the project. + +To view a key result: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues**. +1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) +for `Type = key_result`. +1. Select the title of a key result from the list. + +Alternatively, you can access a key result from the **Child objectives and key results** section in +its parent's objective. + +## Edit title and description + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To edit an OKR: + +1. [Open the objective](okrs.md#view-an-objective) or [key result](#view-a-key-result) that you want to edit. +1. Optional. To edit the title, select it, make your changes, and select any area outside the title + text box. +1. Optional. To edit the description, select the edit icon (**{pencil}**), make your changes, and + select **Save**. + +## Assign users + +To show who is responsible for an OKR, you can assign users to it. + +Users on GitLab Free can assign one user per OKR. +Users on GitLab Premium and higher can assign multiple users to a single OKR. +See also [multiple assignees for issues](project/issues/multiple_assignees_for_issues.md). + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To change the assignee on an OKR: + +1. [Open the objective](okrs.md#view-an-objective) or [key result](#view-a-key-result) that you want to edit. +1. Next to **Assignees**, select **Add assignees**. +1. From the dropdown list, select the users to add as an assignee. +1. Select any area outside the dropdown list. + +## Assign labels + +Prerequisites: + +- You must have at least the Reporter role for the project. + +Use [labels](project/labels.md) to organize OKRs among teams. + +To add labels to an OKR: + +1. [Open the objective](okrs.md#view-an-objective) or [key result](#view-a-key-result) that you want to edit. +1. Next to **Labels**, select **Add labels**. +1. From the dropdown list, select the labels to add. +1. Select any area outside the dropdown list. + +## Add an objective to a milestone + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367463) in GitLab 15.7. + +You can add an objective to a [milestone](project/milestones/index.md). +You can see the milestone title when you view an objective. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To add an objective to a milestone: + +1. [Open the objective](okrs.md#view-an-objective) that you want to edit. +1. Next to **Milestone**, select **Add to milestone**. + If an objective already belongs to a milestone, the dropdown list shows the current milestone. +1. From the dropdown list, select the milestone to be associated with the objective. + +## Set objective progress + +Show how much of the work needed to achieve an objective is finished. + +You can only set progress manually on objectives, and it's not rolled up from child objectives or +key results. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To set progress of an objective: + +1. [Open the objective](okrs.md#view-an-objective) that you want to edit. +1. Next to **Progress**, select the text box. +1. Enter a number from 0 to 100. + +## Set health status + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381899) in GitLab 15.7. + +To better track the risk in meeting your goals, you can assign a [health status](project/issues/managing_issues.md#health-status) +to each objective and key result. +You can use health status to signal to others in your organization whether OKRs are progressing +as planned or need attention to stay on schedule. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To set health status of an OKR: + +1. [Open the key result](okrs.md#view-a-key-result) that you want to edit. +1. Next to **Health status**, select the dropdown list and select the desired health status. + +## Close an OKR + +When an OKR is achieved, you can close it. +The OKR is marked as closed but is not deleted. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To close an OKR: + +1. [Open the objective](okrs.md#view-an-objective) that you want to edit. +1. Next to **Status**, select **Closed**. + +You can reopen a closed OKR the same way. + +## Child objectives and key results + +In GitLab, objectives are similar to key results. +In your workflow, use key results to measure the goal described in the objective. + +You can add child objectives to a total of 9 levels. An objective can have up to 100 child OKRs. +Key results are children of objectives and cannot have children items themselves. + +Child objectives and key results are available in the **Child objectives and key results** section +below an objective's description. + +### Add a child objective + +Prerequisites: + +- You must have at least the Guest role for the project. + +To add a new objective to an objective: + +1. In an objective, in the **Child objectives and key results** section, select **Add** and then + select **New objective**. +1. Enter a title for the new objective. +1. Select **Create objective**. + +To add an existing objective to an objective: + +1. In an objective, in the **Child objectives and key results** section, select **Add** and then + select **Existing objective**. +1. Search for the desired objective by entering part of its title, then selecting the + desired match. + + To add multiple objectives, repeat this step. +1. Select **Add objective**. + +### Add a child key result + +Prerequisites: + +- You must have at least the Guest role for the project. + +To add a new key result to an objective: + +1. In an objective, in the **Child objectives and key results** section, select **Add** and then + select **New key result**. +1. Enter a title for the new key result. +1. Select **Create key result**. + +To add an existing key result to an objective: + +1. In an objective, in the **Child objectives and key results** section, select **Add** and then + select **Existing key result**. +1. Search for the desired OKR by entering part of its title, then selecting the + desired match. + + To add multiple objectives, repeat this step. +1. Select **Add key result**. diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md new file mode 100644 index 00000000000..cdc7cbe947b --- /dev/null +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -0,0 +1,60 @@ +--- +stage: Package +group: Container Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Authenticate with the Container Registry **(FREE)** + +To authenticate with the Container Registry, you can use a: + +- [Personal access token](../../profile/personal_access_tokens.md). +- [Deploy token](../../project/deploy_tokens/index.md). +- [Project access token](../../project/settings/project_access_tokens.md). +- [Group access token](../../group/settings/group_access_tokens.md). + +All of these authentication methods require the minimum scope: + +- For read (pull) access, to be `read_registry`. +- For write (push) access, to be`write_registry` and `read_registry`. + +To authenticate, run the `docker login` command. For example: + + ```shell + docker login registry.example.com -u <username> -p <token> + ``` + +## Use GitLab CI/CD to authenticate + +To use CI/CD to authenticate with the Container Registry, you can use: + +- The `CI_REGISTRY_USER` CI/CD variable. + + This variable has read-write access to the Container Registry and is valid for + one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. + + ```shell + docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + ``` + +- A [CI job token](../../../ci/jobs/ci_job_token.md). + + ```shell + docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY + ``` + +- A [deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) with the minimum scope of: + - For read (pull) access, `read_registry`. + - For write (push) access, `write_registry`. + + ```shell + docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY + ``` + +- A [personal access token](../../profile/personal_access_tokens.md) with the minimum scope of: + - For read (pull) access, `read_registry`. + - For write (push) access, `write_registry`. + + ```shell + docker login -u <username> -p <access_token> $CI_REGISTRY + ``` diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md new file mode 100644 index 00000000000..bbb82300488 --- /dev/null +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -0,0 +1,214 @@ +--- +stage: Package +group: Container Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Build and push container images to the Container Registry **(FREE)** + +Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the Container Registry. + +## Use Docker commands + +You can use Docker commands to build and push container images to your Container Registry: + +1. [Authenticate](authenticate_with_container_registry.md) with the Container Registry. +1. Run the Docker command to build or push. For example: + + - To build: + + ```shell + docker build -t registry.example.com/group/project/image . + ``` + + - To push: + + ```shell + docker push registry.example.com/group/project/image + ``` + +## Configure your `.gitlab-ci.yml` file + +You can configure your `.gitlab-ci.yml` file to build and push container images to the Container Registry. + +- If multiple jobs require authentication, put the authentication command in the `before_script`. +- Before building, use `docker build --pull` to fetch changes to base images. It takes slightly + longer, but it ensures your image is up-to-date. +- Before each `docker run`, do an explicit `docker pull` to fetch + the image that was just built. This step is especially important if you are + using multiple runners that cache images locally. + + If you use the Git SHA in your image tag, each job is unique and you + should never have a stale image. However, it's still possible to have a + stale image if you rebuild a given commit after a dependency has changed. +- Don't build directly to the `latest` tag because multiple jobs may be + happening simultaneously. + +## Use GitLab CI/CD + +You can use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push container images to the +Container Registry. You can use CI/CD to test, build, and deploy your project from the container +image you created. + +### Use a Docker-in-Docker container image from your Container Registry + +You can use your own container images for Docker-in-Docker. + +1. Set up [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker). +1. Update the `image` and `service` to point to your registry. +1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). + +Your `.gitlab-ci.yml` should look similar to this: + +```yaml +build: + image: $CI_REGISTRY/group/project/docker:20.10.16 + services: + - name: $CI_REGISTRY/group/project/docker:20.10.16-dind + alias: docker + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` + +If you forget to set the service alias, the container image can't find the `dind` service, +and an error like the following is shown: + +```plaintext +error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host +``` + +### Use a Docker-in-Docker container image with Dependency Proxy + +You can use your own container images with Dependency Proxy. + +1. Set up [Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker). +1. Update the `image` and `service` to point to your registry. +1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). + +Your `.gitlab-ci.yml` should look similar to this: + +```yaml +build: + image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:20.10.16 + services: + - name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:18.09.7-dind + alias: docker + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests +``` + +If you forget to set the service alias, the container image can't find the `dind` service, +and an error like the following is shown: + +```plaintext +error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host +``` + +## Container Registry examples with GitLab CI/CD + +If you're using Docker-in-Docker on your runners, your `.gitlab-ci.yml` file should look similar to this: + +```yaml +build: + image: docker:20.10.16 + stage: build + services: + - docker:20.10.16-dind + script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker build -t $CI_REGISTRY/group/project/image:latest . + - docker push $CI_REGISTRY/group/project/image:latest +``` + +You can use [CI/CD variables](../../../ci/variables/index.md) in your `.gitlab-ci.yml` file. For example: + +```yaml +build: + image: docker:20.10.16 + stage: build + services: + - docker:20.10.16-dind + variables: + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG + script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker build -t $IMAGE_TAG . + - docker push $IMAGE_TAG +``` + +In this example, `$CI_REGISTRY_IMAGE` resolves to the address of the registry tied +to this project. `$CI_COMMIT_REF_NAME` resolves to the branch or tag name, which +can contain forward slashes. Image tags can't contain forward slashes. Use +`$CI_COMMIT_REF_SLUG` as the image tag. You can declare the variable, `$IMAGE_TAG`, +combining `$CI_REGISTRY_IMAGE` and `$CI_REGISTRY_IMAGE` to save some typing in the +`script` section. + +This example splits the tasks into 4 pipeline stages, including two tests that run in parallel. The `build` is stored in the container +registry and used by subsequent stages, downloading the container image when needed. Changes to `main` also get tagged as +`latest` and deployed using an application-specific deploy script: + +```yaml +image: docker:20.10.16 +services: + - docker:20.10.16-dind + +stages: + - build + - test + - release + - deploy + +variables: + # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled + DOCKER_HOST: tcp://docker:2376 + DOCKER_TLS_CERTDIR: "/certs" + CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG + CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest + +before_script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + +build: + stage: build + script: + - docker build --pull -t $CONTAINER_TEST_IMAGE . + - docker push $CONTAINER_TEST_IMAGE + +test1: + stage: test + script: + - docker pull $CONTAINER_TEST_IMAGE + - docker run $CONTAINER_TEST_IMAGE /script/to/run/tests + +test2: + stage: test + script: + - docker pull $CONTAINER_TEST_IMAGE + - docker run $CONTAINER_TEST_IMAGE /script/to/run/another/test + +release-image: + stage: release + script: + - docker pull $CONTAINER_TEST_IMAGE + - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE + - docker push $CONTAINER_RELEASE_IMAGE + only: + - main + +deploy: + stage: deploy + script: + - ./deploy.sh + only: + - main + environment: production +``` + +NOTE: +This example explicitly calls `docker pull`. If you prefer to implicitly pull the container image using `image:`, +and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor, +make sure that [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work) is set to `always`. diff --git a/doc/user/packages/container_registry/delete_container_registry_images.md b/doc/user/packages/container_registry/delete_container_registry_images.md new file mode 100644 index 00000000000..9adb9313f09 --- /dev/null +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -0,0 +1,117 @@ +--- +stage: Package +group: Container Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Delete container images from the Container Registry **(FREE)** + +You can delete container images from your Container Registry. + +WARNING: +Deleting container images is a destructive action and can't be undone. To restore +a deleted container image, you must rebuild and re-upload it. + +Deleting a container image on self-managed instances doesn't free up storage space, it only marks the image +as eligible for deletion. To actually delete unreferenced container images and recover storage space, administrators +must run [garbage collection](../../../administration/packages/container_registry.md#container-registry-garbage-collection). + +On GitLab.com, the latest version of the Container Registry includes an automatic online garbage +collector. For more information, see [this blog post](https://about.gitlab.com/blog/2021/10/25/gitlab-com-container-registry-update/). +The automatic online garbage collector is an instance-wide feature, rolling out gradually to a subset +of the user base. Some new container image repositories created from GitLab 14.5 onward are served by this +new version of the Container Registry. In this new version of the Container Registry, layers that aren't +referenced by any image manifest, and image manifests that have no tags and aren't referenced by another +manifest (such as multi-architecture images), are automatically scheduled for deletion after 24 hours if +left unreferenced. + +## Use the GitLab UI + +To delete container images using the GitLab UI: + +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Container Registry**. +1. From the **Container Registry** page, you can select what you want to delete, + by either: + + - Deleting the entire repository, and all the tags it contains, by selecting + the red **{remove}** **Trash** icon. + - Navigating to the repository, and deleting tags individually or in bulk + by selecting the red **{remove}** **Trash** icon next to the tag you want + to delete. + +1. In the dialog box, select **Remove tag**. + +## Use the GitLab API + +You can use the API to automate the process of deleting container images. For more +information, see the following endpoints: + +- [Delete a Registry repository](../../../api/container_registry.md#delete-registry-repository) +- [Delete an individual Registry repository tag](../../../api/container_registry.md#delete-a-registry-repository-tag) +- [Delete Registry repository tags in bulk](../../../api/container_registry.md#delete-registry-repository-tags-in-bulk) + +## Use GitLab CI/CD + +NOTE: +GitLab CI/CD doesn't provide a built-in way to remove your container images. This example uses a +third-party tool called [reg](https://github.com/genuinetools/reg) that talks to the GitLab Registry API. +For assistance with this third-party tool, see [the issue queue for reg](https://github.com/genuinetools/reg/issues). + +The following example defines two stages: `build`, and `clean`. The `build_image` job builds a container +image for the branch, and the `delete_image` job deletes it. The `reg` executable is downloaded and used to +remove the container image matching the `$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG` +[predefined CI/CD variable](../../../ci/variables/predefined_variables.md). + +To use this example, change the `IMAGE_TAG` variable to match your needs. + +```yaml +stages: + - build + - clean + +build_image: + image: docker:20.10.16 + stage: build + services: + - docker:20.10.16-dind + variables: + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG + script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker build -t $IMAGE_TAG . + - docker push $IMAGE_TAG + only: + - branches + except: + - main + +delete_image: + before_script: + - curl --fail --show-error --location "https://github.com/genuinetools/reg/releases/download/v$REG_VERSION/reg-linux-amd64" --output ./reg + - echo "$REG_SHA256 ./reg" | sha256sum -c - + - chmod a+x ./reg + image: curlimages/curl:7.86.0 + script: + - ./reg rm -d --auth-url $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $IMAGE_TAG + stage: clean + variables: + IMAGE_TAG: $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG + REG_SHA256: ade837fc5224acd8c34732bf54a94f579b47851cc6a7fd5899a98386b782e228 + REG_VERSION: 0.16.1 + only: + - branches + except: + - main +``` + +NOTE: +You can download the latest `reg` release from [the releases page](https://github.com/genuinetools/reg/releases), then update +the code example by changing the `REG_SHA256` and `REG_VERSION` variables defined in the `delete_image` job. + +## Use a cleanup policy + +You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and +images are regularly removed from the Container Registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 4b4d6190dc2..c3790c252cc 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -8,84 +8,86 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. -NOTE: -If you pull container images from Docker Hub, you can use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) -to avoid rate limits and speed up your pipelines. - -With the Docker Container Registry integrated into GitLab, every GitLab project can -have its own space to store its Docker images. +You can use the integrated Container Registry to store container images for each GitLab project -You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>. +To enable the Container Registry for your GitLab instance, see the [administrator documentation](../../../administration/packages/container_registry.md). -This document is the user guide. To learn how to enable the Container -Registry for your GitLab instance, visit the -[administrator documentation](../../../administration/packages/container_registry.md). +NOTE: +If you pull Docker container images from Docker Hub, you can use the +[GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) to avoid +rate limits and speed up your pipelines. For more information about the Docker Registry, see <https://docs.docker.com/registry/introduction/>. ## View the Container Registry You can view the Container Registry for a project or group. -1. Go to your project or group. -1. Go to **Packages and registries > Container Registry**. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Container Registry**. -You can search, sort, filter, and [delete](#delete-images-using-the-gitlab-ui) -containers on this page. You can share a filtered view by copying the URL from your browser. +You can search, sort, filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) + your container images. You can share a filtered view by copying the URL from your browser. -Only members of the project or group can access a private project's Container Registry. -Images downloaded from a private registry may be [available to other users in a shared runner](https://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). +Only members of the project or group can access the Container Registry for a private project. +Container images downloaded from a private registry may be [available to other users in a shared runner](https://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). -If a project is public, so is the Container Registry. +If a project is public, the Container Registry is also public. -### View the tags of a specific image +### View the tags of a specific container image in the Container Registry You can use the Container Registry **Tag Details** page to view a list of tags associated with a given container image: -1. Go to your project or group. -1. Go to **Packages and registries > Container Registry**. -1. Select the container image you are interested in. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Container Registry**. +1. Select your container image. You can view details about each tag, such as when it was published, how much storage it consumes, and the manifest and configuration digests. -You can search, sort (by tag name), filter, and [delete](#delete-images-using-the-gitlab-ui) +You can search, sort (by tag name), filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) tags on this page. You can share a filtered view by copying the URL from your browser. -## Use images from the Container Registry +## Use container images from the Container Registry -To download and run a container image hosted in the GitLab Container Registry: +To download and run a container image hosted in the Container Registry: -1. Copy the link to your container image: - - Go to your project or group's **Packages and registries > Container Registry** - and find the image you want. - - Next to the image name, select **Copy**. +1. On the top bar, select **Main menu**, and: + - For a project, select **Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Packages and registries > Container Registry**. +1. Find the container image you want to work with and select **Copy**.  -1. Use `docker run` with the image link: +1. Use `docker run` with the copied link: ```shell docker run [options] registry.example.com/group/project/image [arguments] ``` -[Authentication](#authenticate-with-the-container-registry) is needed to download images from a private repository. +NOTE: +You must [authenticate with the container registry](authenticate_with_container_registry.md) to download +container images from a private repository. -For more information on running Docker containers, visit the -[Docker documentation](https://docs.docker.com/get-started/). +For more information on running container images, visit the [Docker documentation](https://docs.docker.com/get-started/). -## Image naming convention +## Naming convention for your container images -Images follow this naming convention: +Your container images must follow this naming convention: ```plaintext <registry URL>/<namespace>/<project>/<image> ``` -If your project is `gitlab.example.com/mynamespace/myproject`, for example, -then your image must be named `gitlab.example.com/mynamespace/myproject` at a minimum. +For example, if your project is `gitlab.example.com/mynamespace/myproject`, +then your container image must be named `gitlab.example.com/mynamespace/myproject`. -You can append additional names to the end of an image name, up to two levels deep. +You can append additional names to the end of a container image name, up to two levels deep. -For example, these are all valid image names for images in the project named `myproject`: +For example, these are all valid names for container images in the project named `myproject`: ```plaintext registry.example.com/mynamespace/myproject:some-tag @@ -99,399 +101,12 @@ registry.example.com/mynamespace/myproject/image:latest registry.example.com/mynamespace/myproject/my/image:rc1 ``` -## Authenticate with the Container Registry - -To authenticate with the Container Registry, you can use a: - -- [Personal access token](../../profile/personal_access_tokens.md). -- [Deploy token](../../project/deploy_tokens/index.md). -- [Project access token](../../project/settings/project_access_tokens.md). -- [Group access token](../../group/settings/group_access_tokens.md). - -All of these require the minimum scope to be: - -- For read (pull) access, `read_registry`. -- For write (push) access, `write_registry` & `read_registry`. - -To authenticate, run the `docker` command. For example: - - ```shell - docker login registry.example.com -u <username> -p <token> - ``` - -## Build and push images by using Docker commands - -Before you can build and push images, you must [authenticate](#authenticate-with-the-container-registry) with the Container Registry. - -To build and push to the Container Registry: - -1. Authenticate with the Container Registry. - -1. Run the command to build or push. For example, to build: - - ```shell - docker build -t registry.example.com/group/project/image . - ``` - - Or to push: - - ```shell - docker push registry.example.com/group/project/image - ``` - -To view these commands, go to your project's **Packages and registries > Container Registry**. - -## Build and push by using GitLab CI/CD - -Use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push images to the -Container Registry. Use it to test, build, and deploy your project from the Docker -image you created. - -### Authenticate by using GitLab CI/CD - -Before you can build and push images by using GitLab CI/CD, you must authenticate with the Container Registry. - -To use CI/CD to authenticate, you can use: - -- The `CI_REGISTRY_USER` CI/CD variable. - - This variable has read-write access to the Container Registry and is valid for - one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. - - ```shell - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - ``` - -- A [CI job token](../../../ci/jobs/ci_job_token.md). - - ```shell - docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY - ``` - -- A [deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) with the minimum scope of: - - For read (pull) access, `read_registry`. - - For write (push) access, `write_registry`. - - ```shell - docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY - ``` - -- A [personal access token](../../profile/personal_access_tokens.md) with the minimum scope of: - - For read (pull) access, `read_registry`. - - For write (push) access, `write_registry`. - - ```shell - docker login -u <username> -p <access_token> $CI_REGISTRY - ``` - -### Configure your `.gitlab-ci.yml` file - -You can configure your `.gitlab-ci.yml` file to build and push images to the Container Registry. - -- If multiple jobs require authentication, put the authentication command in the `before_script`. -- Before building, use `docker build --pull` to fetch changes to base images. It takes slightly - longer, but it ensures your image is up-to-date. -- Before each `docker run`, do an explicit `docker pull` to fetch - the image that was just built. This step is especially important if you are - using multiple runners that cache images locally. - - If you use the Git SHA in your image tag, each job is unique and you - should never have a stale image. However, it's still possible to have a - stale image if you rebuild a given commit after a dependency has changed. -- Don't build directly to the `latest` tag because multiple jobs may be - happening simultaneously. - -### Container Registry examples with GitLab CI/CD - -If you're using Docker-in-Docker on your runners, this is how your `.gitlab-ci.yml` -should look: - -```yaml -build: - image: docker:20.10.16 - stage: build - services: - - docker:20.10.16-dind - script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - - docker build -t $CI_REGISTRY/group/project/image:latest . - - docker push $CI_REGISTRY/group/project/image:latest -``` - -You can also make use of [other CI/CD variables](../../../ci/variables/index.md) to avoid hard-coding: - -```yaml -build: - image: docker:20.10.16 - stage: build - services: - - docker:20.10.16-dind - variables: - IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG - script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - - docker build -t $IMAGE_TAG . - - docker push $IMAGE_TAG -``` - -In this example, `$CI_REGISTRY_IMAGE` resolves to the address of the registry tied -to this project. `$CI_COMMIT_REF_NAME` resolves to the branch or tag name, which -can contain forward slashes. Image tags can't contain forward slashes. Use -`$CI_COMMIT_REF_SLUG` as the image tag. You can declare the variable, `$IMAGE_TAG`, -combining `$CI_REGISTRY_IMAGE` and `$CI_REGISTRY_IMAGE` to save some typing in the -`script` section. - -Here's a more elaborate example that splits up the tasks into 4 pipeline stages, -including two tests that run in parallel. The `build` is stored in the container -registry and used by subsequent stages, downloading the image -when needed. Changes to `main` also get tagged as `latest` and deployed using -an application-specific deploy script: - -```yaml -image: docker:20.10.16 -services: - - docker:20.10.16-dind - -stages: - - build - - test - - release - - deploy - -variables: - # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled - DOCKER_HOST: tcp://docker:2376 - DOCKER_TLS_CERTDIR: "/certs" - CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG - CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest - -before_script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - -build: - stage: build - script: - - docker build --pull -t $CONTAINER_TEST_IMAGE . - - docker push $CONTAINER_TEST_IMAGE - -test1: - stage: test - script: - - docker pull $CONTAINER_TEST_IMAGE - - docker run $CONTAINER_TEST_IMAGE /script/to/run/tests - -test2: - stage: test - script: - - docker pull $CONTAINER_TEST_IMAGE - - docker run $CONTAINER_TEST_IMAGE /script/to/run/another/test - -release-image: - stage: release - script: - - docker pull $CONTAINER_TEST_IMAGE - - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE - - docker push $CONTAINER_RELEASE_IMAGE - only: - - main - -deploy: - stage: deploy - script: - - ./deploy.sh - only: - - main - environment: production -``` - -NOTE: -This example explicitly calls `docker pull`. If you prefer to implicitly pull the -built image using `image:`, and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) -or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor, -make sure that [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work) -is set to `always`. - -### Using a Docker-in-Docker image from your Container Registry - -To use your own Docker images for Docker-in-Docker, follow these steps -in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) section: - -1. Update the `image` and `service` to point to your registry. -1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). - -Below is an example of what your `.gitlab-ci.yml` should look like: - -```yaml -build: - image: $CI_REGISTRY/group/project/docker:20.10.16 - services: - - name: $CI_REGISTRY/group/project/docker:20.10.16-dind - alias: docker - stage: build - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests -``` - -If you forget to set the service alias, the `docker:20.10.16` image is unable to find the -`dind` service, and an error like the following is thrown: - -```plaintext -error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host -``` - -### Using a Docker-in-Docker image with Dependency Proxy - -To use your own Docker images with Dependency Proxy, follow these steps -in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) section: - -1. Update the `image` and `service` to point to your registry. -1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). - -Below is an example of what your `.gitlab-ci.yml` should look like: - -```yaml -build: - image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:20.10.16 - services: - - name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:18.09.7-dind - alias: docker - stage: build - script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests -``` - -If you forget to set the service alias, the `docker:20.10.16` image is unable to find the -`dind` service, and an error like the following is thrown: - -```plaintext -error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host -``` - -## Delete images - -You can delete images from your Container Registry in multiple ways. - -WARNING: -Deleting images is a destructive action and can't be undone. To restore -a deleted image, you must rebuild and re-upload it. - -On self-managed instances, deleting an image doesn't free up storage space - it only marks the image -as eligible for deletion. To actually delete images and recover storage space, in case they're -unreferenced, administrators must run [garbage collection](../../../administration/packages/container_registry.md#container-registry-garbage-collection). - -On GitLab.com, the latest version of the Container Registry includes an automatic online garbage -collector. For more information, see [this blog post](https://about.gitlab.com/blog/2021/10/25/gitlab-com-container-registry-update/). -The automatic online garbage collector is an instance-wide feature, rolling out gradually to a subset -of the user base. Some new image repositories created from GitLab 14.5 onward are served by this -new version of the Container Registry. In this new version of the Container Registry, layers that aren't -referenced by any image manifest, and image manifests that have no tags and aren't referenced by another -manifest (such as multi-architecture images), are automatically scheduled for deletion after 24 hours if -left unreferenced. - -### Delete images using the GitLab UI - -To delete images using the GitLab UI: - -1. Go to your project's or group's **Packages and registries > Container Registry**. -1. From the **Container Registry** page, you can select what you want to delete, - by either: - - - Deleting the entire repository, and all the tags it contains, by selecting - the red **{remove}** **Trash** icon. - - Navigating to the repository, and deleting tags individually or in bulk - by selecting the red **{remove}** **Trash** icon next to the tag you want - to delete. - -1. In the dialog box, select **Remove tag**. - -### Delete images using the API - -If you want to automate the process of deleting images, GitLab provides an API. For more -information, see the following endpoints: - -- [Delete a Registry repository](../../../api/container_registry.md#delete-registry-repository) -- [Delete an individual Registry repository tag](../../../api/container_registry.md#delete-a-registry-repository-tag) -- [Delete Registry repository tags in bulk](../../../api/container_registry.md#delete-registry-repository-tags-in-bulk) - -### Delete images using GitLab CI/CD - -WARNING: -GitLab CI/CD doesn't provide a built-in way to remove your images. This example -uses a third-party tool called [reg](https://github.com/genuinetools/reg) -that talks to the GitLab Registry API. You are responsible for your own actions. -For assistance with this tool, see -[the issue queue for reg](https://github.com/genuinetools/reg/issues). - -The following example defines two stages: `build`, and `clean`. The -`build_image` job builds the Docker image for the branch, and the -`delete_image` job deletes it. The `reg` executable is downloaded and used to -remove the image matching the `$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG` -[predefined CI/CD variable](../../../ci/variables/predefined_variables.md). - -To use this example, change the `IMAGE_TAG` variable to match your needs: - -```yaml -stages: - - build - - clean - -build_image: - image: docker:20.10.16 - stage: build - services: - - docker:20.10.16-dind - variables: - IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG - script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - - docker build -t $IMAGE_TAG . - - docker push $IMAGE_TAG - only: - - branches - except: - - main - -delete_image: - before_script: - - curl --fail --show-error --location "https://github.com/genuinetools/reg/releases/download/v$REG_VERSION/reg-linux-amd64" --output ./reg - - echo "$REG_SHA256 ./reg" | sha256sum -c - - - chmod a+x ./reg - image: curlimages/curl:7.86.0 - script: - - ./reg rm -d --auth-url $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $IMAGE_TAG - stage: clean - variables: - IMAGE_TAG: $CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG - REG_SHA256: ade837fc5224acd8c34732bf54a94f579b47851cc6a7fd5899a98386b782e228 - REG_VERSION: 0.16.1 - only: - - branches - except: - - main -``` - -NOTE: -You can download the latest `reg` release from -[the releases page](https://github.com/genuinetools/reg/releases), then update -the code example by changing the `REG_SHA256` and `REG_VERSION` variables -defined in the `delete_image` job. - -### Delete images by using a cleanup policy - -You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and images are regularly removed from the -Container Registry. - -## Known issues +## Move or rename Container Registry repositories -Moving or renaming existing Container Registry repositories is not supported -after you have pushed images. The images are stored in a path that matches -the repository path. To move or rename a repository with a -Container Registry, you must delete all existing images. -Community suggestions to work around this known issue have been shared in +Moving or renaming existing Container Registry repositories is not supported after you have pushed +container images. The container images are stored in a path that matches the repository path. To move +or rename a repository with a Container Registry, you must delete all existing container images. +Community suggestions to work around this known issue are shared in [issue 18383](https://gitlab.com/gitlab-org/gitlab/-/issues/18383#possible-workaround). ## Disable the Container Registry for a project @@ -500,7 +115,8 @@ The Container Registry is enabled by default. You can, however, remove the Container Registry for a project: -1. Go to your project's **Settings > General** page. +1. On the top bar, select **Main menu > Projects**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility, project features, permissions** section and disable **Container Registry**. 1. Select **Save changes**. @@ -514,10 +130,11 @@ The **Packages and registries > Container Registry** entry is removed from the p By default, the Container Registry is visible to everyone with access to the project. You can, however, change the visibility of the Container Registry for a project. -See the [Container Registry visibility permissions](#container-registry-visibility-permissions) -for more details about the permissions that this setting grants to users. +For more information about the permissions that this setting grants to users, +see [Container Registry visibility permissions](#container-registry-visibility-permissions). -1. Go to your project's **Settings > General** page. +1. On the top bar, select **Main menu > Projects**. +1. On the left sidebar, select **Settings > General**. 1. Expand the section **Visibility, project features, permissions**. 1. Under **Container Registry**, select an option from the dropdown list: @@ -533,19 +150,18 @@ for more details about the permissions that this setting grants to users. ## Container Registry visibility permissions -The ability to view the Container Registry and pull images is controlled by the Container Registry's -visibility permissions. You can change this through the [visibility setting on the UI](#change-visibility-of-the-container-registry) +The ability to view the Container Registry and pull container images is controlled by the Container Registry's +visibility permissions. You can change the visibility through the [visibility setting on the UI](#change-visibility-of-the-container-registry) or the [API](../../../api/container_registry.md#change-the-visibility-of-the-container-registry). -[Other permissions](../../permissions.md) -such as updating the Container Registry and pushing or deleting images are not affected by +[Other permissions](../../permissions.md) such as updating the Container Registry and pushing or deleting container images are not affected by this setting. However, disabling the Container Registry disables all Container Registry operations. -| | | Anonymous<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | -| -------------------- | --------------------- | --------- | ----- | ------------------------------------------ | -| Public project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | Yes | Yes | Yes | -| Public project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Internal project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | Yes | Yes | -| Internal project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | +| | | Anonymous<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | +|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|--------------------------------------|-------|----------------------------------------| +| Public project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | Yes | Yes | Yes | +| Public project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| Internal project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | Yes | Yes | +| Internal project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | +| Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index cbf9af633ac..15948569cb8 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -36,7 +36,7 @@ An image layer is only counted once if: - You share the image layer across different repositories. Only layers that are referenced by tagged images are accounted for. Untagged images and any layers -referenced exclusively by them are subject to [online garbage collection](index.md#delete-images). +referenced exclusively by them are subject to [online garbage collection](delete_container_registry_images.md). Untagged images are automatically deleted after 24 hours if they remain unreferenced during that period. Image layers are stored on the storage backend in the original (usually compressed) format. This @@ -269,7 +269,7 @@ only if the number of tags being cleaned up is minimal. Here are some other options you can use to reduce the Container Registry storage used by your project: -- Use the [GitLab UI](index.md#delete-images) +- Use the [GitLab UI](delete_container_registry_images.md#use-the-gitlab-ui) to delete individual image tags or the entire repository containing all the tags. - Use the API to [delete individual image tags](../../../api/container_registry.md#delete-a-registry-repository-tag). - Use the API to [delete the entire container registry repository containing all the tags](../../../api/container_registry.md#delete-registry-repository). diff --git a/doc/user/packages/container_registry/troubleshoot_container_registry.md b/doc/user/packages/container_registry/troubleshoot_container_registry.md index eac7e0fcacd..68fe430e531 100644 --- a/doc/user/packages/container_registry/troubleshoot_container_registry.md +++ b/doc/user/packages/container_registry/troubleshoot_container_registry.md @@ -87,7 +87,7 @@ The following procedure uses these sample project names: docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1 ``` -1. Delete the images in the old project by using the [UI](index.md#delete-images) or [API](../../../api/packages.md#delete-a-project-package). +1. Delete the images in the old project by using the [UI](delete_container_registry_images.md) or [API](../../../api/packages.md#delete-a-project-package). There may be a delay while the images are queued and deleted. 1. Change the path or transfer the project: diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index b7a9729c8ba..a1a9d2a4915 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -169,7 +169,7 @@ build: - docker build -t test . ``` -You can also use [custom CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) to store and access your personal access token or deploy token. +You can also use [custom CI/CD variables](../../../ci/variables/index.md#for-a-project) to store and access your personal access token or deploy token. ### Store a Docker image in Dependency Proxy cache diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index c6c2f238564..2d1efd024a0 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -78,7 +78,7 @@ The three endpoints are: | -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | Project | `https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<project_id>` with your project ID, found on your project's homepage. | | Group | `https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<group_id>` with your group ID, found on your group's homepage. | -| Instance | `https:///gitlab.example.com/api/v4/packages/maven` | Replace `gitlab.example.com` with your domain name. | +| Instance | `https://gitlab.example.com/api/v4/packages/maven` | Replace `gitlab.example.com` with your domain name. | ### Edit the `pom.xml` for publishing diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index caa305999c5..ab5d652b731 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -151,8 +151,6 @@ Several known issues exist when you allow anyone to pull from the Package Regist - Project-level endpoints are supported. Group-level and instance-level endpoints are not supported. Support for group-level endpoints is proposed in [issue 383537](https://gitlab.com/gitlab-org/gitlab/-/issues/383537). - It does not work with the [Composer](../composer_repository/index.md#install-a-composer-package), because Composer only has a group endpoint. -- It does not work with the [Debian](../debian_repository/index.md#install-a-package) repository. Support for the Debian repository is proposed in [issue 385258](https://gitlab.com/gitlab-org/gitlab/-/issues/385258). -- It does not work with the [Ruby gems](../rubygems_registry/index.md#install-a-ruby-gem) repository. Support for the Ruby gems repository is proposed in [issue 385259](https://gitlab.com/gitlab-org/gitlab/-/issues/385259). - It will work with Conan, but using [`conan search`](../conan_repository/index.md#search-for-conan-packages-in-the-package-registry) does not work. ## Accepting contributions diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index 1085cf5c239..673196ebad5 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -75,6 +75,8 @@ To access these project settings, you must be at least a maintainer on the relat to upload more than one copy of an asset. You can limit the number of duplicated assets to keep and automatically delete the oldest assets once the limit is reached. Unique filenames, such as those produced by Maven snapshots, are not considered when evaluating the number of duplicated assets to keep. + `Number of duplicated assets to keep` has a [fixed cadence of 12 hours](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/packages/cleanup/policy.rb). + ### Set cleanup limits to conserve resources A background process executes the package-cleanup policies. This process can take a long time to finish and consumes diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md new file mode 100644 index 00000000000..e56ae88872a --- /dev/null +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -0,0 +1,146 @@ +--- +stage: Package +group: Package Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Supported package functionality + +The GitLab Package Registry supports different functionalities for each package type. This support includes publishing +and pulling packages, request forwarding, managing duplicates, and authentication. + +## Publishing packages **(FREE)** + +Packages can be published to your project, group, or instance. + +| Package type | Project | Group | Instance | +|-----------------------------------------------------|---------|-------|----------| +| [Maven](../maven_repository/index.md) | Y | N | N | +| [npm](../npm_registry/index.md) | Y | N | N | +| [NuGet](../nuget_repository/index.md) | Y | N | N | +| [PyPI](../pypi_repository/index.md) | Y | N | N | +| [Generic packages](../generic_packages/index.md) | Y | N | N | +| [Terraform](../terraform_module_registry/index.md) | Y | N | N | +| [Composer](../composer_repository/index.md) | N | Y | N | +| [Conan](../conan_repository/index.md) | Y | N | N | +| [Helm](../helm_repository/index.md) | Y | N | N | +| [Debian](../debian_repository/index.md) | Y | N | N | +| [Go](../go_proxy/index.md) | Y | N | Y | +| [Ruby gems](../rubygems_registry/index.md) | Y | N | N | + +## Pulling packages **(FREE)** + +Packages can be pulled from your project, group, or instance. + +| Package type | Project | Group | Instance | +|-----------------------------------------------------|---------|-------|----------| +| [Maven](../maven_repository/index.md) | Y | Y | Y | +| [npm](../npm_registry/index.md) | Y | Y | Y | +| [NuGet](../nuget_repository/index.md) | Y | Y | N | +| [PyPI](../pypi_repository/index.md) | Y | Y | N | +| [Generic packages](../generic_packages/index.md) | Y | N | N | +| [Terraform](../terraform_module_registry/index.md) | N | Y | N | +| [Composer](../composer_repository/index.md) | Y | Y | N | +| [Conan](../conan_repository/index.md) | Y | N | Y | +| [Helm](../helm_repository/index.md) | Y | N | N | +| [Debian](../debian_repository/index.md) | Y | N | N | +| [Go](../go_proxy/index.md) | Y | N | Y | +| [Ruby gems](../rubygems_registry/index.md) | Y | N | N | + +## Forwarding requests **(PREMIUM)** + +Requests for packages not found in your GitLab project are forwarded to the public registry. For example, Maven Central, npmjs, or PyPI. + +| Package type | Supports request forwarding | +|-----------------------------------------------------|-----------------------------| +| [Maven](../maven_repository/index.md) | Y | +| [npm](../npm_registry/index.md) | Y | +| [NuGet](../nuget_repository/index.md) | N | +| [PyPI](../pypi_repository/index.md) | Y | +| [Generic packages](../generic_packages/index.md) | N | +| [Terraform](../terraform_module_registry/index.md) | N | +| [Composer](../composer_repository/index.md) | N | +| [Conan](../conan_repository/index.md) | N | +| [Helm](../helm_repository/index.md) | N | +| [Debian](../debian_repository/index.md) | N | +| [Go](../go_proxy/index.md) | N | +| [Ruby gems](../rubygems_registry/index.md) | N | + +## Allow or prevent duplicates **(FREE)** + +By default, the GitLab package registry either allows or prevents duplicates based on the default of that specific package manager format. + +| Package type | Duplicates allowed? | +|-----------------------------------------------------|---------------------| +| [Maven](../maven_repository/index.md) | Y (configurable) | +| [npm](../npm_registry/index.md) | N | +| [NuGet](../nuget_repository/index.md) | Y | +| [PyPI](../pypi_repository/index.md) | N | +| [Generic packages](../generic_packages/index.md) | Y (configurable) | +| [Terraform](../terraform_module_registry/index.md) | N | +| [Composer](../composer_repository/index.md) | N | +| [Conan](../conan_repository/index.md) | N | +| [Helm](../helm_repository/index.md) | Y | +| [Debian](../debian_repository/index.md) | Y | +| [Go](../go_proxy/index.md) | N | +| [Ruby gems](../rubygems_registry/index.md) | Y | + +## Authentication tokens **(FREE)** + +GitLab tokens are used to authenticate with the GitLab Package Registry. + +The following tokens are supported: + +| Package type | Supported tokens | +|-----------------------------------------------------|------------------------------------------------------------------------| +| [Maven](../maven_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [npm](../npm_registry/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [NuGet](../nuget_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [PyPI](../pypi_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Generic packages](../generic_packages/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Terraform](../terraform_module_registry/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Composer](../composer_repository/index.md) | Personal access, job tokens, deploy (project or group), project access | +| [Conan](../conan_repository/index.md) | Personal access, job tokens, project access | +| [Helm](../helm_repository/index.md) | Personal access, job tokens, deploy (project or group) | +| [Debian](../debian_repository/index.md) | Personal access, job tokens, deploy (project or group) | +| [Go](../go_proxy/index.md) | Personal access, job tokens, project access | +| [Ruby gems](../rubygems_registry/index.md) | Personal access, job tokens, deploy (project or group) | + +## Authentication protocols **(FREE)** + +The following authentication protocols are supported: + +| Package type | Supported auth protocols | +|-----------------------------------------------------|--------------------------| +| [Maven](../maven_repository/index.md) | Headers | +| [npm](../npm_registry/index.md) | OAuth | +| [NuGet](../nuget_repository/index.md) | Basic auth | +| [PyPI](../pypi_repository/index.md) | Basic auth | +| [Generic packages](../generic_packages/index.md) | Basic auth | +| [Terraform](../terraform_module_registry/index.md) | Token | +| [Composer](../composer_repository/index.md) | OAuth | +| [Conan](../conan_repository/index.md) | OAuth, Basic auth | +| [Helm](../helm_repository/index.md) | Basic auth | +| [Debian](../debian_repository/index.md) | Basic auth | +| [Go](../go_proxy/index.md) | Basic auth | +| [Ruby gems](../rubygems_registry/index.md) | Token | + +## Supported hash types **(FREE)** + +Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md). + +The Package Registry supports the following hash types: + +| Package type | Supported hashes | +|--------------------------------------------------|----------------------------------| +| [Maven](../maven_repository/index.md) | MD5, SHA1 | +| [npm](../npm_registry/index.md) | SHA1 | +| [NuGet](../nuget_repository/index.md) | not applicable | +| [PyPI](../pypi_repository/index.md) | MD5, SHA256 | +| [Generic packages](../generic_packages/index.md) | SHA256 | +| [Composer](../composer_repository/index.md) | not applicable | +| [Conan](../conan_repository/index.md) | MD5, SHA1 | +| [Helm](../helm_repository/index.md) | not applicable | +| [Debian](../debian_repository/index.md) | MD5, SHA1, SHA256 | +| [Go](../go_proxy/index.md) | MD5, SHA1, SHA256 | +| [Ruby gems](../rubygems_registry/index.md) | MD5, SHA1, SHA256 (gemspec only) | diff --git a/doc/user/packages/package_registry/supported_hash_types.md b/doc/user/packages/package_registry/supported_hash_types.md index 6d7dbf87468..d39b8d60c93 100644 --- a/doc/user/packages/package_registry/supported_hash_types.md +++ b/doc/user/packages/package_registry/supported_hash_types.md @@ -1,25 +1,11 @@ --- -stage: Package -group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'supported_functionality.md' +remove_date: '2023-04-22' --- -# Supported hash types **(FREE)** +This document was moved to [another location](supported_functionality.md). -Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md). - -The Package Registry supports the following hash types: - -| Package type | Supported hashes | -|--------------------------------------------------|----------------------------------| -| [Maven](../maven_repository/index.md) | MD5, SHA1 | -| [npm](../npm_registry/index.md) | SHA1 | -| [NuGet](../nuget_repository/index.md) | not applicable | -| [PyPI](../pypi_repository/index.md) | MD5, SHA256 | -| [Generic packages](../generic_packages/index.md) | SHA256 | -| [Composer](../composer_repository/index.md) | not applicable | -| [Conan](../conan_repository/index.md) | MD5, SHA1 | -| [Helm](../helm_repository/index.md) | not applicable | -| [Debian](../debian_repository/index.md) | MD5, SHA1, SHA256 | -| [Go](../go_proxy/index.md) | MD5, SHA1, SHA256 | -| [Ruby gems](../rubygems_registry/index.md) | MD5, SHA1, SHA256 (gemspec only) | +<!-- This redirect file can be deleted after <2023-04-22>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/permissions.md b/doc/user/permissions.md index f3702b848fa..8455db45030 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -71,7 +71,7 @@ The following table lists project permissions available for each role: | [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) | | | | | ✓ | | [Clusters](infrastructure/clusters/index.md):<br>View clusters | | | ✓ | ✓ | ✓ | | [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/index.md#delete-images-by-using-a-cleanup-policy) | | | | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/delete_container_registry_images.md#use-a-cleanup-policy) | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*19*) | ✓ (*19*) | ✓ | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | @@ -222,8 +222,8 @@ The following table lists project permissions available for each role: 1. On self-managed GitLab instances, guest users are able to perform this action only on public and internal projects (not on private projects). [External users](admin_area/external_users.md) - must be given explicit access even if the project is internal. For GitLab.com, see the - [GitLab.com visibility settings](gitlab_com/index.md#visibility-settings). + must be given explicit access even if the project is internal. Users with the Guest role on GitLab.com are + only able to perform this action on public projects because internal visibility is not available. 2. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves or are assigned to. 3. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). 4. If the [branch is protected](project/protected_branches.md), this depends on the access given to Developers and Maintainers. @@ -236,7 +236,7 @@ The following table lists project permissions available for each role: 10. Users can only view events based on their individual actions. 11. Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). -12. If the [tag is protected](#release-permissions-with-protected-tags), this depends on the access given to Developers and Maintainers. +12. If the [tag is protected](project/protected_tags.md), this depends on the access given to Developers and Maintainers. 13. A Maintainer or Owner can't change project features visibility level if [project visibility](public_access.md) is set to private. 14. Attached design files are moved together with the issue even if the user doesn't have the @@ -276,7 +276,7 @@ More details about the permissions for some project-level features follow. | View pipeline details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | | View pipelines page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | | View pipelines tab in MR | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | | View and download project-level [Secure Files](../api/secure_files.md) | | | | ✓ | ✓ | ✓ | | Cancel and retry jobs | | | | ✓ | ✓ | ✓ | | Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | @@ -284,7 +284,7 @@ More details about the permissions for some project-level features follow. | Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | | Run CI/CD pipeline for a protected branch | | | | ✓ (*5*) | ✓ (*5*) | ✓ | | Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | | ✓ | ✓ | ✓ | +| View a job with [debug logging](../ci/variables/index.md#enable-debug-logging) | | | | ✓ | ✓ | ✓ | | Use pipeline editor | | | | ✓ | ✓ | ✓ | | Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | | Add specific runners to project | | | | | ✓ | ✓ | @@ -332,24 +332,6 @@ This table shows granted privileges for jobs triggered by specific types of user 1. Only if the triggering user is not an external one. 1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](http://docs.gitlabl.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). -### File Locking permissions **(PREMIUM)** - -The user that locks a file or directory is the only one that can edit and push their changes back to the repository where the locked objects are located. - -Read through the documentation on [permissions for File Locking](project/file_lock.md#permissions) to learn more. - -### Confidential Issues permissions - -[Confidential issues](project/issues/confidential_issues.md) can be accessed by users with reporter and higher permission levels, -as well as by guest users that create a confidential issue or are assigned to it. To learn more, -read through the documentation on [permissions and access to confidential issues](project/issues/confidential_issues.md#permissions-and-access-to-confidential-issues). - -### Container Registry visibility permissions - -The ability to view the Container Registry and pull images is controlled by the Container Registry's -visibility permissions. Find these permissions for the Container Registry as described in the -[related documentation](packages/container_registry/index.md#container-registry-visibility-permissions). - ## Group members permissions Any user can remove themselves from a group, unless they are the last Owner of @@ -448,13 +430,13 @@ To learn more, read through the documentation on > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in GitLab 13.4. -Owners can add members with a "minimal access" role to a parent group. Such users don't automatically have access to +Owners can add members with a "minimal access" role to a root group. Such users don't automatically have access to projects and subgroups underneath. Owners must explicitly add these "minimal access" users to the specific subgroups and projects. You can use minimal access to give the same member more than one role in a group: -1. Add the member to the parent group with a minimal access role. +1. Add the member to the root group with a minimal access role. 1. Invite the member as a direct member with a specific role in any subgroup or project in that group. Because of an [outstanding issue](https://gitlab.com/gitlab-org/gitlab/-/issues/267996), when minimal access users: @@ -470,20 +452,15 @@ Users with even a "minimal access" role are counted against your number of licen requirement does not apply for [GitLab Ultimate](https://about.gitlab.com/pricing/) subscriptions. -## Release permissions with protected tags - -[The permission to create tags](project/protected_tags.md) is used to define if a user can -create, edit, and delete [Releases](project/releases/index.md). - -See [Release permissions](project/releases/index.md#release-permissions) -for more information. - ## Related topics - [The GitLab principles behind permissions](https://about.gitlab.com/handbook/product/gitlab-the-product/#permissions-in-gitlab) - [Members](project/members/index.md) - Customize permissions on [protected branches](project/protected_branches.md) -- [LDAP users permissions](group/access_and_permissions.md#manage-group-memberships-via-ldap) +- [LDAP user permissions](group/access_and_permissions.md#manage-group-memberships-via-ldap) - [Value stream analytics permissions](analytics/value_stream_analytics.md#access-permissions-for-value-stream-analytics) - [Project aliases](../user/project/import/index.md#project-aliases) - [Auditor users](../administration/auditor_users.md) +- [Confidential issues](project/issues/confidential_issues.md) +- [Container Registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) +- [Release permissions](project/releases/index.md#release-permissions) diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 39826bf59c4..5f23f50f439 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -444,7 +444,7 @@ This error occurs in the following scenarios: password. For 2FA-enabled users, a [personal access token](../personal_access_tokens.md) (PAT) must be used instead of a password. To authenticate: - Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required. - - [GitLab Container Registry](../../packages/container_registry/index.md#authenticate-with-the-container-registry) requests, a PAT + - [GitLab Container Registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT with `read_registry` or `write_registry` scope is required. - [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with `read_registry` and `write_registry` scopes is required. diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index d66e555970a..49e6319aa12 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d6c5bd6c108..f178a3254f3 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -75,7 +75,9 @@ The following is hidden from your user profile page (`https://gitlab.example.com - Tabs for activity, groups, contributed projects, personal projects, starred projects, snippets NOTE: -Making your user profile page private does not hide all your public resources from the REST or GraphQL APIs. +Making your user profile page private does not hide all your public resources from +the REST or GraphQL APIs. For example, the email address associated with your commit +signature is accessible unless you [use an automatically-generated private commit email](#use-an-automatically-generated-private-commit-email). ### User visibility @@ -85,7 +87,7 @@ not. When visiting the public page of a user, you can only see the projects which you have privileges to. If the [public level is restricted](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels), -user profiles are only visible to signed-in users. +user profiles are only visible to authenticated users. ## Add details to your profile with a README @@ -389,7 +391,7 @@ Without the `config.extend_remember_period` flag, you would be forced to sign in - Receive emails for: - [Sign-ins from unknown IP addresses or devices](notifications.md#notifications-for-unknown-sign-ins) - [Attempted sign-ins using wrong two-factor authentication codes](notifications.md#notifications-for-attempted-sign-in-using-wrong-two-factor-authentication-codes) -- Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth) +- Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md) - Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications - Manage [SSH keys](../ssh.md) to access your account via SSH - Change your [syntax highlighting theme](preferences.md#syntax-highlighting-theme) diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index d0a420a4bbd..7343aea8ce7 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -248,40 +248,37 @@ enabled a feature flag for [moved sidebar actions](../project/merge_requests/ind The following table presents the events that generate notifications for issues, merge requests, and epics: -| Event | Sent to | -|------------------------|---------| -| Change milestone issue | Subscribers and participants mentioned. | -| Change milestone merge request | Subscribers and participants mentioned. | -| Close epic | | -| Close issue | | -| Close merge request | | -| 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._ | -| Issue due | Participants and Custom notification level with this event selected. | -| 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 epic | | -| New issue | | -| New merge request | | -| New note | 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. | -| 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 and participants mentioned. | -| Remove milestone merge request | Subscribers and participants mentioned. | -| Reopen epic | | -| Reopen issue | | -| Reopen merge request | | -| 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 -if they had been mentioned in the original text. - -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. +| Type | Event | Sent to | +|------|-------|---------| +| Epic | Closed | Subscribers and participants. | +| Epic | New | Anyone mentioned by username in the description, with notification level "Mention" or higher. | +| Epic | New note | 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. | +| Epic | Reopened | Subscribers and participants. | +| Issue | Closed | Subscribers and participants. | +| Issue | Due | Participants and Custom notification level with this event selected. | +| Issue | Milestone changed | Subscribers and participants. | +| Issue | Milestone removed | Subscribers and participants. | +| Issue | New | Anyone mentioned by username in the description, with notification level "Mention" or higher. | +| Issue | New note | 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. | +| Issue | Title or description changed | Any new mentions by username. | +| Issue | Reassigned | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | +| Issue | Reopened | Subscribers and participants. | +| Merge Request | Closed | Subscribers and participants. | +| Merge Request | Conflict | Author and any user that has set the merge request to automatically merge when pipeline succeeds. | +| 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._ | +| Merge Request | Merged | Subscribers and participants. | +| Merge Request | Merged 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 | Milestone changed | Subscribers and participants. | +| Merge Request | Milestone removed | Subscribers and participants. | +| Merge Request | New | Anyone mentioned by username in the description, with notification level "Mention" or higher. | +| Merge Request | New note | 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. | +| Merge Request | Pushed | Participants and Custom notification level with this event selected. | +| Merge Request | Reassigned | Participants, Watchers, Subscribers, Custom notification level with this event selected, and the old assignee. | +| Merge Request | Reopened | Subscribers and participants. | +| Merge Request | Title or description changed | Any new mentions by username. | +| Pipeline | Failed | The author of the pipeline. | +| Pipeline | Fixed | The author of the pipeline. Enabled by default. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1._ | +| Pipeline | Successful | 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. | 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 diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 507ad6378bc..90def3aa773 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -31,7 +31,7 @@ Personal access tokens are: - Required when [two-factor authentication (2FA)](account/two_factor_authentication.md) is enabled. - Used with a GitLab username to authenticate with GitLab features that require usernames. For example, [GitLab-managed Terraform state backend](../infrastructure/iac/terraform_state.md#use-your-gitlab-backend-as-a-remote-data-source) - and [Docker container registry](../packages/container_registry/index.md#authenticate-with-the-container-registry), + and [Docker container registry](../packages/container_registry/authenticate_with_container_registry.md), - Similar to [project access tokens](../project/settings/project_access_tokens.md) and [group access tokens](../group/settings/group_access_tokens.md), but are attached to a user rather than a project or group. @@ -115,6 +115,7 @@ A personal access token can perform actions based on the assigned scopes. | `read_registry` | Grants read-only (pull) access to a [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. | | `write_registry` | Grants read-write (push) access to a [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | | `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator. | +| `admin_mode` | Grants permission to perform API actions as an administrator, when Admin Mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107875) in GitLab 15.8.) | ## When personal access tokens expire diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 65e4a5d9fde..6e188a4923b 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -21,7 +21,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use the GitLab cluster integration, you can still deploy to your cluster. However, you must configure Kubernetes tools yourself - using [CI/CD variables](../../../ci/variables/index.md#custom-cicd-variables) + using [CI/CD variables](../../../ci/variables/index.md#for-a-project) before you can interact with the cluster from your jobs. ## Deployment variables @@ -43,7 +43,7 @@ following command in your deployment job script, for Kubernetes to access the re ``` The Kubernetes cluster integration exposes these -[deployment variables](../../../ci/variables/index.md#deployment-variables) in the +[deployment variables](../../../ci/variables/predefined_variables.md#deployment-variables) in the GitLab CI/CD build environment to deployment jobs. Deployment jobs have [defined a target environment](../../../ci/environments/index.md). diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 95d3bf6e121..c79f250da7a 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -26,7 +26,7 @@ differentiates the new cluster from the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific CI/CD variables](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) work. +[environment-specific CI/CD variables](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) work. The default environment scope is `*`, which means all jobs, regardless of their environment, use that cluster. Each scope can be used only by a single cluster diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index aeeacd495a7..641dff2766e 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -324,7 +324,7 @@ README.md @docs A Code Owner approval rule is optional if any of these conditions are true: -- The user or group are not a member of the project or parent group. +- The user or group are not a member of the project. Code Owners [cannot inherit from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). - [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. - The section is [marked as optional](#make-a-code-owners-section-optional). diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 56bb899c233..e87c5f57fc1 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -15,7 +15,7 @@ Depending on your needs, you might want to use a [deploy token](../deploy_tokens |------------------|-------------|--------------| | Sharing | Shareable between multiple projects, even those in different groups. | Belong to a project or group. | | Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. | -| Validity | Valid as long as it's registered and enabled. | Can be given an expiration date. | +| Validity | Valid as long as it's registered and enabled, and the user that created it exists. | Can be given an expiration date. | | Registry access | Cannot access a package registry. | Can read from and write to a package registry. | Deploy keys can't be used for Git operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 98b46650b42..29d29c12536 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -31,11 +31,12 @@ When importing: - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. -## Prerequisite for GitLab self-managed +## Prerequisites -To import your projects from Bitbucket Cloud, the [Bitbucket Cloud integration](../../../integration/bitbucket.md) -must be enabled. If it isn't enabled, ask your GitLab administrator to enable it. By default it's -enabled on GitLab.com. +- [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator + to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. ## How it works @@ -102,7 +103,7 @@ Bitbucket username after connecting their Bitbucket account in the To fix this, the user must verify that their Bitbucket external UID in the GitLab database matches their current Bitbucket public name, and reconnect if there's a mismatch: -1. [Use the API to get the currently authenticated user](../../../api/users.md#for-normal-users-1). +1. [Use the API to get the currently authenticated user](../../../api/users.md#for-non-administrator-users-1). 1. In the API response, the `identities` attribute contains the Bitbucket account that exists in the GitLab database. If the `extern_uid` doesn't match the current Bitbucket public name, the diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index d7fa1338c55..db2a1d956ab 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -24,10 +24,11 @@ created as private in GitLab as well. ## Import your Bitbucket repositories -Prerequisite: +Prerequisites: -- An administrator must have enabled the **Bitbucket Server** in - **Admin > Settings > General > Visibility and access controls > Import sources**. +- An administrator must enable **Bitbucket Server** in **Admin > Settings > General > Visibility and access controls > Import sources**. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. To import your Bitbucket repositories: diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index f6395fd9234..08ee4c70dda 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -14,6 +14,11 @@ The importer imports all of your cases and comments with the original case numbers and timestamps. You can also map FogBugz users to GitLab users. +Prerequisite: + +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + To import your project from FogBugz: 1. Sign in to GitLab. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 46e6b6d377d..fb64c902b38 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -6,11 +6,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from Gitea to GitLab **(FREE)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. + Import your projects from Gitea to GitLab with minimal effort. NOTE: This requires Gitea `v1.0.0` or later. +Prerequisite: + +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + The Gitea importer can import: - Repository description @@ -30,10 +37,6 @@ 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. If the -namespace is taken, the repository is imported under the user's namespace -that started the import process. - ## Import your Gitea repositories The importer page is visible when you create a new project. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index c1297cbf554..da3637541d9 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -7,6 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from GitHub to GitLab **(FREE)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. + You can import your GitHub repositories: - From either GitHub.com or GitHub Enterprise. @@ -22,6 +24,9 @@ If you are importing to a self-managed GitLab instance, you can use the [GitHub Rake task](../../../administration/raketasks/github_import.md) instead. This allows you to import projects without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. +NOTE: +If you are importing a project using the GitHub Rake task, GitLab still creates namespaces or groups that don't exist. + If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable [GitHub integration](../../../integration/github.md). @@ -40,9 +45,7 @@ When importing projects: - If a user referenced in the project is not found in the GitLab database, the project creator is set as the author and assignee. The project creator is usually the user that initiated the import process. A note on the issue mentioning the original GitHub author is added. -- The importer creates any new namespaces (or groups) if they do not exist, or, if the namespace is taken, the - repository is imported under the namespace of the user who initiated the import process. The namespace or repository - name can also be edited, with the proper permissions. +- You can change the target namespace and target repository name before you import. - The importer also imports branches on forks of projects related to open pull requests. These branches are imported with a naming scheme similar to `GH-SHA-username/pull-request-number/fork-name/branch`. This may lead to a discrepancy in branches compared to those of the GitHub repository. @@ -54,6 +57,9 @@ For an overview of the import process, see the video [Migrating from GitHub to G ## Prerequisites +At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + When issues and pull requests are being imported, the importer attempts to find their GitHub authors and assignees in the database of the GitLab instance. Pull requests are called _merge requests_ in GitLab. @@ -68,6 +74,8 @@ GitLab content imports that use GitHub accounts require that the GitHub public-f all comments and contributions are properly mapped to the same user in GitLab. GitHub Enterprise does not require this field to be populated so you may have to add it on existing accounts. +See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional prerequisites for those imports. + ## Import your GitHub repository into GitLab ### Use the GitHub integration @@ -242,11 +250,15 @@ When they are imported, supported GitHub branch protection rules are mapped to e | GitHub rule | GitLab rule | Introduced in | | :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | -| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | -| **Require a pull request before merging** | **No one** option in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | -| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | -| **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | -| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | +| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | +| **Require a pull request before merging** | **No one** option in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | +| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | +| **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | +| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | +| **Require a pull request before merging - Allow specified actors to bypass required pull requests** (1) | List of users in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) **(PREMIUM)**. Without a Premium license, the list of users that are allowed to push is limited to roles. | [GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/384939) | + +1. To successfully import the **Require a pull request before merging - Allow specified actors to bypass required pull requests** rule, you must add to the parent group in GitLab + the users that are allowed to bypass required pull requests before you begin importing. Mapping GitHub rule **Require status checks to pass before merging** to [external status checks](../merge_requests/status_checks.md) was considered in issue diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 795cb964423..c00709d9697 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -5,7 +5,12 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import a project from GitLab.com to your private GitLab instance **(FREE)** +# Import a project from GitLab.com to your self-managed GitLab instance (deprecated) **(FREE)** + +WARNING: +The GitLab.com importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108502) in GitLab 15.8 +and will be removed in GitLab 16.0. To import GitLab projects from GitLab.com to a self-managed GitLab instance use +[migrating groups and projects by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). You can import your existing GitLab.com projects to your GitLab instance. diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 208bce90453..3df6a543960 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -15,17 +15,22 @@ If you want to bring existing projects to GitLab or copy GitLab projects to a di - Between a self-managed instance and GitLab.com in both directions. - In the same GitLab instance. -For any type of source and target, you can migrate projects: +Prerequisite: -- As part of a [GitLab group migration](../../group/import/index.md). You can't migrate only chosen projects, - but you can migrate many projects at once within a group. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + +For any type of source and target, you can migrate GitLab projects: + +- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all + projects in a group at once. Migrating projects by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready + for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). However, you can't import issues and merge requests this way. To retain metadata like issues and merge requests, either: -- [Migrate projects with groups](../../group/import/index.md). +- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). @@ -45,7 +50,6 @@ You can import projects from: - [GitLab.com](gitlab_com.md) - [Gitea](gitea.md) - [Perforce](perforce.md) -- [From SVN](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Git-as-a-Client) - [TFVC](tfvc.md) - [Repository by URL](repo_by_url.md) - [Uloading a manifest file (AOSP)](manifest.md) @@ -57,6 +61,13 @@ repository is too large, the import can timeout. You can then [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). +## Import from Subversion + +GitLab can not automatically migrate Subversion repositories to Git. Converting Subversion repositories to Git can be difficult, but several tools exist including: + +- [`git svn`](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git), for very small and simple repositories. +- [`reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html), for larger and more complex repositories. + ## Migrate using the API To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). @@ -101,8 +112,8 @@ To view project import history: 1. Select **History** in the upper right corner. 1. If there are any errors for a particular import, you can see them by selecting **Details**. -The history also includes projects created from [built-in](../working_with_projects.md#create-a-project-from-a-built-in-template) -or [custom](../working_with_projects.md#create-a-project-from-a-built-in-template) +The history also includes projects created from [built-in](../index.md#create-a-project-from-a-built-in-template) +or [custom](../index.md#create-a-project-from-a-built-in-template) templates. GitLab uses [import repository by URL](repo_by_url.md) to create a new project from a template. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index ea26613639d..c125102b0c9 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -17,11 +17,10 @@ repositories like the Android Open Source Project (AOSP). ## Requirements -GitLab must be using PostgreSQL for its database, since -[subgroups](../../group/subgroups/index.md) are needed for the manifest import -to work. - -Read more about the [database requirements](../../../install/requirements.md#database). +- GitLab must use PostgreSQL for its database, because [subgroups](../../group/subgroups/index.md) are needed for the manifest import + to work. Read more about the [database requirements](../../../install/requirements.md#database). +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. ## Manifest format diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 49f12ca2ba6..09e7543bc4a 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -5,11 +5,15 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import Phabricator tasks into a GitLab project **(FREE SELF)** +# Import Phabricator tasks into a GitLab project (deprecated) **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. WARNING: +The Phabricator task importer was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106369) in GitLab 15.7 +and will be removed in GitLab 16.0. + +WARNING: The Phabricator task importer is in [beta](../../../policy/alpha-beta-support.md#beta-features) and is [**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index d6f4f862b95..93e3991ba19 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -7,6 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import project from repository by URL **(FREE)** +Prerequisite: + +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. + You can import your existing repositories by providing the Git URL: 1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 6730ef862e6..c9abc0f459d 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -1,5 +1,5 @@ --- -redirect_to: 'index.md' +redirect_to: 'index.md#import-from-subversion' remove_date: '2023-03-15' --- diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 78a6e8d565f..08caa62bcb2 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,161 +1,186 @@ --- 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/product/ux/technical-writing/#assignments +group: Organization +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- -# Organize work with projects **(FREE)** - -In GitLab, you can create projects to host -your codebase. You can also use projects to track issues, plan work, -collaborate on code, and continuously build, test, and use -built-in CI/CD to deploy your app. - -Projects can be available [publicly, internally, or privately](../public_access.md). -GitLab does not limit the number of private projects you can create. - -## Project features - -Projects include the following [features](https://about.gitlab.com/features/): - -**Repositories:** - -- [Issue tracker](issues/index.md): Discuss implementations with your team. - - [Issue boards](issue_board.md): Organize and prioritize your workflow. - - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. -- [Repositories](repository/index.md): Host your code in a fully-integrated platform. - - [Branches](repository/branches/index.md): Use Git branching strategies to - collaborate on code. - - [Protected branches](protected_branches.md): Prevent collaborators - 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/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) -- [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a - vulnerability in your project. - -**Issues and merge requests:** - -- [Issue tracker](issues/index.md): Discuss implementations with your team. - - [Issue boards](issue_board.md): Organize and prioritize your workflow. - - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. -- [Merge requests](merge_requests/index.md): Apply a branching - strategy and get reviewed by your team. - - [Merge request approvals](merge_requests/approvals/index.md): Ask for approval before - implementing a change. - - [Fix merge conflicts from the UI](merge_requests/conflicts.md): View Git diffs from the GitLab UI. - - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results - of the changes proposed in a merge request. -- [Labels](labels.md): Organize issues and merge requests by labels. -- [Time Tracking](time_tracking.md): Track time estimated and - spent on issues and merge requests. -- [Milestones](milestones/index.md): Work toward a target date. -- [Description templates](description_templates.md): Define context-specific - templates for issue and merge request description fields. -- [Slash commands (quick actions)](quick_actions.md): Create text shortcuts for - common actions. -- [Autocomplete characters](autocomplete_characters.md): Autocomplete - references to users, groups, issues, merge requests, and other GitLab - elements. -- [Web IDE](web_ide/index.md) - -**GitLab CI/CD:** - -- [GitLab CI/CD](../../ci/index.md): Use the built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool. - - [Container Registry](../packages/container_registry/index.md): Build and push Docker - images. - - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD - to automatically set up your app's deployment. - - [Enable and disable GitLab CI/CD](../../ci/enable_or_disable_ci.md) - - [Pipelines](../../ci/pipelines/index.md): Configure and visualize - your GitLab CI/CD pipelines from the UI. - - [Scheduled Pipelines](../../ci/pipelines/schedules.md): Schedule a pipeline - to start at a chosen time. - - [Pipeline Graphs](../../ci/pipelines/index.md#visualize-pipelines): View your - pipeline from the UI. - - [Job artifacts](../../ci/pipelines/job_artifacts.md): Define, - 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](../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. -- [GitLab Pages](pages/index.md): Build, test, and deploy your static - website. - -**Other features:** - -- [Wiki](wiki/index.md): Document your GitLab project in an integrated Wiki. -- [Snippets](../snippets.md): Store, share and collaborate on code snippets. -- [Value Stream Analytics](../analytics/value_stream_analytics.md): Review your development lifecycle. -- [Insights](insights/index.md): Configure the insights that matter for your projects. -- [Security Dashboard](../application_security/security_dashboard/index.md) -- [Syntax highlighting](highlighting.md): Customize - your code blocks, overriding the default language choice. -- [Badges](badges.md): Add an image to the **Project information** page. -- [Releases](releases/index.md): Take a snapshot of - the source, build output, metadata, and artifacts - associated with a released version of your code. -- [Package Registry](../packages/package_registry/index.md): Publish and install packages. -- [Code owners](code_owners.md): Specify code owners for specific files. -- [License Compliance](../compliance/license_compliance/index.md): Approve and deny licenses for projects. -- [Dependency List](../application_security/dependency_list/index.md): View project dependencies. -- [Requirements](requirements/index.md): Create criteria to check your products against. -- [Code Intelligence](code_intelligence.md): Navigate code. - -## Project integrations - -[Integrate your project](integrations/index.md) with Jira, Mattermost, -Kubernetes, Slack, and a lot more. - -## Import or export a project - -- [Import a project](import/index.md) from: - - [GitHub to GitLab](import/github.md) - - [Bitbucket to GitLab](import/bitbucket.md) - - [Gitea to GitLab](import/gitea.md) - - [FogBugz to GitLab](import/fogbugz.md) -- [Export a project from GitLab](settings/import_export.md#export-a-project-and-its-data) -- [Importing and exporting projects between GitLab instances](settings/import_export.md) - -## GitLab Workflow - VS Code extension - -To avoid switching from the GitLab UI and VS Code while working in GitLab repositories, you can integrate -the [VS Code](https://code.visualstudio.com/) editor with GitLab through the -[GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). - -To review or contribute to the extension's code, visit [its codebase in GitLab](https://gitlab.com/gitlab-org/gitlab-vscode-extension/). - -## Project APIs - -There are numerous [APIs](../../api/index.md) to use with your projects: - -- [Badges](../../api/project_badges.md) -- [Clusters](../../api/project_clusters.md) -- [Threads](../../api/discussions.md) -- [General](../../api/projects.md) -- [Import/export](../../api/project_import_export.md) -- [Issue board](../../api/boards.md) -- [Labels](../../api/labels.md) -- [Markdown](../../api/markdown.md) -- [Merge requests](../../api/merge_requests.md) -- [Milestones](../../api/milestones.md) -- [Services](../../api/integrations.md) -- [Snippets](../../api/project_snippets.md) -- [Templates](../../api/project_templates.md) -- [Traffic](../../api/project_statistics.md) -- [Variables](../../api/project_level_variables.md) -- [Aliases](../../api/project_aliases.md) -- [DORA4 Analytics](../../api/dora/metrics.md) - -## DORA4 analytics overview - -Project details include the following analytics: - -- Deployment Frequency - -For more information, see [DORA4 Project Analytics API](../../api/dora/metrics.md). +# Create a project **(FREE)** + +You can create a project in many ways in GitLab. + +## Create a blank project + +To create a blank project: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Create blank project**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project deployment target (optional)** field, select your project's deployment target. + This information helps GitLab better understand its users and their deployment requirements. + - To modify the project's [viewing and access rights](../public_access.md) for + users, change the **Visibility Level**. + - To create README file so that the Git repository is initialized, has a default branch, and + can be cloned, select **Initialize repository with a README**. + - To analyze the source code in the project for known security vulnerabilities, + select **Enable Static Application Security Testing (SAST)**. +1. Select **Create project**. + +## Create a project from a built-in template + +A built-in project template populates a new project with files to get you started. +Built-in templates are sourced from the following groups: + +- [`project-templates`](https://gitlab.com/gitlab-org/project-templates) +- [`pages`](https://gitlab.com/pages) + +Anyone can [contribute a built-in template](../../development/project_templates.md). + +To create a project from a built-in template: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Create from template**. +1. Select the **Built-in** tab. +1. From the list of templates: + - To view a preview of the template, select **Preview**. + - To use a template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a project from a custom template **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. + +Custom project templates are available at: + +- The [instance-level](../../user/admin_area/custom_project_templates.md) +- The [group-level](../../user/group/custom_project_templates.md) + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Create from template**. +1. Select the **Instance** or **Group** tab. +1. From the list of templates: + - To view a preview of the template, select **Preview**. + - To use a template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - The description of your project's dashboard in the **Project description (optional)** field. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 + +The HIPAA Audit Protocol template contains issues for audit inquiries in the +HIPAA Audit Protocol published by the U.S Department of Health and Human Services. + +To create a project from the HIPAA Audit Protocol template: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Create from template**. +1. Select the **Built-in** tab. +1. Locate the **HIPAA Audit Protocol** template: + - To view a preview of the template, select **Preview**. + - To use the template for the project, select **Use template**. +1. Enter the project details: + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. + - In the **Project slug** field, enter the path to your project. The GitLab instance uses the + slug as the URL path to the project. To change the slug, first enter the project name, + then change the slug. + - In the **Project description (optional)** field, enter the description of your project's dashboard. + - To modify the project's [viewing and access rights](../public_access.md) for users, + change the **Visibility Level**. +1. Select **Create project**. + +## Create a new project with Git push + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. + +Use `git push` to push a local project repository to GitLab. After you push a repository, +GitLab creates your project in your chosen namespace. + +You cannot use `git push` to create projects with project paths that: + +- Have previously been used. +- Have been [renamed](settings/index.md#rename-a-repository). + +Previously used project paths have a redirect. The redirect causes push attempts to redirect requests +to the renamed project location, instead of creating a new project. To create a new project for a previously +used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). + +Prerequisites: + +- To push with SSH, you must have [an SSH key](../ssh.md) that is + [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). +- You must have permission to add new projects to a namespace. To check if you have permission: + + 1. On the top bar, select **Main menu > Groups** and find your group. + 1. Confirm that **New project** is visible in the upper right + corner. Contact your GitLab + administrator if you require permission. + +To push your repository and create a project: + +1. Push with SSH or HTTPS: + - To push with SSH: + + ```shell + git push --set-upstream git@gitlab.example.com:namespace/myproject.git master + ``` + + - To push with HTTPS: + + ```shell + git push --set-upstream https://gitlab.example.com/namespace/myproject.git master + ``` + + - For `gitlab.example.com`, use the domain name of the machine that hosts your Git repository. + - For `namespace`, use the name of your [namespace](../namespace/index.md). + - For `myproject`, use the name of your project. + - Optional. To export existing repository tags, append the `--tags` flag to your `git push` command. +1. Optional. To configure the remote: + + ```shell + git remote add origin https://gitlab.example.com/namespace/myproject.git + ``` + +When the push completes, GitLab displays the message: + +```shell +remote: The private project namespace/myproject was created. +``` + +To view your new project, go to `https://gitlab.example.com/namespace/myproject`. +Your project's visibility is set to **Private** by default. To change project visibility, adjust your +[project's settings](../public_access.md#change-project-visibility). + +## Related topics + +- For a list of words that you cannot use as project names, see + [reserved project and group names](../../user/reserved_names.md). +- For a list of characters that you cannot use in project and group names, see + [limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). +- [Manage projects](working_with_projects.md). diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md new file mode 100644 index 00000000000..62b25bf8191 --- /dev/null +++ b/doc/user/project/integrations/apple_app_store.md @@ -0,0 +1,59 @@ +--- +stage: Manage +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Apple App Store integration **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. + +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 `apple_app_store_integration`. On GitLab.com, this feature is not available. + +The Apple App Store integration makes it easy to configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. + +The integration is designed to be able to work out of the box with [fastlane](http://fastlane.tools/), but can be used with other build tools as well. + +## Prerequisites + +An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.com/programs/enroll/) is required to enable this integration. + +## Configure GitLab + +GitLab supports enabling the Apple App Store integration at the project level. Complete these steps in GitLab: + +1. In the Apple App Store Connect portal, generate a new private key for your project by following [these instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Apple App Store**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the Apple App Store Connect configuration information: + - **Issuer ID**: The Apple App Store Connect Issuer ID can be found in the *Keys* section under *Users and Access* the Apple App Store Connect portal. + - **Key ID**: The Key ID of the new private key that was just generated. + - **Private Key**: The Private Key that was just generated. Note: you are only be able to download this key one time. + +1. Select **Save changes**. + +After the Apple App Store integration is activated: + +- The global variables `$APP_STORE_CONNECT_API_KEY_ISSUER_ID`, `$APP_STORE_CONNECT_API_KEY_KEY_ID`, and `$APP_STORE_CONNECT_API_KEY_KEY` are created for CI/CD use. +- `$APP_STORE_CONNECT_API_KEY_KEY` contains the Base64 encoded Private Key. + +## Security considerations + +### CI/CD variable security + +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables, including +`$APP_STORE_CONNECT_API_KEY_KEY`, and send them to a third-party server. For more details, see +[CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). + +## fastlane Example + +Because this integration works out of the box with fastlane adding the code below to an app's `fastlane/Fastfile` activates the integration, and create the connection for any interactions with the Apple App Store uploading a Test Flight or public App Store release. + +```ruby +app_store_connect_api_key( + is_key_content_base64: true +) +``` diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 259b91fc1c7..d75f10e0e11 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -19,7 +19,7 @@ This integration can help you if you need GitLab CI/CD and a container image rep In the Harbor instance, ensure that: - The project to be integrated has been created. -- The signed-in user has permission to pull, push, and edit images in the Harbor project. +- The authenticated user has permission to pull, push, and edit images in the Harbor project. ## Configure GitLab diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 9bafa9734e2..dfa5a4593d8 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -107,7 +107,7 @@ can use only one: [Cluster precedence](../../instance/clusters/index.md#cluster-precedence). - If you have managed Prometheus applications installed on multiple Kubernetes clusters at the **same** level, the Prometheus application of a cluster with a - matching [environment scope](../../../ci/environments/index.md#scope-environments-with-specs) is used. + matching [environment scope](../../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) is used. ## Determining the performance impact of a merge diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 2ded5799c23..5c1006b9044 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -59,6 +59,7 @@ The following triggers are available for Slack notifications: |--------------------------------------------------------------------------|------------------------------------------------------| | **Push** | A push to the repository. | | **Issue** | An issue is created, updated, or closed. | +| **Incident** | An incident is created, updated, or closed. | | **Confidential issue** | A confidential issue is created, updated, or closed. | | **Merge request** | A merge request is created, updated, or merged. | | **Note** | A comment is added. | diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 63282d6ec6e..0f462ad41b0 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1019,7 +1019,7 @@ Payload example: ``` NOTE: -The fields `assignee_id`, `state`, `merge_status` are [deprecated](../../../api/merge_requests.md). +The fields `assignee_id` and `merge_status` are [deprecated](../../../api/merge_requests.md). ## Wiki page events @@ -1362,15 +1362,6 @@ Payload example: ## Job events -- Number of retries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) - named `job_webhook_retries_count`. Disabled by default. - -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 -`job_webhook_retries_count`. -On GitLab.com, this feature is not available. - Job events are triggered when the status of a job changes. The `commit.id` in the payload is the ID of the pipeline, not the ID of the commit. @@ -1403,7 +1394,7 @@ Payload example: "build_duration": null, "build_allow_failure": false, "build_failure_reason": "script_failure", - "retries_count": 2, // 2 indicates this is the 2nd retry of this job + "retries_count": 2, // the second retry of this job "pipeline_id": 2366, "project_id": 380, "project_name": "gitlab-org/gitlab-test", @@ -1415,6 +1406,7 @@ Payload example: }, "commit": { "id": 2366, + "name": "Build pipeline", "sha": "2293ada6b400935a1378653304eaf6221e0fdb8f", "message": "test\n", "author_name": "User", @@ -1447,6 +1439,26 @@ Payload example: } ``` +### Number of retries + +> `retries_count` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `job_webhook_retries_count`. Disabled by default. + +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 +`job_webhook_retries_count`. +On GitLab.com, this feature is not available. + +`retries_count` is an integer that indicates if the job is a retry. `0` means that the job +has not been retried. `1` means that it's the first retry. + +### Pipeline name + +> `commit.name` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107963) in GitLab 15.8. + +You can set custom names for pipelines with [`workflow:name`](../../../ci/yaml/index.md#workflowname). +If the pipeline has a name, that name is the value of `commit.name`. + ## Deployment events Deployment events are triggered when a deployment: diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index ea90dda88f6..a5399b70c8f 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -351,6 +351,13 @@ Alternatively, you can use the `/promote` [quick action](../quick_actions.md#iss Read more about [promoting an issues to epics](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). +## Promote an issue to an incident + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5. +> - Quick actions to set issue type as incident upon creation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/376760) in GitLab 15.8. + +You can use the `/promote_to_incident` [quick action](../quick_actions.md) to promote the issue to an [incident](../../../operations/incident_management/incidents.md). + ## Add an issue to an iteration **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. @@ -404,7 +411,8 @@ GitLab displays the results on-screen, but you can also ### Filter with the OR operator -> OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. +> - OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. +> - OR filtering for label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. @@ -412,7 +420,11 @@ To make it available, ask an administrator to [enable the feature flag](../../.. The feature is not ready for production use. When this feature is enabled, you can use the OR operator (**is one of: `||`**) -when you [filter the list of issues](#filter-the-list-of-issues). +when you [filter the list of issues](#filter-the-list-of-issues) by: + +- Assignees +- Author +- Labels `is one of` represents an inclusive OR. For example, if you filter by `Assignee is one of Sidney Jones` and `Assignee is one of Zhang Wei`, GitLab shows issues where either `Sidney`, `Zhang`, or both of them are assignees. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index bb72ab0052d..f9e3f1b9225 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -390,7 +390,7 @@ For a video explanation, see: See the video: <a href="https://www.youtube.com/watch?v=4BCBby6du3c">Use scoped labels for custom fields and custom workflows</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube.com/embed/4BCBby6du3c" frameborder="0" allowfullscreen="true"> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/4BCBby6du3c" frameborder="0" allowfullscreen> </iframe> </figure> ### Nested scopes diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index a7627f12657..0b0184db14c 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -62,6 +62,12 @@ To add a user to a project: 1. Enter an email address and select a [role](../../permissions.md). 1. Optional. Select an **Access expiration date**. From that date onward, the user can no longer access the project. + + WARNING: + If you give a member the Maintainer role and select an expiration date, that member + has full permissions for the time they are in the role. This includes the ability + to extend their own time in the Maintainer role. + 1. Select **Invite**. If the user has a GitLab account, they are added to the members list. @@ -97,6 +103,9 @@ Each user's access is based on: - The role they're assigned in the group. - The maximum role you choose when you invite the group. +If a user has a group role with fewer permissions than the maximum project role, the user keeps the permissions of their group role. +For example, if you add a user with the Guest role to a project with a maximum role of Maintainer, the user has only the permissions of the Guest role. + Prerequisites: - You must have the Maintainer or Owner role. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index b9887212be0..d1ee42f723d 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: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -16,8 +16,16 @@ with `Group 1`, so that both members of `Group 1` and `Group 2` have access to t When a project is shared with a group: - All group members, including members of subgroups or projects that belong to the group, -are assigned the same role in the project. -Each member's role is displayed in **Project information > Members > Max role**. + are assigned the same role in the project. + Each member's role is displayed in **Project information > Members**, in the **Max role** column. + When sharing a project with a group, a user's assigned **Max role** is the lowest + of either: + + - The role assigned in the group membership. + - The maximum role selected when sharing the project with the group. + + Assigning a higher maximum role to the group doesn't give group users higher roles than + the roles already assigned to them in the group. - The group is listed in the **Groups** tab. - The project is listed on the group dashboard. @@ -28,7 +36,7 @@ Be aware of the restrictions that apply when you share projects with: ## Share projects with groups with a more restrictive visibility level -You can share projects only down the group's organization structure. +You can share projects only down the group's organization structure. This means you can share a project with a group that has a more restrictive [visibility level](../../public_access.md#project-and-group-visibility) than the project, but not with a group that has a less restrictive visibility level. @@ -78,8 +86,4 @@ To share a project with a group: ## Prevent project sharing -You can prevent members of a group from -[sharing a project with another group](../members/share_project_with_groups.md). -This restriction allows for tighter control over project access. - For more information, see [Prevent a project from being shared with groups](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 5f81db10cf4..51f7254bfda 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -36,6 +36,10 @@ To add a merge request approval rule: 1. In the **Merge request approvals** section, scroll to **Approval rules**. 1. Select **Add approval rule**. 1. Add a human-readable **Rule name**. +1. Select a **Target branch**: + - To apply the rule to all branches, select **All branches**. + - To apply the rule to all protected branches, select **All protected branches** (GitLab 15.3 and later). + - To apply the rule to a specific branch, select it from the list. 1. Set the number of required approvals in **Approvals required**. A value of `0` makes [the rule optional](#configure-optional-approval-rules), and any number greater than `0` creates a required rule. @@ -221,8 +225,7 @@ appreciated, but not required. To make an approval rule optional: ## Approvals for protected branches -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.8. -> - **All protected branches** target branch option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360930) in GitLab 15.3. +> **All protected branches** target branch option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360930) in GitLab 15.3. Approval rules are often relevant only to specific branches, like your [default branch](../../repository/branches/default.md). To configure an @@ -231,8 +234,7 @@ approval rule for certain branches: 1. [Create an approval rule](#add-an-approval-rule). 1. Go to your project and select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval rules**. -1. Select a **Target branch**: - - To apply the rule to all branches, select **All branches**. +1. For **Target branch**: - To apply the rule to all protected branches, select **All protected branches** (GitLab 15.3 and later). - To apply the rule to a specific branch, select it from the list. diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 52944ee3143..280ad20712b 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Authorization for Merge requests **(FREE)** +# Merge request workflows **(FREE)** There are two main ways to have a merge request flow with GitLab: diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index f6e02dc0dfe..07ee2ef90c4 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -140,6 +140,7 @@ Files marked as viewed are not shown to you again unless either: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `display_merge_conflicts_in_diff`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.7. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.8. Feature flag `display_merge_conflicts_in_diff` removed. To avoid displaying the changes that are already on target branch in the diff, we compare the merge request's source branch with HEAD of the target branch. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index eae4db2d4f7..542edc11c44 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -29,7 +29,54 @@ be associated with a given target branch at a time. ## From an issue -You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). +> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. + +If your development workflow requires an issue for every merge +request, you can create a branch directly from the issue to speed the process up. +The new branch, and later its merge request, are marked as related to this issue. +After merging the merge request, the issue is closed automatically, unless [automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). +You can see a **Create merge request** dropdown below the issue description. + +NOTE: +In GitLab 14.8 and later, selecting **Create merge request** +[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) +instead of immediately creating the merge request. + +The **Create merge request** button doesn't display if: + +- A branch with the same name already exists. +- A merge request already exists for this branch. +- Your project has an active fork relationship. +- Your project is private and the issue is confidential. + +To make this button appear, one possible workaround is to +[remove your project's fork relationship](../settings/index.md#remove-a-fork-relationship). +After removal, the fork relationship cannot be restored. This project can no longer +be able to receive or send merge requests to the source project, or other forks. + +This dropdown contains the options **Create merge request and branch** and **Create branch**. + +After selecting one of these options, a new branch or branch and merge request +is created based on your project's [default branch](../repository/branches/default.md). +The branch name is based on an internal ID, and the issue title. The example +screenshot above creates a branch named +`2-make-static-site-auto-deploy-and-serve`. + +When you select the **Create branch** button in an empty +repository project, GitLab performs these actions: + +- Creates a default branch. +- Commits a blank `README.md` file to it. +- Creates and redirects you to a new branch based on the issue title. +- _If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes,_ + GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) + by helping you create a `.gitlab-ci.yml` file. + +After the branch is created, you can edit files in the repository to fix +the issue. When a merge request is created based on the newly-created branch, +the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the +merge request is merged. ## When you add, edit, or upload a file diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index d0b0ead6b87..231c1dda5b7 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -145,6 +145,11 @@ information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/1 ### Complex merge order dependencies are unsupported +If you attempt to create an indirect, nested dependency, GitLab shows one of these error messages: + +- Dependencies failed to save: Blocked merge request cannot block others +- Dependencies failed to save: Blocking merge request cannot itself be blocked + GitLab supports direct dependencies between merge requests, but does not support [indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393). diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 427ab9606e8..58750cdf5bc 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -42,10 +42,6 @@ before concluding your work and merging the merge request. You can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for a quick overview of working with merge requests. -## How to create a merge request - -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 @@ -112,7 +108,7 @@ To create a merge request to close an issue when it's merged, you can either: choose any name, and GitLab verifies that it's not already in use. The merge request inherits the milestone and labels of the issue, and is set to automatically close the issue when it is merged. - - Create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) + - Create a [new branch](creating_merge_requests.md#from-an-issue) only, with its name starting with the issue number. If the issue is [confidential](../issues/confidential_issues.md), diff --git a/doc/user/project/merge_requests/img/filter_approved_by_merge_requests_v14_6.png b/doc/user/project/merge_requests/img/filter_approved_by_merge_requests_v14_6.png Binary files differdeleted file mode 100644 index 8d47fdc2652..00000000000 --- a/doc/user/project/merge_requests/img/filter_approved_by_merge_requests_v14_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/filter_approver_merge_requests_v14_6.png b/doc/user/project/merge_requests/img/filter_approver_merge_requests_v14_6.png Binary files differdeleted file mode 100644 index 58950031378..00000000000 --- a/doc/user/project/merge_requests/img/filter_approver_merge_requests_v14_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 8309b04758a..21651fd645c 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -19,6 +19,10 @@ Merge requests include: Read more about [how to get started](getting_started.md). +## Create a merge request + +Learn the various ways to [create a merge request](creating_merge_requests.md). + ## View merge requests You can view merge requests for your project, group, or yourself. @@ -63,56 +67,36 @@ or: ## Filter the list of merge requests +> - Filtering by `approved-by` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in GitLab 13.0. +> - Filtering by `reviewer` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. +> - Filtering by potential approvers was moved to GitLab Premium in 13.9. +> - Filtering by `approved-by` moved to GitLab Premium in 13.9. + To filter the list of merge requests: 1. Above the list of merge requests, select **Search or filter results...**. -1. In the dropdown list that appears, select the attribute you wish to filter by. +1. From the dropdown list, select the attribute you wish to filter by. Some examples: + - [**By environment or deployment date**](#filter-merge-requests-by-environment-or-deployment-date). + - **ID**: Enter filter `#30` to return only merge request 30. + - User filters: Type (or select from the dropdown list) any of these filters to display a list of users: + - **Approved-By**, for merge requests already approved by a user. **(PREMIUM)**. + - **Approver**, for merge requests that this user is eligible to approve. + (For more information, read about [Code owners](../code_owners.md)). **(PREMIUM)** + - **Reviewer**, for merge requests reviewed by this user. 1. Select or type the operator to use for filtering the attribute. The following operators are available: - `=`: Is - - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) + - `!=`: Is not 1. Enter the text to filter the attribute by. You can filter some attributes by **None** or **Any**. 1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical `AND`. +1. Select a **Sort direction**, either **{sort-lowest}** for descending order, + or **{sort-highest}** for ascending order. GitLab displays the results on-screen, but you can also [retrieve them as an RSS feed](../../search/index.md#retrieve-search-results-as-feed). -### Filter merge requests by ID - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. - -You can filter the **Merge Request** list to find merge requests by their ID. - -For example, enter filter `#30` to return only merge request 30. - -### Filter merge requests by approvers **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -To filter merge requests by an individual eligible approver ([Code owner](../code_owners.md)), you can type (or select from -the dropdown list) **Approver** and select the user. - - - -### Filter merge requests by "approved by" **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in GitLab 13.0. -> - Moved to GitLab Premium in 13.9. - -To filter merge requests already approved by a specific individual, you can type (or select from -the dropdown list) **Approved-By** and select the user. - - - -### Filter merge requests by reviewer - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. - -To filter review requested merge requests for a specific individual, you can type (or select from -the dropdown list) **Reviewer** and select the user. - ### Filter merge requests by environment or deployment date > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 249a98f1779..b1d07a740bf 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -180,9 +180,9 @@ When a fast-forward merge is not possible, the user is given the option to rebas [Rebasing in (semi-)linear merge methods](#rebasing-in-semi-linear-merge-methods). NOTE: -Projects using the fast-forward merge strategy can't filter merge requests -[by deployment date](../index.md#filter-merge-requests-by-environment-or-deployment-date), -because no merge commit is created. +Projects that use the fast-forward merge strategy can't +[filter merge requests](../index.md#filter-the-list-of-merge-requests) +by deployment date, because no merge commit is created. When you visit the merge request page with `Fast-forward merge` method selected, you can accept it **only if a fast-forward merge is possible**. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 74c3b3e24b6..2894b71e7e6 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -31,15 +31,16 @@ see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epi ## Block merges of merge requests unless all status checks have passed -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372340) in GitLab 15.8. FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to -[enable the feature flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. On GitLab.com, this feature is not available. +[enable the feature flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail, enable this feature using the [project API](../../../api/projects.md#edit-project). You must also [enable the feature flag](../../../administration/feature_flags.md) named -`only_allow_merge_if_all_status_checks_passed`. +`only_allow_merge_if_all_status_checks_passed` on self-managed GitLab. ## Lifecycle @@ -151,12 +152,18 @@ the status check and it **will not** be recoverable. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1. > - UI [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91504) in GitLab 15.2. +> - Ability to retry failed external status checks [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383200) in GitLab 15.8. The status checks widget displays in merge requests and displays the following statuses: - **pending** (**{status-neutral}**), while GitLab waits for a response from an external status check. - **success** (**{status-success}**) or **failed** (**{status-failed}**), when GitLab receives a response from an external status check. +To retry a failed status check: + +1. Expand the merge request widget to show the list of external status checks. +1. Select **Retry** (**{retry}**) on the failed external status check row. The status check is put back into a pending state. + An organization might have a policy that does not allow merging merge requests if external status checks do not pass. However, the details in the widget are for informational purposes only. GitLab does not prevent merging of merge requests that fail status checks. diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index a864a9849b0..120e300da5e 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,7 +64,7 @@ branches. The new mode is available from the comparison target drop down by selecting **main (HEAD)**. In GitLab 13.9, it [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the old default comparison. For technical details, additional information is available in the -[developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch). +[developer documentation](../../../development/merge_request_concepts/diffs/index.md#merge-request-diffs-against-the-head-of-the-target-branch).  diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md new file mode 100644 index 00000000000..0ff354562fd --- /dev/null +++ b/doc/user/project/organize_work_with_projects.md @@ -0,0 +1,33 @@ +--- +stage: Manage +group: Organization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Organize work with projects **(FREE)** + +In GitLab, you can create projects to host +your codebase. You can also use projects to track issues, plan work, +collaborate on code, and continuously build, test, and use +built-in CI/CD to deploy your app. + +Projects can be available [publicly, internally, or privately](../public_access.md). +GitLab does not limit the number of private projects you can create. + +- [Manage projects](working_with_projects.md) +- [Project visibility](../public_access.md) +- [Project settings](../project/settings/index.md) +- [Project access tokens](../project/settings/project_access_tokens.md) +- [Share projects](../project/members/share_project_with_groups.md) +- [Reserved project and group names](../../user/reserved_names.md) +- [Search](../../user/search/index.md) +- [Badges](../../user/project/badges.md) +- [Code intelligence](../../user/project/code_intelligence.md) +- [Compliance](../../user/compliance/index.md) +- [Description templates](../../user/project/description_templates.md) +- [Deploy keys](../../user/project/deploy_keys/index.md) +- [Deploy tokens](../../user/project/deploy_tokens/index.md) +- [File finder](../../user/project/repository/file_finder.md) +- [GitLab Pages](../../user/project/pages/index.md) +- [Migrating projects](../../user/project/import/index.md) +- [Migrate projects by using file exports](../../user/project/settings/import_export.md) 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 dc23540bd1b..2f814bb0e65 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 @@ -165,7 +165,8 @@ If you're using Cloudflare, check Once you have added all the DNS records: -1. Go back at your project's **Settings > Pages**. +1. Go back at your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Locate your domain name and select **Details**. 1. Select the **Retry verification** button to activate your new domain. @@ -287,10 +288,15 @@ meet these requirements. #### Steps - To add the certificate at the time you add a new domain, go to your - project's **Settings > Pages > New Domain**, add the domain name and the certificate. + project's **Settings > Pages > New Domain** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)), add the domain name and the + certificate. - To add the certificate to a domain previously added, go to your project's **Settings > Pages**, locate your domain name, select **Details** and **Edit** to add the certificate. +NOTE: +The Pages menu entry may also be located at **Deployments > Pages**, [more information](../index.md#menu-position-test) + 1. Add the PEM certificate to its corresponding field. 1. If your certificate is missing its intermediate, copy and paste the root certificate (usually available from your CA website) @@ -313,7 +319,8 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. Navigate to your project's **Settings > Pages**. +1. Navigate to your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Tick the checkbox **Force HTTPS (requires valid certificates)**. If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index e9e6e5a9a3c..770fb4f450a 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -42,7 +42,8 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. Navigate to your project's **Settings > Pages**. +1. Navigate to your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Find your domain and select **Details**. 1. Select **Edit** in the top-right corner. 1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**: @@ -69,7 +70,8 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. Go to your project's **Settings > Pages**. +1. Go to your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Select **Edit** on your domain. 1. Select **Retry**. 1. If you're still seeing the same error: @@ -83,7 +85,8 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. Go to your project's **Settings > Pages**. +1. Go to your project's **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). 1. Select **Remove** on your domain. 1. [Add the domain again and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 339ab239588..e0448621c6a 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -28,7 +28,8 @@ If everything is configured correctly, the site can take approximately 30 minute To view the pipeline, go to **CI/CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. +your Pages website. (Note: this may also be +located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 9841e52a089..e1a245851cb 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -24,7 +24,9 @@ To fork a sample project and create a Pages website: GitLab CI/CD builds and deploys your site. The site can take approximately 30 minutes to deploy. -When the pipeline is finished, go to **Settings > Pages** to find the link to your website from your project. +When the pipeline is finished, go to **Settings > Pages** to find the link +to your website from your project. (Note: this may also be +located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index ebadf39a984..82e544b0701 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -27,7 +27,7 @@ To create a GitLab Pages website: ## Prerequisites -You must have a [blank project](../../working_with_projects.md#create-a-blank-project) in GitLab. +You must have a [blank project](../../index.md#create-a-blank-project) in GitLab. ## Create the project files @@ -176,7 +176,8 @@ deploy your website: 1. Save and commit the `.gitlab-ci.yml` file. 1. Go to **CI/CD > Pipelines** to watch the pipeline. 1. When the pipeline succeeds, go to **Settings > Pages** - to view the URL where your site is now available. + to view the URL where your site is now available. (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) When this `pages` job completes successfully, a special `pages:deploy` job appears in the pipeline view. It prepares the content of the website for the diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index a0f9753a40c..a9988b1fb99 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -24,7 +24,8 @@ configured to generate a Pages site. site. When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. +your Pages website. (Note: this may also be +located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index a6069b473e6..984c8e5c619 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -34,8 +34,10 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages**. A **Get Started with Pages** form appears. - If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). +1. On the left sidebar, select **Settings > Pages** (Note: this may also be + located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). + A **Get Started with Pages** form appears. If this form is not available, + see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). 1. For **Step 1**, enter an image name and verify that your files are in a `public` folder. 1. Select **Next**. 1. For **Step 2**, enter your installation steps. If your framework's build process does not diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 9305b92bf7d..89d8fd093b2 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -34,6 +34,13 @@ Pages does not support dynamic server-side processing, for instance, as `.php` a 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/). +## Menu Position Test + +NOTE: +We are currently conducting an A/B test where some users may see the Pages +Menu entry under "Deployments" instead of "Settings". We think that this may +be a more accurate position. Feel free to add any feedback to [the experiment issue](https://gitlab.com/gitlab-org/gitlab/-/issues/373547). + ## Getting started To create a GitLab Pages website: diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index ab97ff08123..b0754e74314 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -38,6 +38,8 @@ Administrators can set a default branch protection level in the Prerequisite: - You must have at least the Maintainer role. +- When granting a group **Allowed to merge** or **Allowed to push** permissions + on a protected branch, the group must be added to the project. To protect a branch: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index a73a5329688..d12a71c9ab3 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -86,7 +86,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | | `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | | `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | -| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. | | `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | | `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) | | `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 6d5378bddb7..7c2d5088f17 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -132,7 +132,7 @@ release: ``` The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a -[custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables), +[custom variable in the UI](../../../ci/variables/index.md#for-a-project), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 62220dd2fde..1abcca547db 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Remote Development **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. 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 `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. @@ -22,7 +22,7 @@ As with all projects, the items mentioned on this page are subject to change or The development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. -You can use the [Web IDE](../web_ide/index.md) to commit changes to a project directly from your web browser without installing any dependencies or cloning any repositories. The Web IDE, however, lacks a native runtime environment on which you would compile code, run tests, or generate real-time feedback in the IDE. For a more complete IDE experience, you can pair the Web IDE with a Remote Development environment that has been properly configured to run as a host. +You can use the [Web IDE](../web_ide/index.md) to commit changes to a project directly from your web browser without installing any dependencies or cloning any repositories. The Web IDE, however, lacks a native runtime environment on which you would compile code, run tests, or generate real-time feedback in the IDE. For a more complete IDE experience, you can pair the [Web IDE Beta](../web_ide_beta/index.md) with a Remote Development environment that has been properly configured to run as a host. ## Connect a remote machine to the Web IDE @@ -81,7 +81,7 @@ To connect a development environment to the Web IDE: 1. [Create a development environment](#manage-a-development-environment). 1. [Fetch a token](#fetch-a-token). -1. [Connect to the Web IDE](#connect-to-the-web-ide). +1. [Configure a remote connection](#configure-a-remote-connection). #### Manage a development environment @@ -134,9 +134,18 @@ To remove a development environment: docker exec my-environment cat TOKEN ``` -#### Connect to the Web IDE +#### Configure a remote connection -To connect to the Web IDE: +To configure a remote connection from the Web IDE: + +1. Open the Web IDE. +1. In the Menu Bar, select **View > Terminal** or press <kbd>Control</kbd>+<kbd>`</kbd>. +1. In the terminal panel, select **Configure a remote connection**. +1. Enter the URL for the remote host including the port (for example, `yourdomain.com:3443`). +1. Enter the project path. +1. Enter the [token you fetched](#fetch-a-token). + +Alternatively, you can pass the parameters from a URL and connect directly to the Web IDE: 1. Run the following command: @@ -145,3 +154,7 @@ To connect to the Web IDE: ``` 1. Go to that URL and enter the [token you fetched](#fetch-a-token). + +## Related topics + +- [Web IDE Beta](../web_ide_beta/index.md) diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index a86e32b4721..4e3510c49b7 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -27,7 +27,7 @@ For more information on managing branches using the GitLab UI, see: - [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a default branch for the repository. You can change this setting at the project, subgroup, group, or instance level. -- [Create a branch](../web_editor.md#create-a-new-branch) +- [Create a branch](../web_editor.md#create-a-branch) - [Protected branches](../../protected_branches.md#protected-branches) - [Delete merged branches](#delete-merged-branches) - [Branch filter search box](#branch-filter-search-box) @@ -119,6 +119,30 @@ The Swap revisions feature allows you to swap the Source and Target revisions. W  +## View branches with configured protections **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../feature_flags.md) named `branch_rules`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Branches in your repository can be [protected](../../protected_branches.md) by limiting +who can push to a branch, require approval for those pushed changes, or merge those changes. +To help you track the protections for all branches, the **Branch rules overview** +page shows your branches with their configured rules. + +To view the **Branch rules overview** list: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Branch Rules** to view all branches with protections. +1. Select **Details** next to your desired branch to show information about its: + - [Branch protections](../../protected_branches.md). + - [Approval rules](../../merge_requests/approvals/rules.md). + - [Status checks](../../merge_requests/status_checks.md). + ## Troubleshooting ### Error: ambiguous `HEAD` branch exists diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 08fe767f9c9..321b9a5eb53 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -21,6 +21,10 @@ When you select **History**, this information is displayed: If you hover over a commit in the UI, the precise date and time of the commit modification are shown. +The name and email information provided are retrieved from the +[Git configuration](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) +of the contributor when a commit is made. + ## Associated `git` command If you're running `git` from the command line, the equivalent command diff --git a/doc/user/project/repository/img/web_editor_line_link_v13_10.png b/doc/user/project/repository/img/web_editor_line_link_v13_10.png Binary files differdeleted file mode 100644 index 36347afcbe8..00000000000 --- a/doc/user/project/repository/img/web_editor_line_link_v13_10.png +++ /dev/null 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 differdeleted file mode 100644 index df5e803d77a..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_dropdown_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png Binary files differdeleted file mode 100644 index fae0fc1425b..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v14_1.png +++ /dev/null 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 differdeleted file mode 100644 index 732173d9c1b..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png b/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png Binary files differdeleted file mode 100644 index cba15631fa8..00000000000 --- a/doc/user/project/repository/img/web_editor_new_branch_page_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png b/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png Binary files differdeleted file mode 100644 index 1f7a6263d9a..00000000000 --- a/doc/user/project/repository/img/web_editor_new_directory_dialog_v14_1.png +++ /dev/null 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 differdeleted file mode 100644 index bbdb9bca199..00000000000 --- a/doc/user/project/repository/img/web_editor_new_directory_dropdown_v14_1.png +++ /dev/null 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 differdeleted file mode 100644 index 1a92555457a..00000000000 --- a/doc/user/project/repository/img/web_editor_new_file_dropdown_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png b/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png Binary files differdeleted file mode 100644 index 3c568e304b2..00000000000 --- a/doc/user/project/repository/img/web_editor_new_file_editor_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_push_widget.png b/doc/user/project/repository/img/web_editor_new_push_widget.png Binary files differdeleted file mode 100644 index 8957b5d6a6b..00000000000 --- a/doc/user/project/repository/img/web_editor_new_push_widget.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_tag_dropdown.png b/doc/user/project/repository/img/web_editor_new_tag_dropdown.png Binary files differdeleted file mode 100644 index 33e8ed891b5..00000000000 --- a/doc/user/project/repository/img/web_editor_new_tag_dropdown.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_new_tag_page.png b/doc/user/project/repository/img/web_editor_new_tag_page.png Binary files differdeleted file mode 100644 index d6d9945397c..00000000000 --- a/doc/user/project/repository/img/web_editor_new_tag_page.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_start_new_merge_request.png b/doc/user/project/repository/img/web_editor_start_new_merge_request.png Binary files differdeleted file mode 100644 index 85f4769661a..00000000000 --- a/doc/user/project/repository/img/web_editor_start_new_merge_request.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png b/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png Binary files differdeleted file mode 100644 index 4608843b1f4..00000000000 --- a/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png b/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png Binary files differdeleted file mode 100644 index ecc4d8e8716..00000000000 --- a/doc/user/project/repository/img/web_editor_template_dropdown_first_file_v14_1.png +++ /dev/null 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 differdeleted file mode 100644 index 5a5562ed38c..00000000000 --- a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png b/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png Binary files differdeleted file mode 100644 index 632f591e25a..00000000000 --- a/doc/user/project/repository/img/web_editor_upload_file_dialog_v14_1.png +++ /dev/null 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 differdeleted file mode 100644 index ad949aae8ce..00000000000 --- a/doc/user/project/repository/img/web_editor_upload_file_dropdown_v14_1.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 83389c15eba..3c33467df3f 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -15,7 +15,7 @@ Each [project](../index.md) contains a repository. To create a repository, you can: -- [Create a project](../../../user/project/working_with_projects.md#create-a-project) or +- [Create a project](../../../user/project/index.md#create-a-project) or - [Fork an existing project](forking_workflow.md). ## Add files to a repository @@ -264,9 +264,7 @@ to fetch configuration from a project that is renamed or moved. - [Repository API](../../../api/repositories.md). - [Find files](file_finder.md) in a repository. - [Branches](branches/index.md). -- [File templates](web_editor.md#template-dropdowns). - [Create a directory](web_editor.md#create-a-directory). -- [Start a merge request](web_editor.md#tips). - [Find file history](git_history.md). - [Identify changes by line (Git blame)](git_blame.md). - [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 2b578977bd2..bc0073e6ec8 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -105,6 +105,20 @@ non-protected branches in the mirroring project are not mirrored and can diverge To use this option, select **Only mirror protected branches** when you create a repository mirror. +## Mirror specific branches + +> Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. + +FLAG: +On self-managed GitLab, by default the field `mirror_branch_regex` is not available. +To make it available, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) +named `mirror_only_branches_match_regex`. +On GitLab.com, this feature is not available. + +To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax), +enter a regular expression into the **Mirror specific branches** field. Branches with names that +do not match the regular expression are not mirrored. + ## Authentication methods for mirrors When you create a mirror, you must configure the authentication method for it. 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 9c977e4da40..a8a79591e9e 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,7 +63,7 @@ To purge files from a GitLab repository: 1. Clone a fresh copy of the repository from the bundle using `--bare` and `--mirror` options: ```shell - git clone --bare --mirror /path/to/project.bundle + git clone --bare /path/to/project.bundle ``` 1. Go to the `project.git` directory: @@ -84,7 +84,7 @@ To purge files from a GitLab repository: ```shell # Using git filter-repo git filter-repo --analyze - head .git/filter-repo/analysis/*-{all,deleted}-sizes.txt + head filter-repo/analysis/*-{all,deleted}-sizes.txt # Using git-sizer git-sizer @@ -117,7 +117,7 @@ To purge files from a GitLab repository: You can use the following command to back up each `commit-map` file: ```shell - cp .git/filter-repo/commit-map ./_filter_repo_commit_map_$(date +%s) + cp filter-repo/commit-map ./_filter_repo_commit_map_$(date +%s) ``` Repeat this step and all following steps (including the [repository cleanup](#repository-cleanup) step) diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index 06affa54a51..85d2ce1d480 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -6,12 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Sign commits with SSH keys **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. - -FLAG: -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 `ssh_commit_signatures`. -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/384202) in GitLab 15.8. Feature flag `ssh_commit_signatures` removed. Use SSH keys to sign Git commits in the same manner as [GPG signed commits](../gpg_signed_commits/index.md). When you sign commits diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index cc89ca0fb1a..b5b2b8aaae9 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -4,253 +4,118 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Web Editor **(FREE)** +# Web Editor **(FREE)** -Sometimes it's easier to make quick changes directly from the GitLab interface -than to clone the project and use the Git command-line tool. In this feature -highlight, we look at how you can create a new file, directory, branch, or -tag from the file browser. All of these actions are available from a single -dropdown list. +You can use the Web Editor to make changes directly from the GitLab UI instead of +cloning a project and using the command line. -## Create a file - -From a project's files page, select the '+' button to the right of the branch selector. -Choose **New file** from the dropdown list. - - -Enter a filename in the **Filename** box. Then, add file content in the editor -area. Add a descriptive commit message and choose a branch. The branch field -defaults to the branch you were viewing in the file browser. If you enter -a new branch name, a checkbox displays, allowing you to start a new merge -request after you commit the changes. +From the project dashboard or repository, you can: -When you are satisfied with your new file, select **Commit Changes** at the bottom. +- [Create a file](#create-a-file). +- [Edit a file](#edit-a-file). +- [Upload a file](#upload-a-file). +- [Create a directory](#create-a-directory). +- [Create a branch](#create-a-branch). +- [Create a tag](#create-a-tag). - +Your [primary email address](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) +is used by default for any change you commit through the Web Editor. -### Shortcuts +## Create a file -You can use shortcuts when editing a file through the Web Editor. It uses the same shortcuts -as the Web IDE. For details, read the documentation for [Command Palette](../web_ide/index.md#command-palette). +To create a text file in the Web Editor: -### Template dropdowns +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **New file**. +1. Complete the fields. + - From the **Select a template type** dropdown list, you can apply a template to the new file. + - To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. +1. Select **Commit changes**. -When starting a new project, there are some common files that the new project -might need. GitLab displays a message to help you: +## Edit a file - +To edit a file in the Web Editor: -When selecting either `LICENSE` or `.gitignore` and so on, a dropdown displays -to provide you a template that may be suitable for your project: +1. On the top bar, select **Main menu > Projects** and find your project. +1. Go to your file. +1. Next to the display buttons, select **Edit**. - +### Keyboard shortcuts -The license, changelog, contribution guide, or `.gitlab-ci.yml` file can also -be added through a button on the project page. In this example, the license -has already been created, which creates a link to the license itself. +When you [edit a file](#edit-a-file) in the Web Editor, you can use the same keyboard shortcuts for the Web IDE. +See the [available shortcuts](../../shortcuts.md#web-ide). - +### Preview Markdown -NOTE: -The **Set up CI/CD** button does not appear on an empty repository. For the button -to display, add a file to your repository. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378966) in GitLab 15.6. -## Preview Markdown +To preview Markdown content in the Web Editor: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378966) in GitLab 15.6. +1. [Edit a file](#edit-a-file). +1. Do one of the following: + - Select the **Preview** tab. + - From the context menu, select **Preview Markdown**. -To preview Markdown content in the Web Editor, select the **Preview** tab. -In this tab, you can see a live Markdown preview that updates as you type alongside your content. +In the **Preview** tab, you can see a live Markdown preview alongside your content. To close the preview panel, do one of the following: - Select the **Write** tab. - From the context menu, select **Hide Live Preview**. -## Highlight lines +### Link to specific lines -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.10 for GitLab SaaS instances. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11 for self-managed instances. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11. -Web Editor enables you to highlight a single line by adding specially formatted -hash information to the file path segment of the URL. For example, the file path segment -`MY_FILE.js#L3` instructs the Web Editor to highlight line 3. +To link to single or multiple lines in the Web Editor, add hash +information to the filename segment of the URL. For example: -The Web Editor also enables you to highlight multiple lines using a similar pattern. In -this case, the file path segment `MY_FILE.js#L3-10` instructs the Web Editor to -highlight lines 3 to 10 of the file. +- `MY_FILE.js#L3` highlights line 3 in `MY_FILE.js`. +- `MY_FILE.js#L3-10` highlights lines 3 to 10 in `MY_FILE.js`. -You don't need to construct these lines manually. Instead, you can: +To link to a single line, you can also: -1. Hover over the number of a line you want to be highlighted when sharing. -1. Right-click the number with your mouse. -1. Select **Copy Link Address** in the context menu. - -  +1. [Edit a file](#edit-a-file). +1. Select a line number. ## Upload a file -The ability to create a file is great when the content is text. However, this -doesn't work well for binary data such as images, PDFs, or other binary file types. In -this case, you need to upload a file. - -From a project's files page, select the '+' button to the right of the branch -selector. Choose **Upload file** from the dropdown: - - +To upload a binary file in the Web Editor: -After the upload dialog pops up, there are two ways to upload your file. Either -drag and drop a file on the popup or use the **click to upload** link. After you -select a file to upload, a file preview displays. - -Enter a commit message, choose a branch, and select **Upload file** when you are -ready. - - +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **Upload file**. +1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. +1. Select **Upload file**. ## Create a directory -To keep files in the repository organized it is often helpful to create a new -directory. - -From a project's files page, select the plus button (`+`) to the right of the branch selector. -Choose **New directory** from the dropdown. - - - -In the new directory dialog, enter a directory name, a commit message, and choose -the target branch. Select **Create directory** to finish. - - - -## Create a new branch - -There are multiple ways to create a branch from the GitLab web interface. - -NOTE: -Use [branch naming patterns](branches/index.md#naming) to streamline merge request creation. - -### Create a new branch from an issue - -> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. - -If your development workflow requires an issue for every merge -request, you can create a branch directly from the issue to speed the process up. -The new branch, and later its merge request, are marked as related to this issue. -After merging the merge request, the issue is closed automatically, unless [automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown below the issue description. - -NOTE: -In GitLab 14.8 and later, selecting **Create merge request** -[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) -instead of immediately creating the merge request. - -The **Create merge request** button doesn't display if: - -- A branch with the same name already exists. -- A merge request already exists for this branch. -- Your project has an active fork relationship. -- Your project is private and the issue is confidential. - -To make this button appear, one possible workaround is to -[remove your project's fork relationship](../settings/index.md#remove-a-fork-relationship). -After removal, the fork relationship cannot be restored. This project can no longer -be able to receive or send merge requests to the source project, or other forks. - - - -This dropdown contains the options **Create merge request and branch** and **Create branch**. - - - -After selecting one of these options, a new branch or branch and merge request -is created based on your project's [default branch](branches/default.md). -The branch name is based on an internal ID, and the issue title. The example -screenshot above creates a branch named -`2-make-static-site-auto-deploy-and-serve`. - -When you select the **Create branch** button in an empty -repository project, GitLab performs these actions: - -- Creates a default branch. -- Commits a blank `README.md` file to it. -- Creates and redirects you to a new branch based on the issue title. -- _If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes,_ - GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) - by helping you create a `.gitlab-ci.yml` file. - -After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly-created branch, -the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the -merge request is merged. - -### Create a new branch from a project's dashboard - -If you want to make changes to several files before creating a new merge -request, you can create a new branch upfront. - -1. From a project's files page, choose **New branch** from the dropdown list. - -  - -1. Enter a new **Branch name**. -1. Optional. Change the **Create from** field to choose which branch, tag, or - commit SHA this new branch originates from. This field autocompletes if you - start typing an existing branch or tag. -1. To return to the file browser on this new branch, select **Create branch**. - -  - -You can now make changes to any files, as needed. When you're ready to merge -the changes back to your [default branch](branches/default.md), you can use the widget at the top of the screen. -This widget only appears for a period of time after you create the branch or -modify files. - - - -## Create a new tag - -Tags help you mark major milestones such as production releases and -release candidates. You can create a tag from a branch or a commit -SHA: - -1. From a project's files page, choose **New tag** from the dropdown list. - -  - -1. Give the tag a name such as `v1.0.0`. -1. Choose the branch or SHA from which you want to create this new tag. -1. Optional. Add a message and release notes. The release notes section supports - Markdown format. -1. Optional. Upload an attachment. -1. Select **Create tag**. GitLab redirects you to the tag list page. - -  - -## Tips +To create a directory in the Web Editor: -When creating or uploading a new file or creating a new directory, you can -trigger a new merge request rather than committing directly to your default branch: +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **New directory**. +1. Complete the fields. To create a merge request with the new directory, ensure the **Start a new merge request with these changes** toggle is turned on. +1. Select **Create directory**. -1. Enter a new branch name in the **Target branch** field. -1. GitLab displays the **Start a new merge request with these changes** checkbox. -1. Commit your changes, and GitLab redirects you to a new merge request form. +## Create a branch -  +To create a [branch](branches/index.md) in the Web Editor: -If you'd prefer to not use your primary email address for commits created -through the web editor, you can choose to use another of your linked email -addresses from the **User Settings > Edit Profile** page. +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **New branch**. +1. Complete the fields. +1. Select **Create branch**. -<!-- ## Troubleshooting +## Create a tag -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +You can create [tags](../../../topics/git/tags.md) to mark milestones such as +production releases and release candidates. To create a tag in the Web Editor: -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +1. On the top bar, select **Main menu > Projects** and find your project. +1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the dropdown list, select **New tag**. +1. Complete the fields. +1. Select **Create tag**. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 0b52440d1e6..83cf47d508c 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Certify +stage: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -111,6 +111,12 @@ With Service Desk, you can use templates for: - [New note emails](#new-note-email) - [New Service Desk issues](#new-service-desk-issues) +#### Email header and footer **(FREE SELF)** + +Instance administrators can add a small header or footer to the GitLab instance and make them +visible in the email template. For more information, see +[System header and footer messages](../admin_area/appearance.md#system-header-and-footer-messages). + #### Thank you email When a user submits an issue through Service Desk, GitLab sends a **thank you email**. @@ -359,6 +365,17 @@ Note that: - The project's visibility (private, internal, public) does not affect Service Desk. - The path to the project, including its group or namespace, is shown in emails. +#### Receiving files attached to comments as email attachments + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. +On GitLab.com, this feature is not available. + +If a comment contains any attachments and their total size is less than or equal to 10 MB, these +attachments are sent as part of the email. In other cases, the email contains links to the attachments. + #### Privacy considerations Service Desk issues are confidential, but the project owner can diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index d83a80ddb13..b85f52d43bb 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -27,14 +27,22 @@ To preserve contribution history, [migrate using direct transfer](../../group/im If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. -## Set up project to migrate using file exports +## Configure file exports as an import source **(FREE SELF)** -Before you can import or export a project and its data, you must set it up. +Before you can migrate projects on a self-managed GitLab instance using file exports, GitLab administrators must: +1. [Enable file exports](../../admin_area/settings/visibility_and_access_controls.md#enable-project-export) on the source + instance. +1. Enable file exports as an import source for the destination instance. On GitLab.com, file exports are already enabled + as an import source. + +To enable file exports as an import source for the destination instance: + +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. -1. Enable the desired **Import sources**. +1. Select the **GitLab export** checkbox. ## Between CE and EE @@ -53,6 +61,7 @@ Prerequisites: - Review the list of [items that are exported](#items-that-are-exported). Not all items are exported. - You must have at least the Maintainer role for the project. +- Users must [set a public email](../../profile/index.md#set-your-public-email) in the source GitLab instance that matches one of their verified emails in the target GitLab instance for the user mapping to work correctly. To export a project and its data, follow these steps: @@ -136,12 +145,13 @@ Prerequisites: - You must have [exported the project and its data](#export-a-project-and-its-data). - Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later than the GitLab version you exported to. -- Review the [Version history](#version-history) - for compatibility issues. +- Review the [Version history](#version-history) for compatibility issues. +- At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. To import a project: -1. When [creating a new project](../working_with_projects.md#create-a-project), +1. When [creating a new project](../index.md#create-a-project), select **Import project**. 1. In **Import project from**, select **GitLab export**. 1. Enter your project name and URL. Then select the file you exported previously. @@ -212,6 +222,11 @@ To help avoid abuse, by default, users are rate limited to: ## Version history +### 15.8+ + +Starting with GitLab 15.8, importing groups from a JSON export is no longer supported. Groups must be imported +in NDJSON format. + ### 14.0+ In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index a88427ab20b..3798643549d 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments' type: reference, index, howto --- @@ -239,7 +239,7 @@ Prerequisites: - You must have at least the Maintainer role for the [group](../../group/manage.md#create-a-group) to which you are transferring. - You must be the Owner of the project you transfer. - The group must allow creation of new projects. -- The project must not contain any [container images](../../packages/container_registry/index.md#known-issues). +- The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). - Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. To transfer a project: diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index fb100986df9..4648df7dbd7 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -91,21 +91,17 @@ You can pick a theme from your [profile preferences](../../profile/preferences.m |-------------------------------------------------------------|-----------------------------------------| |  |  | -## Highlight lines +## Link to specific lines -The Web IDE is built with the [Web Editor](../repository/web_editor.md). This enables the Web IDE to share the -same core features for highlighting and linking to particular lines in the edited files -[described for the Web Editor](../repository/web_editor.md#highlight-lines). +The Web IDE and the [Web Editor](../repository/web_editor.md) share the +same core features. To link to specific lines in the Web IDE, see +[Web Editor](../repository/web_editor.md#link-to-specific-lines). ## Schema based validation -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) validation based on predefined schemas in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `schema_linting`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `schema_linting`. -This feature cannot be enabled or disabled per-project. -On GitLab.com, this feature is available. -You should not use this feature for production environments. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) validation based on predefined schemas in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `schema_linting`. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104399) in GitLab 15.7. +> - On self-managed GitLab [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107488) in GitLab 15.8. The Web IDE provides validation support for certain JSON and YAML files using schemas based on the [JSON Schema Store](https://www.schemastore.org/json/). @@ -446,13 +442,12 @@ when: - You select any area outside the file editor after editing a file. - A file or folder is created, deleted, or renamed. -### Limitations +### Known issues The Web IDE has a few limitations: - Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, the user is limited to having only one active terminal at a time. - - LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content. ### Troubleshooting @@ -463,3 +458,7 @@ The Web IDE has a few limitations: - If the terminal displays **Connection Failure**, then the terminal could not connect to the runner. Try to stop and restart the terminal. If the problem persists, double check your runner configuration. + +## Related topics + +- [Web IDE Beta](../web_ide_beta/index.md) diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md index ef07cca465d..4f84110a038 100644 --- a/doc/user/project/web_ide_beta/index.md +++ b/doc/user/project/web_ide_beta/index.md @@ -6,17 +6,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Web IDE Beta **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. 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 `vscode_web_ide`. On GitLab.com, this feature is available. +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 `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. As announced in [this blog post](https://about.gitlab.com/blog/2022/05/23/the-future-of-the-gitlab-web-ide/), -the current implementation of the Web IDE is being replaced with an -implementation inspired by Visual Studio Code. +the current implementation of the [Web IDE](../web_ide/index.md) is being replaced +with an implementation powered by Visual Studio Code. This effort is still under +development. For updates, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7683). -This effort is currently under development. For updates, -see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7683). +To pair the Web IDE Beta with a Remote Development environment, see [Remote Development](../remote_development/index.md). ## Enable the Web IDE Beta @@ -34,7 +34,7 @@ To open the Web IDE Beta from anywhere in the UI: - Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md). You can also open the Web IDE Beta when viewing a file, the repository file list, -and from merge requests. +or a merge request. ### Use when viewing a file or the repository file list @@ -59,45 +59,48 @@ To open the Web IDE Beta from a merge request: To open any file by its name: -1. Type **Command** + **`P`** (<kbd>⌘</kbd> + <kbd>P</kbd>). -1. Type the name of your file. +1. Press <kbd>Command</kbd>+<kbd>P</kbd>. +1. Enter the name of your file.  ## Search across files -You can use VS Code to quickly search all files in the currently opened folder. +You can use VS Code to quickly search all files in the opened folder. -To enter your search term: +To search across files: -1. Type **Shift** + **Command** + **`F`** (<kbd>⇧</kbd> + <kbd>⌘</kbd> + <kbd>F</kbd>). +1. Press <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>F</kbd>. 1. Enter your search term. In the Web IDE Beta, only partial results from opened files are displayed. Full file search is planned for a later date. -## View list of changed files +## View a list of changed files -To view the list of files you changed in the Web IDE Beta: +To view a list of files you changed in the Web IDE Beta, +in the Activity Bar on the left, select **Source Control**. +Your `CHANGES`, `STAGED CHANGES`, and `MERGE CHANGES` are displayed. -- On the VS Code Activity Bar, on the left, select the Source Control icon: +For details, see the [VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). -Your `CHANGES`, `STAGED CHANGES` and `MERGE CHANGES` are displayed. +## Stop using the Web IDE Beta -For details, see [the VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). +If you do not want to use the Web IDE Beta, you can change your personal preferences. + +1. On the top bar, in the top right corner, select your avatar. +1. Select **Preferences**. +1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. +1. Select **Save changes**. ## Known issues The [Web Terminal](../web_ide/index.md#interactive-web-terminals-for-the-web-ide) and [Live Preview](../web_ide/index.md#live-preview) are not available in the Web IDE Beta. -These features may become available at a later date. +These features might become available at a later date. -### Stop using the Web IDE Beta +## Related topics -If you do not want to use the Web IDE Beta, you can change your personal preferences. - -1. On the top bar, in the top right corner, select your avatar. -1. Select **Preferences**. -1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. -1. Select **Save changes**. +- [Remote Development](../remote_development/index.md) +- [Web IDE](../web_ide/index.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 77a7c48658e..92db90d66dc 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- @@ -16,7 +16,7 @@ To view projects, on the top bar, select **Main menu > Projects > View all proje NOTE: The **Explore projects** tab is visible to unauthenticated users unless the [**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted. Then the tab is visible only to signed-in users. +is restricted. Then the tab is visible only to authenticated users. ### Who can view the Projects page @@ -56,196 +56,6 @@ You can assign topics to a project on the [Project Settings page](settings/index If you're an instance administrator, you can administer all project topics from the [Admin Area's Topics page](../admin_area/index.md#administering-topics). -## Create a project - -To create a project in GitLab: - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select an option: - - Create a [blank project](#create-a-blank-project). - - Create a project from a: - - [built-in template](#create-a-project-from-a-built-in-template). - - [custom template](#create-a-project-from-a-custom-template). - - [HIPAA audit protocol template](#create-a-project-from-the-hipaa-audit-protocol-template). - - [Import a project](../../user/project/import/index.md) - from a different repository. Contact your GitLab administrator if this option is not available. - - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). - -- For a list of words that you cannot use as project names, see - [reserved project and group names](../../user/reserved_names.md). -- For a list of characters that you cannot use in project and group names, see - [limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). - -## Create a blank project - -To create a blank project: - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Create blank project**. -1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. - - In the **Project slug** field, enter the path to your project. The GitLab instance uses the - slug as the URL path to the project. To change the slug, first enter the project name, - then change the slug. - - In the **Project deployment target (optional)** field, select your project's deployment target. - This information helps GitLab better understand its users and their deployment requirements. - - To modify the project's [viewing and access rights](../public_access.md) for - users, change the **Visibility Level**. - - To create README file so that the Git repository is initialized, has a default branch, and - can be cloned, select **Initialize repository with a README**. - - To analyze the source code in the project for known security vulnerabilities, - select **Enable Static Application Security Testing (SAST)**. -1. Select **Create project**. - -## Create a project from a built-in template - -A built-in project template populates a new project with files to get you started. -Built-in templates are sourced from the following groups: - -- [`project-templates`](https://gitlab.com/gitlab-org/project-templates) -- [`pages`](https://gitlab.com/pages) - -Anyone can [contribute a built-in template](../../development/project_templates.md). - -To create a project from a built-in template: - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Create from template**. -1. Select the **Built-in** tab. -1. From the list of templates: - - To view a preview of the template, select **Preview**. - - To use a template for the project, select **Use template**. -1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. - - In the **Project slug** field, enter the path to your project. The GitLab instance uses the - slug as the URL path to the project. To change the slug, first enter the project name, - then change the slug. - - In the **Project description (optional)** field, enter the description of your project's dashboard. - - To modify the project's [viewing and access rights](../public_access.md) for users, - change the **Visibility Level**. -1. Select **Create project**. - -## Create a project from a custom template **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. - -Custom project templates are available at: - -- The [instance-level](../../user/admin_area/custom_project_templates.md) -- The [group-level](../../user/group/custom_project_templates.md) - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Create from template**. -1. Select the **Instance** or **Group** tab. -1. From the list of templates: - - To view a preview of the template, select **Preview**. - - To use a template for the project, select **Use template**. -1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. - - In the **Project slug** field, enter the path to your project. The GitLab instance uses the - slug as the URL path to the project. To change the slug, first enter the project name, - then change the slug. - - The description of your project's dashboard in the **Project description (optional)** field. - - To modify the project's [viewing and access rights](../public_access.md) for users, - change the **Visibility Level**. -1. Select **Create project**. - -## Create a project from the HIPAA Audit Protocol template **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10 - -The HIPAA Audit Protocol template contains issues for audit inquiries in the -HIPAA Audit Protocol published by the U.S Department of Health and Human Services. - -To create a project from the HIPAA Audit Protocol template: - -1. On the top bar, select **Main menu > Projects > View all projects**. -1. On the right of the page, select **New project**. -1. Select **Create from template**. -1. Select the **Built-in** tab. -1. Locate the **HIPAA Audit Protocol** template: - - To view a preview of the template, select **Preview**. - - To use the template for the project, select **Use template**. -1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. - - In the **Project slug** field, enter the path to your project. The GitLab instance uses the - slug as the URL path to the project. To change the slug, first enter the project name, - then change the slug. - - In the **Project description (optional)** field, enter the description of your project's dashboard. - - To modify the project's [viewing and access rights](../public_access.md) for users, - change the **Visibility Level**. -1. Select **Create project**. - -## Create a new project with Git push - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. - -Use `git push` to push a local project repository to GitLab. After you push a repository, -GitLab creates your project in your chosen namespace. - -You cannot use `git push` to create projects with project paths that: - -- Have previously been used. -- Have been [renamed](settings/index.md#rename-a-repository). - -Previously used project paths have a redirect. The redirect causes push attempts to redirect requests -to the renamed project location, instead of creating a new project. To create a new project for a previously -used or renamed project, use the [UI](#create-a-project) or the [Projects API](../../api/projects.md#create-project). - -Prerequisites: - -- To push with SSH, you must have [an SSH key](../ssh.md) that is - [added to your GitLab account](../ssh.md#add-an-ssh-key-to-your-gitlab-account). -- You must have permission to add new projects to a namespace. To check if you have permission: - - 1. On the top bar, select **Main menu > Groups** and find your group. - 1. Confirm that **New project** is visible in the upper right - corner. Contact your GitLab - administrator if you require permission. - -To push your repository and create a project: - -1. Push with SSH or HTTPS: - - To push with SSH: - - ```shell - git push --set-upstream git@gitlab.example.com:namespace/myproject.git master - ``` - - - To push with HTTPS: - - ```shell - git push --set-upstream https://gitlab.example.com/namespace/myproject.git master - ``` - - - For `gitlab.example.com`, use the domain name of the machine that hosts your Git repository. - - For `namespace`, use the name of your [namespace](../namespace/index.md). - - For `myproject`, use the name of your project. - - Optional. To export existing repository tags, append the `--tags` flag to your `git push` command. -1. Optional. To configure the remote: - - ```shell - git remote add origin https://gitlab.example.com/namespace/myproject.git - ``` - -When the push completes, GitLab displays the message: - -```shell -remote: The private project namespace/myproject was created. -``` - -To view your new project, go to `https://gitlab.example.com/namespace/myproject`. -Your project's visibility is set to **Private** by default. To change project visibility, adjust your -[project's settings](../public_access.md#change-project-visibility). - ## Star a project You can add a star to projects you use frequently to make them easier to find. diff --git a/doc/user/public_access.md b/doc/user/public_access.md index acfc28a6f65..773c14c9ec8 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- @@ -32,19 +32,19 @@ They are listed in the public access directory (`/public`) for all users. Public groups can have public, internal, or private subgroups. -**Any signed-in user** has the Guest role on the repository. +**Any authenticated user** has the Guest role on the repository. NOTE: By default, `/public` is visible to unauthenticated users. However, if the [**Public** visibility level](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted, `/public` is visible only to signed-in users. +is restricted, `/public` is visible only to authenticated users. ## Internal projects and groups **(FREE SELF)** -Internal projects can be cloned by any signed-in user except +Internal projects can be cloned by any authenticated user except [external users](admin_area/external_users.md). -They are also listed in the public access directory (`/public`), but only for signed-in users. +They are also listed in the public access directory (`/public`), but only for authenticated users. Internal groups can have internal or private subgroups. diff --git a/doc/user/read_only_namespaces.md b/doc/user/read_only_namespaces.md index b11aac9b00c..345a3a87189 100644 --- a/doc/user/read_only_namespaces.md +++ b/doc/user/read_only_namespaces.md @@ -2,7 +2,6 @@ stage: Growth group: Acquisition info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -noindex: true --- # Read-only namespaces **(FREE SAAS)** diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 3eaf3178f3a..372ec141112 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/search/img/search_navbar_v15_7.png b/doc/user/search/img/search_navbar_v15_7.png Binary files differindex 9175347b36f..775c7f32b37 100644 --- a/doc/user/search/img/search_navbar_v15_7.png +++ b/doc/user/search/img/search_navbar_v15_7.png diff --git a/doc/user/search/img/search_scope_v15_7.png b/doc/user/search/img/search_scope_v15_7.png Binary files differindex 6395b5f1cda..96f6e985523 100644 --- a/doc/user/search/img/search_scope_v15_7.png +++ b/doc/user/search/img/search_scope_v15_7.png diff --git a/doc/user/snippets.md b/doc/user/snippets.md index ee84f8a4169..70669748cd8 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference --- diff --git a/doc/user/ssh.md b/doc/user/ssh.md index 1d82d301e9a..b71b120d246 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -278,7 +278,8 @@ To learn more about using 1Password with SSH keys, see [1Password's documentatio ## Add an SSH key to your GitLab account -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271239) in GitLab 15.4, default expiration date suggested in UI. +> - Suggested default expiration date for keys [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271239) in GitLab 15.4. +> - Usage types for SSH keys [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383046) in GitLab 15.7. To use SSH with GitLab, copy your public key to your GitLab account: diff --git a/doc/user/tasks.md b/doc/user/tasks.md index ffe7777fac0..aad53f4165c 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -30,8 +30,8 @@ and so you can provide a more accurate issue weight and completion criteria. Tasks are a type of work item, a step towards [default issue types](https://gitlab.com/gitlab-org/gitlab/-/issues/323404) in GitLab. For the roadmap of migrating issues and [epics](group/epics/index.md) -to work items and adding custom work item types, visit -[epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or +to work items and adding custom work item types, see +[epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or the [Plan direction page](https://about.gitlab.com/direction/plan/). ## View tasks @@ -168,6 +168,10 @@ To change the assignee on a task: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339756) in GitLab 15.5. +Prerequisites: + +- You must have at least the Reporter role for the project. + To add [labels](project/labels.md) to a task: 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. @@ -225,7 +229,7 @@ To add a task to a milestone: 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Milestone**, select **Add to milestone**. -If a task already belongs to a milestone, the dropdown list shows the current milestone. + If a task already belongs to a milestone, the dropdown list shows the current milestone. 1. From the dropdown list, select the milestone to be associated with the task. ## Set task weight **(PREMIUM)** diff --git a/doc/user/todos.md b/doc/user/todos.md index 4102d31cfc4..221e89d658c 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -50,6 +50,8 @@ A to-do item is added to your To-Do List when: merge request is removed from a [merge train](../ci/pipelines/merge_trains.md), and you're the user that added it. +- [In GitLab 15.8](https://gitlab.com/gitlab-org/gitlab/-/issues/374725) and later, + a member access request is raised for a group or project you're an owner of. When several actions occur for the same user on the same object, GitLab displays the first action as a single to-do item. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 0e5703caffc..c6c27f36618 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -7,6 +7,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Storage usage quota **(FREE)** +Storage usage statistics are available for projects and namespaces. You can use that information to +manage storage usage within the applicable quotas. + +Statistics include: + +- Storage usage across projects in a namespace. +- Storage usage that exceeds the storage quota. +- Available purchased storage. + ## View storage usage Prerequisites: diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 4a8b083e3a2..e4e1edd6346 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -1,10 +1,10 @@ --- stage: Manage -group: Workspace +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Workspace +# Organization DISCLAIMER: This page contains information related to upcoming products, features, and functionality. @@ -15,9 +15,9 @@ The development, release, and timing of any products, features, or functionality sole discretion of GitLab Inc. NOTE: -Workspace is in development. +Organization is in development. -Workspace will be above the [top-level namespaces](../namespace/index.md) for you to manage +Organization will be above the [top-level namespaces](../namespace/index.md) for you to manage everything you do as a GitLab administrator, including: - Defining and applying settings to all of your groups, subgroups, and projects. @@ -26,11 +26,11 @@ everything you do as a GitLab administrator, including: Our goal is to reach feature parity between SaaS and self-managed installations, with all [Admin Area settings](/ee/user/admin_area/settings/index.md) moving to either: -- Groups. Available in the Workspace, top-level groups, and subgroups. +- Groups. Available in the Organization, and subgroups. - 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. -For more information about the state of workspace development, +For more information about the state of organization development, see [epic 9265](https://gitlab.com/groups/gitlab-org/-/epics/9265). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -39,4 +39,4 @@ For a video introduction to the new hierarchy concept for groups and projects fo ## Related topics -- [Workspace developer documentation](../../development/workspace/index.md) +- [Organization developer documentation](../../development/workspace/index.md) |
