diff options
Diffstat (limited to 'doc/user')
309 files changed, 3829 insertions, 8176 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_reports.md b/doc/user/admin_area/analytics/dev_ops_reports.md index 69bf4ff30f1..30ba2ad3e7b 100644 --- a/doc/user/admin_area/analytics/dev_ops_reports.md +++ b/doc/user/admin_area/analytics/dev_ops_reports.md @@ -1,74 +1,11 @@ --- -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 +redirect_to: '../../../administration/analytics/dev_ops_reports.md' +remove_date: '2023-10-06' --- -# DevOps Reports **(FREE SELF)** +This document was moved to [another location](../../../administration/analytics/dev_ops_reports.md). -DevOps Reports give you an overview of your entire instance's adoption of -[Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) -from planning to monitoring. - -To see DevOps Reports: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Analytics > DevOps Reports**. - -## DevOps Score - -> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) from Conversational Development Index in GitLab 12.6. - -NOTE: -To see the DevOps score, you must activate your GitLab instance's [Service Ping](../settings/usage_statistics.md#service-ping). DevOps Score is a comparative tool, so your score data must be centrally processed by GitLab Inc. first. - -You can use the DevOps score to compare your DevOps status to other organizations. - -The DevOps Score tab displays usage of major GitLab features on your instance over -the last 30 days, averaged over the number of billable users in that time period. -You can also see the Leader usage score, calculated from top-performing instances based on -[Service Ping data](../settings/usage_statistics.md#service-ping) that GitLab has collected. -Your score is compared to the lead score of each feature and then expressed -as a percentage at the bottom of said feature. Your overall **DevOps Score** is an average of your -feature scores. - -Service Ping data is aggregated on GitLab servers for analysis. Your usage -information is **not sent** to any other GitLab instances. -If you have just started using GitLab, it might take a few weeks for data to be collected before this -feature is available. - -## DevOps Adoption **(ULTIMATE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](../../../policy/experiment-beta-support.md#beta). -> - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. -> - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. -> - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. -> - Dependency Scanning metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328034) in GitLab 14.2. -> - Multi-select [added](https://gitlab.com/gitlab-org/gitlab/-/issues/333586) in GitLab 14.2. -> - Overview table [added](https://gitlab.com/gitlab-org/gitlab/-/issues/335638) in GitLab 14.3. - -DevOps Adoption shows feature adoption for development, security, and operations. - -| Category | Feature | -| --- | --- | -| Development | Approvals<br>Code owners<br>Issues<br>Merge requests | -| Security | DAST<br>Dependency Scanning<br>Fuzz Testing<br>SAST | -| Operations | Deployments<br>Pipelines<br>Runners | - -You can use Group DevOps Adoption to: - -- Identify specific subgroups that are lagging in their adoption of GitLab features, so you can guide them on -their DevOps journey. -- Find subgroups that have adopted certain features, and provide guidance to other subgroups on -how to use those features. -- Verify if you are getting the return on investment that you expected from GitLab. - -## Add or remove a group - -To add or remove a subgroup from the DevOps Adoption report: - -1. Select **Add or remove groups**. -1. Select the subgroup you want to add or remove and select **Save changes**. - - +<!-- This redirect file can be deleted after <2023-10-06>. --> +<!-- 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/admin_area/analytics/img/admin_devops_adoption_v14_2.png b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png Binary files differdeleted file mode 100644 index 666e03f1d9d..00000000000 --- a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_2.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png Binary files differdeleted file mode 100644 index bd02065556c..00000000000 --- a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 6441cd866c8..f5849f0b876 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -1,26 +1,11 @@ --- -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 +redirect_to: '../../../administration/analytics/index.md' +remove_date: '2023-10-06' --- -# Instance-level analytics **(FREE SELF)** +This document was moved to [another location](../../../administration/analytics/index.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. - -Instance-level analytics provide insights into the feature and data usage of your entire instance. - -## View instance-level analytics - -Prerequisite: - -- You must have administrator access to the instance. - -To view instance-level analytics: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Analytics**, then one of the available analytics: - - - [DevOps Reports](dev_ops_reports.md): Provides an overview of your entire instance's feature usage. - - [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how the data is changing. +<!-- This redirect file can be deleted after <2023-10-06>. --> +<!-- 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/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 49e82f71a3a..12eb44d6ebc 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -1,46 +1,11 @@ --- -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 +redirect_to: '../../../administration/analytics/usage_trends.md' +remove_date: '2023-10-07' --- -# Usage Trends **(FREE SELF)** +This document was moved to [another location](../../../administration/analytics/usage_trends.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235754) in GitLab 13.5 behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46962) in GitLab 13.6. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/285220) from Instance Statistics to Usage Trends in GitLab 13.6. -> - It's enabled on GitLab.com. -> - It's recommended for production use. - -Usage Trends gives you an overview of how much data your instance contains, and how quickly this volume is changing over time. -Usage Trends data refreshes daily. - -## View Usage Trends - -To view Usage Trends: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Analytics > Usage Trends**. - -## Total counts - -At the top of the page, Usage Trends shows total counts for: - -- Users -- Projects -- Groups -- Issues -- Merge requests -- Pipelines - -These figures can be useful for understanding how much data your instance contains in total. - -## Past year trend charts - -Usage Trends also displays line charts that show total counts per month, over the past 12 months, -in the categories shown in [Total counts](#total-counts). - -These charts help you visualize how rapidly these records are being created on your instance. - - +<!-- This redirect file can be deleted after <2023-10-07>. --> +<!-- 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/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 99c2a453b07..6a3760bc62d 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -1,123 +1,11 @@ --- -stage: none -group: unassigned -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: '../../administration/appearance.md' +remove_date: '2023-10-07' --- -# GitLab Appearance **(FREE SELF)** +This document was moved to [another location](../../administration/appearance.md). -Several options are available for customizing the appearance of a self-managed instance -of GitLab. To access these settings: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Appearance**. - -## Navigation bar - -By default, the navigation bar has the GitLab logo, but this can be customized with -any image desired. It is optimized for images 28px high (any width), but any image can be -used (less than 1 MB) and it is automatically resized. - -After you select and upload an image, select **Update appearance settings** at the bottom -of the page to activate it in the GitLab instance. - -NOTE: -GitLab pipeline emails also display the custom logo, unless the logo is in SVG format. If the -custom logo is in SVG format, the default logo is used instead because the SVG format is not -supported by many email clients. - -## Favicon - -By default, the favicon (used by the browser as the tab icon, as well as the CI status icon) -uses the GitLab logo. This can be customized with any icon desired. It must be a -32x32 `.png` or `.ico` image. - -After you select and upload an icon, select **Update appearance settings** at the bottom -of the page to activate it in the GitLab instance. - -## System header and footer messages - -> **Enable header and footer in emails** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. - -You can add a small header message, a small footer message, or both, to the interface -of your GitLab instance. These messages appear on all projects and pages of the -instance, including the sign in / sign up page. The default color is white text on -an orange background, but this can be customized by selecting **Customize colors**. - -Limited [Markdown](../markdown.md) is supported, such as bold, italics, and links, for -example. Other Markdown features, including lists, images, and quotes are not supported -as the header and footer messages can only be a single line. - -You can select **Enable header and footer in emails** to have the text of -the header and footer added to all emails sent by the GitLab instance. - -After you add a message, select **Update appearance settings** at the bottom of the page -to activate it in the GitLab instance. - -## Sign in / Sign up pages - -You can replace the default message on the sign in / sign up page with your own message -and logo. You can make full use of [Markdown](../markdown.md) in the description. - -The optimal size for the logo is 128 x 128 pixels, but any image can be used (below 1 MB) -and it is resized automatically. The logo image appears between the title and -the description, on the left of the sign-up page. - -After you add a message, select **Update appearance settings** at the bottom of the page -to activate it in the GitLab instance. You can also select **Sign-in page**, -to review the saved appearance settings: - -NOTE: -You can add also add a [customized help message](settings/help_page.md) below the sign in message or add [a Sign in text message](settings/sign_in_restrictions.md#sign-in-information). - -## Progressive Web App - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.9. - -GitLab can be installed as a [Progressive Web App](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps) (PWA). -Use the Progressive Web App settings to customize its appearance, including its name, -description, and icon. - -### Configure the PWA settings - -To configure the PWA settings: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Appearance**. -1. Scroll to the **Progressive Web App (PWA)** section. -1. Complete the fields. - - **Icon**: If you use the standard GitLab icon, it is available in sizes 192x192 pixels, - 512x512 pixels, also as a maskable icon. If you use a custom icon, it must be in either size - 192x192 pixels, or 512x512 pixels. -1. Select **Update appearance settings**. - -## New project pages - -You can add a new project guidelines message to the **New project page** in GitLab. -You can make full use of [Markdown](../markdown.md) in the description: - -The message is displayed below the **New Project** message, on the left side -of the **New project page**. - -After you add a message, select **Update appearance settings** at the bottom of the page -to activate it in the GitLab instance. You can also select **New project page**, -which brings you to the new project page so you can review the change. - -## Libravatar - -[Libravatar](https://www.libravatar.org) is supported by GitLab for avatar images, but you must -[manually enable Libravatar support on the GitLab instance](../../administration/libravatar.md) to use the service. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-07>. --> +<!-- 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/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 6fe82b3ae83..4893b94ce50 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -1,120 +1,11 @@ --- -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 -type: reference, howto +redirect_to: '../../administration/broadcast_messages.md' +remove_date: '2023-10-07' --- -# Broadcast messages **(FREE SELF)** +This document was moved to [another location](../../administration/broadcast_messages.md). -> - Target roles [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default. -> - Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83251) and background color removed in GitLab 14.10. - -GitLab can display broadcast messages to users of a GitLab instance. There are two types of broadcast messages: - -- Banners -- Notifications - -Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md). - -## Banners - -Banners are shown on the top of a page and optionally in the command line as a Git remote response. - - - -```shell -$ git push -... -remote: -remote: **Welcome** to GitLab :wave: -remote: -... -``` - -If more than one banner is active at one time, they are displayed at the top of the page in order of creation. In the command line, only the latest banner is shown. - -## Notifications - -Notifications are shown on the bottom right of a page and can contain placeholders. A placeholder is replaced with an attribute of the active user. Placeholders must be surrounded by curly braces, for example `{{name}}`. -The available placeholders are: - -- `{{email}}` -- `{{name}}` -- `{{user_id}}` -- `{{username}}` -- `{{instance_id}}` - -If the user is not signed in, user related values are empty. - - - -If more than one notification is active at one time, only the newest is shown. - -## Add a broadcast message - -To display messages to users on your GitLab instance, add a broadcast message. - -To add a broadcast message: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Messages**. -1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. - The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: - - `color` - - `border` - - `background` - - `padding` - - `margin` - - `text-decoration` -1. Select a **Theme**. The default theme is `indigo`. -1. Select the **Dismissable** checkbox to enable users to dismiss the broadcast message. -1. Optional. Clear the **Git remote responses** checkbox to prevent broadcast messages from being displayed in the command line as Git remote responses. -1. Optional. Select **Target roles** to only show the broadcast message to users with the selected roles. The message displays on group, subgroup, and project pages, and does not display in Git remote responses. -1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `mygroup/myproject*`. -1. Select a date and time (UTC) for the message to start and end. -1. Select **Add broadcast message**. - -When a broadcast message expires, it no longer displays in the user interface but is still listed in the -list of broadcast messages. - -## Edit a broadcast message - -If you must make changes to a broadcast message, you can edit it. - -To edit a broadcast message: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Messages**. -1. From the list of broadcast messages, select the edit button for the message. -1. After making the required changes, select **Update broadcast message**. - -Expired messages can be made active again by changing their end date. - -## Delete a broadcast message - -If you no longer require a broadcast message, you can delete it. -You can delete a broadcast message while it's active. - -To delete a broadcast message: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Messages**. -1. From the list of broadcast messages, select the delete button for the message. - -When a broadcast message is deleted, it's removed from the list of broadcast messages. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-07>. --> +<!-- 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/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 9bacd101c48..f38eed5de43 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -1,86 +1,11 @@ --- -stage: Manage -group: Authentication and Authorization -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: howto +redirect_to: '../../administration/credentials_inventory.md' +remove_date: '2023-10-07' --- -# Credentials inventory **(ULTIMATE SELF)** +This document was moved to [another location](../../administration/credentials_inventory.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20912) in GitLab 12.6. -> - [Bot-created access tokens not displayed in personal access token list](https://gitlab.com/gitlab-org/gitlab/-/issues/351759) in GitLab 14.9. - -GitLab administrators are responsible for the overall security of their instance. To assist, GitLab -provides a Credentials inventory to keep track of all the credentials that can be used to access -their self-managed instance. - -Use Credentials inventory to see for your GitLab instance all: - -- Personal access tokens (PAT). -- Project access tokens (GitLab 14.8 and later). -- SSH keys. -- GPG keys. - -You can also [revoke](#revoke-a-users-personal-access-token) and [delete](#delete-a-users-ssh-key) and see: - -- Who they belong to. -- Their access scope. -- Their usage pattern. -- When they expire. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214809) in GitLab 13.2. -- When they were revoked. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214809) in GitLab 13.2. - -To access the Credentials inventory: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Credentials**. - -## Revoke a user's personal access token - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214811) in GitLab 13.4. - -If you see a **Revoke** button, you can revoke that user's PAT. Whether you see a **Revoke** button depends on the token state, and if an expiration date has been set. For more information, see the following table: - -| Token state | Show Revoke button? | Comments | -|-------------|---------------------|----------------------------------------------------------------------------| -| Active | Yes | Allows administrators to revoke the PAT, such as for a compromised account | -| Expired | No | Not applicable; token is already expired | -| Revoked | No | Not applicable; token is already revoked | - -When a PAT is revoked from the credentials inventory, the instance notifies the user by email. - - - -## Revoke a user's project access token - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243833) in GitLab 14.8. - -The **Revoke** button next to a project access token can be selected to revoke that particular project access token. This both: - -- Revokes the token project access token. -- Enqueues a background worker to delete the project bot user. - - - -## Delete a user's SSH key - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225248) in GitLab 13.5. - -You can **Delete** a user's SSH key by navigating to the credentials inventory's SSH Keys tab. -The instance then notifies the user. - - - -## Review existing GPG keys - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282429) in GitLab 13.10. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292961) in GitLab 13.12. - -You can view all existing GPG in your GitLab instance by navigating to the -credentials inventory GPG Keys tab, as well as the following properties: - -- Who the GPG key belongs to. -- The ID of the GPG key. -- Whether the GPG key is [verified or unverified](../project/repository/gpg_signed_commits/index.md) - - +<!-- This redirect file can be deleted after <2023-10-07>. --> +<!-- 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/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 0e0acf4af57..dc773b0aaca 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -1,73 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../../administration/custom_project_templates.md' +remove_date: '2023-10-10' --- -# Custom instance-level project templates **(PREMIUM SELF)** +This document was moved to [another location](../../administration/custom_project_templates.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. - -GitLab administrators can set a group to be the source of project templates that are -selectable when a new project is created on the instance. These templates can be selected -when you go to **New project > Create from template** and select the **Instance** tab. - -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 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 and Compliance** are set to **Everyone With Access**. - The same applies to internal projects. -- Private projects can be selected only by users who are members of the projects. - -The **Metrics Dashboard** is set to **Only Project Members** when you create a new project. Make -sure you change it to **Everyone With Access** before making it a project template. - -Repository and database information that are copied over to each new project are -identical to the data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). - -To set project templates at the group level, see [Custom group-level project templates](../group/custom_project_templates.md). - -## Select instance-level project template group - -To select the group to use as the source for the project templates: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Templates**. -1. Expand **Custom project templates**. -1. Select a group to use. -1. Select **Save changes**. - -Projects in subgroups of the template group are **not** included in the template list. - -## What is copied from the templates - -The entire custom instance-level project templates repository is copied, including: - -- Branches -- Commits -- Tags - -If the user: - -- Has the Owner role on the custom instance-level project templates project or is a GitLab administrator, all project settings are copied over to the new - project. -- Doesn't have the Owner role or is not a GitLab administrator, project [deploy keys](../project/deploy_keys/index.md#view-deploy-keys) and project - [webhooks](../project/integrations/webhooks.md) aren't copied over because they contain sensitive data. - -To learn more about what is migrated, see -[Items that are exported](../project/settings/import_export.md#items-that-are-exported). - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-10>. --> +<!-- 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/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 72e8269e455..54d7d82af98 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -1,53 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +redirect_to: '../../administration/diff_limits.md' +remove_date: '2023-10-10' --- -# Diff limits administration **(FREE SELF)** +This document was moved to [another location](../../administration/diff_limits.md). -You can set a maximum size for display of diff files (patches). - -For details about diff files, [view changes between files](../project/merge_requests/changes.md). -Read more about the [built-in limits for merge requests and diffs](../../administration/instance_limits.md#merge-requests). - -## Configure diff limits - -WARNING: -These settings are experimental. An increased maximum increases resource -consumption of your instance. Keep this in mind when adjusting the maximum. - -To speed the loading time of merge request views and branch comparison views -on your instance, you can configure three instance-level maximum values for diffs: - -| Value | Definition | Default value | Maximum value | -| ----- | ---------- | :-----------: | :-----------: | -| **Maximum diff patch size** | The total size, in bytes, of the entire diff. | 200 KB | 500 KB | -| **Maximum diff files** | The total number of files changed in a diff. | 1000 | 3000 | -| **Maximum diff lines** | The total number of lines changed in a diff. | 50,000 | 100,000 | - -When a diff reaches 10% of any of these values, the files are shown in a -collapsed view, with a link to expand the diff. Diffs that exceed any of the -set values are presented as **Too large** are cannot be expanded in the UI. - -To configure these values: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Diff limits**. -1. Enter a value for the diff limit. -1. Select **Save changes**. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-10>. --> +<!-- 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/admin_area/email_from_gitlab.md b/doc/user/admin_area/email_from_gitlab.md index fbdfe437719..e5194f05381 100644 --- a/doc/user/admin_area/email_from_gitlab.md +++ b/doc/user/admin_area/email_from_gitlab.md @@ -1,61 +1,11 @@ --- -stage: none -group: unassigned -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: howto, reference +redirect_to: '../../administration/email_from_gitlab.md' +remove_date: '2023-10-10' --- -# Email from GitLab **(PREMIUM SELF)** +This document was moved to [another location](../../administration/email_from_gitlab.md). -GitLab provides a tool to administrators for emailing all users, or users of -a chosen group or project, right from the Admin Area. Users receive the email -at their primary email address. - -For information about email notifications originating from GitLab, read -[GitLab notification emails](../profile/notifications.md). - -## Use-cases - -- Notify your users about a new project, a new feature, or a new product launch. -- Notify your users about a new deployment, or that downtime is expected - for a particular reason. - -## Sending emails to users from GitLab - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select **Send email to users**. - -  - -1. Compose an email and choose where to send it (all users or users of a - chosen group or project). The email body only supports plain text messages. - HTML, Markdown, and other rich text formats are not supported, and is - sent as plain text to users. - -  - -NOTE: -[Starting with GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/31509), email notifications can be sent only once every 10 minutes. This helps minimize performance issues. - -## Unsubscribing from emails - -Users can choose to unsubscribe from receiving emails from GitLab by following -the unsubscribe link in the email. Unsubscribing is unauthenticated in order -to keep this feature simple. - -On unsubscribe, users receive an email notification that unsubscribe happened. -The endpoint that provides the unsubscribe option is rate-limited. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-10>. --> +<!-- 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/admin_area/external_users.md b/doc/user/admin_area/external_users.md index a63093deab0..ec28f109384 100644 --- a/doc/user/admin_area/external_users.md +++ b/doc/user/admin_area/external_users.md @@ -1,80 +1,11 @@ --- -stage: Manage -group: Authentication and Authorization -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: '../../administration/external_users.md' +remove_date: '2023-10-10' --- -# External users **(FREE SELF)** +This document was moved to [another location](../../administration/external_users.md). -In cases where it is desired that a user has access only to some internal or -private projects, there is the option of creating **External Users**. This -feature may be useful when for example a contractor is working on a given -project and should only have access to that project. - -External users: - -- Cannot create project, groups, and snippets in their personal namespaces. -- Can only create projects (including forks), subgroups, and snippets within top-level groups to which they are explicitly granted access. -- Can only access public projects and projects to which they are explicitly granted access, - thus hiding all other internal or private ones from them (like being - logged out). -- Can only access public groups and groups to which they are explicitly granted access, - thus hiding all other internal or private ones from them (like being - logged out). -- Can only access public snippets. - -Access can be granted by adding the user as member to the project or group. -Like usual users, they receive a role in the project or group with all -the abilities that are mentioned in the [permissions table](../permissions.md#project-members-permissions). -For example, if an external user is added as Guest, and your project is internal or -private, they do not have access to the code; you need to grant the external -user access at the Reporter level or above if you want them to have access to the code. You should -always take into account the -[project's visibility and permissions settings](../project/settings/index.md#configure-project-visibility-features-and-permissions) -as well as the permission level of the user. - -NOTE: -External users still count towards a license seat. - -An administrator can flag a user as external by either of the following methods: - -- [Through the API](../../api/users.md#user-modification). -- Using the GitLab UI: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **Admin Area**. - 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. - There, you can find the option to flag the user as external. - -Additionally, users can be set as external users using: - -- [SAML groups](../../integration/saml.md#external-groups). -- [LDAP groups](../../administration/auth/ldap/ldap_synchronization.md#external-groups). -- the [External providers list](../../integration/omniauth.md#create-an-external-providers-list). - -## Set a new user to external - -By default, new users are not set as external users. This behavior can be changed -by an administrator: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Account and limit** section. - -If you change the default behavior of creating new users as external, you -have the option to narrow it down by defining a set of internal users. -The **Internal users** field allows specifying an email address regex pattern to -identify default internal users. New users whose email address matches the regex -pattern are set to internal by default rather than an external collaborator. - -The regex pattern format is in Ruby, but it needs to be convertible to JavaScript, -and the ignore case flag is set (`/regex pattern/i`). Here are some examples: - -- Use `\.internal@domain\.com$` to mark email addresses ending with - `.internal@domain.com` as internal. -- Use `^(?:(?!\.ext@domain\.com).)*$\r?` to mark users with email addresses - not including `.ext@domain.com` as internal. - -WARNING: -Be aware that this regex could lead to a -[regular expression denial of service (ReDoS) attack](https://en.wikipedia.org/wiki/ReDoS). +<!-- This redirect file can be deleted after <2023-10-10>. --> +<!-- 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/admin_area/geo_sites.md b/doc/user/admin_area/geo_sites.md index 3bae90aaec8..cd0f2f5646a 100644 --- a/doc/user/admin_area/geo_sites.md +++ b/doc/user/admin_area/geo_sites.md @@ -1,119 +1,11 @@ --- -stage: Systems -group: Geo -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: '../../administration/geo_sites.md' +remove_date: '2023-10-10' --- -# Geo sites Admin Area **(PREMIUM SELF)** +This document was moved to [another location](../../administration/geo_sites.md). -You can configure various settings for GitLab Geo sites. For more information, see -[Geo documentation](../../administration/geo/index.md). - -On either the primary or secondary site: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Geo > Sites**. - -## Common settings - -All Geo sites have the following settings: - -| Setting | Description | -| --------| ----------- | -| Primary | This marks a Geo site as **primary** site. There can be only one **primary** site. | -| Name | The unique identifier for the Geo site. It's highly recommended to use a physical location as a name. Good examples are "London Office" or "us-east-1". Avoid words like "primary", "secondary", "Geo", or "DR". This makes the failover process easier because the physical location does not change, but the Geo site role can. All nodes in a single Geo site use the same site name. Nodes use the `gitlab_rails['geo_node_name']` setting in `/etc/gitlab/gitlab.rb` to lookup their Geo site record in the PostgreSQL database. If `gitlab_rails['geo_node_name']` is not set, the node's `external_url` with trailing slash is used as fallback. The value of `Name` is case-sensitive, and most characters are allowed. | -| URL | The instance's user-facing URL. | - -The site you're currently browsing is indicated with a blue `Current` label, and -the **primary** node is listed first as `Primary site`. - -## Secondary site settings - -**Secondary** sites have a number of additional settings available: - -| Setting | Description | -|---------------------------|-------------| -| Selective synchronization | Enable Geo [selective sync](../../administration/geo/replication/configuration.md#selective-synchronization) for this **secondary** site. | -| Repository sync capacity | Number of concurrent requests this **secondary** site makes to the **primary** site when backfilling repositories. | -| File sync capacity | Number of concurrent requests this **secondary** site makes to the **primary** site when backfilling files. | - -## Geo backfill - -**Secondary** sites are notified of changes to repositories and files by the **primary** site, -and always attempt to synchronize those changes as quickly as possible. - -Backfill is the act of populating the **secondary** site with repositories and files that -existed *before* the **secondary** site was added to the database. Because there may be -extremely large numbers of repositories and files, it's not feasible to attempt to -download them all at once; so, GitLab places an upper limit on the concurrency of -these operations. - -How long the backfill takes is dependent on the maximum concurrency, but higher -values place more strain on the **primary** site. The limits are configurable. -If your **primary** site has lots of surplus capacity, -you can increase the values to complete backfill in a shorter time. If it's -under heavy load and backfill reduces its availability for standard requests, -you can decrease them. - -## Set up the internal URLs - -> Setting up internal URLs in secondary sites was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77179) in GitLab 14.7. - -You can set up a different URL for synchronization between the primary and secondary site. - -The **primary** site's Internal URL is used by **secondary** sites to contact it -(to sync repositories, for example). The name Internal URL distinguishes it from -[External URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab), -which is used by users. Internal URL does not need to be a private address. - -When [Geo secondary proxying](../../administration/geo/secondary_proxy/index.md) is enabled, -the primary uses the secondary's internal URL to contact it directly. - -The internal URL defaults to external URL. To change it: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Geo > Sites**. -1. Select **Edit** on the site you want to customize. -1. Edit the internal URL. -1. Select **Save changes**. - -When enabled, the Admin Area for Geo shows replication details for each site directly -from the primary site's UI, and through the Geo secondary proxy, if enabled. - -WARNING: -We recommend using an HTTPS connection while configuring the Geo sites. To avoid -breaking communication between **primary** and **secondary** sites when using -HTTPS, customize your Internal URL to point to a load balancer with TLS -terminated at the load balancer. - -WARNING: -Starting with GitLab 13.3 and [until 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/325522), -if you use an internal URL that is not accessible to the users, the -OAuth authorization flow does not work properly, because users are redirected -to the internal URL instead of the external one. - -## Multiple secondary sites behind a load balancer - -**Secondary** sites can use identical external URLs if -a unique `name` is set for each Geo site. The `gitlab.rb` setting -`gitlab_rails['geo_node_name']` must: - -- Be set for each GitLab instance that runs `puma`, `sidekiq`, or `geo_logcursor`. -- Match a Geo site name. - -The load balancer must use sticky sessions to avoid authentication -failures and cross-site request errors. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-10>. --> +<!-- 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/admin_area/img/abuse_report_blocked_user.png b/doc/user/admin_area/img/abuse_report_blocked_user.png Binary files differdeleted file mode 100644 index 435d8dfe821..00000000000 --- a/doc/user/admin_area/img/abuse_report_blocked_user.png +++ /dev/null diff --git a/doc/user/admin_area/img/abuse_reports_page_v13_11.png b/doc/user/admin_area/img/abuse_reports_page_v13_11.png Binary files differdeleted file mode 100644 index ef57f45ab77..00000000000 --- a/doc/user/admin_area/img/abuse_reports_page_v13_11.png +++ /dev/null diff --git a/doc/user/admin_area/img/admin_labels_v14_7.png b/doc/user/admin_area/img/admin_labels_v14_7.png Binary files differdeleted file mode 100644 index 01a4ea0c2cc..00000000000 --- a/doc/user/admin_area/img/admin_labels_v14_7.png +++ /dev/null diff --git a/doc/user/admin_area/img/broadcast_messages_banner_v15_0.png b/doc/user/admin_area/img/broadcast_messages_banner_v15_0.png Binary files differdeleted file mode 100644 index e1b350142b3..00000000000 --- a/doc/user/admin_area/img/broadcast_messages_banner_v15_0.png +++ /dev/null diff --git a/doc/user/admin_area/img/broadcast_messages_notification_v12_10.png b/doc/user/admin_area/img/broadcast_messages_notification_v12_10.png Binary files differdeleted file mode 100644 index fb03748c892..00000000000 --- a/doc/user/admin_area/img/broadcast_messages_notification_v12_10.png +++ /dev/null diff --git a/doc/user/admin_area/img/cohorts_v13_9_a.png b/doc/user/admin_area/img/cohorts_v13_9_a.png Binary files differdeleted file mode 100644 index 1a4590290b9..00000000000 --- a/doc/user/admin_area/img/cohorts_v13_9_a.png +++ /dev/null diff --git a/doc/user/admin_area/img/credentials_inventory_gpg_keys_v14_9.png b/doc/user/admin_area/img/credentials_inventory_gpg_keys_v14_9.png Binary files differdeleted file mode 100644 index 6c4c8f30df6..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_gpg_keys_v14_9.png +++ /dev/null diff --git a/doc/user/admin_area/img/credentials_inventory_personal_access_tokens_v14_9.png b/doc/user/admin_area/img/credentials_inventory_personal_access_tokens_v14_9.png Binary files differdeleted file mode 100644 index 254d520d538..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_personal_access_tokens_v14_9.png +++ /dev/null diff --git a/doc/user/admin_area/img/credentials_inventory_project_access_tokens_v14_9.png b/doc/user/admin_area/img/credentials_inventory_project_access_tokens_v14_9.png Binary files differdeleted file mode 100644 index ae204ac09ef..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_project_access_tokens_v14_9.png +++ /dev/null diff --git a/doc/user/admin_area/img/credentials_inventory_ssh_keys_v14_9.png b/doc/user/admin_area/img/credentials_inventory_ssh_keys_v14_9.png Binary files differdeleted file mode 100644 index 8f2f11515eb..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_ssh_keys_v14_9.png +++ /dev/null diff --git a/doc/user/admin_area/img/email1.png b/doc/user/admin_area/img/email1.png Binary files differdeleted file mode 100644 index e79ccc3e9a9..00000000000 --- a/doc/user/admin_area/img/email1.png +++ /dev/null diff --git a/doc/user/admin_area/img/email2.png b/doc/user/admin_area/img/email2.png Binary files differdeleted file mode 100644 index d073c0e42da..00000000000 --- a/doc/user/admin_area/img/email2.png +++ /dev/null diff --git a/doc/user/admin_area/img/export_permissions_v13_11.png b/doc/user/admin_area/img/export_permissions_v13_11.png Binary files differdeleted file mode 100644 index d9bbe8c3daf..00000000000 --- a/doc/user/admin_area/img/export_permissions_v13_11.png +++ /dev/null diff --git a/doc/user/admin_area/img/impersonate_user_button_v13_8.png b/doc/user/admin_area/img/impersonate_user_button_v13_8.png Binary files differdeleted file mode 100644 index 475315a0c0f..00000000000 --- a/doc/user/admin_area/img/impersonate_user_button_v13_8.png +++ /dev/null diff --git a/doc/user/admin_area/img/index_runners_search_or_filter_v14_5.png b/doc/user/admin_area/img/index_runners_search_or_filter_v14_5.png Binary files differdeleted file mode 100644 index 10b8cc01103..00000000000 --- a/doc/user/admin_area/img/index_runners_search_or_filter_v14_5.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index a59501f14ce..a729cefa7b8 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -1,440 +1,11 @@ --- -stage: none -group: unassigned -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 +redirect_to: '../../administration/admin_area.md' +remove_date: '2023-10-11' --- -# GitLab Admin Area **(FREE SELF)** +This document was moved to [another location](../../administration/admin_area.md). -The Admin Area provides a web UI to manage and configure features of GitLab -self-managed instances. If you are an administrator,to access the Admin Area: - -- In GitLab 16.1 and later: on the left sidebar, expand the top-most chevron (**{chevron-down}**), then select **Admin Area**. -- In GitLab 16.0 and earlier: on the top bar, select **Main menu > Admin**. - -NOTE: -Only administrators can access the Admin Area. - -## Administering projects - -You can administer all projects in the GitLab instance from the Admin Area's Projects page. - -To access the Projects page: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Projects**. -1. Select the **All**, **Private**, **Internal**, or **Public** tab to list only - projects of that criteria. - -By default, all projects are listed, in reverse order of when they were last updated. For each -project, the following information is listed: - -- Name -- Namespace -- Description -- Size, updated every 15 minutes at most - -Projects can be edited or deleted. - -To edit a project's name or description: - -1. In the Projects overview, next to the project you want to edit, select **Edit**. -1. Edit the **Project name** or **Project description**. -1. Select **Save Changes**. - -To delete a project: - -1. In the Projects overview, next to the project you want to delete, select **Delete**. - -The list of projects can be sorted by: - -- Updated date -- Last created -- Name -- Most stars -- Oldest created -- Oldest updated -- Largest repository - -A user can choose to hide or show archived projects in the list. - -In the **Filter by name** field, type the project name you want to find, and GitLab filters -them as you type. - -To filter only projects in that namespace, select from the **Namespace** dropdown list. - -You can combine the filter options. For example, to list only public projects with `score` in their name: - -1. Select the **Public** tab. -1. Enter `score` in the **Filter by name...** input box. - -## Administering users - -You can administer all users in the GitLab instance from the Admin Area's Users page: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. - -To list users matching a specific criteria, select one of the following tabs on the **Users** page: - -- **Active** -- **Admins** -- **2FA Enabled** -- **2FA Disabled** -- **External** -- **[Blocked](moderate_users.md#block-a-user)** -- **[Deactivated](moderate_users.md#deactivate-a-user)** -- **Without projects** - -For each user, the following are listed: - -1. Username -1. Email address -1. Project membership count -1. Group membership count ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276215) in GitLab 13.12) -1. Date of account creation -1. Date of last activity - -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: - -1. Select the sort dropdown list. -1. Select the desired order. - -By default the sort dropdown list shows **Name**. - -To search for users, enter your criteria in the search field. The user search is case -insensitive, and applies partial matching to name and username. To search for an email address, -you must provide the complete email address. - -### User impersonation - -An administrator can "impersonate" any other user, including other administrators. -This allows the administrator to "see what the user sees," and take actions on behalf of the user. -You can impersonate a user in the following ways: - -- Through the UI: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **Admin Area**. - 1. On the left sidebar, select **Overview > Users**. - 1. From the list of users, select a user. - 1. Select **Impersonate**. -- With the API, using [impersonation tokens](../../api/rest/index.md#impersonation-tokens). - -All impersonation activities are [captured with audit events](../../administration/audit_events.md#user-impersonation). - -By default, impersonation is enabled. GitLab can be configured to [disable impersonation](../../api/rest/index.md#disable-impersonation). - - - -### User identities - -> The ability to see a user's SCIM identity was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294608) in GitLab 15.3. - -When using authentication providers, administrators can see the identities for a user: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. From the list of users, select a user. -1. Select **Identities**. - -This list shows the user's identities, including SCIM identities. Administrators can use this information to troubleshoot SCIM-related issues and confirm -the identities being used for an account. - -### User Permission Export **(PREMIUM SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1772) in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292436) in GitLab 13.9. - -An administrator can export user permissions for all users in the GitLab instance from the Admin Area's Users page. -The export lists direct membership the users have in groups and projects. - -The following data is included in the export: - -- Username -- Email -- Type -- Path -- Access level ([Project](../permissions.md#project-members-permissions) and [Group](../permissions.md#group-members-permissions)) -- Date of last activity ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345388) in GitLab 14.6). For a list of activities that populate this column, see the [Users API documentation](../../api/users.md#get-user-activities). - -Only the first 100,000 user accounts are exported. - - - -### Users statistics - -The **Users statistics** page provides an overview of user accounts by role. These statistics are -calculated daily, so user changes made since the last update are not reflected. - -The following totals are also included: - -- Billable users -- Blocked users -- Total users - -GitLab billing is based on the number of [**Billable users**](../../subscriptions/self_managed/index.md#billable-users). - -### Add email to user - -You must be an administrator to manually add emails to users: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Locate the user and select them. -1. Select **Edit**. -1. In **Email**, enter the new email address. This adds the new email address to the - user and sets the previous email address to be a secondary. -1. Select **Save changes**. - -## User cohorts - -The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and their activities over time. - -## Prevent a user from creating groups - -By default, users can create groups. To prevent a user from creating a top level group: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Locate the user and select them. -1. Select **Edit**. -1. Clear the **Can create group** checkbox. -1. Select **Save changes**. - -It is also possible to [limit which roles can create a subgroup within a group](../group/subgroups/index.md#change-who-can-create-subgroups). - -## Administering groups - -You can administer all groups in the GitLab instance from the Admin Area's Groups page. - -To access the Groups page: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. 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, 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**. - -To search for groups by name, enter your criteria in the search field. The group search is case -insensitive, and applies partial matching. - -To [Create a new group](../group/index.md#create-a-group) select **New group**. - -## Administering topics - -- > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.4. -- > Merging topics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366884) in GitLab 15.5. - -[Topics](../project/working_with_projects.md#explore-topics) are used to categorize and find similar projects. - -You can administer all topics in the GitLab instance from the Admin Area's Topics page. - -To access the Topics page: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Topics**. - -For each topic, the page displays its name and the number of projects labeled with the topic. - -To create a new topic, select **New topic**. - -To edit a topic, select **Edit** in that topic's row. - -To remove a topic, select **Remove** in that topic's row. - -To remove a topic and move all assigned projects to another topic, select **Merge topics**. - -To search for topics by name, enter your criteria in the search box. The topic search is case -insensitive and applies partial matching. - -NOTE: -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 Gitaly servers - -You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** -page. For more details, see [Gitaly](../../administration/gitaly/index.md). - -To access the **Gitaly Servers** page: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Gitaly Servers**. - -For each Gitaly server, 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. | - -## 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. - -To access the **Runners** page: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Runners**. - -#### Search and filter runners - -To search runners' descriptions: - -1. In the **Search or filter results...** field, type the description of the runner you want to - find. -1. Press <kbd>Enter</kbd>. - -You can also filter runners by status, type, and tag. To filter: - -1. Select a tab or the **Search or filter results...** field. -1. Select any **Type**, or filter by **Status** or **Tags**. -1. Select or enter your search criteria. - - - -#### Bulk delete runners - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370241) in GitLab 15.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353981) in GitLab 15.5. - -You can delete multiple runners at the same time. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Runners**. -1. To the left of the runners you want to delete, select the checkbox. - To select all of the runners on the page, select the checkbox above - the list. -1. Select **Delete selected**. - -#### Runner attributes - -For each runner, the following attributes are listed: - -| Attribute | Description | -|--------------|-------------| -| Status | The status of the runner. In [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22224), for the **Ultimate** tier, the upgrade status is available. | -| Runner details | Information about the runner, including partial token and details about the computer the runner was registered from. | -| Version | GitLab Runner version. | -| Jobs | Total number of jobs run by the runner. | -| Tags | Tags associated with the runner. | -| Last contact | Timestamp indicating when the runner last contacted the GitLab instance. | - -You can also edit, pause, or remove each runner. - -### Administering Jobs - -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/386311) from **Overview > Jobs** to **CI/CD > Jobs** in GitLab 15.8. - -You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. - -To access the Jobs page: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. 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 job, 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. | - -## Monitoring section - -The following topics document the **Monitoring** section of the Admin Area. - -### System Information - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341248) in GitLab 15.2, support for relative time. "Uptime" statistic was renamed to "System started". - -The **System Info** page provides the following statistics: - -| Field | Description | -|:---------------|:--------------------------------------------------| -| CPU | Number of CPU cores available | -| Memory Usage | Memory in use, and total memory available | -| Disk Usage | Disk space in use, and total disk space available | -| System started | When the system hosting GitLab was started. In GitLab 15.1 and earlier, this was an uptime statistic. | - -These statistics are updated only when you navigate to the **System Info** page, or you refresh the page in your browser. - -### Background Jobs - -The **Background Jobs** page displays the Sidekiq dashboard. Sidekiq is used by GitLab to -perform processing in the background. - -The Sidekiq dashboard consists of the following elements: - -- A tab per jobs' status. -- A breakdown of background job statistics. -- A live graph of **Processed** and **Failed** jobs, with a selectable polling interval. -- An historical graph of **Processed** and **Failed** jobs, with a selectable time span. -- Redis statistics, including: - - Version number - - Uptime, measured in days - - Number of connections - - Current memory usage, measured in MB - - Peak memory usage, measured in MB - -### Logs - -Since GitLab 13.0, **Log** view has been removed from the Admin Area dashboard since the logging does not work in multi-node setups and could cause confusion for administrators by displaying partial information. - -For multi-node systems we recommend ingesting the logs into services like Elasticsearch and Splunk. - -| Log file | Contents | -|:------------------------|:---------| -| `application_json.log` | GitLab user activity | -| `git_json.log` | Failed GitLab interaction with Git repositories | -| `production.log` | Requests received from Puma, and the actions taken to serve those requests | -| `sidekiq.log` | Background jobs | -| `repocheck.log` | Repository activity | -| `integrations_json.log` | Activity between GitLab and integrated systems | -| `kubernetes.log` | Kubernetes activity | - -The contents of these log files can be useful when troubleshooting a problem. - -For details of these log files and their contents, see [Log system](../../administration/logs/index.md). - -The content of each log file is listed in chronological order. To minimize performance issues, a maximum 2000 lines of each log file are shown. - -### Audit Events **(PREMIUM SELF)** - -The **Audit Events** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change. +<!-- This redirect file can be deleted after <2023-10-11>. --> +<!-- 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/admin_area/labels.md b/doc/user/admin_area/labels.md index 16721d144e5..724c9885801 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -1,28 +1,11 @@ --- -stage: Plan -group: Project Management -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 +redirect_to: '../../administration/labels.md' +remove_date: '2023-10-05' --- -# Labels administration **(FREE SELF)** +This document was moved to [another location](../../administration/labels.md). -To manage labels for the GitLab instance, select **Labels** (**{labels}**) from the Admin Area sidebar. For more details on how to manage labels, see [Labels](../project/labels.md). - -Labels created in the Admin Area are automatically added to new projects. -They are not available to new groups. -Updating or adding labels in the Admin Area does not modify labels in existing projects. - - - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-05>. --> +<!-- 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/admin_area/license.md b/doc/user/admin_area/license.md index be6478de2a0..636f5cb2831 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -1,83 +1,11 @@ --- -stage: Fulfillment -group: Provision -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: '../../administration/license.md' +remove_date: '2023-10-11' --- -# Activate GitLab Enterprise Edition (EE) **(PREMIUM SELF)** +This document was moved to [another location](../../administration/license.md). -When you install a new GitLab instance without a license, only Free features -are enabled. To enable more features in GitLab Enterprise Edition (EE), activate -your instance with an activation code. - -## Activate GitLab EE - -In GitLab Enterprise Edition 14.1 and later, you need an activation code to activate -your instance. - -Prerequisite: - -- You must [purchase a subscription](https://about.gitlab.com/pricing/). -- You must be running GitLab Enterprise Edition (EE). -- You must have GitLab 14.1 or later. -- Your instance must be connected to the internet. - -To activate your instance with an activation code: - -1. Copy the activation code, a 24-character alphanumeric string, from either: - - Your subscription confirmation email. - - The [Customers Portal](https://customers.gitlab.com/customers/sign_in), on the **Manage Purchases** page. -1. Sign in to your GitLab self-managed instance. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Subscription**. -1. Paste the activation code in **Activation code**. -1. Read and accept the terms of service. -1. Select **Activate**. - -The subscription is activated. - -If you have an offline environment, -[activate GitLab EE with a license file or key](license_file.md) instead. - -If you have questions or need assistance activating your instance, -[contact GitLab Support](https://about.gitlab.com/support/#contact-support). - -When [the license expires](license_file.md#what-happens-when-your-license-expires), -some functionality is locked. - -## Verify your GitLab edition - -To verify the edition, sign in to GitLab and select -**Help** (**{question-o}**) > **Help**. The GitLab edition and version are listed -at the top of the page. - -If you are running GitLab Community Edition, you can upgrade your installation to GitLab -EE. For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). -If you have questions or need assistance upgrading from GitLab Community Edition (CE) to EE, -[contact GitLab Support](https://about.gitlab.com/support/#contact-support). - -## Troubleshooting - -### Cannot activate instance due to connectivity error - -This error occurs when you use an activation code to activate your instance, but your instance is unable to connect to the GitLab servers. - -You may have connectivity issues due to the following reasons: - -- **You have an offline environment**: - - Configure your setup to allow connection to GitLab servers. If connection to GitLab servers is not possible, contact your Sales Representative to request a license key. You can also contact [GitLab support](https://about.gitlab.com/support/#contact-support) if you need help finding your Sales Representative. -- **Customers Portal is not operational**: - - To check for performance or service disruptions, check the Customers Portal [status](https://status.gitlab.com/). -- **Firewall settings**: - - Check if your GitLab instance has an encrypted connection to `customers.gitlab.com` (with IP addresses 172.64.146.11 and 104.18.41.245) on port 443: - - ```shell - curl --verbose "https://customers.gitlab.com/" - ``` - - - If the curl command returns a failure, either: - - [Configure a proxy](https://docs.gitlab.com/omnibus/settings/environment-variables.html) in `gitlab.rb` to point to your server. - - Contact your network administrator to make changes to the proxy. - - If an SSL inspection appliance is used, you must add the appliance's root CA certificate to `/etc/gitlab/trusted-certs` on the server, then run `gitlab-ctl reconfigure`. -
\ No newline at end of file +<!-- This redirect file can be deleted after <2023-10-11>. --> +<!-- 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/admin_area/license_file.md b/doc/user/admin_area/license_file.md index 12e908b4fe0..4835d656cfa 100644 --- a/doc/user/admin_area/license_file.md +++ b/doc/user/admin_area/license_file.md @@ -1,252 +1,11 @@ --- -stage: Fulfillment -group: Provision -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: '../../administration/license_file.md' +remove_date: '2023-10-11' --- -<!-- To promote the workflow described in license.md, this page is not included in global left nav. --> +This document was moved to [another location](../../administration/license_file.md). -# Activate GitLab EE with a license file or key - -If you receive a license file from GitLab (for example, for a trial), you can -upload it to your instance or add it during installation. The license file is -a base64-encoded ASCII text file with a `.gitlab-license` extension. - -The first time you sign in to your GitLab instance, a note with a -link to the **Add license** page should be displayed. - -Otherwise, to add your license: - -1. Sign in to GitLab as an administrator. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. In the **Add License** area, add a license by either uploading the file or entering the key. -1. Select the **Terms of Service** checkbox. -1. Select **Add license**. - -NOTE: -In GitLab 14.7.x to 14.9.x, you can add the license file with the UI. -In GitLab 14.1.x to 14.7, if you have already activated your subscription with an activation code, you cannot access **Add License** from the Admin Area. You must access **Add License** directly from the URL, `<YourGitLabURL>/admin/license/new`. - -## Activate subscription during installation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114572) in GitLab 16.0. - -To activate your subscription during installation, set the `GITLAB_ACTIVATION_CODE` environment variable with the activation code: - -```shell -export GITLAB_ACTIVATION_CODE=your_activation_code -``` - -## Add license file during installation - -If you have a license, you can also import it when you install GitLab. - -- For self-compiled installations: - - Place the `Gitlab.gitlab-license` file in the `config/` directory. - - To specify a custom location and filename for the license, set the - `GITLAB_LICENSE_FILE` environment variable with the path to the file: - - ```shell - export GITLAB_LICENSE_FILE="/path/to/license/file" - ``` - -- For Linux package installations: - - Place the `Gitlab.gitlab-license` file in the `/etc/gitlab/` directory. - - To specify a custom location and filename for the license, add this entry to `gitlab.rb`: - - ```ruby - gitlab_rails['initial_license_file'] = "/path/to/license/file" - ``` - -WARNING: -These methods only add a license at the time of installation. To renew or upgrade -a license, add the license in the **Admin Area** in the web user interface. - -## Submit license usage data - -If you use a license file or key to activate your instance in an offline environment, you must submit your license -usage data monthly. -To submit the data, [export your license usage](../../subscriptions/self_managed/index.md#export-your-license-usage) -and send it by email to the renewals service, `renewals-service@customers.gitlab.com`. - -If you don't submit your data each month after your subscription start date, an email is sent to the address -associated with your subscription and a banner displays to remind you to submit your data. The banner displays -in the **Admin Area** on the **Dashboard** and on the **Subscription** pages. You can only dismiss it until the -following month after you submit your license usage data. - -## What happens when your license expires - -Fifteen days before the license expires, a notification banner with the upcoming expiration -date displays to GitLab administrators. - -When your license expires, GitLab locks features, like Git pushes -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-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. - -To go back to Free features, [delete all expired licenses](#remove-a-license). - -## Remove a license - -To remove a license from a self-managed instance: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Subscription**. -1. Select **Remove license**. - -Repeat these steps to remove all licenses, including those applied in the past. - -## View license details and history - -To view your license details: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Subscription**. - -You can add and view more than one license, but only the latest license in -the current date range is the active license. - -When you add a future-dated license, it doesn't take effect until its applicable date. -You can view all active subscriptions in the **Subscription history** table. - -You can also [export](../../subscriptions/self_managed/index.md) your license usage information to a CSV file. - -NOTE: -In GitLab 13.6 and earlier, a banner about an expiring license may continue to display -when you add a new license. This happens when the start date of the new license -is in the future and the expiring one is still active. -The banner disappears after the new license becomes active. - -## Troubleshooting - -### No Subscription area in the Admin Area - -You cannot add your license because there is no **Subscription** area. -This issue might occur if: - -- You're running GitLab Community Edition. Before you add your license, you - must [upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition). -- You're using GitLab.com. You cannot add a self-managed license to GitLab.com. - To use paid features on GitLab.com, [purchase a separate subscription](../../subscriptions/gitlab_com/index.md). - -### Users exceed license limit upon renewal - -GitLab displays a message prompting you to purchase -additional users. This issue occurs if you add a license that does not have enough -users to cover the number of users in your instance. - -To fix this issue, purchase additional seats to cover those users. -For more information, read the [licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). - -In GitLab 14.2 and later, for instances that use a license file, the following -rules apply: - -- If the users over license are less than or equal to 10% of the users in the license - file, the license is applied and you pay the overage in the next renewal. -- If the users over license are more than 10% of the users in the license file, - you cannot apply the license without purchasing more users. - -For example, if you purchase a license for 100 users, you can have 110 users when you add -your license. However, if you have 111 users, you must purchase more users before you can add -the license. - -### `Start GitLab Ultimate trial` still displays after adding license - -To fix this issue, restart [Puma or your entire GitLab instance](../../administration/restart_gitlab.md). - -### License commands in the rails console - -The following commands can be run in the [rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). - -WARNING: -Any command that changes data directly could be damaging if not run correctly, or under the right conditions. -We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. - -#### See current license information - -```ruby -# License information (name, company, email address) -License.current.licensee - -# Plan: -License.current.plan - -# Uploaded: -License.current.created_at - -# Started: -License.current.starts_at - -# Expires at: -License.current.expires_at - -# Is this a trial license? -License.current.trial? - -# License ID for lookup on CustomersDot -License.current.license_id - -# License data in Base64-encoded ASCII format -License.current.data - -# Confirm the current billable seat count excluding guest users. This is useful for customers who use an Ultimate subscription tier where Guest seats are not counted. -User.active.without_bots.excluding_guests.count - -``` - -#### Interaction with licenses that start in the future - -```ruby -# Future license data follows the same format as current license data it just uses a different modifier for the License prefix -License.future_dated -``` - -#### Check if a project feature is available on the instance - -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) -``` - -#### Check if a project feature is available in a project - -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>') -p.feature_available?(:jira_dev_panel_integration) -``` - -#### Add a license through the console - -```ruby -key = "<key>" -license = License.new(data: key) -license.save -License.current # check to make sure it applied -``` - -This is needed for example in a known edge-case with -[expired license and multiple LDAP servers](../../administration/auth/ldap/ldap-troubleshooting.md#expired-license-causes-errors-with-multiple-ldap-servers). - -#### Remove licenses - -To clean up the [License History table](../../user/admin_area/license_file.md#view-license-details-and-history): - -```ruby -TYPE = :trial? -# or :expired? - -License.select(&TYPE).each(&:destroy!) - -# or even License.all.each(&:destroy!) -``` +<!-- This redirect file can be deleted after <2023-10-11>. --> +<!-- 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/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 58f54c399df..de079d08d3a 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -1,43 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +redirect_to: '../../administration/merge_requests_approvals.md' +remove_date: '2023-10-12' --- -# Merge request approvals **(PREMIUM SELF)** +This document was moved to [another location](../../administration/merge_requests_approvals.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39060) in GitLab 12.8. - -Merge request approval rules prevent users from overriding certain settings on the project level. -When enabled at the instance level, these settings [cascade](../project/merge_requests/approvals/settings.md#settings-cascading) -and can no longer be changed: - -- In projects. -- In groups. Cascading to groups was [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) - in GitLab 14.5. - -To enable merge request approval settings for an instance: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Push Rules**. -1. Expand **Merge request approvals**. -1. Choose the required options. -1. Select **Save changes**. - -## Available rules - -Merge request approval settings that can be set at an instance level are: - -- **Prevent approval by author**. Prevents project maintainers from allowing request authors to - merge their own merge requests. -- **Prevent approvals by users who add commits**. Prevents project maintainers from allowing users - to approve merge requests if they have submitted any commits to the source branch. -- **Prevent editing approval rules in projects and merge requests**. Prevents users from modifying - the approvers list in project settings or in individual merge requests. - -See also the following, which are affected by instance-level rules: - -- [Project merge request approval rules](../project/merge_requests/approvals/index.md). -- [Group merge request approval settings](../group/manage.md#group-merge-request-approval-settings) available in GitLab 13.9 and later. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index ee6d360ac1d..3390c4791be 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -1,360 +1,11 @@ --- -stage: Manage -group: Authentication and Authorization -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: howto +redirect_to: '../../administration/moderate_users.md' +remove_date: '2023-10-12' --- -# Moderate users (administration) **(FREE SELF)** +This document was moved to [another location](../../administration/moderate_users.md). -This is the administration documentation. For information about moderating users at the group level, see the [group-level documentation](../group/moderate_users.md). - -GitLab administrators can moderate user access by approving, blocking, banning, or deactivating -users. - -## Users pending approval - -A user in _pending approval_ state requires action by an administrator. A user sign up can be in a -pending approval state because an administrator has enabled any of the following options: - -- [Require administrator approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting. -- [User cap](settings/sign_up_restrictions.md#user-cap). -- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#configure-common-settings) -- [Block auto-created users (LDAP)](../../administration/auth/ldap/index.md#basic-configuration-settings) - -When a user registers for an account while this setting is enabled: - -- The user is placed in a **Pending approval** state. -- The user sees a message telling them their account is awaiting approval by an administrator. - -A user pending approval: - -- Is functionally identical to a [blocked](#block-a-user) user. -- Cannot sign in. -- Cannot access Git repositories or the GitLab API. -- Does not receive any notifications from GitLab. -- Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). - -An administrator must [approve their sign up](#approve-or-reject-a-user-sign-up) to allow them to -sign in. - -### View user sign ups pending approval - -To view user sign ups pending approval: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Pending approval** tab. - -### Approve or reject a user sign up - -A user sign up pending approval can be approved or rejected from the Admin Area. - -To approve or reject a user sign up: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Pending approval** tab. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Approve** or **Reject**. - -Approving a user: - -- Activates their account. -- Changes the user's state to active. -- Consumes a subscription [seat](../../subscriptions/self_managed/index.md#billable-users). - -## Block and unblock users - -GitLab administrators can block and unblock users. - -### Block a user - -To completely prevent access of a user to the GitLab instance, -administrators can choose to block the user. - -Users can be blocked [via an abuse report](review_abuse_reports.md#blocking-users), -by removing them in LDAP, or directly from the Admin Area. To do this: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Block**. - -A blocked user: - -- Cannot sign in. -- Cannot access Git repositories or the API. -- Does not receive any notifications from GitLab. -- 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 blocked user are left intact. - -NOTE: -Users can also be blocked using the [GitLab API](../../api/users.md#block-user). - -### Unblock a user - -A blocked user can be unblocked from the Admin Area. To do this: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Blocked** tab. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Unblock**. - -The user's state is set to active and they consume a -[seat](../../subscriptions/self_managed/index.md#billable-users). - -NOTE: -Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). - -The unblock option may be unavailable for LDAP users. To enable the unblock option, -the LDAP identity first needs to be deleted: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Blocked** tab. -1. Select a user. -1. Select the **Identities** tab. -1. Find the LDAP provider and select **Delete**. - -## Activate and deactivate users - -GitLab administrators can deactivate and activate users. - -### Deactivate a user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. - -To temporarily prevent access by a GitLab user that has no recent activity, -administrators can choose to deactivate the user. - -Deactivating a user is functionally identical to [blocking a user](#block-and-unblock-users), -with the following differences: - -- It does not prohibit the user from logging back in via the UI. -- Once a deactivated user logs back into the GitLab UI, their account is set to active. - -A deactivated user: - -- Cannot access Git repositories or the API. -- Does not receive any notifications from GitLab. -- 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. - -NOTE: -Users are notified about account deactivation if -[user deactivation emails](settings/email.md#user-deactivation-emails) are enabled. - -A user can be deactivated from the Admin Area. To do this: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Deactivate**. - -For the deactivation option to be visible to an administrator, the user: - -- Must have a state of active. -- Must be [dormant](#automatically-deactivate-dormant-users). - -NOTE: -Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). - -### Automatically deactivate dormant users - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320875) in GitLab 14.0. -> - Customizable time period [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336747) in GitLab 15.4 -> - The lower limit for inactive period set to 90 days [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100793) in GitLab 15.5 - -Administrators can enable automatic deactivation of users who either: - -- Were created more than a week ago and have not signed in. -- Have no activity for a specified period of time (default and minimum is 90 days). - -To do this: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Account and limit** section. -1. Under **Dormant users**, check **Deactivate dormant users after a period of inactivity**. -1. Under **Days of inactivity before deactivation**, enter the number of days before deactivation. Minimum value is 90 days. -1. Select **Save changes**. - -When this feature is enabled, GitLab runs a job once a day to deactivate the dormant users. - -A maximum of 100,000 users can be deactivated per day. - -### Activate a user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. - -A deactivated user can be activated from the Admin Area. - -To do this: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Deactivated** tab. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Activate**. - -The user's state is set to active and they consume a -[seat](../../subscriptions/self_managed/index.md#billable-users). - -NOTE: -A deactivated user can also activate their account themselves by logging back in via the UI. -Users can also be activated using the [GitLab API](../../api/users.md#activate-user). - -## Ban and unban users - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ban_user_feature_flag`. Disabled by default. -> - Ban and unban users [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.8. Feature flag `ban_user_feature_flag` removed. -> - Hiding merge requests of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107836) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `hide_merge_requests_from_banned_users`. Disabled by default. -> - Hiding comments of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112973) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `hidden_notes`. Disabled by default. - -GitLab administrators can ban and unban users. Banned users are blocked, and their issues, merge requests, and comments are hidden. - -### Ban a user - -To block a user and hide their contributions, administrators can ban the user. - -Users can be banned using the Admin Area. To do this: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Ban user**. - -The banned user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). - -### Unban a user - -A banned user can be unbanned using the Admin Area. To do this: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Banned** tab. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Unban user**. - -The user's state is set to active and they consume a -[seat](../../subscriptions/self_managed/index.md#billable-users). - -### Delete a user - -Use the Admin Area to delete users. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Banned** tab. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Delete user**. -1. Type the username. -1. Select **Delete user**. - -NOTE: -You can only delete a user if there are inherited or direct owners of a group. You cannot delete a user if they are the only group owner. - -You can also delete a user and their contributions, such as merge requests, issues, and groups of which they are the only group owner. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Banned** tab. -1. Optional. Select a user. -1. Select the **{settings}** **User administration** dropdown list. -1. Select **Delete user and contributions**. -1. Type the username. -1. Select **Delete user and contributions**. - -NOTE: -Before 15.1, additionally groups of which deleted user were the only owner among direct members were deleted. - -## Troubleshooting - -When moderating users, you may need to perform bulk actions on them based on certain conditions. The following rails console scripts show some examples of this. You may [start a rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) and use scripts similar to the following: - -### Deactivate users that have no recent activity - -Administrators can deactivate users that have no recent activity. - -WARNING: -Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. - -```ruby -days_inactive = 90 -inactive_users = User.active.where("last_activity_on <= ?", days_inactive.days.ago) - -inactive_users.each do |user| - puts "user '#{user.username}': #{user.last_activity_on}" - user.deactivate! -end -``` - -### Block users that have no recent activity - -Administrators can block users that have no recent activity. - -WARNING: -Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. - -```ruby -days_inactive = 90 -inactive_users = User.active.where("last_activity_on <= ?", days_inactive.days.ago) - -inactive_users.each do |user| - puts "user '#{user.username}': #{user.last_activity_on}" - user.block! -end -``` - -### Block or delete users that have no projects or groups - -Administrators can block or delete users that have no projects or groups. - -WARNING: -Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. - -```ruby -users = User.where('id NOT IN (select distinct(user_id) from project_authorizations)') - -# How many users are removed? -users.count - -# If that count looks sane: - -# You can either block the users: -users.each { |user| user.blocked? ? nil : user.block! } - -# Or you can delete them: - # need 'current user' (your user) for auditing purposes -current_user = User.find_by(username: '<your username>') - -users.each do |user| - DeleteUserWorker.perform_async(current_user.id, user.id) -end -``` +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index f3b09c61532..bda326d4daf 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,146 +1,11 @@ --- -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 +redirect_to: '../../../administration/monitoring/health_check.md' +remove_date: '2023-10-12' --- -# Health Check **(FREE SELF)** +This document was moved to [another location](../../../administration/monitoring/health_check.md). -GitLab provides liveness and readiness probes to indicate service health and -reachability to required services. These probes report on the status of the -database connection, Redis connection, and access to the file system. These -endpoints [can be provided to schedulers like Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) to hold -traffic until the system is ready or restart the container as needed. - -## IP allowlist - -To access monitoring resources, the requesting client IP needs to be included in the allowlist. -For details, see [how to add IPs to the allowlist for the monitoring endpoints](../../../administration/monitoring/ip_allowlist.md). - -## Using the endpoints locally - -With default allowlist settings, the probes can be accessed from localhost using the following URLs: - -```plaintext -GET http://localhost/-/health -``` - -```plaintext -GET http://localhost/-/readiness -``` - -```plaintext -GET http://localhost/-/liveness -``` - -## Health - -Checks whether the application server is running. -It does not verify the database or other services -are running. This endpoint circumvents Rails Controllers -and is implemented as additional middleware `BasicHealthCheck` -very early into the request processing lifecycle. - -```plaintext -GET /-/health -``` - -Example request: - -```shell -curl "https://gitlab.example.com/-/health" -``` - -Example response: - -```plaintext -GitLab OK -``` - -## Readiness - -The readiness probe checks whether the GitLab instance is ready -to accept traffic via Rails Controllers. The check by default -does validate only instance-checks. - -If the `all=1` parameter is specified, the check also validates -the dependent services (Database, Redis, Gitaly etc.) -and gives a status for each. - -```plaintext -GET /-/readiness -GET /-/readiness?all=1 -``` - -Example request: - -```shell -curl "https://gitlab.example.com/-/readiness" -``` - -Example response: - -```json -{ - "master_check":[{ - "status":"failed", - "message": "unexpected Master check result: false" - }], - ... -} -``` - -On failure, the endpoint returns a `503` HTTP status code. - -This check is being exempt from Rack Attack. - -## Liveness - -WARNING: -In GitLab [12.4](https://about.gitlab.com/upcoming-releases/) -the response body of the Liveness check was changed -to match the example below. - -Checks whether the application server is running. -This probe is used to know if Rails Controllers -are not deadlocked due to a multi-threading. - -```plaintext -GET /-/liveness -``` - -Example request: - -```shell -curl "https://gitlab.example.com/-/liveness" -``` - -Example response: - -On success, the endpoint returns a `200` HTTP status code, and a response like below. - -```json -{ - "status": "ok" -} -``` - -On failure, the endpoint returns a `503` HTTP status code. - -This check is being exempt from Rack Attack. - -## Sidekiq - -Learn how to configure the [Sidekiq health checks](../../../administration/sidekiq/sidekiq_health_check.md). - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md index 38aaeb8eb55..0e607b03b82 100644 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ b/doc/user/admin_area/reporting/git_abuse_rate_limit.md @@ -1,49 +1,11 @@ --- -stage: Anti-Abuse -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 +redirect_to: '../../../administration/reporting/git_abuse_rate_limit.md' +remove_date: '2023-10-12' --- -# Git abuse rate limit (administration) **(ULTIMATE SELF)** +This document was moved to [another location](../../../administration/reporting/git_abuse_rate_limit.md). -> - [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. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/394996) in GitLab 15.11. Feature flag `git_abuse_rate_limit_feature_flag` removed. - -This is the administration documentation. For information about Git abuse rate limiting at the group level, see the [group-level documentation](../../group/reporting/git_abuse_rate_limit.md). - -Git abuse rate limiting is a feature to automatically [ban users](../moderate_users.md#ban-and-unban-users) who download, clone, or fork more than a specified number of repositories in any project in the instance in a given time frame. Banned users cannot sign in to the instance and cannot access any non-public group via HTTP or SSH. The rate limit also applies to users who authenticate with a [personal](../../../user/profile/personal_access_tokens.md) or [group access token](../../../user/group/settings/group_access_tokens.md). - -Git abuse rate limiting does not apply to instance administrators, [deploy tokens](../../../user/project/deploy_tokens/index.md), or [deploy keys](../../../user/project/deploy_keys/index.md). - -How GitLab determines a user's rate limit is under development. -GitLab team members can view more information in this confidential epic: -`https://gitlab.com/groups/gitlab-org/modelops/anti-abuse/-/epics/14`. - -## Configure Git abuse rate limiting - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Reporting**. -1. Expand **Git abuse rate limit**. -1. Update the Git abuse rate limit settings: - 1. Enter a number in the **Number of repositories** field, greater than or equal to `0` and less than or equal to `10,000`. This number specifies the maximum amount of unique repositories a user can download in the specified time period before they're banned. When set to `0`, Git abuse rate limiting is disabled. - 1. Enter a number in the **Reporting time period (seconds)** field, greater than or equal to `0` and less than or equal to `86,400` (10 days). This number specifies the time in seconds a user can download the maximum amount of repositories before they're banned. When set to `0`, Git abuse rate limiting is disabled. - 1. Optional. Exclude up to `100` users by adding them to the **Excluded users** field. Excluded users are not automatically banned. - 1. Add up to `100` users to the **Send notifications to** field. You must select at least one user. All application administrators are selected by default. - 1. Optional. Turn on the **Automatically ban users from this namespace when they exceed the specified limits** toggle to enable automatic banning. -1. Select **Save changes**. - -## Automatic ban notifications - -If automatic banning is disabled, a user is not banned automatically when they exceed the limit. However, notifications are still sent to the users listed under **Send notifications to**. You can use this setup to determine the correct values of the rate limit settings before enabling automatic banning. - -If automatic banning is enabled, an email notification is sent when a user is about to be banned, and the user is automatically banned from the GitLab instance. - -## Unban a user - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Banned** tab and search for the account you want to unban. -1. From the **User administration** dropdown list select **Unban user**. -1. On the confirmation dialog, select **Unban user**. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/reporting/ip_addr_restrictions.md b/doc/user/admin_area/reporting/ip_addr_restrictions.md index 5b749c62c30..85783640b28 100644 --- a/doc/user/admin_area/reporting/ip_addr_restrictions.md +++ b/doc/user/admin_area/reporting/ip_addr_restrictions.md @@ -1,33 +1,11 @@ --- -stage: Anti-Abuse -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 +redirect_to: '../../../administration/reporting/ip_addr_restrictions.md' +remove_date: '2023-10-13' --- -# IP address restrictions **(FREE SELF)** +This document was moved to [another location](../../../administration/reporting/ip_addr_restrictions.md). -IP address restrictions help prevent malicious users hiding their activities behind multiple IP addresses. - -GitLab maintains a list of the unique IP addresses used by a user to make requests over a specified period. When the -specified limit is reached, any requests made by the user from a new IP address are rejected with a `403 Forbidden` error. - -IP addresses are cleared from the list when no further requests have been made by the user from the IP address in the specified time period. - -NOTE: -When a runner runs a CI/CD job as a particular user, the runner IP address is also stored against the user's list of -unique IP addresses. Therefore, the IP addresses per user limit should take into account the number of configured active runners. - -## Configure IP address restrictions - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Reporting**. -1. Expand **Spam and Anti-bot Protection**. -1. Update the IP address restrictions settings: - 1. Select the **Limit sign in from multiple IP addresses** checkbox to enable IP address restrictions. - 1. Enter a number in the **IP addresses per user** field, greater than or equal to `1`. This number specifies the - maximum number of unique IP addresses a user can access GitLab from in the specified time period before requests - from a new IP address are rejected. - 1. Enter a number in the **IP address expiration time** field, greater than or equal to `0`. This number specifies the - time in seconds an IP address counts towards the limit for a user, taken from the time the last request was made. -1. Select **Save changes**. +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md index e2508476c80..043481b6255 100644 --- a/doc/user/admin_area/reporting/spamcheck.md +++ b/doc/user/admin_area/reporting/spamcheck.md @@ -1,69 +1,11 @@ --- -stage: Systems -group: Distribution -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: '../../../administration/reporting/spamcheck.md' +remove_date: '2023-10-13' --- -# Spamcheck anti-spam service **(FREE SELF)** +This document was moved to [another location](../../../administration/reporting/spamcheck.md). -> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6259) in GitLab 14.8. - -WARNING: -Spamcheck is available to all tiers, but only on instances using GitLab Enterprise Edition (EE). For [licensing reasons](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6259#note_726605397), it is not included in the GitLab Community Edition (CE) package. You can [migrate from CE to EE](../../../update/package/convert_to_ee.md). - -[Spamcheck](https://gitlab.com/gitlab-org/spamcheck) is an anti-spam engine -developed by GitLab originally to combat rising amount of spam in GitLab.com, -and later made public to be used in self-managed GitLab instances. - -## Enable Spamcheck - -Spamcheck is only available for package-based installations: - -1. Edit `/etc/gitlab/gitlab.rb` and enable Spamcheck: - - ```ruby - spamcheck['enable'] = true - ``` - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Verify that the new services `spamcheck` and `spam-classifier` are - up and running: - - ```shell - sudo gitlab-ctl status - ``` - -## Configure GitLab to use Spamcheck - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Reporting**. -1. Expand **Spam and Anti-bot Protection**. -1. Update the Spam Check settings: - 1. Check the "Enable Spam Check via external API endpoint" checkbox. - 1. For **URL of the external Spam Check endpoint** use `grpc://localhost:8001`. - 1. Leave **Spam Check API key** blank. -1. Select **Save changes**. - -NOTE: -In single-node instances, Spamcheck runs over `localhost`, and hence is running -in an unauthenticated mode. If on multi-node instances where GitLab runs on one -server and Spamcheck runs on another server listening over a public endpoint, it -is recommended to enforce some sort of authentication using a reverse proxy in -front of the Spamcheck service that can be used along with an API key. One -example would be to use `JWT` authentication for this and specifying a bearer -token as the API key. -[Native authentication for Spamcheck is in the works](https://gitlab.com/gitlab-com/gl-security/engineering-and-research/automation-team/spam/spamcheck/-/issues/171). - -## Running Spamcheck over TLS - -Spamcheck service on its own cannot communicate directly over TLS with GitLab. -However, Spamcheck can be deployed behind a reverse proxy which performs TLS -termination. In such a scenario, GitLab can be made to communicate with -Spamcheck over TLS by specifying `tls://` scheme for the external Spamcheck URL -instead of `grpc://` in the Admin Area settings. +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 5cd63ec964c..0e01025896e 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -1,96 +1,11 @@ --- -stage: Anti-Abuse -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 -type: reference, howto +redirect_to: '../../administration/review_abuse_reports.md' +remove_date: '2023-10-11' --- -# Review abuse reports **(FREE SELF)** +This document was moved to [another location](../../administration/review_abuse_reports.md). -View and resolve abuse reports from GitLab users. - -GitLab administrators can view and [resolve](#resolving-abuse-reports) abuse -reports in the Admin Area. - -## Receive notification of abuse reports by email - -To receive notifications of new abuse reports by email: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Reporting**. -1. Expand the **Abuse reports** section. -1. Provide an email address and select **Save changes**. - -The notification email address can also be set and retrieved -[using the API](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). - -## Reporting abuse - -To find out more about reporting abuse, see -[abuse reports user documentation](../report_abuse.md). - -## Resolving abuse reports - -To access abuse reports: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Abuse Reports**. - -There are 3 ways to resolve an abuse report, with a button for each method: - -- Remove user & report. This: - - [Deletes the reported user](../profile/account/delete_account.md) from the - instance. - - Removes the abuse report from the list. -- [Block user](#blocking-users). -- Remove report. This: - - Removes the abuse report from the list. - - Removes access restrictions for the reported user. - -The following is an example of the **Abuse Reports** page: - - - -### Blocking users - -A blocked user cannot sign in or access any repositories, but all of their data -remains. - -Blocking a user: - -- Leaves them in the abuse report list. -- Changes the **Block user** button to a disabled **Already blocked** button. - -The user is notified with the following message: - -```plaintext -Your account has been blocked. If you believe this is in error, contact a staff member. -``` - -After blocking, you can still either: - -- Remove the user and report if necessary. -- Remove the report. - -The following is an example of a blocked user listed on the **Abuse Reports** -page: - - - -NOTE: -Users can be [blocked](../../api/users.md#block-user) and -[unblocked](../../api/users.md#unblock-user) using the GitLab API. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-11>. --> +<!-- 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/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 293decc438e..2deed61388b 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -1,399 +1,11 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +redirect_to: '../../../administration/settings/account_and_limit_settings.md' +remove_date: '2023-10-12' --- -# Account and limit settings **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/account_and_limit_settings.md). -## Default projects limit - -You can configure the default maximum number of projects new users can create in their -personal namespace. This limit affects only new user accounts created after you change -the setting. This setting is not retroactive for existing users, but you can separately edit -the [project limits for existing users](#projects-limit-for-a-user). - -To configure the maximum number of projects in personal namespaces for new users: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Account and limit**. -1. Increase or decrease that **Default projects limit** value. - -If you set **Default projects limit** to 0, users are not allowed to create projects -in their users personal namespace. However, projects can still be created in a group. - -### Projects limit for a user - -You can edit a specific user, and change the maximum number of projects this user -can create in their personal namespace: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview** > **Users**. -1. From the list of users, select a user. -1. Select **Edit**. -1. Increase or decrease the **Projects limit** value. - -## Max attachment size - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/20061) from 10 MB to 100 MB in GitLab 15.7. - -The maximum file size for attachments in GitLab comments and replies is 100 MB. -To change the maximum attachment size: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Account and limit**. -1. Increase or decrease by changing the value in **Maximum attachment size (MB)**. - -If you choose a size larger than the configured value for the web server, -you may receive errors. Read the [troubleshooting section](#troubleshooting) for more -details. - -For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). - -## Max push size - -You can change the maximum push size for your instance: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Account and limit**. -1. Increase or decrease by changing the value in **Maximum push size (MB)**. - -For GitLab.com push size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). - -NOTE: -When you [add files to a repository](../../project/repository/web_editor.md#create-a-file) -through the web UI, the maximum **attachment** size is the limiting factor, -because the [web server](../../../development/architecture.md#components) -must receive the file before GitLab can generate the commit. -Use [Git LFS](../../../topics/git/lfs/index.md) to add large files to a repository. - -## Max export size - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86124) in GitLab 15.0. - -To modify the maximum file size for exports in GitLab: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**, then expand **Account and limit**. -1. Increase or decrease by changing the value in **Maximum export size (MB)**. - -## Max import size - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. - -To modify the maximum file size for imports in GitLab: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Account and limit**. -1. Increase or decrease by changing the value in **Maximum import size (MB)**. - -This setting applies only to repositories -[imported from a GitLab export file](../../project/settings/import_export.md#import-a-project-and-its-data). - -If you choose a size larger than the configured value for the web server, -you may receive errors. See the [troubleshooting section](#troubleshooting) for more -details. - -For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). - -## Personal access token prefix - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20968) in GitLab 13.7. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5, a default prefix. - -You can specify a prefix for personal access tokens. You might use a prefix -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) and -[group access tokens](../../group/settings/group_access_tokens.md) also inherit this prefix. - -### Set a prefix - -To change the default global prefix: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Account and limit** section. -1. Fill in the **Personal Access Token prefix** field. -1. Select **Save changes**. - -You can also configure the prefix by using the -[settings API](../../../api/settings.md). - -## Repository size limit **(PREMIUM SELF)** - -Repositories in your GitLab instance can grow quickly, especially if you are -using LFS. Their size can grow exponentially, rapidly consuming available storage. -To prevent this from happening, you can set a hard limit for your repositories' size. -This limit can be set globally, per group, or per project, with per project limits -taking the highest priority. - -There are numerous use cases where you might set up a limit for repository size. -For instance, consider the following workflow: - -1. Your team develops apps which require large files to be stored in - the application repository. -1. Although you have enabled [Git LFS](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) - to your project, your storage has grown significantly. -1. Before you exceed available storage, you set up a limit of 10 GB - per repository. - -NOTE: -For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). - -### How it works - -Only a GitLab administrator can set those limits. Setting the limit to `0` means -there are no restrictions. - -These settings can be found in: - -- Each project's settings: - 1. From the Project's homepage, navigate to **Settings > General**. - 1. Fill in the **Repository size limit (MB)** field in the **Naming, topics, avatar** section. - 1. Select **Save changes**. -- Each group's settings: - 1. From the Group's homepage, navigate to **Settings > General**. - 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. - 1. Select **Save changes**. -- GitLab global settings: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **Admin Area**. - 1. Select **Settings > General**. - 1. Expand the **Account and limit** section. - 1. Fill in the **Size limit per repository (MB)** field. - 1. Select **Save changes**. - -The first push of a new project, including LFS objects, is checked for size. -If the sum of their sizes exceeds the maximum allowed repository size, the push -is rejected. - -NOTE: -The repository size limit includes repository files and LFS, but does not include artifacts, uploads, -wiki, packages, or snippets. The repository size limit applies to both private and public projects. - -For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). - -## Session duration - -### Customize the default session duration - -You can change how long users can remain signed in without activity. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Account and limit**. The set duration is in **Session duration (minutes)**. - -If [Remember me](#turn-remember-me-on-or-off) is enabled, users' sessions can remain active for an indefinite period of time. - -For details, see [cookies used for sign-in](../../profile/index.md#cookies-used-for-sign-in). - -### Turn **Remember me** on or off - -> Ability to turn the **Remember me** setting on and off [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369133) in GitLab 16.0. - -Users can select the **Remember me** checkbox on sign-in, and their session will remain active for an indefinite period of time when accessed from that specific browser. You can turn off this setting if you need sessions to expire for security or compliance purposes. Turning off this setting will ensure users' sessions expire after the number of minutes of inactivity set when you [customize your session duration](#customize-the-default-session-duration). - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Account and limit**. -1. Select or clear the **Remember me** checkbox to turn this setting on or off. - -### Customize session duration for Git Operations when 2FA is enabled **(PREMIUM SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296669) in GitLab 13.9. -> - It's deployed behind a 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 `two_factor_for_cli`. On GitLab.com, this feature is not available. This feature is not ready for production use. This feature flag also affects [2FA for Git over SSH operations](../../../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations). - -GitLab administrators can choose to customize the session duration (in minutes) for Git operations when 2FA is enabled. The default is 15 and this can be set to a value between 1 and 10080. - -To set a limit on how long these sessions are valid: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Account and limit** section. -1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. -1. Select **Save changes**. - -## Limit the lifetime of SSH keys **(ULTIMATE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `ff_limit_ssh_key_lifetime`. Disabled by default. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/346753) in GitLab 14.6. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.7. [Feature flag `ff_limit_ssh_key_lifetime`](https://gitlab.com/gitlab-org/gitlab/-/issues/347408) removed. - -Users can optionally specify a lifetime for -[SSH keys](../../ssh.md). -This lifetime is not a requirement, and can be set to any arbitrary number of days. - -SSH keys are user credentials to access GitLab. -However, organizations with security requirements may want to enforce more protection by -requiring the regular rotation of these keys. - -### Set a lifetime - -Only a GitLab administrator can set a lifetime. Leaving it empty means -there are no restrictions. - -To set a lifetime on how long SSH keys are valid: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Account and limit** section. -1. Fill in the **Maximum allowable lifetime for SSH keys (days)** field. -1. Select **Save changes**. - -Once a lifetime for SSH keys is set, GitLab: - -- Requires users to set an expiration date that is no later than the allowed lifetime on new - SSH keys. -- Applies the lifetime restriction to existing SSH keys. Keys with no expiry or a lifetime - greater than the maximum immediately become invalid. - -NOTE: -When a user's SSH key becomes invalid they can delete and re-add the same key again. - -## Limit the lifetime of access tokens **(ULTIMATE SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab 12.6. - -Users can optionally specify a lifetime for -access tokens, this includes [personal](../../profile/personal_access_tokens.md), -[group](../../group/settings/group_access_tokens.md), and [project](../../project/settings/project_access_tokens.md) access tokens. -This lifetime is not a requirement, and can be set to any arbitrary number of days. - -Access tokens are the only tokens needed for programmatic access to GitLab. -However, organizations with security requirements may want to enforce more protection by -requiring the regular rotation of these tokens. - -### Set a lifetime - -Only a GitLab administrator can set a lifetime. Leaving it empty means -there are no restrictions. - -To set a lifetime on how long access tokens are valid: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Account and limit** section. -1. Fill in the **Maximum allowable lifetime for access tokens (days)** field. -1. Select **Save changes**. - -Once a lifetime for access tokens is set, GitLab: - -- Applies the lifetime for new personal access tokens, and require users to set an expiration date - and a date no later than the allowed lifetime. -- After three hours, revoke old tokens with no expiration date or with a lifetime longer than the - allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, - or remove it, before revocation takes place. - -## Disable user profile name changes **(PREMIUM SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24605) in GitLab 12.7. - -To maintain integrity of user details in [Audit Events](../../../administration/audit_events.md), GitLab administrators can choose to disable a user's ability to change their profile name. - -To do this: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Account and limit**. -1. Select the **Prevent users from changing their profile name** checkbox. - -NOTE: -When this ability is disabled, GitLab administrators can still use the -[Admin Area](../index.md#administering-users) or the -[API](../../../api/users.md#user-modification) to update usernames. - -## Prevent new users from creating top-level groups - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. - -By default, new users can create top-level groups. GitLab administrators can prevent new users from creating top-level groups: - -- In GitLab 15.5 and later, using either: - - The GitLab UI using the steps in this section. - - The [application setting API](../../../api/settings.md#change-application-settings). -- In GitLab 15.4 and earlier, a [configuration file](../../../administration/user_settings.md#use-configuration-files-to-prevent-new-users-from-creating-top-level-groups). - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. 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 left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Account and limit**. -1. Select the **Make new users' profiles private by default** checkbox. - -## Prevent users from deleting their accounts **(PREMIUM SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26053) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `deleting_account_disabled_for_users`. Enabled by default. - -By default, users can delete their own accounts. GitLab administrators can prevent -users from deleting their own accounts: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Account and limit**. -1. Clear the **Allows users to delete their own accounts** checkbox. - -## Troubleshooting - -### 413 Request Entity Too Large - -When attaching a file to a comment or reply in GitLab displays a `413 Request Entity Too Large` -error, the [max attachment size](#max-attachment-size) -is probably larger than the web server's allowed value. - -To increase the max attachment size to 200 MB in a -[Linux package](https://docs.gitlab.com/omnibus/) install, you may need to -add the line below to `/etc/gitlab/gitlab.rb` before increasing the max attachment size: - -```ruby -nginx['client_max_body_size'] = "200m" -``` - -### This repository has exceeded its size limit - -If you receive intermittent push errors in your [Rails exceptions log](../../../administration/logs/index.md#exceptions_jsonlog), like this: - -```plaintext -Your push has been rejected, because this repository has exceeded its size limit. -``` - -[Housekeeping](../../../administration/housekeeping.md) tasks may be causing your repository size to grow. -To resolve this problem, either of these options helps in the short- to middle-term: - -- Increase the [repository size limit](#repository-size-limit). -- [Reduce the repository size](../../project/repository/reducing_the_repo_size_using_git.md). +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 853a299cdec..72cf369146e 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -1,429 +1,11 @@ --- -stage: Verify -group: Pipeline Execution -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 +redirect_to: '../../../administration/settings/continuous_integration.md' +remove_date: '2023-10-13' --- -# Continuous Integration and Deployment Admin Area settings **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/continuous_integration.md). -The [Admin Area](index.md) has the instance settings for Auto DevOps, runners, and -job artifacts. - -## Auto DevOps - -To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) -for all projects: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**. -1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/requirements.md#auto-devops-base-domain) - which is used for Auto Deploy and Auto Review Apps. -1. Select **Save changes** for the changes to take effect. - -From now on, every existing project and newly created ones that don't have a -`.gitlab-ci.yml` use the Auto DevOps pipelines. - -If you want to disable it for a specific project, you can do so in -[its settings](../../../topics/autodevops/index.md#enable-or-disable-auto-devops). - -## Enable shared runners for new projects - -You can set all new projects to have the instance's shared runners available by default. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand **Continuous Integration and Deployment**. -1. Select the **Enable shared runners for new projects** checkbox. - -Any time a new project is created, the shared runners are available. - -## Shared runners compute quota - -As an administrator you can set either a global or namespace-specific -limit on the number of [units of compute](../../../ci/pipelines/cicd_minutes.md) you can use. - -## Enable a project runner for multiple projects - -If you have already registered a [project runner](../../../ci/runners/runners_scope.md#project-runners) -you can assign that runner to other projects. - -To enable a project runner for more than one project: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. From the left sidebar, select **CI/CD > Runners**. -1. Select the runner you want to edit. -1. In the upper-right corner, select **Edit** (**{pencil}**). -1. Under **Restrict projects for this runner**, search for a project. -1. To the left of the project, select **Enable**. -1. Repeat this process for each additional project. - -## Add a message for shared runners - -To display details about the instance's shared runners in all projects' -runner settings: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand **Continuous Integration and Deployment**. -1. Enter text, including Markdown if you want, in the **Shared runner details** field. For example: - -  - -To view the rendered details: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. -1. Select **Settings > CI/CD**. -1. Expand **Runners**. - - - -## Maximum artifacts size - -The maximum size of the [job artifacts](../../../administration/job_artifacts.md) -can be set at: - -- The instance level. -- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/21688), the project and group level. - -For the setting on GitLab.com, see [Artifacts maximum size](../../gitlab_com/index.md#gitlab-cicd). - -The value is in MB and the default is 100 MB per job. To change it at the: - -- Instance level: - - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **Admin Area**. - 1. On the left sidebar, select **Settings > CI/CD > Continuous Integration and Deployment**. - 1. Change the value of **Maximum artifacts size (MB)**. - 1. Select **Save changes** for the changes to take effect. - -- Group level (this overrides the instance setting): - - 1. Go to the group's **Settings > CI/CD > General Pipelines**. - 1. Change the value of **Maximum artifacts size** (in MB). - 1. Select **Save changes** for the changes to take effect. - -- Project level (this overrides the instance and group settings): - - 1. Go to the project's **Settings > CI/CD > General Pipelines**. - 1. Change the value of **maximum artifacts size** (in MB). - 1. Select **Save changes** for the changes to take effect. - -NOTE: -The setting at all levels is only available to GitLab administrators. - -## Default artifacts expiration - -The default expiration time of the [job artifacts](../../../administration/job_artifacts.md) -can be set in the Admin Area of your GitLab instance. The syntax of duration is -described in [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) -and the default value is `30 days`. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Change the value of default expiration time. -1. Select **Save changes** for the changes to take effect. - -This setting is set per job and can be overridden in -[`.gitlab-ci.yml`](../../../ci/yaml/index.md#artifactsexpire_in). -To disable the expiration, set it to `0`. The default unit is in seconds. - -NOTE: -Any changes to this setting applies to new artifacts only. The expiration time is not -be updated for artifacts created before this setting was changed. -The administrator may need to manually search for and expire previously-created -artifacts, as described in the [troubleshooting documentation](../../../administration/job_artifacts.md#delete-job-artifacts-from-jobs-completed-before-a-specific-date). - -## Keep the latest artifacts for all jobs in the latest successful pipelines - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50889) in GitLab 13.9. - -When enabled (default), the artifacts of the most recent pipeline for each Git ref -([branches and tags](https://git-scm.com/book/en/v2/Git-Internals-Git-References)) -are locked against deletion and kept regardless of the expiry time. - -When disabled, the latest artifacts for any **new** successful or fixed pipelines -are allowed to expire. - -This setting takes precedence over the [project level setting](../../../ci/jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). -If disabled at the instance level, you cannot enable this per-project. - -To disable the setting: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand **Continuous Integration and Deployment**. -1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. -1. Select **Save changes** - -When you disable the feature, the latest artifacts do not immediately expire. -A new pipeline must run before the latest artifacts can expire and be deleted. - -NOTE: -All application settings have a [customizable cache expiry interval](../../../administration/application_settings_cache.md) which can delay the settings affect. - -## Archive jobs - -Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some -of the capabilities of the jobs (metadata stored in the database needed to run the job), -but persisting the traces and artifacts for auditing purposes. - -To set the duration for which the jobs are considered as old and expired: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand the **Continuous Integration and Deployment** section. -1. Set the value of **Archive jobs**. -1. Select **Save changes** for the changes to take effect. - -After that time passes, the jobs are archived in the background and no longer able to be -retried. Make it empty to never expire jobs. It has to be no less than 1 day, -for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. - -For the value set for GitLab.com, see [Scheduled job archiving](../../gitlab_com/index.md#gitlab-cicd). - -## Protect CI/CD variables by default - -To set all new [CI/CD variables](../../../ci/variables/index.md) as -[protected](../../../ci/variables/index.md#protect-a-cicd-variable) by default: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Select **Protect CI/CD variables by default**. - -## Maximum includes - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207270) in GitLab 16.0. - -The maximum number of [includes](../../../ci/yaml/includes.md) per pipeline can be set at the instance level. -The default is `150`. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Change the value of **Maximum includes**. -1. Select **Save changes** for the changes to take effect. - -## Default CI/CD configuration file - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18073) in GitLab 12.5. - -The default CI/CD configuration file and path for new projects can be set in the Admin Area -of your GitLab instance (`.gitlab-ci.yml` if not set): - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Input the new file and path in the **Default CI/CD configuration file** field. -1. Select **Save changes** for the changes to take effect. - -It is also possible to specify a [custom CI/CD configuration file for a specific project](../../../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file). - -## Set CI/CD limits - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352175) in GitLab 14.10. - -You can configure some [CI/CD limits](../../../administration/instance_limits.md#cicd-limits) -from the Admin Area: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand the **Continuous Integration and Deployment** section. -1. In the **CI/CD limits** section, you can set the following limits: - - **Maximum number of jobs in a single pipeline** - - **Total number of jobs in currently active pipelines** - - **Maximum number of active pipelines per project** - - **Maximum number of pipeline subscriptions to and from a project** - - **Maximum number of pipeline schedules** - - **Maximum number of DAG dependencies that a job can have** - - **Maximum number of runners registered per group** - - **Maximum number of runners registered per project** - - **Maximum number of downstream pipelines in a pipeline's hierarchy tree** - -## Enable or disable the pipeline suggestion banner - -By default, a banner displays in merge requests with no pipeline suggesting a -walkthrough on how to add one. - - - -To enable or disable the banner: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Select or clear the **Enable pipeline suggestion banner** checkbox. -1. Select **Save changes**. - -## Required pipeline configuration **(ULTIMATE SELF)** - -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/352316) from GitLab Premium to GitLab Ultimate in 15.0. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389467) in GitLab 15.9. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389467) in GitLab 15.9 -and is planned for removal in 17.0. Use [compliance pipelines](../../group/compliance_frameworks.md#compliance-pipelines) -instead. This change is a breaking change. - -You can set a [CI/CD template](../../../ci/examples/index.md#cicd-templates) -as a required pipeline configuration for all projects on a GitLab instance. You can -use a template from: - -- The default CI/CD templates. -- A custom template stored in an [instance template repository](instance_template_repository.md). - - NOTE: - When you use a configuration defined in an instance template repository, - nested [`include:`](../../../ci/yaml/index.md#include) keywords - (including `include:file`, `include:local`, `include:remote`, and `include:template`) - [do not work](https://gitlab.com/gitlab-org/gitlab/-/issues/35345). - -The project CI/CD configuration merges into the required pipeline configuration when -a pipeline runs. The merged configuration is the same as if the required pipeline configuration -added the project configuration with the [`include` keyword](../../../ci/yaml/index.md#include). -To view a project's full merged configuration, [View full configuration](../../../ci/pipeline_editor/index.md#view-full-configuration) -in the pipeline editor. - -To select a CI/CD template for the required pipeline configuration: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand the **Required pipeline configuration** section. -1. Select a CI/CD template from the dropdown list. -1. Select **Save changes**. - -## Package Registry configuration - -### Maven Forwarding **(PREMIUM SELF)** - -GitLab administrators can disable the forwarding of Maven requests to [Maven Central](https://search.maven.org/). - -To disable forwarding Maven requests: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand the **Package Registry** section. -1. Clear the checkbox **Forward Maven package requests to the Maven Registry if the packages are not found in the GitLab Package Registry**. -1. Select **Save changes**. - -### npm Forwarding **(PREMIUM SELF)** - -GitLab administrators can disable the forwarding of npm requests to [npmjs.com](https://www.npmjs.com/). - -To disable it: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand the **Package Registry** section. -1. Clear the checkbox **Forward npm package requests to the npm Registry if the packages are not found in the GitLab Package Registry**. -1. Select **Save changes**. - -### PyPI Forwarding **(PREMIUM SELF)** - -GitLab administrators can disable the forwarding of PyPI requests to [pypi.org](https://pypi.org/). - -To disable it: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand the **Package Registry** section. -1. Clear the checkbox **Forward PyPI package requests to the PyPI Registry if the packages are not found in the GitLab Package Registry**. -1. Select **Save changes**. - -### Package file size limits - -GitLab administrators can adjust the maximum allowed file size for each package type. - -To set the maximum file size: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand the **Package Registry** section. -1. Find the package type you would like to adjust. -1. Enter the maximum file size, in bytes. -1. Select **Save size limits**. - -## Restrict runner registration by all users in an instance - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22225) in GitLab 14.1. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/368008) in GitLab 15.5. - -GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI. - -When the registration sections are hidden in the UI, members of the project or group must contact administrators to enable runner registration in the group or project. If you plan to prevent registration, ensure users have access to the runners they need to run jobs. - -By default, all members of a project and group are able to register runners. - -To restrict all users in an instance from registering runners: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand **Runners**. -1. In the **Runner registration** section, clear the **Members of the project can register runners** and - **Members of the group can register runners** checkboxes to remove runner registration from the UI. -1. Select **Save changes**. - -NOTE: -After you disable runner registration by members of a project, the registration -token automatically rotates. The token is no longer valid and you must -use the new registration token for the project. - -## Restrict runner registration by all members in a group - -Prerequisites: - -- Runner registration must be enabled for [all users in the instance](#restrict-runner-registration-by-all-users-in-an-instance). - -GitLab administrators can adjust group permissions to restrict runner registration by group members. - -To restrict runner registration by members in a specific group: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Groups** and find your group. -1. Select **Edit**. -1. Clear the **New group runners can be registered** checkbox if you want to disable runner registration by all members in the group. If the setting is read-only, you must enable runner registration for the [instance](#restrict-runner-registration-by-all-users-in-an-instance). -1. Select **Save changes**. - -## Disable runner version management - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114041) in GitLab 15.10. - -By default, GitLab instances periodically fetch official runner version data from GitLab.com to [determine whether the runners need upgrades](../../../ci/runners/configure_runners.md#determine-which-runners-need-to-be-upgraded). - -To disable your instance fetching this data: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > CI/CD**. -1. Expand **Runners**. -1. In the **Runner version management** section, clear the **Fetch GitLab Runner release version data from GitLab.com** checkbox. -1. Select **Save changes**. - -## Troubleshooting - -### 413 Request Entity Too Large - -When build jobs fail with the following error, -increase the [maximum artifacts size](#maximum-artifacts-size). - -```plaintext -Uploading artifacts as "archive" to coordinator... too large archive <job-id> responseStatus=413 Request Entity Too Large status=413" at end of a build job on pipeline when trying to store artifacts to <object-storage>. -``` +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md index e813d8fe2b1..984eeb24bd1 100644 --- a/doc/user/admin_area/settings/deprecated_api_rate_limits.md +++ b/doc/user/admin_area/settings/deprecated_api_rate_limits.md @@ -1,54 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +redirect_to: '../../../administration/settings/deprecated_api_rate_limits.md' +remove_date: '2023-10-13' --- -# Deprecated API rate limits **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/deprecated_api_rate_limits.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68645) in GitLab 14.4. - -Deprecated API endpoints are those which have been replaced with alternative -functionality, but cannot be removed without breaking backward compatibility. -Setting a restrictive rate limit on these endpoints can encourage users to -switch to the alternatives. - -## Deprecated API endpoints - -Not all deprecated API endpoints are included in this rate limit - just those -that might have a performance impact: - -- [`GET /groups/:id`](../../../api/groups.md#details-of-a-group) **without** the `with_projects=0` query parameter. - -## Define Deprecated API rate limits - -Rate limits for deprecated API endpoints are disabled by default. When enabled, they supersede -the general user and IP rate limits for requests to deprecated endpoints. You can keep any general user -and IP rate limits already in place, and increase or decrease the rate limits -for deprecated API endpoints. No other new features are provided by this override. - -Prerequisite: - -- You must have administrator access to the instance. - -To override the general user and IP rate limits for requests to deprecated API endpoints: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Deprecated API Rate Limits**. -1. Select the checkboxes for the types of rate limits you want to enable: - - **Unauthenticated API request rate limit** - - **Authenticated API request rate limit** -1. If you selected **unauthenticated**: - 1. Select the **Maximum unauthenticated API requests per period per IP**. - 1. Select the **Unauthenticated API rate limit period in seconds**. -1. If you selected **authenticated**: - 1. Select the **Maximum authenticated API requests per period per user**. - 1. Select the **Authenticated API rate limit period in seconds**. - -## Related topics - -- [Rate limits](../../../security/rate_limits.md) -- [User and IP rate limits](user_and_ip_rate_limits.md) +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 1caa1728ea4..f90aa7cc865 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -1,125 +1,11 @@ --- -type: reference -stage: Plan -group: Project Management -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: '../../../administration/settings/email.md' +remove_date: '2023-10-14' --- -# Email **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/email.md). -You can customize some of the content in emails sent from your GitLab instance. - -## Custom logo - -The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#navigation-bar). - -## Include author name in email notification email body **(PREMIUM SELF)** - -By default, GitLab overrides the email address in notification emails with the email address -of the issue, merge request, or comment author. Enable this setting to include the author's email -address in the body of the email instead. - -To include the author's email address in the email body: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Email**. -1. Select the **Include author name in email notification email body** checkbox. -1. Select **Save changes**. - -## Enable multipart email **(PREMIUM SELF)** - -GitLab can send email in multipart format (HTML and plain text) or plain text only. - -To enable multipart email: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Email**. -1. Select **Enable multipart email**. -1. Select **Save changes**. - -## Custom hostname for private commit emails **(PREMIUM SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22560) in GitLab 11.5. - -This configuration option sets the email hostname for [private commit emails](../../profile/index.md#use-an-automatically-generated-private-commit-email). - By default it is set to `users.noreply.YOUR_CONFIGURED_HOSTNAME`. - -To change the hostname used in private commit emails: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Email**. -1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field. -1. Select **Save changes**. - -NOTE: -After the hostname is configured, every private commit email using the previous hostname is not -recognized by GitLab. This can directly conflict with certain [Push rules](../../project/repository/push_rules.md) such as -`Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`. - -## Custom additional text **(PREMIUM SELF)** - -You can add additional text at the bottom of any email that GitLab sends. This additional text -can be used for legal, auditing, or compliance reasons, for example. - -To add additional text to emails: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Email**. -1. Enter your text in the **Additional text** field. -1. Select **Save changes**. - -## User deactivation emails - -GitLab sends email notifications to users when their account has been deactivated. - -To disable these notifications: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Email**. -1. Clear the **Enable user deactivation emails** checkbox. -1. Select **Save changes**. - -### Custom additional text in deactivation emails **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355964) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `deactivation_email_additional_text`. Disabled by default. -> - [Enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111882) in GitLab 15.9. - -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 -`deactivation_email_additional_text`. - -You can add additional text at the bottom of the email that GitLab sends to users when their account -is deactivated. This email text is separate from the [custom additional text](#custom-additional-text) -setting. - -To add additional text to deactivation emails: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Email**. -1. Enter your text in the **Additional text for deactivation email** field. -1. Select **Save changes**. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-14>. --> +<!-- 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/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index c15062dd518..02b1ebadc9b 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,144 +1,11 @@ --- -stage: Manage -group: Authentication and Authorization -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: '../../../administration/settings/external_authorization.md' +remove_date: '2023-10-14' --- -# External authorization control **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/external_authorization.md). -> [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) from GitLab Premium to GitLab Free in 11.10. - -In highly controlled environments, it may be necessary for access policy to be -controlled by an external service that permits access based on project -classification and user access. GitLab provides a way to check project -authorization with your own defined service. - -After the external service is configured and enabled, when a project is -accessed, a request is made to the external service with the user information -and project classification label assigned to the project. When the service -replies with a known response, the result is cached for six hours. - -If the external authorization is enabled, GitLab further blocks pages and -functionality that render cross-project data. That includes: - -- Most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge - requests, Assigned issues, To-Do List). -- Under a specific group (Activity, Contribution analytics, Issues, Issue boards, - Labels, Milestones, Merge requests). -- Global and Group search are disabled. - -This is to prevent performing too many requests at once to the external -authorization service. - -Whenever access is granted or denied this is logged in a log file called -`external-policy-access-control.log`. Read more about the logs GitLab keeps in -the [Linux package documentation](https://docs.gitlab.com/omnibus/settings/logs.html). - -When using TLS Authentication with a self signed certificate, the CA certificate -needs to be trusted by the OpenSSL installation. When using GitLab installed -using the Linux package, learn to install a custom CA in the -[Linux package documentation](https://docs.gitlab.com/omnibus/settings/ssl/index.html). -Alternatively, learn where to install custom certificates by using -`openssl version -d`. - -## Configuration - -The external authorization service can be enabled by an administrator: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **External authorization**. -1. Complete the fields. -1. Select **Save changes**. - -### Allow external authorization with deploy tokens and deploy keys - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386656) in GitLab 15.9. -> - Deploy tokens no longer being able to access container or package registries [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387721) in GitLab 16.0. - -You can set your instance to allow external authorization for Git operations with -[deploy tokens](../../project/deploy_tokens/index.md) or [deploy keys](../../project/deploy_keys/index.md). - -Prerequisites: - -- You must be using classification labels without a service URL for external authorization. - -To allow authorization with deploy tokens and keys: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **External authorization**, and: - - Leave the service URL field empty. - - Select **Allow deploy tokens and deploy keys to be used with external authorization**. -1. Select **Save changes**. - -WARNING: -If you enable external authorization, deploy tokens cannot access container or package registries. If you use deploy tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use tokens with container or package registries. - -## How it works - -When GitLab requests access, it sends a JSON POST request to the external -service with this body: - -```json -{ - "user_identifier": "jane@acme.org", - "project_classification_label": "project-label", - "user_ldap_dn": "CN=Jane Doe,CN=admin,DC=acme", - "identities": [ - { "provider": "ldap", "extern_uid": "CN=Jane Doe,CN=admin,DC=acme" }, - { "provider": "bitbucket", "extern_uid": "2435223452345" } - ] -} -``` - -The `user_ldap_dn` is optional and is only sent when the user is signed in -through LDAP. - -`identities` contains the details of all the identities associated with the -user. This is an empty array if there are no identities associated with the -user. - -When the external authorization service responds with a status code 200, the -user is granted access. When the external service responds with a status code -401 or 403, the user is denied access. In any case, the request is cached for -six hours. - -When denying access, a `reason` can be optionally specified in the JSON body: - -```json -{ - "reason": "You are not allowed access to this project." -} -``` - -Any other status code than 200, 401 or 403 also deny access to the user, but the -response isn't cached. - -If the service times out (after 500 ms), a message "External Policy Server did -not respond" is displayed. - -## Classification labels - -You can use your own classification label in the project's -**Settings > General > General project settings** page in the "Classification -label" box. When no classification label is specified on a project, the default -label defined in the [global settings](#configuration) is used. - -On all project pages, in the upper-right corner, the label appears. - - - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-14>. --> +<!-- 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/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md index 9f7a2d13b8e..c87cac2b8ac 100644 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ b/doc/user/admin_area/settings/files_api_rate_limits.md @@ -1,51 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +redirect_to: '../../../administration/settings/files_api_rate_limits.md' +remove_date: '2023-10-14' --- -# Rate limits on Repository files API **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/files_api_rate_limits.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75918) in GitLab 14.6. [Feature flag `files_api_throttling`](https://gitlab.com/gitlab-org/gitlab/-/issues/338903) removed. - -The [Repository files API](../../../api/repository_files.md) enables you to -fetch, create, update, and delete files in your repository. To improve the security -and durability of your web application, you can enforce -[rate limits](../../../security/rate_limits.md) on this API. Any rate limits you -create for the Files API override the [general user and IP rate limits](user_and_ip_rate_limits.md). - -## Define Files API rate limits - -Rate limits for the Files API are disabled by default. When enabled, they supersede -the general user and IP rate limits for requests to the -[Repository files API](../../../api/repository_files.md). You can keep any general user -and IP rate limits already in place, and increase or decrease the rate limits -for the Files API. No other new features are provided by this override. - -Prerequisite: - -- You must have administrator access to the instance. - -To override the general user and IP rate limits for requests to the Repository files API: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Files API Rate Limits**. -1. Select the checkboxes for the types of rate limits you want to enable: - - **Unauthenticated API request rate limit** - - **Authenticated API request rate limit** -1. If you selected **unauthenticated**: - 1. Select the **Max unauthenticated API requests per period per IP**. - 1. Select the **Unauthenticated API rate limit period in seconds**. -1. If you selected **authenticated**: - 1. Select the **Max authenticated API requests per period per user**. - 1. Select the **Authenticated API rate limit period in seconds**. - -## Related topics - -- [Rate limits](../../../security/rate_limits.md) -- [Repository files API](../../../api/repository_files.md) -- [User and IP rate limits](user_and_ip_rate_limits.md) +<!-- This redirect file can be deleted after <2023-10-14>. --> +<!-- 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/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index 6bd5a6dfed4..8e99005509a 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -1,42 +1,11 @@ --- -stage: none -group: unassigned -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: '../../../administration/settings/floc.md' +remove_date: '2023-10-06' --- -# Federated Learning of Cohorts (FLoC) **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/floc.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60933) in GitLab 13.12. - -Federated Learning of Cohorts (FLoC) is a new feature of the Chrome browser. -It works by categorizing users into different cohorts, so that -advertisers can use this data to uniquely target and track users. For more -information, see the [FLoC repository](https://github.com/WICG/floc). - -To avoid users being tracked and categorized in any GitLab instance, FLoC is -disabled by default by sending the following header: - -```plaintext -Permissions-Policy: interest-cohort=() -``` - -To enable it: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Federated Learning of Cohorts (FLoC)**. -1. Select the **Participate in FLoC** checkbox. -1. Select **Save changes**. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-06>. --> +<!-- 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/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md index c9b294417ee..8d7840b804c 100644 --- a/doc/user/admin_area/settings/git_lfs_rate_limits.md +++ b/doc/user/admin_area/settings/git_lfs_rate_limits.md @@ -1,36 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +redirect_to: '../../../administration/settings/git_lfs_rate_limits.md' +remove_date: '2023-10-06' --- -# Rate limits on Git LFS **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/git_lfs_rate_limits.md). -[Git LFS (Large File Storage)](../../../topics/git/lfs/index.md) is a Git extension -for handling large files. If you use Git LFS in your repository, common Git operations -can generate many Git LFS requests. You can enforce -[general user and IP rate limits](user_and_ip_rate_limits.md), but you can also -override the general setting to enforce additional limits on Git LFS requests. This -override can improve the security and durability of your web application. Aside from -precedence, this configuration provides the same features as the general user and IP -rate limits. - -## Configure Git LFS rate limits - -Git LFS rate limits are disabled by default. If enabled and configured, these limits -supersede the [general user and IP rate limits](user_and_ip_rate_limits.md): - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Git LFS Rate Limits**. -1. Select **Enable authenticated Git LFS request rate limit**. -1. Enter a value for **Max authenticated Git LFS requests per period per user**. -1. Enter a value for **Authenticated Git LFS rate limit period in seconds**. -1. Select **Save changes**. - -## Related topics - -- [Rate limiting](../../../security/rate_limits.md) -- [User and IP rate limits](user_and_ip_rate_limits.md) +<!-- This redirect file can be deleted after <2023-10-06>. --> +<!-- 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/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index d28e9ec0249..572a9c55642 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -1,27 +1,11 @@ --- -stage: Systems -group: Gitaly -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: '../../../administration/settings/gitaly_timeouts.md' +remove_date: '2023-10-07' --- -# Gitaly timeouts **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/gitaly_timeouts.md). -[Gitaly](../../../administration/gitaly/index.md) timeouts are configurable. The timeouts can be -configured to make sure that long-running Gitaly calls don't needlessly take up resources. - -To access Gitaly timeout settings: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand the **Gitaly timeouts** section. - -## Available timeouts - -The following timeouts are available. - -| Timeout | Default | Description | -|:--------|:-----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the [worker timeout](../../../administration/operations/puma.md#change-the-worker-timeout) that can be configured for [Puma](../../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | -| Fast | 10 seconds | Timeout for fast Gitaly operations used within requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance. | -| Medium | 30 seconds | Timeout for Gitaly operations that should be fast (possibly within requests) but preferably not used multiple times within a request. For example, loading blobs. Timeout that should be set between Default and Fast. | +<!-- This redirect file can be deleted after <2023-10-07>. --> +<!-- 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/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index febd794b04c..38fe5c3b54c 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -1,111 +1,11 @@ --- -stage: none -group: unassigned -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: howto +redirect_to: '../../../administration/settings/help_page.md' +remove_date: '2023-10-07' --- -# Customize the Help and sign-in page messages **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/help_page.md). -In large organizations, it is useful to have information about who to contact or where -to go for help. You can customize and display this information on the GitLab `/help` page and on -the GitLab sign-in page. - -## Add a help message to the Help page - -You can add a help message, which is shown at the top of the GitLab `/help` page (for example, -<https://gitlab.com/help>): - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Sign-in and Help page**. -1. In **Additional text to show on the Help page**, enter the information you want to display on `/help`. -1. Select **Save changes**. - -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 authenticated users. - -## Add a help message to the sign-in page - -You can add a help message, which is shown on the GitLab sign-in page. The message appears on the sign-in page: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Sign-in and Help page**. -1. In **Additional text to show on the sign-in page**, enter the information you want to - display on the sign-in page. -1. Select **Save changes**. - -You can now see the message on the sign-in page. - -## Hide marketing-related entries from the Help page - -GitLab marketing-related entries are occasionally shown on the Help page. To hide these entries: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Sign-in and Help page**. -1. Select the **Hide marketing-related entries from the Help page** checkbox. -1. Select **Save changes**. - -## Set a custom Support page URL - -You can specify a custom URL to which users are directed when they: - -- Select **Support** from the Help dropdown list. -- Select **See our website for help** on the Help page. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Sign-in and Help page**. -1. In the **Support page URL** field, enter the URL. -1. Select **Save changes**. - -## Redirect `/help` pages - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43157) in GitLab 13.5. -> - [Feature flag `help_page_documentation_redirect`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71737) removed in GitLab 14.4. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71737) in GitLab 14.4. - -You can redirect all `/help` links to a destination that meets the [necessary requirements](#destination-requirements). - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Sign-in and Help page**. -1. In the **Documentation pages URL** field, enter the URL. -1. Select **Save changes**. - -If the "Documentation pages URL" field is empty, the GitLab instance displays a basic version of the documentation sourced from the [`doc` directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) of GitLab. - -### Destination requirements - -When redirecting `/help`, GitLab: - -- Redirects requests to the specified URL. -- Appends `ee` and the documentation path, which includes the version number, to the URL. -- Appends `.html` to the URL, and removes `.md` if necessary. - -For example, if the URL is set to `https://docs.gitlab.com`, requests for -`/help/user/admin_area/settings/help_page.md` redirect to: -`https://docs.gitlab.com/${VERSION}/ee/user/admin_area/settings/help_page.html`. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-07>. --> +<!-- 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/admin_area/settings/img/continuous_integration_shared_runner_details_input_v14_10.png b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_input_v14_10.png Binary files differdeleted file mode 100644 index 08451f36962..00000000000 --- a/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_input_v14_10.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_10.png b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_10.png Binary files differdeleted file mode 100644 index 64bd9cf6911..00000000000 --- a/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_10.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/suggest_pipeline_banner_v14_5.png b/doc/user/admin_area/settings/img/suggest_pipeline_banner_v14_5.png Binary files differdeleted file mode 100644 index 0d9bfa4a173..00000000000 --- a/doc/user/admin_area/settings/img/suggest_pipeline_banner_v14_5.png +++ /dev/null diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md index 99385c77cdf..ad55f424d81 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -1,31 +1,11 @@ --- -stage: Manage -group: Import and Integrate -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: '../../../administration/settings/import_export_rate_limits.md' +remove_date: '2023-10-07' --- -# Rate limits for imports and exports of project and groups **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/import_export_rate_limits.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35728) in GitLab 13.2. - -You can configure the rate limits for imports and exports of projects and groups: - -To change a rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Import and export rate limits**. -1. Change the value of any rate limit. The rate limits are per minute per user, not per IP address. - Set to `0` to disable a rate limit. - -| Limit | Default | -|-------------------------|---------| -| Project Import | 6 | -| Project Export | 6 | -| Project Export Download | 1 | -| Group Import | 6 | -| Group Export | 6 | -| Group Export Download | 1 | - -When a user exceeds a rate limit, it is logged in `auth.log`. +<!-- This redirect file can be deleted after <2023-10-07>. --> +<!-- 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/admin_area/settings/incident_management_rate_limits.md b/doc/user/admin_area/settings/incident_management_rate_limits.md index 0b6e572837e..ad11d6f7f36 100644 --- a/doc/user/admin_area/settings/incident_management_rate_limits.md +++ b/doc/user/admin_area/settings/incident_management_rate_limits.md @@ -1,39 +1,11 @@ --- -type: reference -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 +redirect_to: '../../../administration/settings/incident_management_rate_limits.md' +remove_date: '2023-10-10' --- -# Incident management rate limits **(ULTIMATE SELF)** +This document was moved to [another location](../../../administration/settings/incident_management_rate_limits.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17859) in GitLab 12.5. - -You can limit the number of inbound alerts for [incidents](../../../operations/incident_management/incidents.md) -that can be created in a period of time. The inbound [incident management](../../../operations/incident_management/index.md) -alert limit can help prevent overloading your incident responders by reducing the -number of alerts or duplicate issues. - -As an example, if you set a limit of `10` requests every `60` seconds, -and `11` requests are sent to an [alert integration endpoint](../../../operations/incident_management/integrations.md) within one minute, -the eleventh request is blocked. Access to the endpoint is allowed again after one minute. - -This limit is: - -- Applied independently per project. -- Not applied per IP address. -- Disabled by default. - -Requests that exceed the limit are logged into `auth.log`. - -## Set a limit on inbound alerts - -To set inbound incident management alert limits: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Incident Management Limits**. -1. Select the **Enable Incident Management inbound alert limit** checkbox. -1. Optional. Input a custom value for **Maximum requests per project per rate limit period**. Default is 3600. -1. Optional. Input a custom value for **Rate limit period**. Default is 3600 seconds. +<!-- This redirect file can be deleted after <2023-10-10>. --> +<!-- 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/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 632adf273c4..37112e6897f 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -1,218 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index +redirect_to: '../../../administration/settings/index.md' +remove_date: '2023-10-10' --- -# Admin Area settings **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/index.md). -As an administrator of a GitLab self-managed instance, you can manage the behavior of your -deployment. - -The **Admin Area** is not accessible on GitLab.com, and settings can only be changed by the -GitLab.com administrators. For the settings and limits on the GitLab.com instance, -read [GitLab.com settings](../../gitlab_com/index.md). - -## Access the Admin Area - -To access the **Admin Area**: - -1. Sign in to your GitLab instance as an administrator. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings**, and the group of settings to view: - - [General](#general) - - [Geo](#geo) - - [CI/CD](#cicd) - - [Integrations](#integrations) - - [Metrics and profiling](#metrics-and-profiling) - - [Network](#network) - - [Preferences](#preferences) - - [Reporting](#reporting) - - [Repository](#repository) - - [Templates](#templates) - -### General - -The **General** settings contain: - -- [Visibility and access controls](visibility_and_access_controls.md) - Set default and - restrict visibility levels. Configure import sources and Git access protocol. -- [Account and limit](account_and_limit_settings.md) - Set projects and maximum size limits, - session duration, user options, and check feature availability for namespace plan. -- [Diff limits](../diff_limits.md) - Diff content limits. -- [Sign-up restrictions](sign_up_restrictions.md) - Configure the way a user creates a new account. -- [Sign in restrictions](sign_in_restrictions.md) - Set requirements for a user to sign in. - Enable mandatory two-factor authentication. -- [Terms of Service and Privacy Policy](terms.md) - Include a Terms of Service agreement - and Privacy Policy that all users must accept. -- [External Authentication](external_authorization.md#configuration) - External Classification Policy Authorization. -- [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) - - Set max session time for web terminal. -- [FLoC](floc.md) - Enable or disable - [Federated Learning of Cohorts (FLoC)](https://en.wikipedia.org/wiki/Federated_Learning_of_Cohorts) tracking. - -### CI/CD - -The **CI/CD** settings contain: - -- [Continuous Integration and Deployment](continuous_integration.md) - - Auto DevOps, runners and job artifacts. -- [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) - - Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/index.md). - This pipeline configuration is run after the project's own configuration. -- [Package Registry](continuous_integration.md#package-registry-configuration) - - Settings related to the use and experience of using the GitLab Package Registry. Some - [risks are involved](../../packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries) - in enabling some of these settings. - -## Security and Compliance settings - -- [License compliance settings](security_and_compliance.md#choose-package-registry-metadata-to-sync): Enable or disable synchronization of package metadata by a registry type. - -### Geo **(PREMIUM SELF)** - -The **Geo** setting contains: - -- [Geo](../../../administration/geo/index.md) - Replicate your GitLab instance to other - geographical locations. Redirects to **Admin Area > Geo > Settings** are no - longer available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). - -### Integrations - -The **Integrations** settings contain: - -- [Elasticsearch](../../../integration/advanced_search/elasticsearch.md#enable-advanced-search) - - Elasticsearch integration. Elasticsearch AWS IAM. -- [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) - - Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). -- [Mailgun](../../../administration/integration/mailgun.md) - Enable your GitLab instance - to receive invite email bounce events from Mailgun, if it is your email provider. -- [PlantUML](../../../administration/integration/plantuml.md) - Allow rendering of PlantUML - diagrams in documents. -- [Slack application](../../../user/project/integrations/gitlab_slack_application.md) - - Slack integration allows you to interact with GitLab via slash commands in a chat window. - This option is only available on GitLab.com, though it may be - [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). -- [Customer experience improvement and third-party offers](third_party_offers.md) - - Control the display of customer experience improvement content and third-party offers. -- [Snowplow](../../../development/internal_analytics/snowplow/index.md) - Configure the Snowplow integration. -- [Google GKE](../../project/clusters/add_gke_clusters.md) - Google GKE integration enables - you to provision GKE clusters from GitLab. -- [Amazon EKS](../../project/clusters/add_eks_clusters.md) - Amazon EKS integration enables - you to provision EKS clusters from GitLab. - -### Metrics and profiling - -The **Metrics and profiling** settings contain: - -- [Metrics - Prometheus](../../../administration/monitoring/prometheus/gitlab_metrics.md) - - Enable and configure Prometheus metrics. -- [Metrics - Grafana](../../../administration/monitoring/performance/grafana_configuration.md#integrate-with-gitlab-ui) - - Enable and configure Grafana. -- [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-for-non-administrators) - - Enable access to the Performance Bar for non-administrator users in a given group. -- [Usage statistics](usage_statistics.md) - Enable or disable version check and Service Ping. - -### Network - -The **Network** settings contain: - -- Performance optimization - Various settings that affect GitLab performance, including: - - [Write to `authorized_keys` file](../../../administration/operations/fast_ssh_key_lookup.md#set-up-fast-lookup). - - [Push event activities limit and bulk push events](push_event_activities_limit.md). -- [User and IP rate limits](user_and_ip_rate_limits.md) - Configure limits for web and API requests. - These rate limits can be overridden: - - [Package Registry Rate Limits](package_registry_rate_limits.md) - Configure specific - limits for Packages API requests that supersede the user and IP rate limits. - - [Git LFS Rate Limits](git_lfs_rate_limits.md) - Configure specific limits for - Git LFS requests that supersede the user and IP rate limits. - - [Files API Rate Limits](files_api_rate_limits.md) - Configure specific limits for - Files API requests that supersede the user and IP rate limits. - - [Search rate limits](../../../administration/instance_limits.md#search-rate-limit) - Configure global search request rate limits for authenticated and unauthenticated users. - - [Deprecated API Rate Limits](deprecated_api_rate_limits.md) - Configure specific limits - for deprecated API requests that supersede the user and IP rate limits. -- [Outbound requests](../../../security/webhooks.md) - Allow requests to the local network from webhooks and integrations, or deny all outbound requests. -- [Protected Paths](protected_paths.md) - Configure paths to be protected by Rack Attack. -- [Incident Management Limits](../../../operations/incident_management/index.md) - Limit the - number of inbound alerts that can be sent to a project. -- [Notes creation limit](rate_limit_on_notes_creation.md) - Set a rate limit on the note creation requests. -- [Get single user limit](rate_limit_on_users_api.md) - Set a rate limit on users API endpoint to get a user by ID. -- [Projects API rate limits for unauthenticated requests](rate_limit_on_projects_api.md) - Set a rate limit on Projects list API endpoint for unauthenticated requests. - -### Preferences - -The **Preferences** settings contain: - -- [Email](email.md) - Various email settings. -- [What's new](../../../administration/whats-new.md) - Configure **What's new** drawer and content. -- [Help page](help_page.md) - Help page text and support page URL. -- [Pages](../../../administration/pages/index.md#custom-domain-verification) - - Size and domain settings for static websites. -- [Polling interval multiplier](../../../administration/polling.md) - - Configure how frequently the GitLab UI polls for updates. -- [Gitaly timeouts](gitaly_timeouts.md) - Configure Gitaly timeouts. -- Localization: - - [Default first day of the week](../../profile/preferences.md). - - [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). -- [Sidekiq Job Limits](sidekiq_job_limits.md) - Limit the size of Sidekiq jobs stored in Redis. - -### Reporting - -The **Reporting** settings contain: - -- Spam and Anti-bot protection: - - Anti-spam services, such as [reCAPTCHA](../../../integration/recaptcha.md), - [Akismet](../../../integration/akismet.md), or [Spamcheck](../reporting/spamcheck.md). - - [IP address restrictions](../reporting/ip_addr_restrictions.md). -- [Abuse reports](../review_abuse_reports.md) - Set notification email for abuse reports. -- [Git abuse rate limit](../reporting/git_abuse_rate_limit.md) - Configure Git abuse rate limit settings. **(ULTIMATE SELF)** - -### Repository - -The **Repository** settings contain: - -- [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) - - Set a custom branch name for new repositories created in your instance. -- [Repository's initial default branch protection](../../project/repository/branches/default.md#instance-level-default-branch-protection) - - Configure the branch protections to apply to every repository's default branch. -- [Repository mirror](visibility_and_access_controls.md#enable-project-mirroring) - - Configure repository mirroring. -- [Repository storage](../../../administration/repository_storage_types.md) - Configure storage path settings. -- Repository maintenance: - - [Repository checks](../../../administration/repository_checks.md) - Configure - automatic Git checks on repositories. - - [Housekeeping](../../../administration/housekeeping.md). Configure automatic - Git housekeeping on repositories. - - [Inactive project deletion](../../../administration/inactive_project_deletion.md). Configure inactive - project deletion. -- [Repository static objects](../../../administration/static_objects_external_storage.md) - - Serve repository static objects (for example, archives and blobs) from an external storage (for example, a CDN). - -### Templates **(PREMIUM SELF)** - -The **Templates** settings contain: - -- [Templates](instance_template_repository.md#configuration) - Set instance-wide template repository. -- [Custom project templates](../custom_project_templates.md) - Select the custom project template source group. - -## Default first day of the week - -You can change the [Default first day of the week](../../profile/preferences.md) -for the entire GitLab instance: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Scroll to the **Localization** section, and select your desired first day of the week. - -## Default language - -You can change the [Default language](../../profile/preferences.md) -for the entire GitLab instance: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Scroll to the **Localization** section, and select your desired default language. +<!-- This redirect file can be deleted after <2023-10-10>. --> +<!-- 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/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index a5148c41b74..752630ea922 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -1,84 +1,11 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +redirect_to: '../../../administration/settings/instance_template_repository.md' +remove_date: '2023-10-11' --- -# Instance template repository **(PREMIUM SELF)** +This document was moved to [another location](../../../administration/settings/instance_template_repository.md). -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) to behave like group-level templates in GitLab 13.9. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. - -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 through the [Web Editor](../../project/repository/web_editor.md) -while the project remains secure. - -## Configuration - -To select a project to serve as the custom template repository: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Templates**. -1. Expand **Templates** -1. From the dropdown list, select the project to use as the template repository. -1. Select **Save changes**. -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](../../project/repository/web_editor.md) -and through the [API settings](../../../api/settings.md). - -## Supported file types and locations - -Templates must be added to a specific subdirectory in the repository, -corresponding to the kind of template. The following types of custom templates -are supported: - -| Type | Directory | Extension | -| :---------------: | :-----------: | :-----------: | -| `Dockerfile` | `Dockerfile` | `.dockerfile` | -| `.gitignore` | `gitignore` | `.gitignore` | -| `.gitlab-ci.yml` | `gitlab-ci` | `.yml` | -| `LICENSE` | `LICENSE` | `.txt` | - -Each template must go in its respective subdirectory, have the correct -extension and not be empty. So, the hierarchy should look like this: - -```plaintext -|-- README.md -|-- Dockerfile - |-- custom_dockerfile.dockerfile - |-- another_dockerfile.dockerfile -|-- gitignore - |-- custom_gitignore.gitignore - |-- another_gitignore.gitignore -|-- gitlab-ci - |-- custom_gitlab-ci.yml - |-- another_gitlab-ci.yml -|-- LICENSE - |-- custom_license.txt - |-- another_license.txt -``` - -Your custom templates are displayed on the dropdown list when a new file is added through the GitLab UI: - - - -If this feature is disabled or no templates are present, -no **Custom** section displays in the selection dropdown. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-11>. --> +<!-- 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/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md index a1bc339ddd9..269864bdd49 100644 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ b/doc/user/admin_area/settings/package_registry_rate_limits.md @@ -1,57 +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 -type: reference +redirect_to: '../../../administration/settings/package_registry_rate_limits.md' +remove_date: '2023-10-11' --- -# Package Registry Rate Limits **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/package_registry_rate_limits.md). -With the [GitLab Package Registry](../../packages/package_registry/index.md), -you can use GitLab as a private or public registry for a variety of common package managers. You can -publish and share packages, which others can consume as a dependency in downstream projects through -the [Packages API](../../../api/packages.md). - -If downstream projects frequently download such dependencies, many requests are made through the -Packages API. You may therefore reach enforced [user and IP rate limits](user_and_ip_rate_limits.md). -To address this issue, you can define specific rate limits for the Packages API: - -- [Unauthenticated requests (per IP)](#enable-unauthenticated-request-rate-limit-for-packages-api). -- [Authenticated API requests (per user)](#enable-authenticated-api-request-rate-limit-for-packages-api). - -These limits are disabled by default. - -When enabled, they supersede the general user and IP rate limits for requests to -the Packages API. You can therefore keep the general user and IP rate limits, and -increase the rate limits for the Packages API. Besides this precedence, there is -no difference in functionality compared to the general user and IP rate limits. - -## Enable unauthenticated request rate limit for packages API - -To enable the unauthenticated request rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Package registry rate limits**. -1. Select **Enable unauthenticated request rate limit**. - - - Optional. Update the **Maximum unauthenticated requests per rate limit period per IP** value. - Defaults to `800`. - - Optional. Update the **Unauthenticated rate limit period in seconds** value. - Defaults to `15`. - -## Enable authenticated API request rate limit for packages API - -To enable the authenticated API request rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network** -1. Expand **Package registry rate limits**. -1. Select **Enable authenticated API request rate limit**. - - - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value. - Defaults to `1000`. - - Optional. Update the **Authenticated API rate limit period in seconds** value. - Defaults to `15`. +<!-- This redirect file can be deleted after <2023-10-11>. --> +<!-- 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/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 1bb4465020c..eff19caabbe 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -1,138 +1,11 @@ --- -stage: Manage -group: Import and Integrate -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: '../../../administration/settings/project_integration_management.md' +remove_date: '2023-10-11' --- -# Project integration management **(FREE)** +This document was moved to [another location](../../../administration/settings/project_integration_management.md). -Project integrations can be configured and enabled by project administrators. As a GitLab instance -administrator, you can set default configuration parameters for a given integration that all projects -can inherit and use, enabling the integration for all projects that are not already using custom -settings. - -You can update these default settings at any time, changing the settings used for all projects that -are set to use instance-level or group-level defaults. Updating the default settings also enables the integration -for all projects that didn't have it already enabled. - -Only the complete settings for an integration can be inherited. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). - -## Manage instance-level default settings for a project integration **(FREE SELF)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2137) in GitLab 13.3 for project-level integrations. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level integrations. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Integrations**. -1. Select an integration. -1. Enter configuration details and select **Save changes**. - -WARNING: -This may affect all or most of the groups and projects on your GitLab instance. Review the details -below. - -If this is the first time you are setting up instance-level settings for an integration: - -- The integration is enabled for all groups and projects that don't already have this integration configured, - if you have the **Enable integration** toggle turned on in the instance-level settings. -- Groups and projects that already have the integration configured are not affected, but can choose to use the - inherited settings at any time. - -When you make further changes to the instance defaults: - -- They are immediately applied to all groups and projects that have the integration set to use default settings. -- They are immediately applied to newer groups and projects, created after you last saved defaults for the - integration. If your instance-level default setting has the **Enable integration** toggle turned - on, the integration is automatically enabled for all such groups and projects. -- Groups and projects with custom settings selected for the integration are not immediately affected and may - choose to use the latest defaults at any time. - -Only the complete settings for an integration can be inherited. Per-field inheritance -is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allow -administrators to update settings inherited by groups and projects without enabling the -integration on all non-configured groups and projects by default. - -### Remove an instance-level default setting - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Integrations**. -1. Select an integration. -1. Select **Reset** and confirm. - -Resetting an instance-level default setting removes the integration from all projects that have the integration set to use default settings. - -### View projects that override the default settings - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218252) in GitLab 14.2. - -You can view which projects in your instance use custom settings that [override the instance-level default settings](#use-custom-settings-for-a-group-or-project-integration) -for an integration. - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Integrations**. -1. Select an integration. -1. Select the **Projects using custom settings** tab. - -## Manage group-level default settings for a project integration - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6. - -1. Navigate to the group's **Settings > Integrations**. -1. Select an integration. -1. Enter configuration details and select **Save changes**. - -WARNING: -This may affect all or most of the subgroups and projects belonging to the group. Review the details below. - -If this is the first time you are setting up group-level settings for an integration: - -- The integration is enabled for all subgroups and projects belonging to the group that don't already have - this integration configured, if you have the **Enable integration** toggle turned on in the group-level - settings. -- Subgroups and projects that already have the integration configured are not affected, but can choose to use - the inherited settings at any time. - -When you make further changes to the group defaults: - -- They are immediately applied to all subgroups and projects belonging to the group that have the integration - set to use default settings. -- They are immediately applied to newer subgroups and projects, even those created after you last saved defaults for the - integration. If your group-level default setting has the **Enable integration** toggle turned on, - the integration is automatically enabled for all such subgroups and projects. - -- Subgroups and projects with custom settings selected for the integration are not immediately affected and - may choose to use the latest defaults at any time. - -Only the complete settings for an integration can be inherited. Per-field inheritance -is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allow -administrators to update settings inherited by subgroups and projects without enabling the -integration on all non-configured groups and projects by default. - -### Remove a group-level default setting - -1. Navigate to the group's **Settings > Integrations**. -1. Select an integration. -1. Select **Reset** and confirm. - -Resetting a group-level default setting removes integrations that use default settings and belong to a project or subgroup of the group. - -## Use instance-level or group-level default settings for a project integration - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level settings. - -1. Navigate to **Project > Settings > Integrations**. -1. Choose the integration you want to enable or update. -1. From the dropdown list, select **Use default settings**. -1. Ensure the toggle is set to **Enable integration**. -1. Select **Save changes**. - -## Use custom settings for a group or project integration - -1. Navigate to project or group's **Settings > Integrations**. -1. Choose the integration you want to enable or update. -1. From the dropdown list, select **Use custom settings**. -1. Ensure the toggle is set to **Enable integration** and enter all required settings. -1. Select **Save changes**. +<!-- This redirect file can be deleted after <2023-10-11>. --> +<!-- 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/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index 4080ee6a540..519d035244a 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -1,43 +1,11 @@ --- -stage: none -group: unassigned -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 +redirect_to: '../../../administration/settings/protected_paths.md' +remove_date: '2023-10-12' --- -# Protected paths **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/protected_paths.md). -Rate limiting is a technique that improves the security and durability of a web -application. For more details, see [Rate limits](../../../security/rate_limits.md). - -You can rate limit (protect) specified paths. For these paths, GitLab responds with HTTP status -code `429` to POST requests at protected paths that exceed 10 requests per minute per IP address. - -For example, the following are limited to a maximum 10 requests per minute: - -- User sign-in -- User sign-up (if enabled) -- User password reset - -After 10 requests, the client must wait 60 seconds before it can try again. - -See also: - -- List of paths [protected by default](../../../administration/instance_limits.md#by-protected-path). -- [User and IP rate limits](../../admin_area/settings/user_and_ip_rate_limits.md#response-headers) - for the headers returned to blocked requests. - -## Configure protected paths - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31246) in GitLab 12.4. - -Throttling of protected paths is enabled by default and can be disabled or -customized on **Admin > Network > Protected Paths**, along with these options: - -- Maximum number of requests per period per user. -- Rate limit period in seconds. -- Paths to be protected. - - - -Requests over the rate limit are logged into `auth.log`. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index 56a2902f2d9..b7e059cf820 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -1,38 +1,11 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +redirect_to: '../../../administration/settings/push_event_activities_limit.md' +remove_date: '2023-10-12' --- -# Push event activities limit and bulk push events **(FREE)** +This document was moved to [another location](../../../administration/settings/push_event_activities_limit.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31007) in GitLab 12.4. - -Set the number of branches or tags to limit the number of single push events -allowed at once. If the number of events is greater than this, GitLab creates -bulk push event instead. - -For example, if 4 branches are pushed and the limit is currently set to 3, -the activity feed displays: - - - -With this feature, when a single push includes a lot of changes (for example, 1,000 -branches), only 1 bulk push event is created instead of 1,000 push -events. This helps in maintaining good system performance and preventing spam on -the activity feed. - -To modify this setting: - -- In the Admin Area: - 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). - 1. Select **Admin Area**. - 1. Select **Settings > Network**. - 1. Expand **Performance optimization**. -- Through the [Application settings API](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) - as `push_event_activities_limit`. - -The default value is `3`, but the value can be greater than or equal to `0`. Setting this value to `0` does not disable throttling. - - +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index 09a1e023c2b..aca30177c54 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -1,36 +1,11 @@ --- -type: reference -stage: Plan -group: Project Management -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: '../../../administration/settings/rate_limit_on_issues_creation.md' +remove_date: '2023-10-12' --- -# Rate limits on issue creation **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/rate_limit_on_issues_creation.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28129) in GitLab 12.10. - -This setting allows you to rate limit the requests to the issue and epic creation endpoints. -To can change its value: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Issues Rate Limits**. -1. Under **Max requests per minute**, enter the new value. -1. Select **Save changes**. - -For example, if you set a limit of 300, requests using the -[Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/projects/issues_controller.rb) -action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. - -When using [epics](../../group/epics/index.md), epic creation shares this rate limit with issues. - - - -This limit is: - -- Applied independently per project and per user. -- Not applied per IP address. -- Disabled by default. To enable it, set the option to any value other than `0`. - -Requests over the rate limit are logged into the `auth.log` file. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md index 59548836e78..6d5c93f8554 100644 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -1,35 +1,11 @@ --- -type: reference -stage: Plan -group: Project Management -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: '../../../administration/settings/rate_limit_on_notes_creation.md' +remove_date: '2023-10-12' --- -# Rate limits on note creation **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/rate_limit_on_notes_creation.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53637) in GitLab 13.9. - -You can configure the per-user rate limit for requests to the note creation endpoint. - -To change the note creation rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Notes rate limit**. -1. In the **Maximum requests per minute** box, enter the new value. -1. Optional. In the **Users to exclude from the rate limit** box, list users allowed to exceed the limit. -1. Select **Save changes**. - -This limit is: - -- Applied independently per user. -- Not applied per IP address. - -The default value is `300`. - -Requests over the rate limit are logged into the `auth.log` file. - -For example, if you set a limit of 300, requests using the -[Projects::NotesController#create](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/notes_controller.rb) -action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/rate_limit_on_pipelines_creation.md b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md index 2d0c4405211..c469a77f7d2 100644 --- a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md @@ -1,35 +1,11 @@ --- -type: reference -stage: Verify -group: Pipeline Execution -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: '../../../administration/settings/rate_limit_on_pipelines_creation.md' +remove_date: '2023-10-12' --- -# Rate limits on pipeline creation **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/rate_limit_on_pipelines_creation.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362475) in GitLab 15.0. - -You can set a limit so that users and processes can't request more than a certain number of pipelines each minute. This limit can help save resources and improve stability. - -For example, if you set a limit of `10`, and `11` requests are sent to the [trigger API](../../../ci/triggers/index.md) within one minute, -the eleventh request is blocked. Access to the endpoint is allowed again after one minute. - -This limit is: - -- Applied to the number of pipelines created for the same combination of project, commit, and user. -- Not applied per IP address. -- Disabled by default. - -Requests that exceed the limit are logged in the `application_json.log` file. - -## Set a pipeline request limit - -To limit the number of pipeline requests: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Pipelines Rate Limits**. -1. Under **Max requests per minute**, enter a value greater than `0`. -1. Select **Save changes**. -1. Enable `ci_enforce_throttle_pipelines_creation` feature flag to enable the rate limit. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/rate_limit_on_projects_api.md b/doc/user/admin_area/settings/rate_limit_on_projects_api.md index 326dd3b4706..12577ba44b1 100644 --- a/doc/user/admin_area/settings/rate_limit_on_projects_api.md +++ b/doc/user/admin_area/settings/rate_limit_on_projects_api.md @@ -1,37 +1,11 @@ --- -type: reference -stage: Data Stores -group: Tenant Scale -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: '../../../administration/settings/rate_limit_on_projects_api.md' +remove_date: '2023-10-12' --- -# Rate limit on Projects API **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/rate_limit_on_projects_api.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112283) in GitLab 15.10 with a [flag](../../../administration/feature_flags.md) named `rate_limit_for_unauthenticated_projects_api_access`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/391922) on May 08, 2023. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119603) in GitLab 16.0 by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120445) in GitLab 16.0. Feature flag `rate_limit_for_unauthenticated_projects_api_access` removed. - -You can configure the rate limit per IP address for unauthenticated requests to the [list all projects API](../../../api/projects.md#list-all-projects). - -To change the rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Projects API rate limit**. -1. In the **Maximum requests per 10 minutes per IP address** text box, enter the new value. -1. Select **Save changes**. - -The rate limit: - -- Applies per IP address. -- Doesn't apply to authenticated requests. -- Can be set to 0 to disable rate limiting. - -The default value of the rate limit is `400`. - -Requests over the rate limit are logged into the `auth.log` file. - -For example, if you set a limit of 400, unauthenticated requests to the `GET /projects` API endpoint that -exceed a rate of 400 within 10 minutes are blocked. Access to the endpoint is restored after ten minutes have elapsed. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/rate_limit_on_users_api.md b/doc/user/admin_area/settings/rate_limit_on_users_api.md index 112518131bf..80acbf21023 100644 --- a/doc/user/admin_area/settings/rate_limit_on_users_api.md +++ b/doc/user/admin_area/settings/rate_limit_on_users_api.md @@ -1,34 +1,11 @@ --- -type: reference -stage: Manage -group: Authentication and Authorization -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: '../../../administration/settings/rate_limit_on_users_api.md' +remove_date: '2023-10-12' --- -# Rate limits on Users API **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/rate_limit_on_users_api.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78364) in GitLab 14.8. - -You can configure the per user rate limit for requests to [Users API](../../../api/users.md). - -To change the rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Users API rate limit**. -1. In the **Maximum requests per 10 minutes** text box, enter the new value. -1. Optional. In the **Users to exclude from the rate limit** box, list users allowed to exceed the limit. -1. Select **Save changes**. - -This limit is: - -- Applied independently per user. -- Not applied per IP address. - -The default value is `300`. - -Requests over the rate limit are logged into the `auth.log` file. - -For example, if you set a limit of 300, requests to the `GET /users/:id` API endpoint -exceeding a rate of 300 per 10 minutes are blocked. Access to the endpoint is allowed after ten minutes have elapsed. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/profile/saved_replies.md b/doc/user/admin_area/settings/rate_limits_on_git_ssh_operations.md index 1f4e4f5fa51..b60a78d1f49 100644 --- a/doc/user/profile/saved_replies.md +++ b/doc/user/admin_area/settings/rate_limits_on_git_ssh_operations.md @@ -1,11 +1,11 @@ --- -redirect_to: 'comment_templates.md' -remove_date: '2023-06-22' +redirect_to: '../../../administration/settings/rate_limits_on_git_ssh_operations.md' +remove_date: '2023-10-12' --- -This document was moved to [another location](comment_templates.md). +This document was moved to [another location](../../../administration/settings/rate_limits_on_git_ssh_operations.md). -<!-- This redirect file can be deleted after <2023-06-22>. --> +<!-- This redirect file can be deleted after <2023-10-12>. --> <!-- 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/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index 78e65f7ba7b..5cfee536a58 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -1,29 +1,11 @@ --- -stage: none -group: unassigned -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 +redirect_to: '../../../administration/settings/rate_limits_on_raw_endpoints.md' +remove_date: '2023-10-12' --- -# Rate limits on raw endpoints **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/rate_limits_on_raw_endpoints.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30635) in GitLab 12.2. - -This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **Performance optimization**. - -For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` are blocked. Access to the raw file is released after 1 minute. - - - -This limit is: - -- Applied independently per project, per file path. -- Not applied per IP address. -- Active by default. To disable, set the option to `0`. - -Requests over the rate limit are logged into `auth.log`. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/scim_setup.md b/doc/user/admin_area/settings/scim_setup.md index 0471dffe442..4ebd8a84f8a 100644 --- a/doc/user/admin_area/settings/scim_setup.md +++ b/doc/user/admin_area/settings/scim_setup.md @@ -1,43 +1,11 @@ --- -type: reference, howto -stage: Manage -group: Authentication and Authorization -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: '../../../administration/settings/scim_setup.md' +remove_date: '2023-10-12' --- -# Configure SCIM for self-managed GitLab instances **(PREMIUM SELF)** +This document was moved to [another location](../../../administration/settings/scim_setup.md). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8902) in GitLab 15.8. - -You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically: - -- Create users. -- Block users. - -The [internal GitLab SCIM API](../../../development/internal_api/index.md#instance-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). - -If you are a GitLab.com user, see [configuring SCIM for GitLab.com groups](../../../user/group/saml_sso/scim_setup.md). - -## Configure GitLab - -Prerequisites: - -- Configure [SAML single sign-on](../../../integration/saml.md). - -To configure GitLab SCIM: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **SCIM Token** section and select **Generate a SCIM token**. -1. For configuration of your identity provider, save the: - - Token from the **Your SCIM token** field. - - URL from the **SCIM API endpoint URL** field. - -## Remove access - -Removing or deactivating a user on the identity provider blocks the user on -the GitLab instance, while the SCIM identity remains linked to the GitLab user. - -To update the user SCIM identity, use the -[internal GitLab SCIM API](../../../development/internal_api/index.md#update-a-single-scim-provisioned-user-1). +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/admin_area/settings/security_and_compliance.md b/doc/user/admin_area/settings/security_and_compliance.md index 54fd04f6521..8c1e514c575 100644 --- a/doc/user/admin_area/settings/security_and_compliance.md +++ b/doc/user/admin_area/settings/security_and_compliance.md @@ -1,25 +1,11 @@ --- -stage: Secure -group: Composition Analysis -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: howto +redirect_to: '../../../administration/settings/security_and_compliance.md' +remove_date: '2023-10-13' --- -# Security and Compliance Admin Area settings **(ULTIMATE SELF)** +This document was moved to [another location](../../../administration/settings/security_and_compliance.md). -The settings for package metadata synchronization are located in the [Admin Area](index.md). - -## Choose package registry metadata to sync - -WARNING: -The full package metadata sync can add up to 30 GB to the PostgreSQL database. Ensure you have provisioned enough disk space for the database before enabling this feature. -We are actively working on reducing this data size in [epic 10415](https://gitlab.com/groups/gitlab-org/-/epics/10415). - -To choose the packages you want to synchronize with the GitLab License Database for [License Compliance](../../compliance/license_scanning_of_cyclonedx_files/index.md): - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Security and Compliance**. -1. Expand **License Compliance**. -1. Select or clear checkboxes for the package registries that you want to sync. -1. Select **Save changes**. +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md index 08c3ced4c4e..81be26ec8e0 100644 --- a/doc/user/admin_area/settings/sidekiq_job_limits.md +++ b/doc/user/admin_area/settings/sidekiq_job_limits.md @@ -1,35 +1,11 @@ --- -stage: none -group: unassigned -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 +redirect_to: '../../../administration/settings/sidekiq_job_limits.md' +remove_date: '2023-10-13' --- -# Sidekiq job size limits **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/sidekiq_job_limits.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68982) in GitLab 14.3. - -[Sidekiq](../../../administration/sidekiq/index.md) jobs get stored in -Redis. To avoid excessive memory for Redis, we: - -- Compress job arguments before storing them in Redis. -- Reject jobs that exceed the specified threshold limit after compression. - -To access Sidekiq job size limits: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Sidekiq job size limits**. -1. Adjust the compression threshold or size limit. The compression can - be disabled by selecting the **Track** mode. - -## Available settings - -| Setting | Default | Description | -|-------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Limiting mode | Compress | This mode compresses the jobs at the specified threshold and rejects them if they exceed the specified limit after compression. | -| Sidekiq job compression threshold (bytes) | 100 000 (100 KB) | When the size of arguments exceeds this threshold, they are compressed before being stored in Redis. | -| Sidekiq job size limit (bytes) | 0 | The jobs exceeding this size after compression are rejected. This avoids excessive memory usage in Redis leading to instability. Setting it to 0 prevents rejecting jobs. | - -After changing these values, [restart Sidekiq](../../../administration/restart_gitlab.md). +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 3b79e55f998..c3957ed97eb 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -1,201 +1,11 @@ --- -stage: none -group: unassigned -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: '../../../administration/settings/sign_in_restrictions.md' +remove_date: '2023-10-13' --- -# Sign-in restrictions **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/sign_in_restrictions.md). -You can use **Sign-in restrictions** to customize authentication restrictions for web interfaces as well as Git over HTTP(S). - -## Settings - -To access sign-in restriction settings: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Sign-in restrictions** section. - -## Password authentication enabled - -You can restrict the password authentication for web interface and Git over HTTP(S): - -- **Web interface**: When this feature is disabled, the **Standard** sign-in tab - is removed and an [external authentication provider](../../../administration/auth/index.md) - must be used. -- **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) - or LDAP password must be used to authenticate. - -In the event of an external authentication provider outage, use the [GitLab Rails console](../../../administration/operations/rails_console.md) to [re-enable the standard web sign-in form](#re-enable-standard-web-sign-in-form-in-rails-console). This configuration can also be changed over the [Application settings REST API](../../../api/settings.md#change-application-settings) while authenticating with an administrator account's personal access token. - -## Admin Mode - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. - -If you're an administrator, you might want to work in GitLab without administrator access. -You could either create a separate user account that does not have -administrator access or use Admin Mode. - -With Admin Mode, your account does not have administrator access by default. -You can continue to access groups and projects you're a member of. However, for administrative tasks, -you must authenticate (except for [certain features](#limitations-of-admin-mode)). - -When Admin Mode is enabled, it applies to all administrators on the instance. - -When Admin Mode is enabled for an instance, administrators: - -- Are allowed to access group and projects for which they are members. -- Cannot access the **Admin Area**. - -### Enable Admin Mode for your instance - -Administrators can enable Admin Mode though the API, the Rails console, or the UI. - -#### Use the API to enable Admin Mode - -Make the following request to your instance endpoint: - -```shell -curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab.example.com>/api/v4/application/settings?admin_mode=true" -``` - -Replace `<gitlab.example.com>` with your instance URL. - -For more information, see the [list of settings that can be accessed through API calls](../../../api/settings.md). - -#### Use the Rails console to enable Admin Mode - -Open the [Rails console](../../../administration/operations/rails_console.md) and run the following: - -```ruby -::Gitlab::CurrentSettings.update!(admin_mode: true) -``` - -#### Use the UI to enable Admin Mode - -To enable Admin Mode through the UI: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Sign-in restrictions**. -1. In the **Admin Mode** section, select the **Require additional authentication for administrative tasks** checkbox. - -### Turn on Admin Mode for your session - -To turn on Admin Mode for your current session and access potentially dangerous resources: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Enter Admin Mode**. -1. Try to access any part of the UI with `/admin` in the URL (which requires administrator access). - -When Admin Mode status is disabled or turned off, administrators cannot access resources unless -they've been explicitly granted access. For example, administrators get a `404` error -if they try to open a private group or project, unless they are members of that group or project. - -2FA should be enabled for administrators. 2FA, OmniAuth providers, and LDAP -authentication are supported by Admin Mode. Admin Mode status is stored in the current user session and remains active until either: - -- It is explicitly disabled. -- It is disabled automatically after six hours. - -### Turn off Admin Mode for your session - -To turn off Admin Mode for your current session: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Leave Admin Mode**. - -### Limitations of Admin Mode - -Admin Mode times out after six hours, and you cannot change this timeout limit. - -The following access methods are **not** protected by Admin Mode: - -- Git client access (SSH using public keys or HTTPS using Personal Access Tokens). -- API access using a Personal Access Token. - -In other words, administrators who are otherwise limited by Admin Mode can still use -Git clients, and access RESTful API endpoints as administrators, without additional -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: - -- **API**: - - ```shell - curl --request PUT --header "PRIVATE-TOKEN:$ADMIN_TOKEN" "<gitlab-url>/api/v4/application/settings?admin_mode=false" - ``` - -- [**Rails console**](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - - ```ruby - ::Gitlab::CurrentSettings.update!(admin_mode: false) - ``` - -## Two-factor authentication - -When this feature is enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). - -After the two-factor authentication is configured as mandatory, users are allowed -to skip forced configuration of two-factor authentication for the configurable grace -period in hours. - - - -## Email notification for unknown sign-ins - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218457) in GitLab 13.2. - -When enabled, GitLab notifies users of sign-ins from unknown IP addresses or devices. For more information, -see [Email notification for unknown sign-ins](../../profile/notifications.md#notifications-for-unknown-sign-ins). - - - -## Sign-in information - -All users that are not logged in are redirected to the page represented by the configured -**Home page URL** if value is not empty. - -All users are redirected to the page represented by the configured **Sign-out page URL** -after sign out if value is not empty. - -In the **Sign-in restrictions** section, scroll to the **Sign-in text** field. You can add a -custom message for your users in Markdown format. - -For example, if you include the following information in the noted text box: - -```markdown -# Custom sign-in text - -To access this text box: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Sign-in restrictions** section. -``` - -Your users see the **Custom sign-in text** when they navigate to the sign-in screen for your -GitLab instance. - -## Troubleshooting - -### Re-enable standard web sign-in form in rails console - -Re-enable the standard username and password-based sign-in form if it was disabled as a [Sign-in restriction](#password-authentication-enabled). - -You can use this method through the [rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) when a configured external authentication provider (through SSO or an LDAP configuration) is facing an outage and direct sign-in access to GitLab is required. - -```ruby -Gitlab::CurrentSettings.update!(password_authentication_enabled_for_web: true) -``` +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 0dcca5e7518..553caa9ff0d 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -1,206 +1,11 @@ --- -stage: none -group: unassigned -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 +redirect_to: '../../../administration/settings/sign_up_restrictions.md' +remove_date: '2023-10-13' --- -# Sign-up restrictions **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/sign_up_restrictions.md). -You can enforce the following restrictions on sign ups: - -- Disable new sign ups. -- Require administrator approval for new sign ups. -- Require user email confirmation. -- Allow or deny sign ups using specific email domains. - -## Disable new sign ups - -By default, any user visiting your GitLab domain can sign up for an account. For customers running -public-facing GitLab instances, we **highly** recommend that you consider disabling new sign ups if -you do not expect public users to sign up for an account. - -To disable sign ups: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Sign-up restrictions**. -1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. - -## Require administrator approval for new sign ups - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267568) in GitLab 13.6. - -When this setting is enabled, any user visiting your GitLab domain and signing up for a new account using the registration form -must be explicitly [approved](../moderate_users.md#approve-or-reject-a-user-sign-up) by an -administrator before they can start using their account. In GitLab 13.6 and later, this setting is -enabled by default for new GitLab instances. It is only applicable if sign ups are enabled. - -To require administrator approval for new sign ups: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Sign-up restrictions**. -1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. - -In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273258), if an administrator disables this setting, the users in pending approval state are -automatically approved in a background job. - -NOTE: -This setting doesn't apply to LDAP or OmniAuth users. To enforce approvals for new users -signing up using OmniAuth or LDAP, set `block_auto_created_users` to `true` in the -[OmniAuth configuration](../../../integration/omniauth.md#configure-common-settings) or -[LDAP configuration](../../../administration/auth/ldap/index.md#basic-configuration-settings). -A [user cap](#user-cap) can also be used to enforce approvals for new users. - -## Confirm user email - -> - Soft email confirmation [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47003) in GitLab 12.2 [with a flag](../../../operations/feature_flags.md) named `soft_email_confirmation`. -> - Soft email confirmation [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107302/diffs) from a feature flag to an application setting in GitLab 15.9. - -You can send confirmation emails during sign up and require that users confirm -their email address before they are allowed to sign in. - -For example, to enforce confirmation of the email address used for new sign ups: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Sign-up restrictions**. -1. Under **Email confirmation settings**, select **Hard**. - -The following settings are available: - -- **Hard** - Send a confirmation email during sign up. New users must confirm their email address before they can log in. -- **Soft** - Send a confirmation email during sign up. New users can log in immediately, but must confirm their email in three days. Unconfirmed accounts are deleted. -- **Off** - New users can sign up without confirming their email address. - -## User cap - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4315) in GitLab 13.7. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292600) in GitLab 13.9. - -When the number of billable users reaches the user cap, any user who is added or requests access must be -[approved](../moderate_users.md#approve-or-reject-a-user-sign-up) by an administrator before they can start using -their account. - -If an administrator [increases](#set-the-user-cap-number) or [removes](#remove-the-user-cap) the -user cap, the users in pending approval state are automatically approved in a background job. - -NOTE: -The amount of billable users [is updated once a day](../../../subscriptions/self_managed/index.md#billable-users). -This means the user cap might apply only retrospectively after the cap has already been exceeded. -To ensure the cap is enabled immediately, set it to a low value below the current number of -billable users, for example: `1`. - -On instances that use LDAP or OmniAuth, enabling and disabling -[administrator approval for new sign ups](#require-administrator-approval-for-new-sign-ups) -involves changing the Rails configuration, and may require downtime. -User cap can be used instead. As noted above, set the cap to value that ensures it is enforced immediately. - -### Set the user cap number - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Sign-up restrictions**. -1. Enter a number in **User cap**. -1. Select **Save changes**. - -New user sign ups are subject to the user cap restriction. - -## Remove the user cap - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Sign-up restrictions**. -1. Remove the number from **User cap**. -1. Select **Save changes**. - -New users sign ups are not subject to the user cap restriction. Users in pending approval state are -automatically approved in a background job. - -## Minimum password length limit - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20661) in GitLab 12.6 - -You can [change](../../../security/password_length_limits.md#modify-minimum-password-length) -the minimum number of characters a user must have in their password using the GitLab UI. - -### Password complexity requirements **(PREMIUM SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354965) in GitLab 15.2. - -By default, the only requirement for user passwords is [minimum password length](#minimum-password-length-limit). -You can add additional complexity requirements. Changes to password complexity requirements apply to new passwords: - -- For new users that sign up. -- For existing users that reset their password. - -Existing passwords are unaffected. To change password complexity requirements: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Sign-up restrictions**. -1. Under **Minimum password length (number of characters)**, select additional password complexity requirements. You can require numbers, uppercase letters, lowercase letters, - and symbols. -1. Select **Save changes**. - -## Allow or deny sign ups using specific email domains - -You can specify an inclusive or exclusive list of email domains which can be used for user sign up. - -These restrictions are only applied during sign up from an external user. An administrator can add a -user through the administrator panel with a disallowed domain. The users can also change their -email addresses to disallowed domains after sign up. - -### Allowlist email domains - -You can restrict users only to sign up using email addresses matching the given -domains list. - -### Denylist email domains - -You can block users from signing up when using an email addresses of specific domains. This can -reduce the risk of malicious users creating spam accounts with disposable email addresses. - -### Create email domain allowlist or denylist - -To create an email domain allowlist or denylist: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Sign-up restrictions**. -1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list - manually or upload a `.txt` file that contains list entries. - - Both the allowlist and denylist accept wildcards. For example, you can use -`*.company.com` to accept every `company.com` subdomain, or `*.io` to block all -domains ending in `.io`. Domains must be separated by a whitespace, -semicolon, comma, or a new line. - -  - -## Set up LDAP user filter - -You can limit GitLab access to a subset of the LDAP users on your LDAP server. - -See the [documentation on setting up an LDAP user filter](../../../administration/auth/ldap/index.md#set-up-ldap-user-filter) for more information. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/slack_app.md b/doc/user/admin_area/settings/slack_app.md new file mode 100644 index 00000000000..5aae85081ed --- /dev/null +++ b/doc/user/admin_area/settings/slack_app.md @@ -0,0 +1,109 @@ +--- +stage: Manage +group: Import and Integrate +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 for Slack app administration **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for self-managed instances in GitLab 16.2. + +NOTE: +This page contains information about administering the GitLab for Slack app for self-managed instances. For user documentation, see [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md). + +The GitLab for Slack app distributed through the Slack App Directory only works with GitLab.com. +On self-managed GitLab, you can create your own copy of the GitLab for Slack app from a [manifest file](https://api.slack.com/reference/manifests#creating_apps) and configure your instance. + +The app is a private one-time copy installed in your Slack workspace only and not distributed through the Slack App Directory. To have the [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md) on your self-managed instance, you must enable the integration. + +## Create a GitLab for Slack app + +Prerequisite: + +- You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). + +To create a GitLab for Slack app: + +- **In GitLab**: + + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **GitLab for Slack app**. + 1. Select **Create Slack app**. + +You're then redirected to Slack for the next steps. + +- **In Slack**: + + 1. Select the Slack workspace to create the app in, then select **Next**. + 1. Slack displays a summary of the app for review. To view the complete manifest, select **Edit Configurations**. To go back to the review summary, select **Next**. + 1. Select **Create**. + 1. Select **Got it** to close the dialog. + 1. Select **Install to Workspace**. + +## Configure the settings + +After you've [created a GitLab for Slack app](#create-a-gitlab-for-slack-app), you can configure the settings in GitLab: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **GitLab for Slack app**. +1. Select the **Enable GitLab for Slack app** checkbox. +1. Enter the details of your GitLab for Slack app: + 1. Go to [Slack API](https://api.slack.com/apps). + 1. Search for and select **GitLab (\<your host name\>)**. + 1. Scroll to **App Credentials**. +1. Select **Save changes**. + +### Test your configuration + +To test your GitLab for Slack app configuration: + +1. Enter the `/gitlab help` slash command into a channel in your Slack workspace. +1. Press <kbd>Enter</kbd>. + +You should see a list of available Slash commands. + +To use Slash commands for a project, configure the [GitLab for Slack app](../../../user/project/integrations/gitlab_slack_application.md) for the project. + +## Update the GitLab for Slack app + +When GitLab releases new features for the GitLab for Slack app, you might have to manually update your copy to use the new features. + +To update your copy of the GitLab for Slack app: + +- **In GitLab**: + + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **GitLab for Slack app**. + 1. Select **Download latest manifest file** to download `slack_manifest.json`. + +- **In Slack**: + + 1. Go to [Slack API](https://api.slack.com/apps). + 1. Search for and select **GitLab (\<your host name\>)**. + 1. On the left sidebar, select **App Manifest**. + 1. Select the **JSON** tab to switch to a JSON view of the manifest. + 1. Copy the contents of the `slack_manifest.json` file you've downloaded from GitLab. + 1. Paste the contents into the JSON viewer to replace any existing contents. + 1. Select **Save Changes**. + +## Connectivity requirements + +To enable the GitLab for Slack app functionality, your network must allow inbound and outbound connections between GitLab and Slack. + +- For [Slack notifications](../../../user/project/integrations/gitlab_slack_application.md#slack-notifications), the GitLab instance must be able to send requests to `https://slack.com`. +- For [Slash commands](../../../user/project/integrations/gitlab_slack_application.md#slash-commands) and other features, the GitLab instance must be able to receive requests from `https://slack.com`. + +## Troubleshooting + +### Slash commands return `/gitlab failed with the error "dispatch_failed"` in Slack + +Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure: + +- The GitLab for Slack app is properly [configured](#configure-the-settings), and the **Enable GitLab for Slack app** checkbox is selected. +- Your GitLab instance [allows requests to and from Slack](#connectivity-requirements). diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 8563f778292..444eeeb15ea 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -1,49 +1,11 @@ --- -stage: none -group: unassigned -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 +redirect_to: '../../../administration/settings/terms.md' +remove_date: '2023-10-13' --- -# Terms of Service and Privacy Policy **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/terms.md). -An administrator can enforce acceptance of a terms of service and privacy policy. -When this option is enabled, new and existing users must accept the terms. - -When enabled, you can view the Terms of Service at the `-/users/terms` page on the instance, -for example `https://gitlab.example.com/-/users/terms`. - -## Enforce a Terms of Service and Privacy Policy - -To enforce acceptance of a Terms of Service and Privacy Policy: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Terms of Service and Privacy Policy** section. -1. Check the **All users must accept the Terms of Service and Privacy Policy to access GitLab** checkbox. -1. Input the text of the **Terms of Service and Privacy Policy**. You can use [Markdown](../../markdown.md) - in this text box. -1. Select **Save changes**. - -For each update to the terms, a new version is stored. When a user accepts or declines the terms, -GitLab records which version they accepted or declined. - -Existing users must accept the terms on their next GitLab interaction. -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: - - - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/terraform_limits.md b/doc/user/admin_area/settings/terraform_limits.md index 0e620bb84ce..8fed7589bb7 100644 --- a/doc/user/admin_area/settings/terraform_limits.md +++ b/doc/user/admin_area/settings/terraform_limits.md @@ -1,28 +1,11 @@ --- -stage: Deploy -group: Environments -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 +redirect_to: '../../../administration/settings/terraform_limits.md' +remove_date: '2023-10-13' --- -# Terraform limits **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/terraform_limits.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352951) in GitLab 15.7. - -You can limit the total storage of [Terraform state files](../../../administration/terraform_state.md). -The limit applies to each individual -state file version, and is checked whenever a new version is created. - -To add a storage limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Preferences**. -1. Expand **Terraform limits**. -1. Adjust the size limit. - -## Available settings - -| Setting | Default | Description | -|------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| Terraform state size limit (bytes) | 0 | Terraform state files that exceed this size are not saved, and associated Terraform operations are rejected. Set to 0 to allow files of unlimited size. | +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 39e2275f411..54c5b36bbc0 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,38 +1,11 @@ --- -stage: Data Stores -group: Tenant Scale -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 +redirect_to: '../../../administration/settings/third_party_offers.md' +remove_date: '2023-10-13' --- -# Customer experience improvement and third-party offers **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/third_party_offers.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in GitLab 11.1. - -Within GitLab, we inform users of available third-party offers they might find valuable in order -to enhance the development of their projects. An example is the Google Cloud Platform free credit -for using [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). - -Furthermore, we use content to improve customer experience. An example are the personalization -questions when creating a group. - -To toggle the display of customer experience improvement content and third-party offers: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand **Customer experience improvement and third-party offers**. -1. Select **Do not display content for customer experience improvement and offers from third parties**. -1. Select **Save changes**. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index ed0c8d21931..5b2afd3ad90 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -1,230 +1,11 @@ --- -stage: Analytics -group: Analytics Instrumentation -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: '../../../administration/settings/usage_statistics.md' +remove_date: '2023-10-13' --- -# Usage statistics **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/usage_statistics.md). -GitLab Inc. periodically collects information about your instance in order -to perform various actions. - -All usage statistics are [opt-out](#enable-or-disable-usage-statistics). - -## Service Ping - -Service Ping is a process that collects and sends a weekly payload to GitLab Inc. -For more information, see the [Service Ping guide](../../../development/internal_analytics/service_ping/index.md). When Service Ping is enabled, GitLab gathers data from other instances and enables certain [instance-level analytics features](../analytics/index.md) -that are dependent on Service Ping. - -### Why enable Service Ping? - -The main purpose of Service Ping is to build a better GitLab. We collect data about how GitLab is used -to understand feature or stage adoption and usage. This data gives an insight into how GitLab adds -value and helps our team understand the reasons why people use GitLab, and with this knowledge we're able to make better product decisions. - -There are several other benefits to enabling Service Ping: - -- Analyze the users' activities over time of your GitLab installation. -- A [DevOps Score](../analytics/dev_ops_reports.md#devops-score) to give you an overview of your entire instance's adoption of concurrent DevOps from planning to monitoring. -- More proactive support (assuming that our [Customer Success Managers (CSMs)](https://handbook.gitlab.com/job-families/sales/customer-success-management/) and support organization used the data to deliver more value). -- Insight and advice into how to get the most value out of your investment in GitLab. -- Reports that show how you compare against other similar organizations (anonymized), with specific advice and recommendations on how to improve your DevOps processes. -- Participation in our [Registration Features Program](#registration-features-program) to receive free paid features. - -## Registration Features Program - -> Introduced in GitLab 14.1. - -In GitLab versions 14.1 and later, GitLab Free customers with a self-managed instance running -GitLab Enterprise Edition can receive paid features by registering with GitLab and sending us -activity data through Service Ping. Features introduced here do not remove the feature from its paid -tier. Users can continue to access the features in a paid tier without sharing usage data. - -### Features available in 14.1 and later - -- [Email from GitLab](../email_from_gitlab.md). - -### 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-group-access-by-ip-address). - -### Features available in 16.0 and later - -- [View description change history](../../../user/discussions/index.md#view-description-change-history). -- [Maintenance mode](../../../administration/maintenance_mode/index.md). -- [Configurable issue boards](../../project/issue_board.md#configurable-issue-boards). -- [Coverage-guided fuzz testing](../../application_security/coverage_fuzzing/index.md). -- [Password complexity requirements](../../../user/admin_area/settings/sign_up_restrictions.md#password-complexity-requirements). - -NOTE: -Registration is not yet required for participation, but may be added in a future milestone. - -### Enable registration features - -1. Sign in as a user with administrator access. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Metrics and profiling**. -1. Expand the **Usage statistics** section. -1. If not enabled, select the **Enable Service Ping** checkbox. -1. Select the **Enable Registration Features** checkbox. -1. Select **Save changes**. - -## Version check - -If enabled, version check informs you if a new version is available and the -importance of it through a status. The status displays on the help pages (`/help`) -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. -- Red: The version of GitLab you are running is vulnerable. You should install - the latest version with security fixes as soon as possible. - - - -GitLab Inc. collects your instance's version and hostname (through the HTTP -referer) as part of the version check. No other information is collected. - -This information is used, among other things, to identify to which versions -patches must be backported, making sure active GitLab instances remain -secure. - -If you [disable version check](#enable-or-disable-usage-statistics), this information isn't collected. - -### Request flow example - -The following example shows a basic request/response flow between a -self-managed GitLab instance and the GitLab Version Application: - -```mermaid -sequenceDiagram - participant GitLab instance - participant Version Application - GitLab instance->>Version Application: Is there a version update? - loop Version Check - Version Application->>Version Application: Record version info - end - Version Application->>GitLab instance: Response (PNG/SVG) -``` - -## Configure your network - -To send usage statistics to GitLab Inc., you must allow network traffic from your -GitLab instance to the host `version.gitlab.com` on port `443`. - -If your GitLab instance is behind a proxy, set the appropriate -[proxy configuration variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html). - -## Enable or disable usage statistics - -To enable or disable Service Ping and version check: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Metrics and profiling**. -1. Expand **Usage statistics**. -1. Select or clear the **Enable version check** and **Enable Service Ping** checkboxes. -1. Select **Save changes**. - -NOTE: -Service Ping settings only control whether the data is being shared with GitLab, or used only internally. -Even if you disable Service Ping, the `gitlab_service_ping_worker` background job still periodically generates a Service Ping payload for your instance. -The payload is available in the [Service Usage data](#manually-upload-service-ping-payload) admin section. - -## Disable usage statistics with the configuration file - -NOTE: -The method to disable Service Ping in the GitLab configuration file does not work in -GitLab versions 9.3 to 13.12.3. For more information about how to disable it, see [troubleshooting](../../../development/internal_analytics/service_ping/troubleshooting.md#cannot-disable-service-ping-with-the-configuration-file). - -To disable Service Ping and prevent it from being configured in the future through -the Admin Area: - -**For installations using the Linux package:** - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_rails['usage_ping_enabled'] = false - ``` - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -**For installations from source:** - -1. Edit `/home/git/gitlab/config/gitlab.yml`: - - ```yaml - production: &base - # ... - gitlab: - # ... - usage_ping_enabled: false - ``` - -1. Restart GitLab: - - ```shell - sudo service gitlab restart - ``` - -## View the Service Ping payload - -You can view the exact JSON payload sent to GitLab Inc. in the Admin Area. To view the payload: - -1. Sign in as a user with administrator access. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Metrics and profiling**. -1. Expand the **Usage statistics** section. -1. Select **Preview payload**. - -For an example payload, see [Example Service Ping payload](../../../development/internal_analytics/service_ping/index.md#example-service-ping-payload). - -## Manually upload Service Ping payload - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7388) in GitLab 14.8 with a flag named `admin_application_settings_service_usage_data_center`. Disabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83265) in GitLab 14.10. - -You can upload the Service Ping payload to GitLab even if your instance doesn't have internet access, -or if the Service Ping [cron job](../../../development/internal_analytics/service_ping/index.md#how-service-ping-works) is not enabled. - -To upload the payload manually: - -1. Sign in as a user with administrator access. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Service** usage data. -1. Select **Download payload**. -1. Save the JSON file. -1. Visit [Service usage data center](https://version.gitlab.com/usage_data/new). -1. Select **Choose file** and choose the file from p5. -1. Select **Upload**. - -The uploaded file is encrypted and sent using secure HTTPS protocol. HTTPS creates a secure -communication channel between web browser and the server, and protects transmitted data against man-in-the-middle attacks. - -If there are problems with the manual upload: - -1. Open a confidential issue in the [security fork of version app project](https://gitlab.com/gitlab-org/security/version.gitlab.com). -1. Attach the JSON payload if possible. -1. Tag `@gitlab-org/analytics-section/analytics-instrumentation` who will triage the issue. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-13>. --> +<!-- 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/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index d145c351f3e..fae47358879 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -1,240 +1,11 @@ --- -stage: none -group: unassigned -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 +redirect_to: '../../../administration/settings/user_and_ip_rate_limits.md' +remove_date: '2023-10-14' --- -# User and IP rate limits **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/user_and_ip_rate_limits.md). -Rate limiting is a common technique used to improve the security and durability -of a web application. For more details, see -[Rate limits](../../../security/rate_limits.md). - -The following limits are disabled by default: - -- [Unauthenticated API requests (per IP)](#enable-unauthenticated-api-request-rate-limit). -- [Unauthenticated web requests (per IP)](#enable-unauthenticated-web-request-rate-limit). -- [Authenticated API requests (per user)](#enable-authenticated-api-request-rate-limit). -- [Authenticated web requests (per user)](#enable-authenticated-web-request-rate-limit). - -NOTE: -By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations -may trigger the rate limits configured for unauthenticated requests. - -NOTE: -[In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/344807), -the rate limits for API requests don't affect requests made by the frontend, as these are always -counted as web traffic. - -## Enable unauthenticated API request rate limit - -To enable the unauthenticated request rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **User and IP rate limits**. -1. Select **Enable unauthenticated API request rate limit**. - - - Optional. Update the **Maximum unauthenticated API requests per rate limit period per IP** value. - Defaults to `3600`. - - Optional. Update the **Unauthenticated rate limit period in seconds** value. - Defaults to `3600`. - -## Enable unauthenticated web request rate limit - -To enable the unauthenticated request rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **User and IP rate limits**. -1. Select **Enable unauthenticated web request rate limit**. - - - Optional. Update the **Maximum unauthenticated web requests per rate limit period per IP** value. - Defaults to `3600`. - - Optional. Update the **Unauthenticated rate limit period in seconds** value. - Defaults to `3600`. - -## Enable authenticated API request rate limit - -To enable the authenticated API request rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **User and IP rate limits**. -1. Select **Enable authenticated API request rate limit**. - - - Optional. Update the **Maximum authenticated API requests per rate limit period per user** value. - Defaults to `7200`. - - Optional. Update the **Authenticated API rate limit period in seconds** value. - Defaults to `3600`. - -## Enable authenticated web request rate limit - -To enable the unauthenticated request rate limit: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **User and IP rate limits**. -1. Select **Enable authenticated web request rate limit**. - - - Optional. Update the **Maximum authenticated web requests per rate limit period per user** value. - Defaults to `7200`. - - Optional. Update the **Authenticated web rate limit period in seconds** value. - Defaults to `3600`. - -## Use a custom rate limit response - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50693) in GitLab 13.8. - -A request that exceeds a rate limit returns a `429` response code and a -plain-text body, which by default is `Retry later`. - -To use a custom response: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > Network**. -1. Expand **User and IP rate limits**. -1. In the **Plain-text response to send to clients that hit a rate limit** text box, - add the plain-text response message. - -## Response headers - -> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/731) in GitLab 13.8, the `RateLimit` headers. `Retry-After` was introduced in an earlier version. - -When a client exceeds the associated rate limit, the following requests are -blocked. The server may respond with rate-limiting information allowing the -requester to retry after a specific period of time. These information are -attached into the response headers. - -| Header | Example | Description | -|:----------------------|:--------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `RateLimit-Limit` | `60` | The request quota for the client **each minute**. If the rate limit period set in the Admin Area is different from 1 minute, the value of this header is adjusted to approximately the nearest 60-minute period. | -| `RateLimit-Name` | `throttle_authenticated_web` | Name of the throttle blocking the requests. | -| `RateLimit-Observed` | `67` | Number of requests associated to the client in the time window. | -| `RateLimit-Remaining` | `0` | Remaining quota in the time window. The result of `RateLimit-Limit` - `RateLimit-Observed`. | -| `RateLimit-Reset` | `1609844400` | [Unix time](https://en.wikipedia.org/wiki/Unix_time)-formatted time when the request quota is reset. | -| `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | [RFC2616](https://www.rfc-editor.org/rfc/rfc2616#section-3.3.1)-formatted date and time when the request quota is reset. | -| `Retry-After` | `30` | Remaining duration **in seconds** until the quota is reset. This is a [standard HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | - -## Use an HTTP header to bypass rate limiting - -> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/622) in GitLab 13.6. - -Depending on the needs of your organization, you may want to enable rate limiting -but have some requests bypass the rate limiter. - -You can do this by marking requests that should bypass the rate limiter with a custom -header. You must do this somewhere in a load balancer or reverse proxy in front of -GitLab. For example: - -1. Pick a name for your bypass header. For example, `Gitlab-Bypass-Rate-Limiting`. -1. Configure your load balancer to set `Gitlab-Bypass-Rate-Limiting: 1` on requests - that should bypass GitLab rate limiting. -1. Configure your load balancer to either: - - Erase `Gitlab-Bypass-Rate-Limiting`. - - Set `Gitlab-Bypass-Rate-Limiting` to a value other than `1` on all requests that - should be affected by rate limiting. -1. Set the environment variable `GITLAB_THROTTLE_BYPASS_HEADER`. - - For [Linux package installations](https://docs.gitlab.com/omnibus/settings/environment-variables.html), - set `'GITLAB_THROTTLE_BYPASS_HEADER' => 'Gitlab-Bypass-Rate-Limiting'` in `gitlab_rails['env']`. - - For source installations, set `export GITLAB_THROTTLE_BYPASS_HEADER=Gitlab-Bypass-Rate-Limiting` - in `/etc/default/gitlab`. - -It is important that your load balancer erases or overwrites the bypass -header on all incoming traffic. Otherwise, you must trust your -users to not set that header and bypass the GitLab rate limiter. - -The bypass works only if the header is set to `1`. - -Requests that bypassed the rate limiter because of the bypass header -are marked with `"throttle_safelist":"throttle_bypass_header"` in -[`production_json.log`](../../../administration/logs/index.md#production_jsonlog). - -To disable the bypass mechanism, make sure the environment variable -`GITLAB_THROTTLE_BYPASS_HEADER` is unset or empty. - -## Allow specific users to bypass authenticated request rate limiting - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49127) in GitLab 13.7. - -Similarly to the bypass header described above, it is possible to allow -a certain set of users to bypass the rate limiter. This only applies -to authenticated requests: with unauthenticated requests, by definition -GitLab does not know who the user is. - -The allowlist is configured as a comma-separated list of user IDs in -the `GITLAB_THROTTLE_USER_ALLOWLIST` environment variable. If you want -users 1, 53 and 217 to bypass the authenticated request rate limiter, -the allowlist configuration would be `1,53,217`. - -- For [Linux package installations](https://docs.gitlab.com/omnibus/settings/environment-variables.html), - set `'GITLAB_THROTTLE_USER_ALLOWLIST' => '1,53,217'` in `gitlab_rails['env']`. -- For source installations, set `export GITLAB_THROTTLE_USER_ALLOWLIST=1,53,217` - in `/etc/default/gitlab`. - -Requests that bypassed the rate limiter because of the user allowlist -are marked with `"throttle_safelist":"throttle_user_allowlist"` in -[`production_json.log`](../../../administration/logs/index.md#production_jsonlog). - -At application startup, the allowlist is logged in [`auth.log`](../../../administration/logs/index.md#authlog). - -## Try out throttling settings before enforcing them - -> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/629) in GitLab 13.6. - -You can try out throttling settings by setting the `GITLAB_THROTTLE_DRY_RUN` environment variable to -a comma-separated list of throttle names. - -The possible names are: - -- `throttle_unauthenticated` - - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_api` or `throttle_unauthenticated_web` instead. - `throttle_unauthenticated` is still supported and selects both of them. -- `throttle_unauthenticated_api` -- `throttle_unauthenticated_web` -- `throttle_authenticated_api` -- `throttle_authenticated_web` -- `throttle_unauthenticated_protected_paths` -- `throttle_authenticated_protected_paths_api` -- `throttle_authenticated_protected_paths_web` -- `throttle_unauthenticated_packages_api` -- `throttle_authenticated_packages_api` -- `throttle_authenticated_git_lfs` -- `throttle_unauthenticated_files_api` -- `throttle_authenticated_files_api` -- `throttle_unauthenticated_deprecated_api` -- `throttle_authenticated_deprecated_api` - -For example, to try out throttles for all authenticated requests to -non-protected paths can be done by setting -`GITLAB_THROTTLE_DRY_RUN='throttle_authenticated_web,throttle_authenticated_api'`. - -To enable dry run mode for all throttles, the variable can be set to `*`. - -Setting a throttle to dry run mode logs a message to the -[`auth.log`](../../../administration/logs/index.md#authlog) when it would hit the limit, while letting the -request continue. The log message contains an `env` field set to `track`. The `matched` -field contains the name of throttle that was hit. - -It is important to set the environment variable **before** enabling -the rate limiting in the settings. The settings in the Admin Area -take effect immediately, while setting the environment variable -requires a restart of all the Puma processes. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-14>. --> +<!-- 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/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index dd53efaf518..c9ff105f8c9 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -1,363 +1,11 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +redirect_to: '../../../administration/settings/visibility_and_access_controls.md' +remove_date: '2023-10-14' --- -# Control access and visibility **(FREE SELF)** +This document was moved to [another location](../../../administration/settings/visibility_and_access_controls.md). -GitLab enables users with administrator access to enforce -specific controls on branches, projects, snippets, groups, and more. - -To access the visibility and access control options: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. - -## Define which roles can create projects - -Instance-level protections for project creation define which roles can -[add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group) -on the instance. To alter which roles have permission to create projects: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. For **Default project creation protection**, select the desired roles: - - No one. - - Maintainers. - - Developers and Maintainers. -1. Select **Save changes**. - -## Restrict project deletion to administrators **(PREMIUM SELF)** - -> User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. - -By default both administrators and anyone with the **Owner** role can delete a project. To restrict project deletion to only administrators: - -1. Sign in to GitLab as a user with administrator access. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. Scroll to: - - (GitLab 15.1 and later) **Allowed to delete projects**, and select **Administrators**. - - (GitLab 15.0 and earlier) **Default project deletion protection** and select **Only admins can delete project**. -1. Select **Save changes**. - -## Deletion protection **(PREMIUM SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2 for groups created after August 12, 2021. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) from default delayed project deletion in GitLab 15.1. -> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. -> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. -> - [Removed option to delete immediately](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `always_perform_delayed_deletion`. Disabled by default. -> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -Instance-level protection against accidental deletion of groups and projects. - -### Retention period - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. - -Groups and projects remain restorable within a defined retention period. By default this is 7 days but it can be changed. -Setting the retention period to `0` means that groups and project are removed immediately and cannot be restored. - -In GitLab 15.1 and later, the retention period must be between `1` and `90`. If the retention period was `0` before the 15.1 update, -then it gets automatically changed to `1` while also disabling deletion protection the next time any application setting is changed. - -### Delayed project deletion - -> - User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -To configure delayed project deletion: - -1. Sign in to GitLab as a user with administrator access. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. Scroll to: - - (In GitLab 15.11 and later with `always_perform_delayed_deletion` feature flag enabled, or GitLab 16.0 and later) **Deletion protection** and set the retention period to a value between `1` and `90`. - - (GitLab 15.1 and later) **Deletion protection** and select keep deleted groups and projects, and select a retention period. - - (GitLab 15.0 and earlier) **Default delayed project protection** and select **Enable delayed project deletion by - default for newly-created groups.** Then set a retention period in **Default deletion delay**. -1. Select **Save changes**. - -Deletion protection is not available for projects only (without being also being enabled for groups). - -In GitLab 15.1, and later this setting is enforced on groups when disabled and it cannot be overridden. - -### Delayed group deletion - -> - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -> - [Changed to default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) on the Premium and Ultimate tier in GitLab 16.0. - -Groups remain restorable if the retention period is `1` or more days. - -In GitLab 15.1 and later, delayed group deletion can be enabled by setting **Deletion projection** to **Keep deleted**. -In GitLab 15.11 and later with the `always_perform_delayed_deletion` feature flag enabled, or in GitLab 16.0 and later: - -- The **Keep deleted** option is removed. -- Delayed group deletion is the default. - -### Override defaults and delete immediately - -Alternatively, projects that are marked for removal can be deleted immediately. To do so: - -1. [Restore the project](../../project/settings/index.md#restore-a-project). -1. Delete the project as described in the - [Administering Projects page](../../admin_area/index.md#administering-projects). - -## Configure project visibility defaults - -To set the default [visibility levels for new projects](../../public_access.md): - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -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 authenticated user except external users. - - **Public** - The project can be accessed without any authentication. -1. Select **Save changes**. - -## Configure snippet visibility defaults - -To set the default visibility levels for new [snippets](../../snippets.md): - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. Select the desired default snippet visibility. -1. Select **Save changes**. - -For more details on snippet visibility, read -[Project visibility](../../public_access.md). - -## Configure group visibility defaults - -To set the default visibility levels for new groups: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -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 authenticated user except external users. - - **Public** - The group and any public projects can be viewed without any authentication. -1. Select **Save changes**. - -For more details on group visibility, see -[Group visibility](../../group/index.md#group-visibility). - -## Restrict visibility levels - -When restricting visibility levels, consider how these restrictions interact -with permissions for subgroups and projects that inherit their visibility from -the item you're changing. - -To restrict visibility levels for groups, projects, snippets, and selected pages: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -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: - - Only administrators are able to create public groups, projects, and snippets. - - User profiles are only visible to authenticated users through the Web interface. - - User attributes through 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. - - If you restrict the **Internal** level: - - Only administrators are able to create internal groups, projects, and snippets. - - If you restrict the **Private** level: - - Only administrators are able to create private groups, projects, and snippets. -1. Select **Save changes**. - -For more details on project visibility, see -[Project visibility](../../public_access.md). - -## Configure allowed import sources - -Before you can import projects from other systems, you must enable the -[import source](../../gitlab_com/index.md#default-import-sources) for that system. - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. Select each of **Import sources** to allow. -1. Select **Save changes**. - -## Enable project export - -To enable the export of -[projects and their data](../../project/settings/import_export.md#export-a-project-and-its-data): - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -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 using the UI. - -To enable migration of groups by direct transfer: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. 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**. - -The same setting -[is available](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) in the API as the -`bulk_import_enabled` attribute. - -## Configure enabled Git access protocols - -With GitLab access restrictions, you can select the protocols users can use to -communicate with GitLab. Disabling an access protocol does not block port access to the -server itself. The ports used for the protocol, SSH or HTTP(S), are still accessible. -The GitLab restrictions apply at the application level. - -To specify the enabled Git access protocols: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. Select the desired Git access protocols: - - Both SSH and HTTP(S) - - Only SSH - - Only HTTP(S) -1. Select **Save changes**. - -When both SSH and HTTP(S) are enabled, users can choose either protocol. -If only one protocol is enabled: - -- The project page shows only the allowed protocol's URL, with no option to - change it. -- GitLab shows a tooltip when you hover over the protocol for the URL, if user action - (such as adding a SSH key or setting a password) is required: - -  - -GitLab only allows Git actions for the protocols you select. - -WARNING: -GitLab versions [10.7 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021), -allow the HTTP(S) protocol for Git clone or fetch requests done by GitLab Runner -from CI/CD jobs, even if you select **Only SSH**. - -## Customize Git clone URL for HTTP(S) - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18422) in GitLab 12.4. - -You can customize project Git clone URLs for HTTP(S), which affects the clone -panel: - -For example, if: - -- Your GitLab instance is at `https://example.com`, then project clone URLs are like - `https://example.com/foo/bar.git`. -- You want clone URLs that look like `https://git.example.com/gitlab/foo/bar.git` instead, - you can set this setting to `https://git.example.com/gitlab/`. - - - -To specify a custom Git clone URL for HTTP(S): - -1. Enter a root URL for **Custom Git clone URL for HTTP(S)**. -1. Select **Save changes**. - -NOTE: -SSH clone URLs can be customized in `gitlab.rb` by setting `gitlab_rails['gitlab_ssh_host']` and -other related settings. - -## Configure defaults for RSA, DSA, ECDSA, ED25519, ECDSA_SK, ED25519_SK SSH keys - -These options specify the permitted types and lengths for SSH keys. - -To specify a restriction for each key type: - -1. Select the desired option from the dropdown list. -1. Select **Save changes**. - -For more details, see [SSH key restrictions](../../../security/ssh_keys_restrictions.md). - -## Enable project mirroring - -This option is enabled by default. By disabling it, both -[pull mirroring](../../project/repository/mirror/pull.md) and [push mirroring](../../project/repository/mirror/push.md) no longer -work in every repository. They can only be re-enabled by an administrator user on a per-project basis. - - - -## Configure globally-allowed IP address ranges - -> - [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-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. - -For example, if the GitLab Pages daemon runs on the `10.0.0.0/24` range, you can specify that range as globally-allowed. -This means GitLab Pages can still fetch artifacts from pipelines even if group-level IP address restrictions don't -include the `10.0.0.0/24` range. - -To add a IP address range to the group-level allowlist: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. In **Globally-allowed IP ranges**, provide a list of IP address ranges. 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**. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, 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. --> +<!-- This redirect file can be deleted after <2023-10-14>. --> +<!-- 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/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index 6f2798f437c..b0b4facd7db 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -1,40 +1,11 @@ --- -stage: none -group: unassigned -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: '../../administration/user_cohorts.md' +remove_date: '2023-10-11' --- -# Cohorts **(FREE SELF)** +This document was moved to [another location](../../administration/user_cohorts.md). -You can analyze your users' GitLab activities over time. - -How do you interpret the user cohorts table? Let's review an example with the -following user cohorts: - - - -For the cohort of March 2020, three users were added to this server and have -been active since this month. One month later (April 2020), two users are still -active. Five months later (August 2020), one user from this cohort is still -active, or 33% of the original cohort of three that joined in March. - -The **Inactive users** column shows the number of users who were added during -the month, but who never had any activity in the instance. - -How do we measure the activity of users? GitLab considers a user active if: - -- The user signs in. -- The user has Git activity (whether push or pull). -- The user visits pages related to dashboards, projects, issues, or merge - requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54947) in GitLab 11.8). -- The user uses the API. -- The user uses the GraphQL API. - -## View user cohorts - -To view user cohorts: - -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select the **Cohorts** tab. +<!-- This redirect file can be deleted after <2023-10-11>. --> +<!-- 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/ai_features.md b/doc/user/ai_features.md index d5f7201556e..b9bcaec8b57 100644 --- a/doc/user/ai_features.md +++ b/doc/user/ai_features.md @@ -46,20 +46,14 @@ The following feature is in Beta: ## Experiment AI features -[Experiment features](../policy/experiment-beta-support.md#experiment) will soon require -[Experiment features to be enabled](group/manage.md#enable-experiment-features). - -## Third-party AI features - -Third-party AI features require [third-party AI services to be enabled](group/manage.md#enable-third-party-ai-features). - -For Experiment third-party AI features, [Experiment features must be enabled](group/manage.md#enable-experiment-features) as well. +[Experiment](../policy/experiment-beta-support.md#experiment) AI features require +[Experiment features to be enabled](group/manage.md#enable-experiment-features) as well as [third-party AI services to be enabled](group/manage.md#enable-third-party-ai-features). ### Explain Selected Code in the Web UI **(ULTIMATE SAAS)** > Introduced in GitLab 15.11 as an [Experiment](../policy/experiment-beta-support.md#experiment) on GitLab.com. -This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. +This AI feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by Google's Codey for Code Chat (codechat-bison). GitLab can help you get up to speed faster if you: @@ -70,16 +64,32 @@ By using a large language model, GitLab can explain the code in natural language Prerequisites: -- The project must be a public project on GitLab.com. +Additional prerequisites [beyond the two above](#experiment-ai-features). + +- The project must be on GitLab.com. - You must have the GitLab Ultimate subscription tier. -- You must be a member of the project. +- You must be a member of the project with sufficient permissions to view the repository. To explain your code: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select any file in your project that contains code. +1. On the file, select the lines that you want to have explained. +1. On the left side, select the question mark (**{question}**). You might have to scroll to the first line of your selection to view it. This sends the selected code, together with a prompt, to provide an explanation to the large language model. +1. A drawer is displayed on the right side of the page. Wait a moment for the explanation to be generated. +1. Provide feedback about how satisfied you are with the explanation, so we can improve the results. + +You can also have code explained in the context of a merge request. To explain +code in a merge request: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. On the left sidebar, select **Code > Merge requests**, then select your merge request. 1. On the secondary menu, select **Changes**. -1. Go to the file, and select the lines that you want to have explained. +1. On the file you would like explained, select the three dots (**{ellipsis_v}**) and select **View File @ $SHA**. + + A separate browser tab opens and shows the full file with the latest changes. + +1. On the new tab, select the lines that you want to have explained. 1. On the left side, select the question mark (**{question}**). You might have to scroll to the first line of your selection to view it. This sends the selected code, together with a prompt, to provide an explanation to the large language model. 1. A drawer is displayed on the right side of the page. Wait a moment for the explanation to be generated. 1. Provide feedback about how satisfied you are with the explanation, so we can improve the results. @@ -120,20 +130,23 @@ Review the drawer on the right-hand side of your screen. We cannot guarantee that the large language model produces results that are correct. Use the explanation with caution. -### GitLab Chat **(ULTIMATE SAAS)** +### GitLab Duo Chat **(ULTIMATE SAAS)** > Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). This feature is an [Experiment](../policy/experiment-beta-support.md) on GitLab.com that is powered by OpenAI's GPT-3. It requires the [group-level third-party AI features setting](group/manage.md#enable-third-party-ai-features) to be enabled. -Getting help has never been easier. If you have a question about how the GitLab product works, you can ask product how-to questions and get AI generated support from GitLab Chat. +Getting help has never been easier. If you have a question about how the GitLab product works, you can ask product how-to questions and get AI generated support from GitLab Duo Chat. 1. In the lower-left corner, select the Help icon. -1. Select **Ask in GitLab Chat**. A drawer opens on the right side of your screen. +1. Select **Ask in GitLab Duo Chat**. A drawer opens on the right side of your screen. 1. Enter your question in the chat input box and press **Enter** or select **Send**. It may take a few seconds for the interactive AI chat to search the product documentation and produce an answer. To give feedback, select the **Give Feedback** link. +NOTE: +Only the last 50 messages in the chat history are retained. The chat history expires 3 days after last use. + ### Summarize merge request changes **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10400) in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md index e29e02c867f..9d2c91b6bc8 100644 --- a/doc/user/analytics/analytics_dashboards.md +++ b/doc/user/analytics/analytics_dashboards.md @@ -9,21 +9,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 15.9 as an [Experiment](../../policy/experiment-beta-support.md#experiment) feature [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. 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 `combined_analytics_dashboards`. +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. On GitLab.com, this feature is not available. This feature is not ready for production use. -## Dashboards +Analytics dashboards help you visualize the collected data. +You can use built-in dashboards or create your own with custom visualizations. -Each project can have an unlimited number of dashboards, only limited by the instances [repository size limits](../project/repository/reducing_the_repo_size_using_git.md#storage-limits). -These dashboards are defined using the GitLab YAML schema, and stored in the `.gitlab/analytics/dashboards/` directory of a project repository. -The dashboard file name and containing directory should be the same, for example `my_dashboard/my_dashboard.yaml`. For more information see [defining a dashboard](#define-a-dashboard). -Each dashboard can reference one or more [visualizations](#define-a-chart-visualization), which are shared across dashboards. - -Project maintainers can enforce approval rules on dashboard changes using features such as [code owners](../project/codeowners/index.md) and [approval rules](../project/merge_requests/approvals/rules.md). -Your dashboard files are versioned in source control with the rest of a project's code. - -### Data sources +## Data sources A data source is a connection to a database or collection of data which can be used by your dashboard filters and visualizations to query and retrieve results. @@ -32,15 +25,96 @@ The following data sources are configured for analytics dashboards: - [Product analytics](../product_analytics/index.md) -### View project dashboards +## Built-in dashboards + +To help you get started with analytics, GitLab provides two built-in dashboards with predefined visualizations: + +- **Audience**, which displays metrics related to traffic, such as number of users and sessions. +- **Behavior**, which displays metrics related to user activity, such as number of page views and events. + +These dashboards are labeled **By GitLab**, and you cannot edit them. +Instead, you can create a custom dashboard with a similar style. + +## Custom dashboards -To view a list of dashboards for a project: +With custom dashboards, you can design and create visualizations for the metrics that are most relevant to your use case. +You can create custom dashboards with the dashboard designer. + +- Each project can have an unlimited number of dashboards. +The only limitation might be the [repository size limit](../project/repository/reducing_the_repo_size_using_git.md#storage-limits). +- Each dashboard can reference one or more [visualizations](#define-a-chart-visualization). +- Visualizations are shared across dashboards. + +Project maintainers can enforce approval rules on dashboard changes with features such as [code owners](../project/codeowners/index.md) and [approval rules](../project/merge_requests/approvals/rules.md). +Your dashboard files are versioned in source control with the rest of a project's code. + +## Dashboard designer + +> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. 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, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +NOTE: +This feature does not work in conjunction with the `product_analytics_snowplow_support` feature flag. + +You can use the dashboard designer to: + +- Create custom dashboards. +- Rename custom dashboards. +- Add visualizations to new and existing custom dashboards. +- Resize or move panels in custom dashboards. + +## View project dashboards + +To view a list of dashboards (both built-in and custom) for a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Analyze > Dashboards**. 1. From the list of available dashboards, select the dashboard you want to view. -### Define a dashboard +## Change the location of dashboards + +You can change the location of your project or group dashboards. + +### Group dashboards + +NOTE: +This feature will be connected to group-level dashboards as part of [issue #411572](https://gitlab.com/gitlab-org/gitlab/-/issues/411572). + +To change the location of a group's dashboards: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project you want to store your dashboard files in. + The project must belong to the group for which you create the dashboards. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. +1. Expand **Analytics**. +1. In the **Analytics Dashboards** section, select your dashboard files project. +1. Select **Save changes**. + +### Project dashboards + +Dashboards are usually defined in the project where the analytics data is being retrieved from. +However, you can also have a separate project for dashboards. +This is recommended if you want to enforce specific access rules to the dashboard definitions or share dashboards across multiple projects. + +NOTE: +You can share dashboards only between projects that are located in the same group. + +To change the location of project dashboards: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project, + or select **Create new...** (**{plus}**) and **New project/repository** + to create the project to store your dashboard files. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and find the analytics project. +1. Select **Settings > General**. +1. Expand **Analytics**. +1. In the **Analytics Dashboards** section, select your dashboard files project. +1. Select **Save changes**. + +## Define a dashboard To define a dashboard: @@ -67,7 +141,7 @@ and one visualization (line chart) that applies to all dashboards, the file stru │ └── example_line_chart.yaml ``` -### Define a chart visualization +## Define a chart visualization You can define different charts, and add visualization options to some of them: @@ -91,65 +165,7 @@ create a `line_chart.yaml` file with the following required fields: - data - options -### Change the location of project dashboards - -Dashboards are usually defined in the project where analytics data is being retrieved. -However, you can also have a separate project for dashboards. -This is recommended if you want to enforce specific access rules to the dashboard definitions or share dashboards across multiple projects. - -NOTE: -You can share dashboards only between projects that are located in the same group. - -To change the location of project dashboards: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project, - or select **Create new...** (**{plus}**) and **New project/repository** - to create the project to store your dashboard files. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and find the project you want to use the dashboards for. -1. Select **Settings > General**. -1. Expand **Analytics**. -1. In the **Analytics Dashboards** section, select the project that contains the dashboard files. -1. Select **Save changes**. - -### Change the location of group dashboards - -NOTE: -This feature will be connected to group-level dashboards in [issue 411572](https://gitlab.com/gitlab-org/gitlab/-/issues/411572). - -If you want to use dashboards for a group, you must store the dashboard files in a project that belongs to that group. -You can change the source project of a group's dashboards at any time. - -To change the location of a group's dashboards: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Settings > General**. -1. Expand **Analytics**. -1. In the **Analytics Dashboards** section, select the project that contains the dashboard files. -1. Select **Save changes**. - -## Dashboards designer - -> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. 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 `combined_analytics_dashboards_editor`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. - -NOTE: -This feature does not work in conjunction with the `product_analytics_snowplow_support` feature flag. - -You can use the dashboards designer to: - -- Create custom dashboards -- Rename custom dashboards -- Add visualizations to new and existing custom dashboards -- Resize or move panels within custom dashboards - -You cannot edit the built-in dashboards labeled as `By GitLab`. -To edit these dashboards you should create a new custom dashboard which uses the same visualizations. - -### Create a custom dashboard +## Create a custom dashboard To create a custom dashboard: @@ -161,9 +177,9 @@ To create a custom dashboard: 1. Optional. Drag or resize the selected panel how you prefer. 1. Select **Save**. -### Edit a custom dashboard +## Edit a custom dashboard -You can edit your custom dashboard's title and add or resize visualizations within the dashboard designer. +You can edit your custom dashboard's title and add or resize visualizations in the dashboard designer. To edit an existing custom dashboard: @@ -175,3 +191,20 @@ To edit an existing custom dashboard: 1. Optional. From the **Add visualizations** list on the right, select other visualizations to add to the dashboard. 1. Optional. In the dashboard, select a panel and drag or resize it how you prefer. 1. Select **Save**. + +## Troubleshooting + +### `Something went wrong while loading the dashboard.` + +If the dashboard displays a global error message that data could not be loaded, first try reloading the page. If the error persists: + +- Check that your configurations match the [JSON schema](#define-a-dashboard) defined in `ee/app/validators/json_schemas/analytics_dashboard.json`. +- For product analytics, check your [admin and project settings](../product_analytics/index.md#project-level-settings), and make sure they are set up correctly. + +### Dashboard panel error + +If a dashboard panel displays an error message: + +- Check your [Cube query](../product_analytics/index.md#product-analytics-dashboards) and [visualization](../analytics/analytics_dashboards.md#define-a-chart-visualization) +configurations, and make sure they are set up correctly. +- For [product analytics](../product_analytics/index.md), also check that your visualization's Cube query is valid. diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index 6b7b1d87843..bdfeffcec05 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -43,7 +43,7 @@ High deployment frequency means you can get feedback sooner and iterate faster t ### How deployment frequency is calculated In GitLab, Deployment frequency is measured by the average number of deployments per day to a given environment, based on the deployment's end time (its `finished_at` property). -GitLab calculates the deployment frequency from the number of finished deployments on the given day. +GitLab calculates the deployment frequency from the number of finished deployments on the given day. Only successful deployments (`Deployment.statuses = success`) are counted. The calculation takes into account the production `environment tier` or the environments named `production/prod`. The environment must be part of the production deployment tier for its deployment information to appear on the graphs. diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index e78f55911e6..c057a8b193d 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -27,7 +27,7 @@ GitLab provides several analytics features at the group level. Some of these fea - [Issue](../group/issues_analytics/index.md) - [Productivity](productivity_analytics.md) - [Repositories](../group/repositories_analytics/index.md) -- [Value Stream](../group/value_stream_analytics/index.md) +- [Value Stream Management Analytics](value_stream_analytics.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) ## Project-level analytics @@ -43,7 +43,7 @@ You can use GitLab to review analytics at the project level. Some of these featu - [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development) - [Repository](repository_analytics.md) -- [Value Stream](value_stream_analytics.md) +- [Value Stream Management Analytics](value_stream_analytics.md), and [Value Stream Management Dashboard](value_streams_dashboard.md) ### Remove project analytics from the left sidebar diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index 9b332d78060..a853263d20f 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -11,15 +11,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392734) in GitLab 16.0. Feature flag `group_analytics_dashboards_page` removed. You can leave feedback on dashboard bugs or functionality in [issue 381787](https://gitlab.com/gitlab-org/gitlab/-/issues/381787). +For more information, see also the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). -The Value Streams Dashboard is a customizable dashboard that enables 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/). +The Value Streams Dashboard is a customizable dashboard you can use to identify trends, patterns, and opportunities for digital transformation improvements. -## 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. +With the Value Streams Dashboard, you can compare software delivery metrics. +This comparison can help you understand whether projects and groups are improving. The Value Streams Dashboard includes the following metrics: @@ -57,7 +54,7 @@ To view the value streams dashboard: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Analyze > Value stream analytics**. -1. Below the **Filter results** text box, in the **Key metrics** row, select **Value Streams Dashboard / DORA**. +1. Below the **Filter results** text box, in the **Lifecycle metrics** row, select **Value Streams Dashboard / DORA**. 1. Optional. To open the new page, append this path `/analytics/dashboards/value_streams_dashboard` to the group URL (for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards/value_streams_dashboard`). @@ -79,7 +76,8 @@ For example, the parameter `query=gitlab-org/gitlab-ui,gitlab-org/plan-stage` di ### Using YAML configuration -To change the default content of the page, you need to create a YAML configuration file in a project of your choice. Query parameters can still be used to override the YAML configuration. +To customize the default content of the page, you need to create a YAML configuration file in a project of your choice. In this file you can define various settings and parameters, such as title, description, and number of panels and labels filters. The file is schema-driven and managed with version control systems like Git. This enables tracking and maintaining a history of configuration changes, reverting to previous versions if necessary, and collaborating effectively with team members. +Query parameters can still be used to override the YAML configuration. First, you need to set up the project. @@ -110,12 +108,25 @@ description: 'Custom description' # title - Change the title of the panel. [optional] # data.namespace - The Group or Project path to use for the chart panel. # data.exclude_metrics - Hide rows by metric ID from the chart panel. +# data.filter_labels - +# Only show results for data that matches the queried label(s). If multiple labels are provided, +# only a single label needs to match for the data to be included in the results. +# Compatible metrics (other metrics will be automatically excluded): +# * lead_time +# * cycle_time +# * issues +# * issues_completed +# * merge_request_throughput +# (This option is dependant on the `vsd_graphql_dora_and_flow_metrics` feature.) panels: - title: 'My Custom Project' data: namespace: group/my-custom-project - data: namespace: group/another-project + filter_labels: + - in_development + - in_review - title: 'My Custom Group' data: namespace: group/my-custom-group @@ -134,6 +145,9 @@ panels: namespace: my-group ``` +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview of editing label filters in the configuration file, see [GitLab Value Streams Dashboard - Label filters demo](https://www.youtube.com/watch?v=4qDAHCxCfik). + ## Dashboard metrics and drill-down reports | Metric | Description | Drill-down report | Documentation page | ID | @@ -142,8 +156,8 @@ panels: | Lead time for changes | The time to successfully deliver a commit into production. This metric reflects the efficiency of CI/CD pipelines. | [Lead time tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=lead-time) | [Lead time for changes](dora_metrics.md#lead-time-for-changes) | `lead_time_for_changes` | | Time to restore service | The time it takes an organization to recover from a failure in production. | [Time to restore service tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=time-to-restore-service) | [Time to restore service](dora_metrics.md#time-to-restore-service) | `time_to_restore_service` | | Change failure rate | Percentage of deployments that cause an incident in production. | [Change failure rate tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=change-failure-rate) | [Change failure rate](dora_metrics.md#change-failure-rate) | `change_failure_rate` | -| Lead time | Median time from issue created to issue closed. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#key-metrics) | `lead_time` | -| Cycle time | Median time from the earliest commit of a linked issue's merge request to when that issue is closed. | [VSA overview](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#key-metrics) | `cycle_time` | +| Lead time | Median time from issue created to issue closed. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#lifecycle-metrics) | `lead_time` | +| Cycle time | Median time from the earliest commit of a linked issue's merge request to when that issue is closed. | [VSA overview](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](../group/value_stream_analytics/index.md#lifecycle-metrics) | `cycle_time` | | New issues | Number of new issues created. | [Issue Analytics](https://gitlab.com/groups/gitlab-org/-/issues_analytics) | Issue analytics [for projects](issue_analytics.md) and [for groups](../../user/group/issues_analytics/index.md) | `issues` | | Closed issues | Number of issues closed by month. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [Value Stream Analytics](../group/value_stream_analytics/index.md) | `issues_completed` | | Number of deploys | Total number of deploys to production. | [Merge Request Analytics](https://gitlab.com/gitlab-org/gitlab/-/analytics/merge_request_analytics) | [Merge request analytics](merge_request_analytics.md) | `deploys` | diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 28e72816a99..e8feb0f4a59 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -2032,7 +2032,7 @@ Follow these steps to view details of a fuzzing fault: 1. You can view faults in a project, or a merge request: - - In a project, go to the project's **Security and Compliance > Vulnerability Report** + - In a project, go to the project's **Secure > Vulnerability report** page. This page shows all vulnerabilities from the default branch only. - In a merge request, go the merge request's **Security** section and select the **Expand** button. API Fuzzing faults are available in a section labeled @@ -2452,7 +2452,7 @@ See the following documentation sections for assistance: See [Performance Tuning and Testing Speed](#performance-tuning-and-testing-speed) -### Error waiting for API Fuzzing 'http://127.0.0.1:5000' to become available +### Error: `Error waiting for API Fuzzing 'http://127.0.0.1:5000' to become available` A bug exists in versions of the API Fuzzing analyzer prior to v1.6.196 that can cause a background process to fail under certain conditions. The solution is to update to a newer version of the API Fuzzing analyzer. diff --git a/doc/user/application_security/comparison_dependency_and_container_scanning.md b/doc/user/application_security/comparison_dependency_and_container_scanning.md new file mode 100644 index 00000000000..d02d94b7a3e --- /dev/null +++ b/doc/user/application_security/comparison_dependency_and_container_scanning.md @@ -0,0 +1,34 @@ +--- +stage: Secure +group: Composition Analysis +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 +--- + +# Dependency Scanning compared to Container Scanning + +GitLab offers both [Dependency Scanning](dependency_scanning/index.md) and +[Container Scanning](container_scanning/index.md) to ensure coverage for all of these +dependency types. To cover as much of your risk area as possible, we encourage you to use all of our +security scanning tools: + +- Dependency Scanning analyzes your project and tells you which software dependencies, + including upstream dependencies, have been included in your project, and what known + risks the dependencies contain. +- Container Scanning analyzes your containers and tells you about known risks in the operating + system's (OS) packages. + +The following table summarizes which types of dependencies each scanning tool can detect: + +| Feature | Dependency Scanning | Container Scanning | +|----------------------------------------------------------------------------------------------|---------------------|----------------------------------------------| +| Identify the manifest, lock file, or static file that introduced the dependency | **{check-circle}** | **{dotted-circle}** | +| Development dependencies | **{check-circle}** | **{dotted-circle}** | +| Dependencies in a lock file committed to your repository | **{check-circle}** | **{check-circle}** <sup>1</sup> | +| Binaries built by Go | **{dotted-circle}** | **{check-circle}** <sup>2</sup> <sup>3</sup> | +| Dynamically-linked language-specific dependencies installed by the Operating System | **{dotted-circle}** | **{check-circle}** <sup>3</sup> | +| Operating system dependencies | **{dotted-circle}** | **{check-circle}** | +| Language-specific dependencies installed on the operating system (not built by your project) | **{dotted-circle}** | **{check-circle}** | + +1. Lock file must be present in the image to be detected. +1. Binary file must be present in the image to be detected. +1. Only when using Trivy. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 042ed0190c4..791a73bfdc2 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -32,7 +32,8 @@ you wrote yourself. GitLab offers both Container Scanning and [Dependency Scanning](../dependency_scanning/index.md) to ensure coverage for all of these dependency types. To cover as much of your risk area as -possible, we encourage you to use all of our security scanners. +possible, we encourage you to use all of our security scanners. For a comparison of these features, see +[Dependency Scanning compared to Container Scanning](../comparison_dependency_and_container_scanning.md). ## Overview @@ -240,8 +241,7 @@ When you enable this feature, you may see [duplicate findings](../terminology/in in the [Vulnerability Report](../vulnerability_report/index.md) if [Dependency Scanning](../dependency_scanning/index.md) is enabled for your project. This happens because GitLab can't automatically deduplicate findings -across different types of scanning tools. Reference [this comparison](../dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning) -between GitLab Dependency Scanning and Container Scanning for more details on which types of dependencies are likely to be duplicated. +across different types of scanning tools. To understand which types of dependencies are likely to be duplicated, see [Dependency Scanning compared to Container Scanning](../comparison_dependency_and_container_scanning.md). #### Available CI/CD variables @@ -328,7 +328,7 @@ To enable Container Scanning in a project, create a merge request from the Secur page: 1. In the project where you want to enable Container Scanning, go to - **Security and Compliance > Security configuration**. + **Secure > Security configuration**. 1. In the **Container Scanning** row, select **Configure with a merge request**. This automatically creates a merge request with the changes necessary to enable Container Scanning. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 7b263e5817d..0338555598c 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -189,7 +189,7 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, selecting a link, or filling a form. | | `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | | `DAST_BROWSER_MAX_RESPONSE_SIZE_MB` | number | `15` | The maximum size of a HTTP response body. Responses with bodies larger than this are blocked by the browser. Defaults to 10 MB. | -| `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_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. Defaults to `800ms`.| | `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_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`. | @@ -212,6 +212,75 @@ For authentication CI/CD variables, see [Authentication](authentication.md). | `DAST_WEBSITE` | URL | `https://example.com` | The URL of the website to scan. | | `SECURE_ANALYZERS_PREFIX` | URL | `registry.organization.com` | Set the Docker registry base address from which to download the analyzer. | +## Managing scope + +Scope controls what URLs DAST follows when crawling the target application. Properly managed scope minimizes scan run time while ensuring only the target application is checked for vulnerabilities. + +### Types of scope + +There are three types of scope: + +- in scope +- out of scope +- excluded from scope + +#### In scope + +DAST follows in-scope URLs and searches the DOM for subsequent actions to perform to continue the crawl. +Recorded in-scope HTTP messages are passively checked for vulnerabilities and used to build attacks when running a full scan. + +#### Out of scope + +DAST follows out-of-scope URLs for non-document content types such as image, stylesheet, font, script, or AJAX request. +[Authentication](#scope-works-differently-during-authentication) aside, DAST does not follow out-of-scope URLs for full page loads, such as when clicking a link to an external website. +Except for passive checks that search for information leaks, recorded HTTP messages for out-of-scope URLs are not checked for vulnerabilities. + +#### Excluded from scope + +DAST does not follow excluded-from-scope URLs. Except for passive checks that search for information leaks, recorded HTTP messages for excluded-from-scope URLs are not checked for vulnerabilities. + +### Scope works differently during authentication + +Many target applications have an authentication process that depends on external websites, such as when using an identity access management provider for single sign on (SSO). +To ensure that DAST can authenticate with these providers, DAST follows out-of-scope URLs for full page loads during authentication. DAST does not follow excluded-from-scope URLs. + +### How DAST blocks HTTP requests + +DAST instructs the browser to make the HTTP request as usual when blocking a request due to scope rules. The request is subsequently intercepted and rejected with the reason `BlockedByClient`. +This approach allows DAST to record the HTTP request while ensuring it never reaches the target server. Passive checks such as [200.1](checks/200.1.md) use these recorded requests to verify information sent to external hosts. + +### How to configure scope + +By default, URLs matching the host of the target application are considered in-scope. All other hosts are considered out-of-scope. + +Scope is configured using the following variables: + +- Use `DAST_BROWSER_ALLOWED_HOSTS` to add in-scope hosts. +- Use `DAST_BROWSER_IGNORED_HOSTS` to add to out-of-scope hosts. +- Use `DAST_BROWSER_EXCLUDED_HOSTS` to add to excluded-from-scope hosts. +- Use `DAST_EXCLUDE_URLS` to set specific URLs to be excluded-from-scope. + +Rules: + +- Excluding a host is given priority over ignoring a host, which is given priority over allowing a host. +- Configuring scope for a host does not configure scope for the subdomains of that host. +- Configuring scope for a host does not configure scope for all ports on that host. + +The following could be a typical configuration: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://my.site.com" # my.site.com URLs are considered in-scope by default + DAST_BROWSER_ALLOWED_HOSTS: "api.site.com:8443" # include the API as part of the scan + DAST_BROWSER_IGNORED_HOSTS: "analytics.site.com" # explicitly disregard analytics from the scan + DAST_BROWSER_EXCLUDED_HOSTS: "ads.site.com" # don't visit any URLs on the ads subdomain + DAST_EXCLUDE_URLS: "https://my.site.com/user/logout" # don't visit this URL +``` + ## Vulnerability detection Vulnerability detection is gradually being migrated from the default Zed Attack Proxy (ZAP) solution diff --git a/doc/user/application_security/dast/browser_based_troubleshooting.md b/doc/user/application_security/dast/browser_based_troubleshooting.md index 6cc80bcfbc3..f659001e7c5 100644 --- a/doc/user/application_security/dast/browser_based_troubleshooting.md +++ b/doc/user/application_security/dast/browser_based_troubleshooting.md @@ -100,7 +100,7 @@ For example, the following log entry has level `INFO`, is part of the `CRAWL` lo Logs are sent either to file or to console (the CI/CD job log). You can configure each destination to accept different logs using the environment variables `DAST_BROWSER_LOG` for console logs and `DAST_BROWSER_FILE_LOG` for file logs. -In the following example, the file log defaults to `DEBUG` level, the console log defaults to `INFO` level and logs the `AUTH` module at `DEBUG` level. +For example: ```yaml include: @@ -108,9 +108,10 @@ include: dast: variables: - DAST_BROWSER_LOG: "auth:debug" - DAST_BROWSER_FILE_LOG: "loglevel:debug" - DAST_BROWSER_FILE_LOG_PATH: "/zap/wrk/dast-scan.log" + DAST_BROWSER_SCAN: "true" + DAST_BROWSER_LOG: "auth:debug" # console log defaults to INFO level, logs AUTH module at DEBUG + DAST_BROWSER_FILE_LOG: "loglevel:debug,cache:warn" # file log defaults to DEBUG level, logs CACHE module at WARN + DAST_BROWSER_FILE_LOG_PATH: "$CI_PROJECT_DIR/dast-scan.log" # Save the file log in the project directory so it can be recognized as an artifact artifacts: paths: - dast-scan.log diff --git a/doc/user/application_security/dast/checks/16.9.md b/doc/user/application_security/dast/checks/16.9.md index b0ba502b578..c63a620794e 100644 --- a/doc/user/application_security/dast/checks/16.9.md +++ b/doc/user/application_security/dast/checks/16.9.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description A `Content-Security-Policy-Report-Only` (CSPRO) was identified on the target site. CSP-Report-Only headers -aid in determining how to implement a `Content-Security-Policy` that does not disrupt normal use of the target +aid in determining how to implement a `Content-Security-Policy` that does not disrupt use of the target site. ## Remediation diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 499efd3f60d..0eec04bfeff 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -461,132 +461,95 @@ The DAST job does not require the project's repository to be present when runnin ## On-demand scans -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. -> - The saved scans feature was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5100) in GitLab 13.9. -> - The option to select a branch was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4847) in GitLab 13.10. -> - DAST branch selection [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/322672) in GitLab 13.11. -> - Auditing for DAST profile management was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. +> Auditing for DAST profile management [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger -the scan. You must either start it manually, or schedule it to run. - -An on-demand DAST scan: - -- Can run a specific combination of a [site profile](#site-profile) and a - [scanner profile](#scanner-profile). -- Is associated with your project's default branch. -- Is saved on creation so it can be run later. +the scan. You must either start it manually, or schedule it to run. For on-demand DAST scans, +a [site profile](#site-profile) defines **what** is to be scanned, and a +[scanner profile](#scanner-profile) defines **how** the application is to be scanned. An on-demand scan can be run in active or passive mode: -- _Passive mode_ is the default and runs a ZAP Baseline Scan. -- _Active mode_ runs a ZAP Full Scan which is potentially harmful to the site being scanned. To - minimize the risk of accidental damage, running an active scan requires a [validated site profile](#site-profile-validation). +- **Passive mode**: The default mode, which runs a ZAP Baseline Scan. +- **Active mode**: Runs a ZAP Full Scan which is potentially harmful to the site being scanned. To + minimize the risk of accidental damage, running an active scan requires a + [validated site profile](#site-profile-validation). ### View on-demand DAST scans -To view on-demand scans, from your project's home page, go to **Security & Compliance > On-demand -scans** in the left sidebar. +To view on-demand scans: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Secure > On-demand scans**. On-demand scans are grouped by their status. The scan library contains all available on-demand scans. -From the **On-demand scans** page you can: - -- [Run](#run-an-on-demand-dast-scan) an on-demand scan. -- View the results of an on-demand scan. -- Cancel (**{cancel}**) a pending or running on-demand scan. -- Retry (**{retry}**) a scan that failed, or succeeded with warnings. -- [Edit](#edit-an-on-demand-scan) (**{pencil}**) an on-demand scan's settings. -- [Delete](#delete-an-on-demand-scan) an on-demand scan. - ### Run an on-demand DAST scan Prerequisites: - You must have permission to run an on-demand DAST scan against a protected branch. The default - branch is automatically protected. For more information, read + branch is automatically protected. For more information, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). -- A [scanner profile](#create-a-scanner-profile). -- A [site profile](#create-a-site-profile). -- If you are running an active scan the site profile must have been [validated](#validate-a-site-profile). - -You can run an on-demand scan immediately, once at a scheduled date and time or at a specified -frequency: - -- Every day -- Every week -- Every month -- Every 3 months -- Every 6 months -- Every year - -To run an on-demand scan immediately, either: - -- [Create and run an on-demand scan immediately](#create-and-run-an-on-demand-scan-immediately). -- [Run a previously saved on-demand scan](#run-a-saved-on-demand-scan). - -To run an on-demand scan either at a scheduled date or frequency, read -[Schedule an on-demand scan](#schedule-an-on-demand-scan). - -#### Create and run an on-demand scan immediately - -1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left - sidebar. -1. Select **New scan**. -1. Complete the **Scan name** and **Description** fields. -1. In GitLab 13.10 and later, select the desired branch from the **Branch** dropdown list. -1. In **Scanner profile**, select a scanner profile from the dropdown list. -1. In **Site profile**, select a site profile from the dropdown list. -1. To run the on-demand scan immediately, select **Save and run scan**. Otherwise, select - **Save scan** to [run](#run-a-saved-on-demand-scan) it later. - -The on-demand DAST scan runs and the project's dashboard shows the results. -#### Run a saved on-demand scan - -To run a saved on-demand scan: +To run an existing on-demand scan: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the scan's row, select **Run scan**. - If the branch saved in the scan no longer exists, you must first - [edit the scan](#edit-an-on-demand-scan), select a new branch, and save the edited scan. + If the branch saved in the scan no longer exists, you must: + + 1. [Edit the scan](#edit-an-on-demand-scan). + 1. Select a new branch. + 1. Save the edited scan. The on-demand DAST scan runs, and the project's dashboard shows the results. -#### Schedule an on-demand scan +#### Create an on-demand scan > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. > - [Feature flag `dast_on_demand_scans_scheduler` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.5. -To schedule a scan: +After you create an on-demand scan, you can: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +- Run it immediately. +- Save it to be run in the future. +- Schedule it to be run at a specified schedule. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Secure > On-demand scans**. 1. Select **New scan**. -1. Complete the **Scan name** and **Description** text boxes. -1. In GitLab 13.10 and later, from the **Branch** dropdown list, select the desired branch. -1. In the **Scanner profile** section, from the dropdown list, select a scanner profile. -1. In the **Site profile** section, from the dropdown list, select a site profile. -1. Select **Schedule scan**. -1. In the **Start time** section, select a time zone, date, and time. -1. From the **Repeats** dropdown list, select your desired frequency: - - To run the scan once, select **Never**. - - For a recurring scan, select any other option. -1. To run the on-demand scan immediately, select **Save and run scan**. To [run](#run-a-saved-on-demand-scan) it according to the schedule you set, select - **Save scan**. +1. Complete the **Scan name** and **Description** fields. +1. In the **Branch** dropdown list, select the desired branch. +1. Select **Select scanner profile** or **Change scanner profile** to open the drawer, and either: + - Select a scanner profile from the drawer, **or** + - Select **New profile**, create a [scanner profile](#scanner-profile), then select **Save profile**. +1. Select **Select site profile** or **Change site profile** to open the drawer, and either: + - Select a site profile from the **Site profile library** drawer, or + - Select **New profile** create a [site profile](#site-profile), then select **Save profile**. +1. To run the on-demand scan: + + - Immediately, select **Save and run scan**. + - In the future, select **Save scan**. + - On a schedule: + + - Turn on the **Enable scan schedule** toggle. + - Complete the schedule fields. + - Select **Save scan**. + +The on-demand DAST scan runs as specified and the project's dashboard shows the results. ### View details of an on-demand scan To view details of an on-demand scan: -1. From your project's home page, go to **Security & Compliance > On-demand scans**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. @@ -594,17 +557,19 @@ To view details of an on-demand scan: To edit an on-demand scan: -1. From your project's home page, go to **Security & Compliance > On-demand scans**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. -1. Edit the form. +1. Edit the saved scan's details. 1. Select **Save scan**. ### Delete an on-demand scan To delete an on-demand scan: -1. From your project's home page, go to **Security & Compliance > On-demand scans**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. 1. On the confirmation dialog, select **Delete**. @@ -645,66 +610,63 @@ This data can only be read and decrypted with a valid secrets file. ### Site profile validation -> - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. -> - Meta tag validation [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2. +> Meta tag validation [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2. Site profile validation reduces the risk of running an active scan against the wrong website. A site -must be validated before an active scan can run against it. The site validation methods are as -follows: +must be validated before an active scan can run against it. Each of the site validation methods are +equivalent in functionality, so use whichever is most suitable: -- _Text file validation_ requires a text file be uploaded to the target site. The text file is +- **Text file validation**: Requires a text file be uploaded to the target site. The text file is allocated a name and content that is unique to the project. The validation process checks the file's content. -- _Header validation_ requires the header `Gitlab-On-Demand-DAST` be added to the target site, +- **Header validation**: Requires the header `Gitlab-On-Demand-DAST` be added to the target site, with a value unique to the project. The validation process checks that the header is present, and checks its value. -- _Meta tag validation_ requires the meta tag named `gitlab-dast-validation` be added to the target site, - with a value unique to the project. Make sure it's added to the `<head>` section of the page. The validation process checks that the meta tag is present, and - checks its value. - -All these methods are equivalent in functionality. Use whichever is feasible. - -In [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/324990), site profile -validation happens in a CI job using the [GitLab Runner](../../../ci/runners/index.md). +- **Meta tag validation**: Requires the meta tag named `gitlab-dast-validation` be added to the + target site, with a value unique to the project. Make sure it's added to the `<head>` section of + the page. The validation process checks that the meta tag is present, and checks its value. ### Create a site profile To create a site profile: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select **New > Site Profile**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select **New > Site profile**. 1. Complete the fields then select **Save profile**. -The site profile is created. +The site profile is saved, for use in an on-demand scan. ### Edit a site profile -If a site profile is linked to a security policy, a user cannot edit the profile from this page. See -[Scan execution policies](../policies/scan-execution-policies.md) -for more information. +NOTE: +If a site profile is linked to a security policy, you cannot edit the profile from this page. See +[Scan execution policies](../policies/scan-execution-policies.md) for more information. When a validated site profile's file, header, or meta tag is edited, the site's [validation status](#site-profile-validation) is revoked. To edit a site profile: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. In the **DAST Profiles** row select **Manage**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. 1. Edit the fields then select **Save profile**. ### Delete a site profile +NOTE: If a site profile is linked to a security policy, a user cannot delete the profile from this page. -See [Scan execution policies](../policies/scan-execution-policies.md) -for more information. +See [Scan execution policies](../policies/scan-execution-policies.md) for more information. To delete a site profile: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. In the **DAST Profiles** row select **Manage**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. 1. In the profile's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. 1. Select **Delete** to confirm the deletion. @@ -766,8 +728,9 @@ have their validation status revoked. To revoke a site profile's validation status: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. In the **DAST Profiles** row select **Manage**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Beside the validated profile, select **Revoke validation**. The site profile's validation status is revoked. @@ -818,9 +781,6 @@ app.get('/dast-website-target', function(req, res) { ## Scanner profile -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) in GitLab 13.5: scan mode, AJAX spider, debug messages. - A scanner profile defines the configuration details of a security scanner. A scanner profile can be referenced in `.gitlab-ci.yml` and on-demand scans. @@ -839,38 +799,41 @@ A scanner profile contains: To create a scanner profile: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. In the **DAST Profiles** row, select **Manage**. -1. Select **New > Scanner Profile**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select **New > Scanner profile**. 1. Complete the form. For details of each field, see [Scanner profile](#scanner-profile). 1. Select **Save profile**. ### Edit a scanner profile -If a scanner profile is linked to a security policy, a user cannot edit the profile from this page. -See [Scan execution policies](../policies/scan-execution-policies.md) -for more information. +NOTE: +If a scanner profile is linked to a security policy, you cannot edit the profile from this page. +For more information, see [Scan execution policies](../policies/scan-execution-policies.md). To edit a scanner profile: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. In the **DAST Profiles** row, select **Manage**. -1. Select the **Scanner Profiles** tab. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select the **Scanner profiles** tab. 1. In the scanner's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. 1. Edit the form. 1. Select **Save profile**. ### Delete a scanner profile +NOTE: If a scanner profile is linked to a security policy, a user cannot delete the profile from this -page. See [Scan execution policies](../policies/scan-execution-policies.md) -for more information. +page. For more information, see [Scan execution policies](../policies/scan-execution-policies.md). To delete a scanner profile: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. In the **DAST Profiles** row, select **Manage**. -1. Select the **Scanner Profiles** tab. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Secure > Security configuration**. +1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. +1. Select the **Scanner profiles** tab. 1. In the scanner's row, select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. 1. Select **Delete**. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index d494259ecc4..b03f9102dae 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -1950,7 +1950,7 @@ Follow these steps to view details of a vulnerability: 1. You can view vulnerabilities in a project, or a merge request: - - In a project, go to the project's **Security and Compliance > Vulnerability Report** + - In a project, go to the project's **Secure > Vulnerability report** page. This page shows all vulnerabilities from the default branch only. - In a merge request, go the merge request's **Security** section and select the **Expand** button. DAST API vulnerabilities are available in a section labeled @@ -2360,7 +2360,7 @@ See the following documentation sections for assistance: See [Performance Tuning and Testing Speed](#performance-tuning-and-testing-speed) -### Error waiting for DAST API 'http://127.0.0.1:5000' to become available +### Error: `Error waiting for DAST API 'http://127.0.0.1:5000' to become available` A bug exists in versions of the DAST API analyzer prior to v1.6.196 that can cause a background process to fail under certain conditions. The solution is to update to a newer version of the DAST API analyzer. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index afed5b3b0ca..d41c0eff860 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -7,16 +7,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency list **(ULTIMATE)** -> - Application dependencies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab 12.0. > - System dependencies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6698) in GitLab 14.6. +> - Group-level dependency list [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8090) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies`. Disabled by default. -Use the dependency list to review your project's dependencies and key +FLAG: +On self-managed GitLab, by default the group-level dependency list is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `group_level_dependencies`. On GitLab.com, this feature is not available. + +Use the dependency list to review your project or group's dependencies and key details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Project Dependency](https://www.youtube.com/watch?v=ckqkn9Tnbw4). -To see the dependency list, go to your project and select **Security and Compliance > Dependency list**. +To see the dependency list, go to your project and select **Secure > Dependency list**. This information is sometimes referred to as a Software Bill of Materials, SBOM, or BOM. @@ -89,4 +92,4 @@ You can download your project's list of dependencies and their details in JSON f ### Using the API -You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the Gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). +You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the [Gemnasium family of analyzers](../dependency_scanning/index.md#dependency-analyzers) and not any other of the GitLab dependency analyzers. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 4feac0cb5e6..0d7d495ba49 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -1,124 +1,11 @@ --- -type: reference, howto -stage: Secure -group: Composition Analysis -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: 'index.md' +remove_date: '2023-09-22' --- -# Dependency Scanning Analyzers **(ULTIMATE)** +This document was moved to [another location](index.md). -Dependency Scanning supports the following official analyzers: - -- [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) -- [`gemnasium-maven`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven) -- [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) - -The analyzers are published as Docker images, which Dependency Scanning uses -to launch dedicated containers for each analysis. - -Dependency Scanning is pre-configured with a set of **default images** that are -maintained by GitLab, but users can also integrate their own **custom images**. - -## Official default analyzers - -Any custom change to the official analyzers can be achieved by using a -[CI/CD variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings). - -### Using a custom Docker mirror - -You can switch to a custom Docker registry that provides the official analyzer -images under a different prefix. For instance, the following instructs Dependency -Scanning to pull `my-docker-registry/gl-images/gemnasium` -instead of `registry.gitlab.com/security-products/gemnasium`. -In `.gitlab-ci.yml` define: - -```yaml -include: - template: Security/Dependency-Scanning.gitlab-ci.yml - -variables: - SECURE_ANALYZERS_PREFIX: my-docker-registry/gl-images -``` - -This configuration requires that your custom registry provides images for all -the official analyzers. - -### Disable specific analyzers - -You can select the official analyzers you don't want to run. Here's how to disable -the `gemnasium` analyzer. -In `.gitlab-ci.yml` define: - -```yaml -include: - template: Security/Dependency-Scanning.gitlab-ci.yml - -variables: - DS_EXCLUDED_ANALYZERS: "gemnasium" -``` - -### Disabling default analyzers - -Setting `DS_EXCLUDED_ANALYZERS` to a list of the official analyzers disables them. -In `.gitlab-ci.yml` define: - -```yaml -include: - template: Security/Dependency-Scanning.gitlab-ci.yml - -variables: - DS_EXCLUDED_ANALYZERS: "gemnasium, gemnasium-maven, gemnasium-python" -``` - -This is used when one totally relies on [custom analyzers](#custom-analyzers). - -## Custom analyzers - -You can provide your own analyzers by -defining CI jobs in your CI configuration. For consistency, you should suffix your custom Dependency -Scanning jobs with `-dependency_scanning`. Here's how to add a scanning job that's based on the -Docker image `my-docker-registry/analyzers/nuget` and generates a Dependency Scanning report -`gl-dependency-scanning-report.json` when `/analyzer run` is executed. Define the following in -`.gitlab-ci.yml`: - -```yaml -nuget-dependency_scanning: - image: - name: "my-docker-registry/analyzers/nuget" - script: - - /analyzer run - artifacts: - reports: - dependency_scanning: gl-dependency-scanning-report.json -``` - -The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate custom security scanners into GitLab. - -## Analyzers data - -The following table lists the data available for the Gemnasium analyzer. - -| Property \ Tool | Gemnasium | -|---------------------------------------|:------------------:| -| Severity | ✓ | -| Title | ✓ | -| File | ✓ | -| Start line | 𐄂 | -| End line | 𐄂 | -| External ID (for example, CVE) | ✓ | -| URLs | ✓ | -| Internal doc/explanation | ✓ | -| Solution | ✓ | -| Confidence | 𐄂 | -| Affected item (for example, class or package) | ✓ | -| Source code extract | 𐄂 | -| Internal ID | ✓ | -| Date | ✓ | -| Credits | ✓ | - -- ✓ => we have that data -- ⚠ => we have that data, but it's partially reliable, or we need to extract that data from unstructured content -- 𐄂 => we don't have that data, or it would need to develop specific or inefficient/unreliable logic to obtain it. - -The values provided by these tools are heterogeneous, so they are sometimes -normalized into common values (for example, `severity`, `confidence`, etc). +<!-- This redirect file can be deleted after <2023-09-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 -->
\ No newline at end of file diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index df9e1d72dba..15fed4f2adc 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Secure group: Composition Analysis 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 @@ -17,6 +16,11 @@ aspects of inspecting the items your code uses. These items typically include ap dependencies that are almost always imported from external sources, rather than sourced from items you wrote yourself. +GitLab offers both Dependency Scanning and [Container Scanning](../container_scanning/index.md) to +ensure coverage for all of these dependency types. To cover as much of your risk area as possible, +we encourage you to use all of our security scanners. For a comparison of these features, see +[Dependency Scanning compared to Container Scanning](../comparison_dependency_and_container_scanning.md). + If you're using [GitLab CI/CD](../../../ci/index.md), you can use dependency scanning to analyze your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive dependencies (also known as nested dependencies). You can take advantage of dependency scanning by @@ -38,48 +42,6 @@ vulnerability. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Dependency Scanning](https://www.youtube.com/watch?v=TBnfbGk4c4o). -## Dependency Scanning compared to Container Scanning - -GitLab offers both Dependency Scanning and Container Scanning -to ensure coverage for all of these dependency types. To cover as much of your risk area as -possible, we encourage you to use all of our security scanning tools: - -- Dependency Scanning analyzes your project and tells you which software dependencies, - including upstream dependencies, have been included in your project, and what known - risks the dependencies contain. Dependency Scanning modifies its behavior based - on the language and package manager of the project. It typically looks for a lock file - then performs a build to fetch upstream dependency information. In the case of - containers, Dependency Scanning uses the compatible manifest and reports only these - declared software dependencies (and those installed as a sub-dependency). - Dependency Scanning cannot detect software dependencies that are pre-bundled - into the container's base image. To identify pre-bundled dependencies, enable - [Container Scanning](../container_scanning/index.md) language scanning using the - [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/index.md#report-language-specific-findings). -- [Container Scanning](../container_scanning/index.md) analyzes your containers and tells - you about known risks in the operating system's (OS) packages. You can configure it - to also report on software and language dependencies, if you enable it and use - the [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/index.md#report-language-specific-findings). - Turning this variable on can result in some duplicate findings, as we do not yet - de-duplicate results between Container Scanning and Dependency Scanning. For more details, - efforts to de-duplicate these findings can be tracked in - [this epic](https://gitlab.com/groups/gitlab-org/-/epics/8026). - -The following table summarizes which types of dependencies each scanning tool can detect: - -| Feature | Dependency Scanning | Container Scanning | -| ----------------------------------------------------------- | ------------------- | ------------------- | -| Identify the manifest, lock file, or static file that introduced the dependency | **{check-circle}** | **{dotted-circle}** | -| Development dependencies | **{check-circle}** | **{dotted-circle}** | -| Dependencies in a lock file committed to your repository | **{check-circle}** | **{check-circle}** <sup>1</sup> | -| Binaries built by Go | **{dotted-circle}** | **{check-circle}** <sup>2</sup> <sup>3</sup> | -| Dynamically-linked language-specific dependencies installed by the Operating System | **{dotted-circle}** | **{check-circle}** <sup>3</sup> | -| Operating system dependencies | **{dotted-circle}** | **{check-circle}** | -| Language-specific dependencies installed on the operating system (not built by your project) | **{dotted-circle}** | **{check-circle}** | - -1. Lock file must be present in the image to be detected. -1. Binary file must be present in the image to be detected. -1. Only when using Trivy - ## Requirements Dependency Scanning runs in the `test` stage, which is available by default. If you redefine the @@ -101,21 +63,6 @@ If you need it, explain why by filling out [the survey](https://docs.google.com/ ## Supported languages and package managers -Dependency Scanning automatically detects the languages used in the repository. All analyzers -matching the detected languages are run. There is usually no need to customize the selection of -analyzers. We recommend not specifying the analyzers so you automatically use the full selection -for best coverage, avoiding the need to make adjustments when there are deprecations or removals. -However, you can override the selection using the variable `DS_EXCLUDED_ANALYZERS`. - -The language detection relies on CI job [`rules`](../../../ci/yaml/index.md#rules) and searches a -maximum of two directory levels from the repository's root. For example, the -`gemnasium-dependency_scanning` job is enabled if a repository contains either `Gemfile`, -`api/Gemfile`, or `api/client/Gemfile`, but not if the only supported dependency file is `api/v1/client/Gemfile`. - -For Java and Python, when a supported dependency file is detected, Dependency Scanning attempts to build the project and execute some Java or Python commands to get the list of dependencies. For all other projects, the lock file is parsed to obtain the list of dependencies without needing to build the project first. - -When a supported dependency file is detected, all dependencies, including transitive dependencies are analyzed. There is no limit to the depth of nested or transitive dependencies that are analyzed. - The following languages and dependency managers are supported: <style> @@ -341,6 +288,40 @@ table.supported-languages ul { </ol> <!-- markdownlint-enable MD044 --> +## Dependency detection + +Dependency Scanning automatically detects the languages used in the repository. All analyzers +matching the detected languages are run. There is usually no need to customize the selection of +analyzers. We recommend not specifying the analyzers so you automatically use the full selection for +best coverage, avoiding the need to make adjustments when there are deprecations or removals. +However, you can override the selection using the variable `DS_EXCLUDED_ANALYZERS`. + +The language detection relies on CI job [`rules`](../../../ci/yaml/index.md#rules) and searches a +maximum of two directory levels from the repository's root. For example, the +`gemnasium-dependency_scanning` job is enabled if a repository contains either `Gemfile`, +`api/Gemfile`, or `api/client/Gemfile`, but not if the only supported dependency file is +`api/v1/client/Gemfile`. + +For Java and Python, when a supported dependency file is detected, Dependency Scanning attempts to +build the project and execute some Java or Python commands to get the list of dependencies. For all +other projects, the lock file is parsed to obtain the list of dependencies without needing to build +the project first. + +When a supported dependency file is detected, all dependencies, including transitive dependencies +are analyzed. There is no limit to the depth of nested or transitive dependencies that are analyzed. + +### Dependency analyzers + +Dependency Scanning supports the following official analyzers: + +- [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) +- [`gemnasium-maven`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven) +- [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) + +The analyzers are published as Docker images, which Dependency Scanning uses +to launch dedicated containers for each analysis. You can also integrate a custom +[security scanner](../../../development/integrations/secure.md). + ### How analyzers obtain dependency information GitLab analyzers obtain dependency information using one of the following two methods: @@ -358,7 +339,7 @@ The following package managers use lockfiles that GitLab analyzers are capable o | 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) | +| NuGet | v1, v2 | [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<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [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) | | pnpm | v5.3, v5.4, v6 | [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1), [8.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1) | | yarn | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup> | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2), [2.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock), [3.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock) | @@ -649,12 +630,11 @@ The following variables allow configuration of global dependency scanning settin | CI/CD variables | Description | | ----------------------------|------------ | | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | -| `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](analyzers.md). | +| `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](#dependency-analyzers). | | `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | | `DS_IMAGE_SUFFIX` | Suffix added to the image name. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354796) in GitLab 14.10.) Automatically set to `"-fips"` when FIPS mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357922) in GitLab 15.0.) | | `DS_MAX_DEPTH` | Defines how many directory levels deep that the analyzer should search for supported files to scan. A value of `-1` scans all directories regardless of depth. Default: `2`. | -| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info`. | +| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). | #### Configuring specific analyzers used by dependency scanning @@ -1044,24 +1024,6 @@ See explanations of the variables above in the [configuration section](#configur See the following sections for configuring specific languages and package managers. -#### JavaScript (npm and yarn) projects - -Add the following to the variables section of `.gitlab-ci.yml`: - -```yaml -RETIREJS_JS_ADVISORY_DB: "example.com/jsrepository.json" -RETIREJS_NODE_ADVISORY_DB: "example.com/npmrepository.json" -``` - -#### Ruby (gem) projects - -Add the following to the variables section of `.gitlab-ci.yml`: - -```yaml -BUNDLER_AUDIT_ADVISORY_DB_REF_NAME: "master" -BUNDLER_AUDIT_ADVISORY_DB_URL: "gitlab.example.com/ruby-advisory-db.git" -``` - #### Python (pip) If you need to install Python packages before the analyzer runs, you should use `pip install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. @@ -1173,12 +1135,10 @@ version number). ## Troubleshooting -### Increase log verbosity +### Debug-level logging -When a [job log](../../../ci/jobs/index.md#expand-and-collapse-job-log-sections) -doesn't contain enough information about a dependency-scanning failure, -[set `SECURE_LOG_LEVEL` to `debug`](#configuring-dependency-scanning) -and check the resulting, more verbose log. +Debug-level logging can help when troubleshooting. For details, see +[debug-level logging](../index.md#debug-level-logging). ### Working around missing support for certain languages or package managers diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 8e2f54fed44..7213fa2ba18 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -250,6 +250,7 @@ kics-iac-sast: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. > - Enabled by default in 15.10. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/375128) in GitLab 16.2. To help you focus on the vulnerabilities that are still relevant, GitLab IaC Scanning automatically [resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when: @@ -270,15 +271,10 @@ pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml ## Troubleshooting -### IaC debug logging +### Debug-level logging -To help troubleshoot IaC jobs, you can increase the [Secure scanner log verbosity](../sast/index.md#logging-level) -by using a global CI/CD variable set to `debug`: - -```yaml -variables: - SECURE_LOG_LEVEL: "debug" -``` +Debug-level logging can help when troubleshooting. For details, see +[debug-level logging](../index.md#debug-level-logging). ### IaC Scanning findings show as `No longer detected` unexpectedly diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 8bbe4db62a9..56a79191833 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -82,7 +82,7 @@ Dependency analysis can run: image is built - [Container Scanning](container_scanning/index.md). For more details, see -[Dependency Scanning compared to Container Scanning](dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning). +[Dependency Scanning compared to Container Scanning](comparison_dependency_and_container_scanning.md). Additionally, dependencies in operational container images can be analyzed for vulnerabilities on a regular schedule or cadence. For more details, see [Operational Container Scanning](../../user/clusters/agent/vulnerabilities.md). @@ -239,6 +239,16 @@ reports are available to download. To download a report, select  +Security scans produce at least one of these [CI `artifacts:reports` types](../../ci/yaml/artifacts_reports.md): + +- `artifacts:reports:api_fuzzing` +- `artifacts:reports:container_scanning` +- `artifacts:reports:coverage_fuzzing` +- `artifacts:reports:dast` +- `artifacts:reports:dependency_scanning` +- `artifacts:reports:sast` +- `artifacts:reports:secret_detection` + ### Ultimate A merge request contains a security widget which displays a summary of the _new_ results. New results are determined by comparing the findings of the merge request against the findings of the most recent completed pipeline (`success`, `failed`, `canceled` or `skipped`) for the commit when the feature branch was created from the target branch. @@ -247,7 +257,10 @@ If security scans have not run for the completed pipeline in the target branch w The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both new and existing findings. -From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View full report** to go directly to the **Security** tab in the latest branch pipeline. +From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. + +For each security report type, the widget displays the first 25 added and 25 fixed findings, sorted by severity. To see all +findings, select **View full report** to go directly to the **Security** tab in the latest branch pipeline.  @@ -523,24 +536,48 @@ Feedback is welcome on our vision for [unifying the user experience for these tw ## Troubleshooting -<!-- NOTE: The below subsection(`### Secure job failing with exit code 1`) documentation URL is referred in the [/gitlab-org/security-products/analyzers/command](https://gitlab.com/gitlab-org/security-products/analyzers/command/-/blob/main/command.go#L19) repository. If this section/subsection changes, please ensure to update the corresponding URL in the mentioned repository. ---> +### Logging level -### Secure job failing with exit code 1 +The verbosity of logs output by GitLab analyzers is determined by the `SECURE_LOG_LEVEL` environment +variable. Messages of this logging level or higher are output. + +From highest to lowest severity, the logging levels are: + +- `fatal` +- `error` +- `warn` +- `info` (default) +- `debug` + +#### Debug-level logging WARNING: Debug logging can be a serious security risk. The output may contain the content of environment variables and other secrets available to the job. The output is uploaded -to the GitLab server and visible in job logs. +to the GitLab server and is visible in job logs. -If a Secure job is failing and it's unclear why, add `SECURE_LOG_LEVEL: "debug"` as a global CI/CD variable for -more verbose output that is helpful for troubleshooting. +To enable debug-level logging, add the following to your `.gitlab-ci.yml` file: ```yaml variables: SECURE_LOG_LEVEL: "debug" ``` +This indicates to all GitLab analyzers that they are to output **all** messages. For more details, +see [logging level](#logging-level). + +<!-- NOTE: The below subsection(`### Secure job failing with exit code 1`) documentation URL is referred in the [/gitlab-org/security-products/analyzers/command](https://gitlab.com/gitlab-org/security-products/analyzers/command/-/blob/main/command.go#L19) repository. If this section/subsection changes, please ensure to update the corresponding URL in the mentioned repository. +--> + +### Secure job failing with exit code 1 + +If a Secure job is failing and it's unclear why: + +1. Enable [debug-level logging](#debug-level-logging). +1. Run the job. +1. Examine the job's output. +1. Set the logging level to `info` (default). + ### Outdated security reports When a security report generated for a merge request becomes outdated, the merge request shows a diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 1ee4d9b2a19..63f3763cab9 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -7,6 +7,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Offline environments **(ULTIMATE SELF)** +NOTE: +To set up an offline environment, you must receive an [opt-out exemption of cloud licensing](https://about.gitlab.com/pricing/licensing-faq/cloud-licensing/#offline-cloud-licensing) prior to purchase. For more details, contact your GitLab sales representative. + It's possible to run most of the GitLab security scanners when not connected to the internet. This document describes how to operate Secure Categories (that is, scanner types) in an offline diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index bd3da0b5913..4e610d64ec9 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Policies in GitLab provide security teams a way to require scans of their choice to be run whenever a project pipeline runs according to the configuration specified. Security teams can therefore be confident that the scans they set up have not been changed, altered, or disabled. You -can access these by navigating to your project's **Security and Compliance > Policies** page. +can access these by navigating to your project's **Secure > Policies** page. GitLab supports the following security policies: @@ -141,7 +141,6 @@ The workaround is to amend your group or instance push rules to allow branches f ### Troubleshooting common issues configuring security policies -- Confirm that projects contain a `.gitlab-ci.yml` file. This file is required for scan execution policies. - Confirm that scanners are properly configured and producing results for the latest branch. Security Policies are designed to require approval when there are no results (no security report), as this ensures that no vulnerabilities are introduced. We cannot know if there are any vulnerabilities unless the scans enforced by the policy complete successfully and are evaluated. - When running scan execution policies based on a SAST action, ensure target repositories contain proper code files. SAST runs different analyzers [based on the types of files in the repo](../sast/index.md#supported-languages-and-frameworks), and if no supported files are found it will not run any jobs. See the [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) for more details. - Check for any branch configuration conflicts. If your policy is configured to enforce rules on `main` but some projects within the scope are using `master` as their default branch, the policy is not applied for the latter. Support for specifying the `default` branch in your policies is proposed in [epic 9468](https://gitlab.com/groups/gitlab-org/-/epics/9468). diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index e18d4d1787e..b84d4d2e49e 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -6,16 +6,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Scan execution policies **(ULTIMATE)** -> - Group-level security policies were [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2. -> - Group-level security policies were [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4. +> - Group-level security policies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2. +> - Group-level security policies [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4. > - Operational container scanning [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3410) in GitLab 15.5 - -Group, subgroup, or project owners can use scan execution policies to require that security scans run on a specified -schedule or with the project pipeline. The security scan runs with multiple project pipelines if you define the policy -at a group or subgroup level. GitLab injects the required scans into the CI pipeline as new jobs. In the event -of a job name collision, GitLab adds a dash and a number to the job name. GitLab increments the number until the name -no longer conflicts with existing job names. If you create a policy at the group level, it applies to every child project -or subgroup. You cannot edit a group-level policy from a child project or subgroup. +> - Support for custom CI variables in the Scan Execution Policies editor [introduced](https://gitlab.com/groups/gitlab-org/-/epics/9566) in GitLab 16.2. +> - Enforcement of scan execution policies on projects with an existing GitLab CI/CD configuration [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6880) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `scan_execution_policy_pipelines`. Enabled by default. + +FLAG: +On self-managed GitLab, this feature is enabled by default. To disable it, ask an +administrator to [disable the feature flag](../../../administration/feature_flags.md) named +`scan_execution_policy_pipelines`. On GitLab.com, this feature is enabled. + +Group, subgroup, or project owners can use scan execution policies to require that security scans +run on a specified schedule or with the project pipeline. The security scan runs with multiple +project pipelines if you define the policy at a group or subgroup level. GitLab injects the required +scans into the CI/CD pipeline as new jobs. + +Scan execution policies are enforced for all applicable projects, even those without a GitLab +CI/CD configuration file or where AutoDevOps is disabled. Security policies create the file +implicitly so that the policies can be enforced. This ensures policies enabling execution of +secret detection, static analysis, or other scanners that do not require a build in the +project, are still able to execute and be enforced. + +In the event of a job name collision, GitLab appends a hyphen and a number to the job name. GitLab +increments the number until the name no longer conflicts with existing job names. If you create a +policy at the group level, it applies to every child project or subgroup. You cannot edit a +group-level policy from a child project or subgroup. This feature has some overlap with [compliance framework pipelines](../../group/compliance_frameworks.md#compliance-pipelines), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). @@ -46,6 +62,13 @@ before the policy changes take effect.  +NOTE: +Selection of site and scanner profiles using the rule mode editor for DAST execution policies differs based on +whether the policy is being created at the project or group level. For project-level policies the rule mode editor +presents a list of profiles to choose from that are already defined in the project. For group-level policies +you are required to type in the names of the profiles to use, and to prevent pipeline errors, profiles with +matching names must exist in all of the group's projects. + ## Scan execution policies schema The YAML file with scan execution policies consists of an array of objects matching scan execution @@ -57,41 +80,52 @@ When you save a new policy, GitLab validates its contents against [this JSON sch If you're not familiar with how to read [JSON schemas](https://json-schema.org/), the following sections and tables provide an alternative. -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `scan_execution_policy` | `array` of scan execution policy | | List of scan execution policies (maximum 5) | +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `scan_execution_policy` | `array` of scan execution policy | true | | List of scan execution policies (maximum 5) | ## Scan execution policy schema -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `name` | `string` | | Name of the policy. Maximum of 255 characters.| -| `description` (optional) | `string` | | Description of the policy. | -| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | -| `rules` | `array` of rules | | List of rules that the policy applies. | -| `actions` | `array` of actions | | List of actions that the policy enforces. | +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `name` | `string` | true | | Name of the policy. Maximum of 255 characters.| +| `description` (optional) | `string` | true | | Description of the policy. | +| `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | +| `rules` | `array` of rules | true | | List of rules that the policy applies. | +| `actions` | `array` of actions | true | | List of actions that the policy enforces. | ## `pipeline` rule type +> - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. +> - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. + This rule enforces the defined actions whenever the pipeline runs for a selected branch. -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `type` | `string` | `pipeline` | The rule's type. | -| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | `default`, `protected` or `all` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `type` | `string` | true | `pipeline` | The rule's type. | +| `branches` <sup>1</sup> | `array` of `string` | true if `branch_type` field does not exist | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | +| `branch_type` <sup>1</sup> | `string` | true if `branches` field does not exist | `default`, `protected` or `all` | The types of branches the given policy applies to. | + +1. You must specify only one of `branches` or `branch_type`. ## `schedule` rule type +> - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. +> - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. + This rule enforces the defined actions and schedules a scan on the provided date/time. -| Field | Type | Possible values | Description | -|------------|------|-----------------|-------------| -| `type` | `string` | `schedule` | The rule's type. | -| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). This field is required if the `agents` field is not set. Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | `default`, `protected` or `all` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | -| `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. Minimum of 15 minute intervals when used together with the `branches` field. | -| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. This field is required if the `branches` field is not set. | +| Field | Type | Required | Possible values | Description | +|------------|------|----------|-----------------|-------------| +| `type` | `string` | true | `schedule` | The rule's type. | +| `branches` <sup>1</sup> | `array` of `string` | true if either `branch_type` or `agents` fields does not exist | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | +| `branch_type` <sup>1</sup> | `string` | true if either `branches` or `agents` fields does not exist | `default`, `protected` or `all` | The types of branches the given policy applies to. | +| `cadence` | `string` | true | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. Minimum of 15 minute intervals when used together with the `branches` field. | +| `timezone` | `string` | false | Time zone identifier (for example, `America/New_York`) | Time zone to apply to the cadence. Value must be an IANA Time Zone Database identifier. | +| `agents` <sup>1</sup> | `object` | true if either `branch_type` or `branches` fields do not exists | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. | + +1. You must specify only one of `branches`, `branch_type`, or `agents`. GitLab supports the following types of CRON syntax for the `cadence` field: @@ -118,9 +152,9 @@ When using the `schedule` rule type in conjunction with the `branches` field, no Use this schema to define `agents` objects in the [`schedule` rule type](#schedule-rule-type). -| Field | Type | Possible values | Description | -|--------------|---------------------|--------------------------|-------------| -| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces are scanned. | +| Field | Type | Required | Possible values | Description | +|--------------|---------------------|----------|--------------------------|-------------| +| `namespaces` | `array` of `string` | true | The namespace that is scanned. If empty, all namespaces are scanned. | #### Policy example diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index d8cd984ad40..0aac36988d4 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -61,32 +61,33 @@ When you save a new policy, GitLab validates its contents against [this JSON sch If you're not familiar with how to read [JSON schemas](https://json-schema.org/), the following sections and tables provide an alternative. -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `scan_result_policy` | `array` of Scan Result Policy | | List of scan result policies (maximum 5). | +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `scan_result_policy` | `array` of Scan Result Policy | true | | List of scan result policies (maximum 5). | ## Scan result policy schema -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `name` | `string` | | Name of the policy. Maximum of 255 characters.| -| `description` (optional) | `string` | | Description of the policy. | -| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | -| `rules` | `array` of rules | | List of rules that the policy applies. | -| `actions` | `array` of actions | | List of actions that the policy enforces. | +| Field | Type | Required |Possible values | Description | +|-------|------|----------|----------------|-------------| +| `name` | `string` | true | | Name of the policy. Maximum of 255 characters.| +| `description` (optional) | `string` | true | | Description of the policy. | +| `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | +| `rules` | `array` of rules | true | | List of rules that the policy applies. | +| `actions` | `array` of actions | true | | List of actions that the policy enforces. | ## `scan_finding` rule type This rule enforces the defined actions based on security scan findings. -| Field | Type | Possible values | Description | -|------------|------|--------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `type` | `string` | `scan_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. | -| `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. `sast` includes results from both SAST and SAST IaC scanners. | -| `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`, `new_needs_triage`, `new_dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that 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. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br> The `new_needs_triage` option considers the status<br><br> • Detected<br><br> The `new_dismissed` option considers the status<br><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. | +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `type` | `string` | true | `scan_finding` | The rule's type. | +| `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `scanners` | `array` of `string` | true | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. `sast` includes results from both SAST and SAST IaC scanners. | +| `vulnerabilities_allowed` | `integer` | true | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | +| `severity_levels` | `array` of `string` | true | `info`, `unknown`, `low`, `medium`, `high`, `critical` | The severity levels for this rule to consider. | +| `vulnerability_states` | `array` of `string` | true | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed`, `new_needs_triage`, `new_dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that 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. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br> The `new_needs_triage` option considers the status<br><br> • Detected<br><br> The `new_dismissed` option considers the status<br><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 @@ -95,28 +96,29 @@ This rule enforces the defined actions based on security scan findings. 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. The `newly_detected` state triggers approval when either a new package is introduced or when a new license for an existing package is detected. | +| Field | Type | Required | Possible values | Description | +|------------|------|----------|-----------------|-------------| +| `type` | `string` | true | `license_finding` | The rule's type. | +| `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `match_on_inclusion` | `boolean` | true | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | +| `license_types` | `array` of `string` | true | license types | [SPDX license names](https://spdx.org/licenses) to match on, for example `Affero General Public License v1.0` or `MIT License`. | +| `license_states` | `array` of `string` | true | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. The `newly_detected` state triggers approval when either a new package is introduced or when a new license for an existing package is detected. | ## `require_approval` action type This action sets an approval rule to be required when conditions are met for at least one rule in the defined policy. -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `type` | `string` | `require_approval` | The action's type. | -| `approvals_required` | `integer` | Greater than or equal to zero | The number of MR approvals required. | -| `user_approvers` | `array` of `string` | Username of one of more users | The users to consider as approvers. Users must have access to the project to be eligible to approve. | -| `user_approvers_ids` | `array` of `integer` | ID of one of more users | The IDs of users to consider as approvers. Users must have access to the project to be eligible to approve. | -| `group_approvers` | `array` of `string` | Path of one of more groups | The groups to consider as approvers. Users with [direct membership in the group](../../project/merge_requests/approvals/rules.md#group-approvers) are eligible to approve. | -| `group_approvers_ids` | `array` of `integer` | ID of one of more groups | The IDs of groups to consider as approvers. Users with [direct membership in the group](../../project/merge_requests/approvals/rules.md#group-approvers) are eligible to approve. | -| `role_approvers` | `array` of `string` | One or more [roles](../../../user/permissions.md#roles) (for example: `owner`, `maintainer`) | The roles to consider as approvers that are eligible to approve. | +| Field | Type | Required | Possible values | Description | +|-------|------|----------|-----------------|-------------| +| `type` | `string` | true | `require_approval` | The action's type. | +| `approvals_required` | `integer` | true | Greater than or equal to zero | The number of MR approvals required. | +| `user_approvers` | `array` of `string` | false | Username of one of more users | The users to consider as approvers. Users must have access to the project to be eligible to approve. | +| `user_approvers_ids` | `array` of `integer` | false | ID of one of more users | The IDs of users to consider as approvers. Users must have access to the project to be eligible to approve. | +| `group_approvers` | `array` of `string` | false | Path of one of more groups | The groups to consider as approvers. Users with [direct membership in the group](../../project/merge_requests/approvals/rules.md#group-approvers) are eligible to approve. | +| `group_approvers_ids` | `array` of `integer` | false | ID of one of more groups | The IDs of groups to consider as approvers. Users with [direct membership in the group](../../project/merge_requests/approvals/rules.md#group-approvers) are eligible to approve. | +| `role_approvers` | `array` of `string` | false | One or more [roles](../../../user/permissions.md#roles) (for example: `owner`, `maintainer`) | The roles to consider as approvers that are eligible to approve. | Requirements and limitations: @@ -215,7 +217,16 @@ It corresponds to a single object from the previous example: There are several situations where the scan result policy requires an additional approval step. For example: -- The number of security jobs is reduced in the working branch and no longer matches the number of security jobs in the target branch. Users can't skip the Scanning Result Policies by removing scanning jobs from the CI configuration. +- The number of security jobs is reduced in the working branch and no longer matches the number of + security jobs in the target branch. Users can't skip the Scanning Result Policies by removing + scanning jobs from the CI/CD configuration. Only the security scans that are configured in the + scan result policy rules are checked for removal. + + For example, consider a situation where the default branch pipeline has four security scans: + `sast`, `secret_detection`, `container_scanning`, and `dependency_scanning`. A scan result + policy enforces two scanners: `container_scanning` and `dependency_scanning`. If an MR removes a + scan that is configured in scan result policy, `container_scanning` for example, an additional + approval is required. - Someone stops a pipeline security job, and users can't skip the security scan. - A job in a merge request fails and is configured with `allow_failure: false`. As a result, the pipeline is in a blocked state. - A pipeline has a manual job that must run successfully for the entire pipeline to pass. diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 2008375d2a2..a9bc331ae7b 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -172,6 +172,7 @@ GitLab SAST uses an advanced vulnerability tracking algorithm to more accurately Advanced vulnerability tracking is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): - C, in the Semgrep-based analyzer only +- C#, in the Semgrep-based analyzer only - Go, in the Semgrep-based analyzer only - Java, in the Semgrep-based analyzer only - JavaScript, in the Semgrep-based analyzer only @@ -186,6 +187,7 @@ For more information, see the confidential project `https://gitlab.com/gitlab-or > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. > - Enabled by default in GitLab 15.10. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/375128) in GitLab 16.2. To help you focus on the vulnerabilities that are still relevant, GitLab SAST automatically [resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when: @@ -290,9 +292,7 @@ The method you can use depends on your GitLab license tier. #### Configure SAST with customizations **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab 13.3. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab 13.4. -> - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/3635) in GitLab 13.5. +> [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410013) individual SAST analyzers configuration options from the UI in GitLab 16.2. NOTE: The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal @@ -309,9 +309,6 @@ To enable and configure SAST with customizations: Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST Configuration page, their values are inherited from the GitLab SAST template. - -1. Optionally, expand the **SAST analyzers** section, select individual - [SAST analyzers](analyzers.md) and enter custom analyzer values. 1. Select **Create Merge Request**. 1. Review and merge the merge request. @@ -519,21 +516,6 @@ variables: SEARCH_MAX_DEPTH: 10 ``` -#### Logging level - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. - -To control the verbosity of logs, set the `SECURE_LOG_LEVEL` environment variable. Messages of this -logging level or higher are output. - -From highest to lowest severity, the logging levels are: - -- `fatal` -- `error` -- `warn` -- `info` (default) -- `debug` - #### Custom Certificate Authority To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle @@ -616,7 +598,7 @@ flags are added to the scanner's CLI options. | Analyzer | CLI option | Description | |------------------------------------------------------------------------------|--------------------|------------------------------------------------------------------------------| | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) | `--max-memory` | Sets the maximum system memory to use when running a rule on a single file. Measured in MB. | -| [Flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | `--neverignore` | Never ignore security issues, even if they have an “ignore” directive in a comment. Adding this option is likely to result in the analyzer detecting additional vulnerability findings which cannot be automatically resolved. | +| [Flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | `--neverignore` | Never ignore security issues, even if they have an "ignore" directive in a comment. Adding this option is likely to result in the analyzer detecting additional vulnerability findings which cannot be automatically resolved. | | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | `-effort` | Sets the analysis effort level. Valid values are `min`, `less`, `more` and `max`, defined in increasing order of scan's precision and ability to detect more vulnerabilities. Default value is set to `max` which may require more memory and time to complete the scan, depending on the project's size. In case you face memory or performance issues, you may reduce the analysis effort level to a lower value. For example: `-effort less`. | #### Custom CI/CD variables @@ -772,14 +754,10 @@ By default SAST analyzers are supported in GitLab instances hosted on SELinux. A ## Troubleshooting -### SAST debug logging - -Increase the [Secure scanner log verbosity](#logging-level) to `debug` in a global CI variable to help troubleshoot SAST jobs. +### Debug-level logging -```yaml -variables: - SECURE_LOG_LEVEL: "debug" -``` +Debug-level logging can help when troubleshooting. For details, see +[debug-level logging](../index.md#debug-level-logging). ### Pipeline errors related to changes in the GitLab-managed CI/CD template diff --git a/doc/user/application_security/secret_detection/automatic_response.md b/doc/user/application_security/secret_detection/automatic_response.md index 8f78d36976b..66ed2f10a3c 100644 --- a/doc/user/application_security/secret_detection/automatic_response.md +++ b/doc/user/application_security/secret_detection/automatic_response.md @@ -23,6 +23,7 @@ GitLab supports automatic response for the following types of secrets: | GitLab [Personal access tokens](../../profile/personal_access_tokens.md) | Immediately revoke token, send email to owner | ✅ | ✅ [15.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) | | Amazon Web Services (AWS) [IAM access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | Notify AWS | ✅ | ⚙ | | Google Cloud [service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys), [API keys](https://cloud.google.com/docs/authentication/api-keys), and [OAuth client secrets](https://support.google.com/cloud/answer/6158849#rotate-client-secret) | Notify Google Cloud | ✅ | ⚙ | +| Postman [API keys](https://learning.postman.com/docs/developer/postman-api/authentication/) | Notify Postman; Postman emails the key owner | ✅ | ⚙ | **Component legend** diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 2e6de222ec3..ea2a66c7cc7 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -40,7 +40,7 @@ contains more than 100 patterns. Most Secret Detection patterns search for specific types of secrets. Many services add prefixes or other structural details to their secrets so they can be identified if they're leaked. -For example, GitLab [adds a `glpat-` prefix](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) to project, group, and personal access tokens by default. +For example, GitLab [adds a `glpat-` prefix](../../../administration/settings/account_and_limit_settings.md#personal-access-token-prefix) to project, group, and personal access tokens by default. To provide more reliable, high-confidence results, Secret Detection only looks for passwords or other unstructured secrets in specific contexts like URLs. @@ -83,7 +83,7 @@ Secret Detection can detect if a secret was added in one commit and removed in a - Commit range - If the `SECRET_DETECTION_LOG_OPTS` variable is set, the secrets analyzer fetches the entire + If the `SECRET_DETECTION_LOG_OPTIONS` variable is set, the secrets analyzer fetches the entire history of the branch or reference the pipeline is being run for. Secret Detection then runs, scanning the commit range specified. @@ -621,7 +621,7 @@ The check is always on; you don't have to set it up. Your text is checked for the following secret types: - GitLab [personal access tokens](../../../security/token_overview.md#personal-access-tokens) - - If a [personal access token prefix](../../../user/admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) has been configured, a token using this prefix is checked. + - If a [personal access token prefix](../../../administration/settings/account_and_limit_settings.md#personal-access-token-prefix) has been configured, a token using this prefix is checked. - GitLab [feed tokens](../../../security/token_overview.md#feed-token) This feature is separate from Secret Detection scanning, which checks your Git repository for leaked secrets. @@ -629,21 +629,10 @@ This feature is separate from Secret Detection scanning, which checks your Git r ## Troubleshooting -### Set the logging level +### Debug-level logging -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. - -Set the logging level to `debug` when you need diagnostic information in a Secret Detection job log. - -WARNING: -Debug logging can be a serious security risk. The output may contain the content of environment -variables and other secrets available to the job. The output is uploaded to the GitLab server and -visible in job logs. - -1. In the `.gitlab-ci.yml` file, set the `SECURE_LOG_LEVEL` CI/CD variable to `debug`. -1. Run the Secret Detection job. -1. Analyze the content of the Secret Detection job. -1. In the `.gitlab-ci.yml` file, set the `SECURE_LOG_LEVEL` CI/CD variable to `info` (default). +Debug-level logging can help when troubleshooting. For details, see +[debug-level logging](../index.md#debug-level-logging). ### Warning: `gl-secret-detection-report.json: no matching files` @@ -661,8 +650,8 @@ For example, you could have a pipeline triggered from a merge request containing clone is not deep enough to contain all of the relevant commits. To verify the current value, see [pipeline configuration](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). -To confirm this as the cause of the error, set the [logging level](#set-the-logging-level) to -`debug`, then rerun the pipeline. The logs should look similar to the following example. The text +To confirm this as the cause of the error, enable [debug-level logging](../index.md#debug-level-logging), +then rerun the pipeline. The logs should look similar to the following example. The text "object not found" is a symptom of this error. ```plaintext diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 39d8e28e564..1950c620627 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -199,8 +199,9 @@ To manually apply the patch that GitLab generated for a vulnerability: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. NOTE: -Security training is not available in an offline environment because it uses content from -third-party vendors. +Security training is not accessible in an environment that is offline, meaning computers that are isolated from the public internet as a security measure. Some third-party training vendors may require you to sign up for a _free_ account. Sign up for an account by going to +any of [Secure Code Warrior](https://www.securecodewarrior.com/), [Kontra](https://application.security/), or [SecureFlag](https://www.secureflag.com/). +GitLab does not send any user information to these third-party vendors; we do send the CWE or OWASP identifier and the language name of the file extension. Security training helps your developers learn how to fix vulnerabilities. Developers can view security training from selected educational providers, relevant to the detected vulnerability. @@ -211,6 +212,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. +Each integration submits the Vulnerability identifier, for example CWE or OWASP, and the language to the security training vendor. The resulting link to the vendor training is what appears in a GitLab Vulnerability. + ## View security training for a vulnerability > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. @@ -218,8 +221,8 @@ To enable security training for vulnerabilities in your project: The vulnerability page may include a training link relevant to the detected vulnerability if security training is enabled. The availability of training depends on whether the enabled training vendor has content matching the particular vulnerability. Training content is requested based on the [vulnerability identifiers](../../../development/integrations/secure.md#identifiers). -The identifier given to a vulnerability varies from one vulnerability to the next. The available training -content varies between vendors. This means some vulnerabilities do not display training content. +The identifier given to a vulnerability varies from one vulnerability to the next and the available training +content varies between vendors. Some vulnerabilities do not display training content. Vulnerabilities with a CWE are most likely to return a training result. To view the security training for a vulnerability: diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index ab90ac18b8e..9553d15bbe9 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -18,7 +18,33 @@ most to least severe: - `Info` - `Unknown` -Most GitLab vulnerability analyzers are wrappers around popular open source scanning tools. Each +GitLab analyzers make an effort to fit the severity descriptions below, but they may not always be correct. Analyzers and scanners provided by third-party vendors may not follow the same classification. + +## Critical severity + +Vulnerabilities identified at the Critical Severity level should be investigated immediately. Vulnerabilities at this level assume exploitation of the flaw could lead to full system or data compromise. Examples of critical severity flaws are Command/Code Injection and SQL Injection. Typically these flaws are rated with CVSS 3.1 between 9.0-10.0. + +## High severity + +High severity vulnerabilities can be characterized as flaws that may lead to an attacker accessing application resources or unintended exposure of data. Examples of high severity flaws are External XML Entity Injection (XXE), Server Side Request Forgery (SSRF), Local File Include/Path Traversal and certain forms of Cross-Site Scripting (XSS). Typically these flaws are rated with CVSS 3.1 between 7.0-8.9. + +## Medium severity + +Medium severity vulnerabilities usually arise from misconfiguration of systems or lack of security controls. Exploitation of these vulnerabilities may lead to accessing a restricted amount of data or could be used in conjunction with other flaws to gain unintended access to systems or resources. Examples of medium severity flaws are reflected XSS, incorrect HTTP session handling, and missing security controls. Typically these flaws are rated with CVSS 3.1 between 4.0-6.9. + +## Low severity + +Low severity vulnerabilities contain flaws that may not be directly exploitable but introduce unnecessary weakness to an application or system. These flaws are usually due to missing security controls, or unnecessary disclose information about the application environment. Examples of low severity vulnerabilities are missing cookie security directives, verbose error or exception messages. Typically these flaws are rated with CVSS 3.1 between 1.0-3.9. + +## Info severity + +Info level severity vulnerabilities contain information that may have value, but are not necessarily associated to a particular flaw or weakness. Typically these issues do not have a CVSS rating. + +## Unknown severity + +Issues identified at this level do not have enough context to clearly demonstrate severity. + +GitLab vulnerability analyzers include popular open source scanning tools. Each open source scanning tool provides their own native vulnerability severity level value. These values can be one of the following: diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index f04fece7b76..d2041083d36 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -411,7 +411,7 @@ Color written inside backticks is followed by a color "chip": ### Equations and Formulas (STEM) -If you need to include Science, Technology, Engineering and Math (STEM) +If you need to include Science, Technology, Engineering, and Math (STEM) expressions, set the `stem` attribute in the document's header to `latexmath`. Equations and formulas are rendered using [KaTeX](https://katex.org/): diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index c3aad86461b..aaba0225653 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -6,11 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Emoji reactions **(FREE)** -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from "award emojis" to "emoji reactions" in GitLab 16.0. -> - Reacting with emojis on work items (such as tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393599) in GitLab 16.0. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from "award emoji" to "emoji reactions" in GitLab 16.0. +> - Reacting with emoji on work items (such as tasks, objectives, and key results) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393599) in GitLab 16.0. +> - Reacting with emoji on design discussion comments [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29756) in GitLab 16.2. When you're collaborating online, you get fewer opportunities for high-fives -and thumbs-ups. React with emojis on: +and thumbs-ups. React with emoji on: - [Issues](project/issues/index.md). - [Tasks](tasks.md). @@ -25,19 +26,10 @@ and thumbs-ups. React with emojis on: Emoji reactions make it much easier to give and receive feedback without a long comment thread. -For information on the relevant API, see [Emoji reactions API](../api/award_emoji.md). - -## Sort issues and merge requests on vote count - -You can quickly sort issues and merge requests by the number of votes ("thumbs up" and "thumbs down" emoji) they -have received. The sort options can be found in the dropdown list as "Most -popular" and "Least popular". +"Thumbs up" and "thumbs down" emoji are used to calculate an issue or merge request's position when +[sorting by popularity](project/issues/sorting_issue_lists.md#sorting-by-popularity). - - -The total number of votes is not summed up. An issue with 18 upvotes and 5 -downvotes is considered more popular than an issue with 17 upvotes and no -downvotes. +For information on the relevant API, see [Emoji reactions API](../api/award_emoji.md). ## Emoji reactions for comments @@ -51,14 +43,26 @@ To add an emoji reaction: To remove an emoji reaction, select the emoji again. -## Custom emojis +## Custom emoji + +> - [Introduced for GraphQL API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../administration/feature_flags.md) named `custom_emoji`. Disabled by default. +> - Enabled on GitLab.com in GitLab 14.0. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/333095) UI to add emoji in GitLab 16.2. + +Custom emoji show in the emoji picker everywhere you can react with emoji. +To add an emoji reaction to a comment or description: + +1. Select **Add reaction** (**{slight-smile}**). +1. Select the GitLab logo (**{tanuki}**) or scroll down to the **Custom** section. +1. Select an emoji from the emoji picker. + + -You can upload custom emojis to a GitLab instance with the GraphQL API. -For more information, see [Use custom emojis with GraphQL](../api/graphql/custom_emoji.md). +To use them in a text box, type the filename between two colons. +For example, `:thank-you:`. -Custom emojis don't show in the emoji picker. -To use them in a text box, type the filename without the extension and surrounded by colons. -For example, for a file named `thank-you.png`, type `:thank-you:`. +You can upload custom emoji to a GitLab instance with the GraphQL API. +For more information, see [Use custom emoji with GraphQL](../api/graphql/custom_emoji.md). -For a list of custom emojis available for GitLab.com, see +For a list of custom emoji available for GitLab.com, see [the `custom_emoji` project](https://gitlab.com/custom_emoji/custom_emoji/-/tree/main/img). diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 106f751555a..aff78ed477b 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -11,10 +11,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346585) to make the `id` attribute optional in GitLab 15.7. > - Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/395364) in GitLab 16.1 to prioritize Flux for GitOps. -NOTE: -From GitLab 15.10, you should use [Flux](gitops/flux.md) for GitOps. For more information, see -[this announcement blog post](https://about.gitlab.com/blog/2023/02/08/why-did-we-choose-to-integrate-fluxcd-with-gitlab/). +GitLab integrates [Flux](https://fluxcd.io/flux/) for GitOps. +To get started with Flux, see the [Flux for GitOps tutorial](gitops/flux_tutorial.md). With GitOps, you can manage containerized clusters and applications from a Git repository that: @@ -25,163 +25,155 @@ By combining GitLab, Kubernetes, and GitOps, you can have: - GitLab as the GitOps operator. - Kubernetes as the automation and convergence system. -- GitLab CI/CD for Continuous Integration and the agent for Continuous Deployment. +- GitLab CI/CD for Continuous Integration. +- The agent for Continuous Deployment and cluster observability. - Built-in automatic drift remediation. - Resource management with [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/) for transparent multi-actor field management. +## Deployment sequence + This diagram shows the repositories and main actors in a GitOps deployment: ```mermaid sequenceDiagram participant D as Developer participant A as Application code repository - participant M as Manifest repository - participant K as GitLab agent + participant M as Deployment repository + participant R as OCI registry participant C as Agent configuration repository + participant K as GitLab agent + participant F as Flux loop Regularly K-->>C: Grab the configuration end D->>+A: Pushing code changes A->>M: Updating manifest - loop Regularly - K-->>M: Watching changes - M-->>K: Pulling and applying changes - end + M->>R: Build an OCI artifact + M->>K: Notify + K->>F: Notify and watch sync + R-->>F: Pulling and applying changes + K->>M: Notify after sync ``` -For details, view the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). +You should use both Flux and `agentk` for GitOps deployments. Flux keeps the cluster state synchronized with the source, while `agentk` simplifies the Flux setup, provides cluster-to-GitLab access management, and visualizes the cluster state in the GitLab UI. -## GitOps workflow steps +### OCI for source control -To update a Kubernetes cluster by using GitOps, complete the following steps. +You should use OCI images as a source controller for Flux, instead of a Git repository. The [GitLab container registry](../../packages/container_registry/index.md) supports OCI images. -1. Ensure you have a working Kubernetes cluster, and that the manifests or [Helm charts](gitops/helm.md) are in a GitLab project. -1. In the same project, [register and install the GitLab agent](install/index.md). -1. Configure the agent configuration file so that the agent monitors the project for changes to the Kubernetes manifests. - Use the [GitOps configuration reference](#gitops-configuration-reference) for guidance. +| OCI registry | Git repository | +| --- | --- | +| Designed to serve container images at scale. | Designed to version and store source code. | +| Immutable, supports security scans. | Mutable. | +| The default Git branch can store cluster state without triggering a sync. | The default Git branch triggers a sync when used to store cluster state. | -Any time you commit updates to your Kubernetes manifests, the agent updates the cluster. +## Repository structure -## GitOps configuration reference +To simplify configuration, use one delivery repository per team. +You can package the delivery repository into multiple OCI images per application. -The following snippet shows an example of the possible keys and values for the GitOps section of an [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +For additional repository structure recommendations, see the [Flux documentation](https://fluxcd.io/flux/guides/repository-structure/). -```yaml -gitops: - manifest_projects: - - id: gitlab-org/cluster-integration/gitlab-agent - ref: # either `branch`, `tag` or `commit` can be specified - branch: production - # commit: <mysha> - # tag: v1.0 - default_namespace: my-ns - paths: - # Read all YAML files from this directory. - - glob: '/team1/app1/*.yaml' - # Read all .yaml files from team2/apps and all subdirectories. - - glob: '/team2/apps/**/*.yaml' - # If 'paths' is not specified or is an empty list, the configuration below is used. - - glob: '/**/*.{yaml,yml,json}' - reconcile_timeout: 3600s - dry_run_strategy: none - prune: true - prune_timeout: 3600s - prune_propagation_policy: foreground - inventory_policy: must_match -``` +## Immediate Git repository reconciliation -| Keyword | Description | -|--|--| -| `manifest_projects` | Projects where your Kubernetes manifests are stored. The agent monitors the files in the repositories in these projects. When manifest files change, the agent deploys the changes to the cluster. | -| `id` | Path to a Git repository that has Kubernetes manifests in YAML or JSON format. No authentication mechanisms are supported. Default is the agent configuration repository. | -| `ref` | Optional. Git reference in the configured Git repository to fetch the Kubernetes manifest files from. If not specified or empty, the default branch is used. If specified, it must contain either `branch`, `tag`, or `commit`. | -| `ref.branch` | Branch name in the configured Git repository to fetch the Kubernetes manifest files from. | -| `ref.tag` | Tag name in the configured Git repository to fetch the Kubernetes manifest files from. | -| `ref.commit` | Commit SHA in the configured Git repository to fetch the Kubernetes manifest files from. | -| `default_namespace` | Namespace to use if not set explicitly in object manifest. Also used for inventory `ConfigMap` objects. | -| `paths` | Repository paths to scan for manifest files. Directories with names that start with a dot `(.)` are ignored. | -| `paths[].glob` | Required. See [doublestar](https://github.com/bmatcuk/doublestar#about) and [the match function](https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match) for globbing rules. | -| `reconcile_timeout` | Determines whether the applier should wait until all applied resources have been reconciled, and if so, how long to wait. Default is 3600 seconds (1 hour). | -| `dry_run_strategy` | Determines whether changes [should be performed](https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/common/common.go#L68-L89). Can be: `none`, `client`, or `server`. Default is `none`.| -| `prune` | Determines whether pruning of previously applied objects should happen after apply. Default is `true`. | -| `prune_timeout` | Determines whether to wait for all resources to be fully deleted after pruning, and if so, how long to wait. Default is 3600 seconds (1 hour). | -| `prune_propagation_policy` | The deletion propagation policy that [should be used for pruning](https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470). Can be: `orphan`, `background`, or `foreground`. Default is `foreground`. | -| `inventory_policy` | Determines whether an inventory object can take over objects that belong to another inventory object or don't belong to any inventory object. This is done by determining if the apply/prune operation can go through for a resource based on comparison of the `inventory-id` value in the package and the `owning-inventory` annotation (`config.k8s.io/owning-inventory`) [in the live object](https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66). Can be: `must_match`, `adopt_if_no_inventory`, or `adopt_all`. Default is `must_match`. | +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `notify_kas_on_git_push`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126527) in GitLab 16.2. -## GitOps annotations +Usually, the Flux source controller reconciles Git repositories at configured intervals. +This can cause delays between a `git push` and the reconciliation of the cluster state, and results in +unnecessary pulls from GitLab. -The GitLab agent for Kubernetes has annotations you can use to: +The agent for Kubernetes automatically detects Flux `GitRepository` objects that +reference GitLab projects in the instance the agent is connected to, +and configures a [`Receiver`](https://fluxcd.io/flux/components/notification/receiver/) for the instance. +When the agent for Kubernetes detects a `git push`, the `Receiver` is triggered +and Flux reconciles the cluster with any changes to the repository. -- **Sort resources**: Apply or delete resources in a specific order. -- **Use apply-time mutation**: Dynamically substitute fields from one resource configuration to another. +To use immediate Git repository reconciliation, you must have a Kubernetes cluster that runs: -The agent has [default sorting](https://github.com/kubernetes-sigs/cli-utils/blob/d7d63f4b62897f584ca9e02b6faf4d2f327a9b09/pkg/ordering/sort.go#L74), -but with annotations, you can fine-tune the order and apply time-value injection. +- The agent for Kubernetes. +- Flux `source-controller` and `notification-controller`. -To provide the GitOps functionality, the GitLab agent for Kubernetes uses the [`cli-utils` library](https://github.com/kubernetes-sigs/cli-utils/), -a Kubernetes SIG project. For more information, see the available annotations in the [`cli-utils` documentation](https://github.com/kubernetes-sigs/cli-utils/blob/master/README.md). +Immediate Git repository reconciliation can reduce the time between a push and reconciliation, +but it doesn't guarantee that every `git push` event is received. You should still set +[`GitRepository.spec.interval`](https://fluxcd.io/flux/components/source/gitrepositories/#interval) +to an acceptable duration. -## Automatic drift remediation +### Custom webhook endpoints -Drift happens when the current configuration of an infrastructure resource differs from its desired configuration. -Typically, this is caused by manually editing resources directly rather than via the used infrastructure-as-code -mechanism. Minimizing the risk of drift helps to ensure configuration consistency and successful operations. +When the agent for Kubernetes calls the `Receiver` webhook, +the agent defaults to `http://webhook-receiver.flux-system.svc.cluster.local`, +which is also the default URL set by a Flux bootstrap installation. To configure a custom +endpoint, set `flux.webhook_receiver_url` to a URL that the agent can resolve. For example: -In GitLab, the agent for Kubernetes regularly compares the desired state from the `git` repository with -the actual state from the Kubernetes cluster. Deviations from the `git` state are fixed at every check. These checks -happen automatically every 5 minutes. They are not configurable. +```yaml +flux: + webhook_receiver_url: http://webhook-receiver.another-flux-namespace.svc.cluster.local +``` -The agent uses [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/). -As a result, every field in a resource can have different managers. Only fields managed by `git` -are checked for drift. This facilitates the use of in-cluster controllers to modify resources like -[Horizontal Pod Autoscalers](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). +There is special handing for +[service proxy URLs](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster-services/) configured +in this format: `/api/v1/namespaces/[^/]+/services/[^/]+/proxy`. For example: -## Related topics +```yaml +flux: + webhook_receiver_url: /api/v1/namespaces/flux-system/services/http:webhook-receiver:80/proxy +``` -- [Deploying Helm charts with the GitOps workflow](gitops/helm.md) -- [GitOps working examples for training and demos](https://gitlab.com/groups/guided-explorations/gl-k8s-agent/gitops/-/wikis/home) -- [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters) -- [Managing Kubernetes secrets in a GitOps workflow](gitops/secrets_management.md) -- [Application and manifest repository example](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service-gitops) +In these cases, the agent for Kubernetes uses the available Kubernetes configuration +and context to connect to the API endpoint. +You can use this if you run an agent outside a cluster +and you haven't [configured an `Ingress`](https://fluxcd.io/flux/guides/webhook-receivers/#expose-the-webhook-receiver) +for the Flux notification controller. + +WARNING: +You should configure only trusted service proxy URLs. +When you provide a service proxy URL, +the agent for Kubernetes sends typical Kubernetes API requests which include +the credentials necessary to authenticate with the API service. -## Troubleshooting +## Token management -### Avoiding conflicts when you have multiple projects +To use certain Flux features, you might need multiple access tokens. Additionally, you can use multiple token types to achieve the same result. -The agent watches each glob pattern set under a project's `paths` section independently, and makes updates to the cluster concurrently. -If changes are found at multiple paths, when the agent attempts to update the cluster, -a conflict can occur. +This section provides guidelines for the tokens you might need, and provides token type recommendations where possible. -To prevent this from happening, consider storing a logical group of manifests in a single place and reference them only once to avoid overlapping globs. +### GitLab access by Flux -For example, both of these globs match `*.yaml` files in the root directory -and could cause conflicts: +To access the GitLab the container registry or Git repositories, Flux can use: -```yaml -gitops: - manifest_projects: - - id: project1 - paths: - - glob: '/**/*.yaml' - - glob: '/*.yaml' -``` +- A project or group deploy token. +- A project or group deploy key. +- A project or group access token. +- A personal access token. -Instead, specify a single glob that matches all `*.yaml` files recursively: +The token does not need write access. -```yaml -gitops: - manifest_projects: - - id: project1 - paths: - - glob: '/**/*.yaml' -``` +You should use project deploy tokens if `http` access is possible. +If you require `git+ssh` access, you should use deploy keys. +To compare deploy keys and deploy tokens, see [Deploy keys](../../project/deploy_keys/index.md). -### Use multiple agents or projects +Support for automating deploy token creation, rotation, and reporting is proposed in [issue 389393](https://gitlab.com/gitlab-org/gitlab/-/issues/389393). -If you store your Kubernetes manifests in separate GitLab projects, -update your agent configuration file with the location of these projects. +### Flux to GitLab notification -WARNING: -The project with the agent's -configuration file can be private or public. Other projects with Kubernetes manifests must be public. Support for private manifest projects is tracked -in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7704). +If you configure Flux to synchronize from a Git source, [Flux can register an external job status](https://fluxcd.io/flux/components/notification/provider/#git-commit-status-updates) in GitLab pipelines. + +To get external job statuses from Flux, you can use: + +- A project or group deploy token. +- A project or group access token. +- A personal access token. + +The token requires `api` scope. To minimize the attack surface of a leaked token, you should use +a project access token. + +Integrating Flux into GitLab pipelines as a job is proposed in [issue 405007](https://gitlab.com/gitlab-org/gitlab/-/issues/405007). + +## Related topics + +- [GitOps working examples for training and demos](https://gitlab.com/groups/guided-explorations/gl-k8s-agent/gitops/-/wikis/home) +- [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters) +- Managing Kubernetes secrets in a GitOps workflow + - [with SOPS built-in to Flux](https://fluxcd.io/flux/guides/mozilla-sops/) + - [with Sealed Secrets](https://fluxcd.io/flux/guides/sealed-secrets/) diff --git a/doc/user/clusters/agent/gitops/agent.md b/doc/user/clusters/agent/gitops/agent.md new file mode 100644 index 00000000000..07ed2b3a691 --- /dev/null +++ b/doc/user/clusters/agent/gitops/agent.md @@ -0,0 +1,255 @@ +--- +stage: Deploy +group: Environments +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 +--- + +# Using GitOps with the agent for Kubernetes (deprecated) **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346585) to make the `id` attribute optional in GitLab 15.7. +> - Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/406545) in GitLab 16.2. You should use the [Flux integration](../gitops.md) for GitOps. + +This diagram shows the repositories and main actors in a GitOps deployment: + +```mermaid +sequenceDiagram + participant D as Developer + participant A as Application code repository + participant M as Manifest repository + participant K as GitLab agent + participant C as Agent configuration repository + loop Regularly + K-->>C: Grab the configuration + end + D->>+A: Pushing code changes + A->>M: Updating manifest + loop Regularly + K-->>M: Watching changes + M-->>K: Pulling and applying changes + end +``` + +For details, view the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). + +## Migrate to Flux + +You should migrate your legacy GitOps deployments so they can be +deployed with Flux. To migrate, configure Flux to deploy manifests +with Kustomize. If you don't have a `kustomization.yaml` file in +the given path, it is generated automatically. + +Prerequisites: + +- A configuration like: + + ```yaml + manifest_projects: + - id: my-group/my-project + default_namespace: production + paths: + - glob: 'environments/production/**/*.yaml' + ``` + +- A [Flux installation](https://fluxcd.io/flux/installation/) with manifests in `environments/flux-system`. +- You use a deploy token to access GitLab. +- Your cluster can access GitLab over HTTPS. + +To migrate: + +1. Create a file called `environments/flux-system/production.yaml` with the following contents: + + ```yaml + # This manifest was generated by flux. DO NOT EDIT. + --- + apiVersion: source.toolkit.fluxcd.io/v1 + kind: GitRepository + metadata: + name: production + namespace: flux-system + spec: + interval: 1m0s + ref: + branch: main + secretRef: + name: gitlab-deploy-token + url: https://gitlab.example.com/my-group/my-project.git + --- + apiVersion: kustomize.toolkit.fluxcd.io/v1 + kind: Kustomization + metadata: + name: production + namespace: flux-system + spec: + interval: 10m0s + path: ./environments/production + prune: true + sourceRef: + kind: GitRepository + name: production + ``` + +1. Optional. Because `agentk` uses the `default_namespace` by default, you might need to add a `kustomization.yaml` file to `/environments/production/` and list the relevant resources. + For example: + + ```yaml + apiVersion: kustomize.config.k8s.io/v1beta1 + kind: Kustomization + namespace: default + resources: + - relative/path/to-your/resource-1.yaml + - relative/path/to-your/resource-2.yaml + ``` + + When you commit the `kustomization.yaml` file to the repository, a reconciliation with Flux and `agentk` is triggered. + Because `agentk` can't handle the Kustomization file, it logs errors when you commit the file. + +1. To ensure Flux has taken over the management of the resource, check for the resource in the `status.inventory` value of the `production` Flux Kustomization object: + + ```shell + kubectl get kustomization production -n flux-system -o json | jq '.status.inventory.entries' + ``` + +1. Remove the entry from the `manifest_projects` list. + +After you migrate, your GitOps deployments deploy with Flux. +To get the most out of your Flux integration, see the [Flux Kustomization CRD](https://fluxcd.io/flux/components/kustomize/kustomization/) and [GitLab Flux documentation](../gitops.md). + +## GitOps workflow steps + +To update a Kubernetes cluster by using GitOps, complete the following steps. + +1. Ensure you have a working Kubernetes cluster, and that the manifests are in a GitLab project. +1. In the same project, [register and install the GitLab agent](../install/index.md). +1. Configure the agent configuration file so that the agent monitors the project for changes to the Kubernetes manifests. + Use the [GitOps configuration reference](#gitops-configuration-reference) for guidance. + +Any time you commit updates to your Kubernetes manifests, the agent updates the cluster. + +## GitOps configuration reference + +The following snippet shows an example of the possible keys and values for the GitOps section of an [agent configuration file](../install/index.md#create-an-agent-configuration-file) (`config.yaml`). + +```yaml +gitops: + manifest_projects: + - id: gitlab-org/cluster-integration/gitlab-agent + ref: # either `branch`, `tag` or `commit` can be specified + branch: production + # commit: <mysha> + # tag: v1.0 + default_namespace: my-ns + paths: + # Read all YAML files from this directory. + - glob: '/team1/app1/*.yaml' + # Read all .yaml files from team2/apps and all subdirectories. + - glob: '/team2/apps/**/*.yaml' + # If 'paths' is not specified or is an empty list, the configuration below is used. + - glob: '/**/*.{yaml,yml,json}' + reconcile_timeout: 3600s + dry_run_strategy: none + prune: true + prune_timeout: 3600s + prune_propagation_policy: foreground + inventory_policy: must_match +``` + +| Keyword | Description | +|--|--| +| `manifest_projects` | Projects where your Kubernetes manifests are stored. The agent monitors the files in the repositories in these projects. When manifest files change, the agent deploys the changes to the cluster. | +| `id` | Path to a Git repository that has Kubernetes manifests in YAML or JSON format. No authentication mechanisms are supported. Default is the agent configuration repository. | +| `ref` | Optional. Git reference in the configured Git repository to fetch the Kubernetes manifest files from. If not specified or empty, the default branch is used. If specified, it must contain either `branch`, `tag`, or `commit`. | +| `ref.branch` | Branch name in the configured Git repository to fetch the Kubernetes manifest files from. | +| `ref.tag` | Tag name in the configured Git repository to fetch the Kubernetes manifest files from. | +| `ref.commit` | Commit SHA in the configured Git repository to fetch the Kubernetes manifest files from. | +| `default_namespace` | Namespace to use if not set explicitly in object manifest. Also used for inventory `ConfigMap` objects. | +| `paths` | Repository paths to scan for manifest files. Directories with names that start with a dot `(.)` are ignored. | +| `paths[].glob` | Required. See [doublestar](https://github.com/bmatcuk/doublestar#about) and [the match function](https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match) for globbing rules. | +| `reconcile_timeout` | Determines whether the applier should wait until all applied resources have been reconciled, and if so, how long to wait. Default is 3600 seconds (1 hour). | +| `dry_run_strategy` | Determines whether changes [should be performed](https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/common/common.go#L68-L89). Can be: `none`, `client`, or `server`. Default is `none`.| +| `prune` | Determines whether pruning of previously applied objects should happen after apply. Default is `true`. | +| `prune_timeout` | Determines whether to wait for all resources to be fully deleted after pruning, and if so, how long to wait. Default is 3600 seconds (1 hour). | +| `prune_propagation_policy` | The deletion propagation policy that [should be used for pruning](https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470). Can be: `orphan`, `background`, or `foreground`. Default is `foreground`. | +| `inventory_policy` | Determines whether an inventory object can take over objects that belong to another inventory object or don't belong to any inventory object. This is done by determining if the apply/prune operation can go through for a resource based on comparison of the `inventory-id` value in the package and the `owning-inventory` annotation (`config.k8s.io/owning-inventory`) [in the live object](https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66). Can be: `must_match`, `adopt_if_no_inventory`, or `adopt_all`. Default is `must_match`. | + +## GitOps annotations + +The GitLab agent for Kubernetes has annotations you can use to: + +- **Sort resources**: Apply or delete resources in a specific order. +- **Use apply-time mutation**: Dynamically substitute fields from one resource configuration to another. + +The agent has [default sorting](https://github.com/kubernetes-sigs/cli-utils/blob/d7d63f4b62897f584ca9e02b6faf4d2f327a9b09/pkg/ordering/sort.go#L74), +but with annotations, you can fine-tune the order and apply time-value injection. + +To provide the GitOps functionality, the GitLab agent for Kubernetes uses the [`cli-utils` library](https://github.com/kubernetes-sigs/cli-utils/), +a Kubernetes SIG project. For more information, see the available annotations in the [`cli-utils` documentation](https://github.com/kubernetes-sigs/cli-utils/blob/master/README.md). + +## Automatic drift remediation + +Drift happens when the current configuration of an infrastructure resource differs from its desired configuration. +Typically, this is caused by manually editing resources directly rather than via the used infrastructure-as-code +mechanism. Minimizing the risk of drift helps to ensure configuration consistency and successful operations. + +In GitLab, the agent for Kubernetes regularly compares the desired state from the `git` repository with +the actual state from the Kubernetes cluster. Deviations from the `git` state are fixed at every check. These checks +happen automatically every 5 minutes. They are not configurable. + +The agent uses [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/). +As a result, every field in a resource can have different managers. Only fields managed by `git` +are checked for drift. This facilitates the use of in-cluster controllers to modify resources like +[Horizontal Pod Autoscalers](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). + +## Related topics + +- [GitOps working examples for training and demos](https://gitlab.com/groups/guided-explorations/gl-k8s-agent/gitops/-/wikis/home) +- [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters) +- [Managing Kubernetes secrets in a GitOps workflow](secrets_management.md) +- [Application and manifest repository example](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service-gitops) + +## Troubleshooting + +### Avoiding conflicts when you have multiple projects + +The agent watches each glob pattern set under a project's `paths` section independently, and makes updates to the cluster concurrently. +If changes are found at multiple paths, when the agent attempts to update the cluster, +a conflict can occur. + +To prevent this from happening, consider storing a logical group of manifests in a single place and reference them only once to avoid overlapping globs. + +For example, both of these globs match `*.yaml` files in the root directory +and could cause conflicts: + +```yaml +gitops: + manifest_projects: + - id: project1 + paths: + - glob: '/**/*.yaml' + - glob: '/*.yaml' +``` + +Instead, specify a single glob that matches all `*.yaml` files recursively: + +```yaml +gitops: + manifest_projects: + - id: project1 + paths: + - glob: '/**/*.yaml' +``` + +### Use multiple agents or projects + +If you store your Kubernetes manifests in separate GitLab projects, +update your agent configuration file with the location of these projects. + +WARNING: +The project with the agent's +configuration file can be private or public. Other projects with Kubernetes manifests must be public. Support for private manifest projects is tracked +in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7704). diff --git a/doc/user/clusters/agent/gitops/example_repository_structure.md b/doc/user/clusters/agent/gitops/example_repository_structure.md index 93c05e40bfd..a5bc3b153fe 100644 --- a/doc/user/clusters/agent/gitops/example_repository_structure.md +++ b/doc/user/clusters/agent/gitops/example_repository_structure.md @@ -60,7 +60,7 @@ the deployment branch back to the repository using the provided token. To preser commit history between both branches, the CI/CD job uses a fast-forward merge. Each cluster has an agent for Kubernetes, and each agent is configured to -[sync manifests from the branch corresponding to its cluster](../gitops.md#gitops-configuration-reference). +sync manifests from the branch corresponding to its cluster. In your own project, you can different GitOps tool like Flux, or use the same configuration to deploy to virtual machines with GitLab CI/CD. diff --git a/doc/user/clusters/agent/gitops/flux.md b/doc/user/clusters/agent/gitops/flux.md index f0a681c1a5c..13fcfeb28e9 100644 --- a/doc/user/clusters/agent/gitops/flux.md +++ b/doc/user/clusters/agent/gitops/flux.md @@ -1,97 +1,11 @@ --- -stage: Deploy -group: Environments -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: '../gitops.md' +remove_date: '2023-10-12' --- -# Flux (Beta) **(FREE)** +This document was moved to [another location](../gitops.md). -Flux is a GitOps tool that helps you manage your Kubernetes clusters. -You can use Flux to: - -- Keep your clusters in sync with your Git repositories. -- Reconcile code changes with your deployments. -- Manage your Flux installation itself with a bootstrap. - -You can use the agent for Kubernetes with Flux to: - -- Trigger immediate Git repository reconciliation. - -To get started, see the [Flux installation documentation](https://fluxcd.io/flux/installation). - -Support for Flux is in [Beta](../../../../policy/experiment-beta-support.md#beta). - -## Bootstrap installation - -Use the Flux command [`bootstrap gitlab`](https://fluxcd.io/flux/installation/#gitlab-and-gitlab-enterprise) -to configure a Kubernetes cluster to manage itself from a Git repository. - -You must authenticate your installation with either: - -- Recommended. [A project access token](../../../project/settings/project_access_tokens.md). -- A [group access token](../../../group/settings/group_access_tokens.md). -- A [personal access token](../../../profile/personal_access_tokens.md). - -Some Flux features like [automated image updates](https://fluxcd.io/flux/guides/image-update/) require -write access to the source repositories. - -## GitOps repository structure - -You should organize your repositories to meet the needs of your team. For detailed recommendations, see the Flux [repository structure documentation](https://fluxcd.io/flux/guides/repository-structure/). - -## Immediate Git repository reconciliation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1. - -Usually, the Flux source controller reconciles Git repositories at configured intervals. -This can cause delays between a `git push` and the reconciliation of the cluster state, and results in -unnecessary pulls from GitLab. - -The agent for Kubernetes automatically detects Flux `GitRepository` objects that -reference GitLab projects in the instance the agent is connected to, -and configures a [`Receiver`](https://fluxcd.io/flux/components/notification/receiver/) for the instance. -When the agent for Kubernetes detects a `git push`, the `Receiver` is triggered -and Flux reconciles the cluster with any changes to the repository. - -To use immediate Git repository reconciliation, you must have a Kubernetes cluster that runs: - -- The agent for Kubernetes. -- Flux `source-controller` and `notification-controller`. - -Immediate Git repository reconciliation can reduce the time between a push and reconciliation, -but it doesn't guarantee that every `git push` event is received. You should still set -[`GitRepository.spec.interval`](https://fluxcd.io/flux/components/source/gitrepositories/#interval) -to an acceptable duration. - -### Custom webhook endpoints - -When the agent for Kubernetes calls the `Receiver` webhook, -the agent defaults to `http://webhook-receiver.flux-system.svc.cluster.local`, -which is also the default URL set by a Flux bootstrap installation. To configure a custom -endpoint, set `flux.webhook_receiver_url` to a URL that the agent can resolve. For example: - -```yaml -flux: - webhook_receiver_url: http://webhook-receiver.another-flux-namespace.svc.cluster.local -``` - -There is special handing for -[service proxy URLs](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster-services/) configured -in this format: `/api/v1/namespaces/[^/]+/services/[^/]+/proxy`. For example: - -```yaml -flux: - webhook_receiver_url: /api/v1/namespaces/flux-system/services/http:webhook-receiver:80/proxy -``` - -In these cases, the agent for Kubernetes uses the available Kubernetes configuration -and context to connect to the API endpoint. -You can use this if you run an agent outside a cluster -and you haven't [configured an `Ingress`](https://fluxcd.io/flux/guides/webhook-receivers/#expose-the-webhook-receiver) -for the Flux notification controller. - -WARNING: -You should configure only trusted service proxy URLs. -When you provide a service proxy URL, -the agent for Kubernetes sends typical Kubernetes API requests which include -the credentials necessary to authenticate with the API service. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index c6c9ed9e373..8aee0c01d65 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -9,6 +9,9 @@ info: A tutorial using Flux This tutorial teaches you how to set up Flux for GitOps. You'll complete a bootstrap installation, install `agentk` in your cluster, and deploy a simple `nginx` application. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview of an example Flux +configuration, see [Flux bootstrap and manifest synchronization with GitLab](https://www.youtube.com/watch?v=EjPVRM-N_PQ). + To set up Flux for GitOps: 1. [Create a personal access token](#create-a-personal-access-token) @@ -97,7 +100,7 @@ To install `agentk`: apiVersion: v1 kind: Namespace metadata: - name: gitlab + name: gitlab ``` 1. Apply the agent registration token as a secret in the cluster: @@ -140,7 +143,7 @@ To install `agentk`: sourceRef: kind: HelmRepository name: gitlab-agent - namespace: gitlab-agent + namespace: gitlab interval: 1h0m0s values: config: @@ -177,8 +180,6 @@ To demonstrate, deploy an `nginx` application and point Flux at it: interval: 1m0s ref: branch: main - secretRef: - name: example-nginx-app url: https://gitlab.com/gitlab-examples/ops/gitops-demo/example-mini-flux-deployment.git --- apiVersion: kustomize.toolkit.fluxcd.io/v1 diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md index 182fd87e6f9..22587cd0e5d 100644 --- a/doc/user/clusters/agent/gitops/helm.md +++ b/doc/user/clusters/agent/gitops/helm.md @@ -1,152 +1,11 @@ --- -stage: Deploy -group: Environments -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: '../gitops.md' +remove_date: '2023-10-22' --- -# Using Helm charts to update a Kubernetes cluster (Experiment) **(FREE)** +This document was moved to [another location](../gitops.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371019) in GitLab 15.4. -> - Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7. - -You can deploy Helm charts to your Kubernetes cluster and keep the resources in your cluster in sync -with your charts and values. To do this, you use the pull-based GitOps features of the agent for -Kubernetes. - -This feature is an Experiment and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/7938) -to track future work. Tell us about your use cases by leaving comments in the epic. - -NOTE: -This feature is an Experiment. In future releases, to accommodate new features, the configuration format might change without notice. - -## GitOps workflow steps - -To update a Kubernetes cluster by using GitOps with charts, complete the following steps. - -1. Ensure you have a working Kubernetes cluster, and that the chart is in a GitLab project. -1. In the same project, [register and install the GitLab agent](../install/index.md). -1. Configure the agent configuration file so that the agent monitors the project for changes to the chart. - Use the [GitOps configuration reference](#helm-configuration-reference) for guidance. - -## Helm chart with GitOps workflow - -To update a Kubernetes cluster by using Helm charts: - -1. Ensure you have a working Kubernetes cluster. -1. In a GitLab project: - - Store your Helm charts. - - [Register and install the GitLab agent](../install/index.md). -1. Update the agent configuration file so that the agent monitors the project for changes to the chart. - Use the [configuration reference](#helm-configuration-reference) for guidance. - -Any time you commit updates to your chart repository, the agent applies the chart in the cluster. - -## Helm configuration reference - -The following snippet shows an example of the possible keys and values for the GitOps section of an [agent configuration file](../install/index.md#create-an-agent-configuration-file) (`config.yaml`). - -```yaml -gitops: - charts: - - release_name: my-application-release - source: - project: - id: my-group/my-project-with-chart - ref: - branch: production - path: dir-in-project/with/charts - namespace: my-ns - max_history: 1 - values: - - inline: - someKey: example value -``` - -| Keyword | Description | -|--|--| -| `charts` | List of charts you want to be applied in your cluster. Charts are applied concurrently. | -| `release_name` | Required. Name of the release to use when applying the chart. | -| `values` | Optional. [Custom values](#custom-values) for the release. An array of objects. Only supports `inline` values. | -| `namespace` | Optional. Namespace to use when applying the chart. Defaults to `default`. | -| `max_history` | Optional. Maximum number of release [revisions to store in the cluster](https://helm.sh/docs/helm/helm_history/). | -| `source` | Required. From where the chart should get installed. Only supports project sources. | -| `source.project.id` | Required. ID of the project where Helm chart is committed. Authentication is not supported. | -| `source.project.ref` | Optional. Git reference in the configured Git repository to fetch the Chart from. If not specified or empty, the default branch is used. If specified, it must contain either `branch`, `tag`, or `commit`. | -| `source.project.ref.branch` | Branch name in the configured Git repository to fetch the Chart from. | -| `source.project.ref.tag` | Tag name in the configured Git repository to fetch the Chart from. | -| `source.project.ref.commit` | Commit SHA in the configured Git repository to fetch the Chart from. | -| `source.project.path` | Optional. Path of the chart in the project repository. Root of the repository is used by default. Should be the directory with the `Chart.yaml` file. | - -## Custom values - -> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/766) in GitLab 15.6. Requires both GitLab and the installed agent to be version 15.6 or later. - -To customize the values for a release, set the `values` key. It must be -an array of objects. Each object must have exactly one top-level key that describes -where the values come from. The supported top-level keys are: - -- `inline`: Specify the values inline in YAML format, similar to a Helm values - file. - -When installing a chart with custom values: - -- Custom values get merged on top of the chart's default `values.yaml` file. -- Values from subsequent entries in the `values` array overwrite values from - previous entries. - -Example: - -```yaml -gitops: - charts: - - release_name: some-release - values: - - inline: - someKey: example value - # ... -``` - -## Automatic drift remediation - -Drift happens when the current configuration of an infrastructure resource differs from its desired configuration. -Typically, drift is caused by manually editing resources directly, rather than by editing the code that describes the desired state. Minimizing the risk of drift helps to ensure configuration consistency and successful operations. - -In GitLab, the agent for Kubernetes regularly compares the desired state from the chart source with -the actual state from the Kubernetes cluster. Deviations from the desired state are fixed at every check. These checks -happen automatically every 5 minutes. They are not configurable. - -## Example repository layout - -```plaintext -/my-chart - ├── templates - | └── ... - ├── charts - | └── ... - ├── Chart.yaml - ├── Chart.lock - ├── values.yaml - ├── values.schema.json - └── some-file-used-in-chart.txt -``` - -## Known issues - -The following are known issues: - -- Your chart must be in a GitLab project. The project must be an agent configuration project or a public - project. This known issue also exists for manifest-based GitOps and is tracked in - [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7704). -- Values for the chart must be in a `values.yaml` file. This file must be with the chart, - in the same project and path. -- Because of drift detection and remediation, the release history stored in the cluster is not useful. - A new release is created every five minutes and the oldest release is discarded. - Eventually history consists only of the same information. - View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/372023) for details. - -## Troubleshooting - -### Agent cannot find values for the chart - -Make sure values are in `values.yaml` and in the same directory as the `Chart.yaml` file. -The filename must be lowercase, with `.yaml` extension (not `.yml`). +<!-- This redirect file can be deleted after 2023-10-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/clusters/agent/gitops/secrets_management.md b/doc/user/clusters/agent/gitops/secrets_management.md index 6e1b7da9c6c..a9590f34183 100644 --- a/doc/user/clusters/agent/gitops/secrets_management.md +++ b/doc/user/clusters/agent/gitops/secrets_management.md @@ -4,7 +4,11 @@ group: Environments 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 --- -# Managing Kubernetes secrets in a GitOps workflow +# Managing Kubernetes secrets in a GitOps workflow (deprecated) + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/406545) in GitLab 16.2. +To manage cluster resources with GitOps, you should use the [Flux integration](../../../clusters/agent/gitops.md). You should never store Kubernetes secrets in unencrypted form in a `git` repository. If you use a GitOps workflow, you can follow these steps to securely manage your secrets. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 8b1a55bc7bd..a0d6e0d415d 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -34,7 +34,7 @@ You can choose from two primary workflows. The GitOps workflow is recommended. ### GitOps workflow -You should use Flux for GitOps. To get started, see the GitLab [Flux documentation](../../../user/clusters/agent/gitops/flux.md). +You should use Flux for GitOps. To get started, see [Tutorial: Set up Flux for GitOps](gitops/flux_tutorial.md) ### GitLab CI/CD workflow @@ -55,8 +55,11 @@ This workflow has a weaker security model and is not recommended for production ## Supported Kubernetes versions for GitLab features GitLab supports the following Kubernetes versions. If you want to run -GitLab in a Kubernetes cluster, you might need a different version of Kubernetes. -GitLab in a Kubernetes cluster, you might need [a different version of Kubernetes](https://docs.gitlab.com/charts/installation/cloud/index.html). +GitLab in a Kubernetes cluster, you might need a different version of Kubernetes: + +- For the [Helm Chart](https://docs.gitlab.com/charts/installation/cloud/index.html). +- For [GitLab Operator](https://docs.gitlab.com/operator/installation.html#kubernetes). + You can upgrade your Kubernetes version to a supported version at any time: diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 76fcc73504c..c847eaff13f 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -42,7 +42,7 @@ To install the agent in your cluster: For configuration settings, the agent uses a YAML file in the GitLab project. You must create this file if: -- You use [a GitOps workflow](../gitops.md#gitops-workflow-steps). +- You use [a GitOps workflow](../gitops/agent.md#gitops-workflow-steps). - You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#gitlab-cicd-workflow-steps) and want to authorize a different project to use the agent. - You [allow specific project or group members to access Kubernetes](../user_access.md). @@ -181,7 +181,7 @@ GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org To configure your agent, add content to the `config.yaml` file: -- For a GitOps workflow, [view the configuration reference](../gitops.md#gitops-configuration-reference). +- For a GitOps workflow, [view the configuration reference](../gitops/agent.md#gitops-configuration-reference). - For a GitLab CI/CD workflow, [authorize the agent to access your projects](../ci_cd_workflow.md#authorize-the-agent). Then [add `kubectl` commands to your `.gitlab-ci.yml` file](../ci_cd_workflow.md#update-your-gitlab-ciyml-file-to-run-kubectl-commands). @@ -238,6 +238,10 @@ helm upgrade gitlab-agent gitlab/gitlab-agent \ --set image.tag=v14.9.1 ``` +The Helm chart is updated separately from the agent for Kubernetes, and might occasionally lag behind the latest version of the agent. If you run `helm repo update` and don't specify an image tag, your agent runs the version specified in the chart. + +To use the latest release of the agent for Kubernetes, set the image tag to match the most recent agent image. + ## Uninstall the agent If you [installed the agent with Helm](#install-the-agent-with-helm), then you can also uninstall with Helm. For example, if the release and namespace are both called `gitlab-agent`, then you can uninstall the agent using the following command: diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 9c0733d66b7..eddc6ef3e16 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -11,7 +11,7 @@ When you are using the GitLab agent for Kubernetes, you might experience issues You can start by viewing the service logs: ```shell -kubectl logs -f -l=app=gitlab-agent -n gitlab-agent +kubectl logs -f -l=app.kubernetes.io/name=gitlab-agent -n gitlab-agent ``` If you are a GitLab administrator, you can also view the [GitLab agent server logs](../../../administration/clusters/kas.md#troubleshooting). @@ -108,8 +108,7 @@ certificate authority that is unknown to the agent. To fix this issue, you can present the CA certificate file to the agent by [customizing the Helm installation](install/index.md#customize-the-helm-installation). -Add `--set config.caCert="$(cat ~/path/to/ca.crt)"` to the `helm install` command. Make sure to replace `~/path/to/ca.crt` -with the path to your internal CA's certificate file. The file should be a valid PEM or DER-encoded certificate. +Add `--set-file config.caCert=my-custom-ca.pem` to the `helm install` command. The file should be a valid PEM or DER-encoded certificate. When you deploy `agentk` with a set `config.caCert` value, the certificate is added to `configmap` and the certificate file is mounted in `/etc/ssl/certs`. diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md index be3f88d072e..7e04091c940 100644 --- a/doc/user/clusters/agent/user_access.md +++ b/doc/user/clusters/agent/user_access.md @@ -6,7 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Grant users Kubernetes access (Beta) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). +> - Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2. +> - Feature flags `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125835) in GitLab 16.2. As an administrator of Kubernetes clusters in an organization, you can grant Kubernetes access to members of a specific project or group. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 8bf9ac7cf06..e8fb399d1b0 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -107,7 +107,8 @@ For more information about debugging, see [troubleshooting documentation](troubl > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327152) in GitLab 14.9. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336641) in GitLab 14.10, the agent token can be revoked from the UI. -> - Two-token limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361030) in GitLab 16.1. +> - Two-token limit [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361030/) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `cluster_agents_limit_tokens_created`. +> - Two-token limit [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/412399) in GitLab 16.2. Feature flag `cluster_agents_limit_tokens_created` removed. An agent can have only two active tokens at one time. diff --git a/doc/user/clusters/create/index.md b/doc/user/clusters/create/index.md index 57526394301..8dfeafeb48e 100644 --- a/doc/user/clusters/create/index.md +++ b/doc/user/clusters/create/index.md @@ -11,4 +11,5 @@ You connect the clusters to GitLab by using the agent for Kubernetes. - [Create a cluster on Google GKE](../../infrastructure/clusters/connect/new_gke_cluster.md) - [Create a cluster on Amazon EKS](../../infrastructure/clusters/connect/new_eks_cluster.md) +- [Create a cluster on Azure AKS](../../infrastructure/clusters/connect/new_aks_cluster.md) - [Create a cluster on Civo](../../infrastructure/clusters/connect/new_civo_cluster.md) diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index c6a61f58974..fa56dc320be 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -15,7 +15,7 @@ WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. 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 `certificate_based_clusters`. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `certificate_based_clusters`. Cluster environments provide a consolidated view of which CI [environments](../../ci/environments/index.md) are deployed to the Kubernetes cluster and it: @@ -48,7 +48,7 @@ To: After you have successful deployments to your group-level or instance-level cluster: -1. Navigate to your group's **Kubernetes** page. +1. Go to your group's **Kubernetes** page. 1. Select the **Environments** tab. Only successful deployments to the cluster are included in this page. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index ff6cf6bb1a8..9f769c6535c 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -16,7 +16,7 @@ To manage cluster applications, use the [GitLab agent](agent/index.md) with the [Cluster Management Project Template](management_project_template.md). 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 `certificate_based_clusters`. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `certificate_based_clusters`. A project can be designated as the management project for a cluster. A management project can be used to run deployment jobs with @@ -58,7 +58,7 @@ To associate a cluster management project with your cluster: 1. Navigate to the appropriate configuration page. For a: - [Project-level cluster](../project/clusters/index.md), go to your project's - **Infrastructure > Kubernetes clusters** page. + **Operate > Kubernetes clusters** page. - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. - [Instance-level cluster](../instance/clusters/index.md): diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index b7a68317fba..238cf10cba9 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -695,7 +695,7 @@ Additional configuration may be needed for connecting to private registries for: Prior to GitLab 13.3, offline environments required an exact name match for [project policies](../license_approval_policies.md). In GitLab 13.3 and later, GitLab matches the name of [project policies](../license_approval_policies.md) -with identifiers from the [SPDX license list](https://spdx.org/licenses/). +with license names from the [SPDX license list](https://spdx.org/licenses/). A local copy of the SPDX license list is distributed with the GitLab instance. If needed, the GitLab instance's administrator can manually update it with a [Rake task](../../../raketasks/spdx.md). @@ -705,9 +705,9 @@ We recommend that you use the most recent version of all containers, and the mos ## Troubleshooting -### ASDF_PYTHON_VERSION does not automatically install the version +### `ASDF_PYTHON_VERSION` does not automatically install the version -Defining a non-latest Python version in ASDF_PYTHON_VERSION [doesn't have it automatically installed](https://gitlab.com/gitlab-org/gitlab/-/issues/325604). If your project requires a non-latest version of Python: +Defining a non-latest Python version in `ASDF_PYTHON_VERSION` [doesn't have it automatically installed](https://gitlab.com/gitlab-org/gitlab/-/issues/325604). If your project requires a non-latest version of Python: 1. Define the required version by setting the `ASDF_PYTHON_VERSION` CI/CD variable. 1. Pass a custom script to the `SETUP_CMD` CI/CD variable to install the required version and dependencies. diff --git a/doc/user/compliance/license_list.md b/doc/user/compliance/license_list.md index 7f55ba50c5b..deec4e28911 100644 --- a/doc/user/compliance/license_list.md +++ b/doc/user/compliance/license_list.md @@ -24,7 +24,7 @@ Alternatively, licenses will also appear under the license list when using our d 1. Your project must use at least one of the [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). -When everything is configured, on the left sidebar, select **Security & Compliance > License Compliance**. +When everything is configured, on the left sidebar, select **Secure > License compliance**. The licenses are displayed, where: diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md index 22defd593cd..1fbe67a62b2 100644 --- a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -23,7 +23,7 @@ Licenses not in the SPDX list are reported as "Unknown". License information can Prerequisites: -- On GitLab self-managed only, enable [Synchronization with the GitLab License Database](../../admin_area/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in Admin Area for the GitLab instance. On GitLab SaaS this step has already been completed. +- On GitLab self-managed only, enable [Synchronization with the GitLab License Database](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in Admin Area for the GitLab instance. On GitLab SaaS this step has already been completed. - Enable [Dependency Scanning](../../application_security/dependency_scanning/index.md#configuration) and ensure that its prerequisites are met. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 03b48fd42b6..2e26b67170c 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -56,7 +56,7 @@ in a different color. > [Flag](../../administration/feature_flags.md) named `disable_all_mention` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110586) in GitLab 16.1. Disabled by default. [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/18442). FLAG: -On self-managed GitLab, by default this flag is not enabled. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) +On self-managed GitLab, by default this flag is not enabled. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `disable_all_mention`. On GitLab.com, this flag is enabled. @@ -103,7 +103,7 @@ To add a commit diff comment: The comment is displayed on the merge request's **Overview** tab. -The comment is not displayed on your project's **Repository > Commits** page. +The comment is not displayed on your project's **Code > Commits** page. NOTE: When your comment contains a reference to a commit included in the merge request, diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md index 36f698daf81..27fff4bf8e3 100644 --- a/doc/user/enterprise_user/index.md +++ b/doc/user/enterprise_user/index.md @@ -10,7 +10,7 @@ type: reference Enterprise users have user accounts that are administered by an organization that has purchased a [GitLab subscription](../../subscriptions/index.md). -Enterprise users are identified by the [**Enterprise** badge](../project/badges.md) +Enterprise users are identified by the **Enterprise** badge next to their names on the [Members list](../group/index.md#filter-and-sort-members-in-a-group). ## Provision an enterprise user @@ -47,17 +47,33 @@ Prerequisites: - A project in the group. - You must have the Owner role in the top-level group. -Setting up a verified domain is similar to [setting up a custom domain on GitLab Pages](../project/pages/custom_domains_ssl_tls_certification/index.md). However, you must: +Domain verification applies at the top-level group and to all subgroups and projects +nested under that top-level parent group. -- Link the domain to a single project. -- Configure the `TXT` only in the DNS record to verify the domain's ownership. +You cannot verify a domain for more than one group. For example, if a group named +'group1' has a verified domain named 'domain1', you cannot also verify 'domain1' +for a different group named 'group2'. -Domain verification is tied to the project you choose. A project is required because domain verification reuses the GitLab Pages verification feature, which requires a project. Domain verification applies at the top-level group and to all subgroups and projects nested under that top-level parent group. -A member in the chosen project with [at least the Maintainer role](../permissions.md#project-members-permissions) can modify or remove the domain verification. -If needed, you can create a new project to set up domain verification directly under your top-level group. This limits the ability to modify the domain verification to members with at least the Maintainer role. -For more information on group-level domain verification, see [epic 5299](https://gitlab.com/groups/gitlab-org/-/epics/5299). +Setting up a verified domain is similar to [setting up a custom domain on GitLab Pages](../project/pages/custom_domains_ssl_tls_certification/index.md). However, you: + +- Do not need to have a GitLab Pages website. +- Must link the domain to a single project, despite domain verification applying + at the top-level group and to all nested subgroups and projects, because domain + verification: + - Is tied to the project you choose. + - Reuses the GitLab Pages custom domain verification feature, which requires a project. +- Must configure the `TXT` only in the DNS record to verify the domain's ownership. + +In addition to appearing in the top-level group Domain Verification list, the +domain will also appear in the chosen project. A member in this project with +[at least the Maintainer role](../permissions.md#project-members-permissions) +can modify or remove the domain verification. -Steps: +If needed, you can create a new project to set up domain verification directly +under your top-level group. This limits the ability to modify the domain verification +to members with at least the Maintainer role. + +For more information on group-level domain verification, see [epic 5299](https://gitlab.com/groups/gitlab-org/-/epics/5299). #### 1. Add a custom domain for the matching email domain @@ -96,21 +112,13 @@ After you have added all the DNS records:  WARNING: -For GitLab instances with domain verification enabled, -if the domain cannot be verified for 7 days, that domain is removed -from the GitLab project. +For GitLab instances with domain verification enabled, if the domain cannot be verified for 7 days, that domain is removed from the GitLab project. > **Notes:** > -> - Domain verification is **required for GitLab.com users**; - for GitLab self-managed instances, your GitLab administrator has the option - to [disabled custom domain verification](../../administration/pages/index.md#custom-domain-verification). -> - [DNS propagation may take some time (up to 24 hours)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), - although it's usually a matter of minutes to complete. Until it does, verification - fails, and attempts to visit your domain result in a 404. -> - Once your domain has been verified, leave the verification record - in place. Your domain is periodically reverified, and may be - disabled if the record is removed. +> - Domain verification is **required for GitLab.com users** to be marked as enterprise users. +> - [DNS propagation can take up to 24 hours](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a couple of minutes to complete. Until it completes, the domain shows as unverified. +> - Once your domain has been verified, leave the verification record in place. Your domain is periodically reverified, and may be disabled if the record is removed. > - A valid certificate is not required for domain verification. ### View domains in group diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index 410bdc4b5f5..0af5c76ade8 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -7,9 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Free user limit **(FREE SAAS)** 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. +private visibility on GitLab SaaS. For existing namespaces created before December 28, 2022, the limit was applied on June 13, 2023. When the five-user limit is applied, top-level private namespaces exceeding the user limit are placed in a read-only state. These diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 82d0bfb035a..04858d8ac34 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -26,15 +26,23 @@ GitLab.com uses the default [SSH key restrictions](../../security/ssh_keys_restr ## SSH host keys fingerprints -Below are the fingerprints for SSH host keys on GitLab.com. The first time you -connect to a GitLab.com repository, one of these keys is displayed in the output. +Go to the current instance configuration to see the SSH host key fingerprints on +GitLab.com. + +1. Sign in to GitLab. +1. On the left sidebar, select **Help** (**{question-o}**) > **Help**. +1. On the Help page, select **Check the current instance configuration**. + +In the instance configuration, you see the **SSH host key fingerprints**: | Algorithm | MD5 (deprecated) | SHA256 | |------------------|------------------|---------| +| ECDSA | `f1:d0:fb:46:73:7a:70:92:5a:ab:5d:ef:43:e2:1c:35` | `HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw` | | ED25519 | `2e:65:6a:c8:cf:bf:b2:8b:9a:bd:6d:9f:11:5c:12:16` | `eUXGGm1YGsMAS7vkcx6JOJdOGHPem5gQp4taiCfCLB8` | | RSA | `b6:03:0e:39:97:9e:d0:e7:24:ce:a3:77:3e:01:42:09` | `ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ` | -| DSA (deprecated) | `7a:47:81:3a:ee:89:89:64:33:ca:44:52:3d:30:d4:87` | `p8vZBUOR0XQz6sYiaWSMLmh0t9i8srqYKool/Xfdfqw` | -| ECDSA | `f1:d0:fb:46:73:7a:70:92:5a:ab:5d:ef:43:e2:1c:35` | `HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw` | + +The first time you connect to a GitLab.com repository, one of these keys is +displayed in the output. ## SSH `known_hosts` entries @@ -61,11 +69,11 @@ and has its own dedicated IP addresses: The IP addresses for `mg.gitlab.com` are subject to change at any time. -### Service Desk custom mailbox +### Service Desk alias email address On GitLab.com, there's a mailbox configured for Service Desk with the email address: `contact-project+%{key}@incoming.gitlab.com`. To use this mailbox, configure the -[custom suffix](../project/service_desk.md#configure-a-custom-email-address-suffix) in project +[custom suffix](../project/service_desk.md#configure-a-suffix-for-service-desk-alias-email) in project settings. ## Backups @@ -156,8 +164,8 @@ the related documentation. | Setting | GitLab.com | Default (self-managed) | |----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|------------------------| -| Artifacts maximum size (compressed) | 1 GB | See [Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size). | -| Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | See [Default artifacts expiration](../admin_area/settings/continuous_integration.md#default-artifacts-expiration). | +| Artifacts maximum size (compressed) | 1 GB | See [Maximum artifacts size](../../administration/settings/continuous_integration.md#maximum-artifacts-size). | +| Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | See [Default artifacts expiration](../../administration/settings/continuous_integration.md#default-artifacts-expiration). | | Scheduled Pipeline Cron | `*/5 * * * *` | See [Pipeline schedules advanced configuration](../../administration/cicd.md#change-maximum-scheduled-pipeline-frequency). | | Maximum jobs in active pipelines | `500` for Free tier, `1000` for all trial tiers, `20000` for Premium, and `100000` for Ultimate. | See [Number of jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines). | | Maximum CI/CD subscriptions to a project | `2` | See [Number of CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project). | @@ -191,11 +199,11 @@ varies by format: ## Account and limit settings GitLab.com has the following account limits enabled. If a setting is not listed, -the default value [is the same as for self-managed instances](../admin_area/settings/account_and_limit_settings.md): +the default value [is the same as for self-managed instances](../../administration/settings/account_and_limit_settings.md): | Setting | GitLab.com default | |-------------------------------|--------------------| -| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | +| [Repository size including LFS](../../administration/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | | [Maximum import size](../project/settings/import_export.md#import-a-project-and-its-data) | 5 GB | | Maximum attachment size | 100 MB | @@ -216,7 +224,7 @@ The import sources that are available by default depend on which GitLab you use: - GitLab.com: all available import sources are enabled by default. - GitLab self-managed: no import sources are enabled by default and must be - [enabled](../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources). + [enabled](../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources). | Import source | GitLab.com default | GitLab self-managed default | |:----------------------------------------------------------------------------------------------------|:-----------------------|:----------------------------| @@ -343,7 +351,7 @@ after the limits change in January, 2021: More details are available on the rate limits for [protected paths](#protected-paths-throttle) and -[raw endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). +[raw endpoints](../../administration/settings/rate_limits_on_raw_endpoints.md). GitLab can rate-limit requests at several layers. The rate limits listed here are configured in the application. These limits are the most @@ -355,8 +363,8 @@ for GitLab.com, see For information on rate limiting responses, see: -- [List of headers on responses to blocked requests](../admin_area/settings/user_and_ip_rate_limits.md#response-headers). -- [Customizable response text](../admin_area/settings/user_and_ip_rate_limits.md#use-a-custom-rate-limit-response). +- [List of headers on responses to blocked requests](../../administration/settings/user_and_ip_rate_limits.md#response-headers). +- [Customizable response text](../../administration/settings/user_and_ip_rate_limits.md#use-a-custom-rate-limit-response). ### Protected paths throttle @@ -366,7 +374,7 @@ paths that exceed 10 requests per **minute** per IP address. See the source below for which paths are protected. This includes user creation, user confirmation, user sign in, and password reset. -[User and IP rate limits](../admin_area/settings/user_and_ip_rate_limits.md#response-headers) +[User and IP rate limits](../../administration/settings/user_and_ip_rate_limits.md#response-headers) includes a list of the headers responded to blocked requests. See [Protected Paths](../admin_area/settings/protected_paths.md) for more details. diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index b7acded6720..8bebaae003c 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -41,7 +41,7 @@ The group's new subgroups have push rules set for them based on either: > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/365357) in GitLab 16.0. You can set the permitted protocols used to access a group's repositories to either SSH, HTTPS, or both. This setting -is disabled when the [instance setting](../admin_area/settings/visibility_and_access_controls.md#configure-enabled-git-access-protocols) is +is disabled when the [instance setting](../../administration/settings/visibility_and_access_controls.md#configure-enabled-git-access-protocols) is configured by an administrator. To change the permitted Git access protocols for a group: @@ -63,11 +63,11 @@ address. This top-level group setting applies to: - The GitLab UI, including subgroups, projects, and issues. It does not apply to GitLab Pages. - [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) +[globally-allowed IP address ranges](../../administration/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). +[globally-allowed IP addresses](../../administration/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges). To restrict group access by IP address: @@ -253,6 +253,8 @@ For more information on the administration of LDAP and group sync, refer to the NOTE: When you add LDAP synchronization, if an LDAP user is a group member and they are not part of the LDAP group, they are removed from the group. +You can use a workaround to [manage project access through LDAP groups](../project/settings/index.md#manage-project-access-through-ldap-groups). + ### Create group links via CN **(PREMIUM SELF)** To create group links via CN: diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 47764b0c915..267cdbbebd3 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -11,8 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can create a compliance framework that is a label to identify that your project has certain compliance requirements or needs additional oversight. The label can optionally enforce -[compliance pipeline configuration](#compliance-pipelines) to the projects on which it is -[applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). +[compliance pipeline configuration](#compliance-pipelines) to the projects on which it is applied. Compliance frameworks are created on top-level groups. Group owners can create, edit, and delete compliance frameworks: @@ -24,6 +23,33 @@ Compliance frameworks are created on top-level groups. Group owners can create, Subgroups and projects have access to all compliance frameworks created on their top-level group. However, compliance frameworks cannot be created, edited, or deleted at the subgroup or project level. Project owners can choose a framework to apply to their projects. +## Add a compliance framework to a project + +Prerequisite: + +- The group to which the project belongs must have a compliance framework. + +To assign a compliance framework to a project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings** > **General**. +1. Expand **Compliance frameworks**. +1. Select a compliance framework. +1. Select **Save changes**. + +NOTE: +Frameworks cannot be added to projects in personal namespaces. + +### GraphQL API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) in GitLab 14.2. + +You can use the [GraphQL API](../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework) to add a +compliance framework to a project. + +If you create compliance frameworks on subgroups with GraphQL, the framework is created on the root ancestor if the user +has the correct permissions. The GitLab UI presents a read-only view to discourage this behavior. + ## Default compliance frameworks > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375036) in GitLab 15.6. @@ -104,6 +130,10 @@ However, the compliance pipeline configuration can reference the `.gitlab-ci.yml - Jobs and variables defined in the compliance pipeline can't be changed by variables in the labeled project's `.gitlab-ci.yml` file. +NOTE: +Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/414004), project pipelines must be included first at the top of compliance pipeline configuration +to prevent projects overriding settings downstream. + For more information, see: - [Example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from @@ -151,6 +181,13 @@ The following example `.compliance-gitlab-ci.yml` includes the `include` keyword configuration is also executed. ```yaml +include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) + - project: '$CI_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_SHA' # Must be defined or MR pipelines always use the use default branch + rules: + - if: $CI_PROJECT_PATH != "my-group/project-1" # Must be the hardcoded path to the project that hosts this configuration. + # Allows compliance team to control the ordering and interweaving of stages/jobs. # Stages without jobs defined will remain hidden. stages: @@ -210,13 +247,6 @@ audit trail: - echo "running $FOO" after_script: - "# No after scripts." - -include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) - - project: '$CI_PROJECT_PATH' - file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_SHA' # Must be defined or MR pipelines always use the use default branch - rules: - - if: $CI_PROJECT_PATH != "my-group/project-1" # Must be the hardcoded path to the project that hosts this configuration. ``` The `rules` configuration in the `include` definition avoids circular inclusion in case the compliance pipeline must be able to run in the host project itself. @@ -334,20 +364,6 @@ This alternative ensures the compliance pipeline does not re-start the parent pi ## Troubleshooting -### Cannot remove compliance framework from a project - -Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390626), if you move a project, its compliance -framework becomes orphaned and can't be removed. To manually remove a compliance framework from a project, run the -following GraphQL mutation with your project's ID: - -```graphql -mutation { - projectSetComplianceFramework(input: {projectId: "gid://gitlab/Project/1234567", complianceFrameworkId: null}) { - errors - } -} -``` - ### Compliance jobs are overwritten by target repository If you use the `extends` statement in a compliance pipeline configuration, compliance jobs are overwritten by the target repository job. For example, diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index cbab83dd61e..6bd57079c67 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -17,7 +17,7 @@ You can [customize the list](../project/index.md#create-a-project) of available 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. -You can also configure [custom templates for the instance](../admin_area/custom_project_templates.md). +You can also configure [custom templates for the instance](../../administration/custom_project_templates.md). ## Set up group-level project templates diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 4a913c385a0..47bcd92f134 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -107,8 +107,8 @@ To remove a list from an epic board: 1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). The list settings sidebar opens on the right. -1. Select **Remove list**. A confirmation dialog appears. -1. Select **OK**. +1. Select **Remove list**. +1. On the confirmation dialog, select **OK**. ### Create an epic from an epic board diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 9436ff317a7..8265540cc34 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -66,7 +66,7 @@ The parent epic's start date then reflects this change and propagates upwards to > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79940) in GitLab 14.9 [with a flag](../../../administration/feature_flags.md) named `epic_color_highlight`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `epic_color_highlight`. +On self-managed GitLab, by default this feature is not available. To make it available per group, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `epic_color_highlight`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. The feature is not ready for production use. @@ -161,9 +161,9 @@ Prerequisites: To close an epic, at the top of an epic, select **Close epic**. -<!-- Delete when the `moved_mr_sidebar` feature flag is removed --> +<!-- Delete when the `move_close_into_dropdown` feature flag is removed --> If you don't see this action at the top of an epic, your project or instance might have -enabled a feature flag for [moved actions](../../project/merge_requests/index.md#move-sidebar-actions) +enabled a feature flag to [moved it in the actions menu](../../project/issues/managing_issues.md#move-the-close-button-into-the-actions-menu). You can also use the `/close` [quick action](../../project/quick_actions.md). @@ -183,6 +183,10 @@ To do so, either: - Use the `/reopen` [quick action](../../project/quick_actions.md). +<!-- Delete when the `move_close_into_dropdown` feature flag is removed --> +If you don't see this action at the top of an epic, your project or instance might have +enabled a feature flag to [moved it in the actions menu](../../project/issues/managing_issues.md#move-the-close-button-into-the-actions-menu). + ## Go to an epic from an issue If an issue belongs to an epic, you can go to the parent epic with the @@ -262,7 +266,7 @@ To filter: 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 `or_issuable_queries`. +To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `or_issuable_queries`. On GitLab.com, this feature is not available. The feature is not ready for production use. @@ -351,8 +355,8 @@ you might not have permission to. ### Add a new issue to an epic -You can add an existing issue to an epic, or create a new issue that's -automatically added to the epic. +Add an existing issue to an epic, or create a new issue that's automatically +added to the epic. #### Add an existing issue to an epic @@ -389,6 +393,12 @@ To add an existing issue to an epic: Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts. +You can create a new issue from an epic only in projects that are in the epic's group or one of its +descendant subgroups. +To create a new issue in a [project that was shared with the epic's group](../../project/members/share_project_with_groups.md), +first [create the issue directly in the project](../../project/issues/create_issues.md#from-a-project), and +then [add an existing issue to an epic](#add-an-existing-issue-to-an-epic). + Prerequisites: - You must have at least the Guest role for the issue's project and the epic's group. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 0b9a1552281..154eb467ece 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -30,7 +30,7 @@ If you migrate from GitLab.com to self-managed GitLab, an administrator can crea > - `bulk_import_projects` feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.10. 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). +feature, an administrator can [enable it in application settings](../../../administration/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer). Migrating groups by direct transfer copies the groups from one place to another. You can: @@ -66,6 +66,8 @@ transfer. ### Limits +Hardcoded limits apply on migration by direct transfer. + | Limit | Description | |:------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 6 | Maximum number of migrations permitted by a destination GitLab instance per minute per user. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386452) in GitLab 15.9. | @@ -105,7 +107,7 @@ To migrate groups by direct transfer: - The network connection between instances or GitLab.com must support HTTPS. - Any firewalls must not block the connection between the source and destination GitLab instances. - Both GitLab instances must have group migration by direct transfer - [enabled in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) + [enabled in application settings](../../../administration/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) by an instance administrator. - The source GitLab instance must be running GitLab 14.0 or later. - You must have a [personal access token](../../../user/profile/personal_access_tokens.md) for the source GitLab @@ -136,10 +138,10 @@ To ensure GitLab maps users and their contributions correctly: Create the group you want to import to and connect the source GitLab instance: 1. Create either: - - A new group. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New group**. Then select **Import group**. + - A new group. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**. Then select **Import group**. - A new subgroup. On existing group's page, either: - Select **New subgroup**. - - On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New subgroup**. Then select the **import an existing group** link. + - On the left sidebar, at the top, select **Create new** (**{plus}**) and **New subgroup**. Then select the **import an existing group** link. 1. Enter the URL of a GitLab instance running GitLab 14.0 or later. 1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your source GitLab instance. 1. Select **Connect instance**. @@ -176,7 +178,7 @@ You can view all groups migrated by you by direct transfer listed on the group i To view group import history: 1. Sign in to GitLab. -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New group**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**. 1. Select **Import group**. 1. In the upper-right corner, select **History**. 1. If there are any errors for a particular import, you can see them by selecting **Details**. @@ -208,10 +210,10 @@ Group items that are migrated to the destination GitLab instance include: | Boards | [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18938) | | Board lists | [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24863) | | Epics <sup>1</sup> | [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/250281) | -| Group labels | [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) | +| Group labels <sup>2</sup> | [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) | | Iterations | [GitLab 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/292428) | | Iteration cadences | [GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96570) | -| Members <sup>2</sup> | [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/299415) | +| Members <sup>3</sup> | [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/299415) | | Group milestones | [GitLab 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/292427) | | Namespace settings | [GitLab 14.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85128) | | Release milestones | [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/339422) | @@ -222,6 +224,8 @@ Group items that are migrated to the destination GitLab instance include: associations [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62074) in GitLab 13.12, state and state ID [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28203) in GitLab 13.7, and system note metadata [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63551) in GitLab 14.0. +1. Group Labels cannot retain any associated Label Priorities during import. These labels will need to be re-prioritized manually + once the relevant Project is migrated to the destination instance. 1. Group members are associated with the imported group if the user: - Already exists in the destination GitLab instance. - Has a public email in the source GitLab instance that matches a confirmed email in the destination GitLab instance. @@ -490,7 +494,7 @@ for your version of GitLab to check which items can be imported to the destinati Group items that are exported include: - Milestones -- Labels +- Group Labels (_without_ associated label priorities) - Boards and Board Lists - Badges - Subgroups (including all the aforementioned data) @@ -550,7 +554,7 @@ You can also export a group [using the API](../../../api/group_import_export.md) ### Import the group -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New subgroup**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New subgroup**. 1. Select the **import an existing group** link. 1. Enter your group name. 1. Accept or modify the associated group URL. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 322cefc71d9..7ff9648e41e 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -38,7 +38,7 @@ Like projects, a group can be configured to limit the visibility of it to: - All authenticated users. - Only explicit group members. -The restriction for [visibility levels](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) +The restriction for [visibility levels](../../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels) on the application setting level also applies to groups. If set to internal, the explore page is empty for anonymous users. The group page has a visibility level icon. @@ -67,7 +67,7 @@ This page shows groups that you are a member of: To create a group: -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New group**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**. 1. Select **Create group**. 1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see [reserved names](../reserved_names.md). @@ -107,7 +107,7 @@ A group can also be removed from the groups dashboard: This action removes the group. It also adds a background job to delete all projects in the group. -In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on GitLab [Premium](https://about.gitlab.com/pricing/premium/) and [Ultimate](https://about.gitlab.com/pricing/ultimate/), this action adds a background job to mark a group for deletion. By default, the job schedules the deletion seven days in the future. You can modify this retention period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#deletion-protection). +In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on GitLab [Premium](https://about.gitlab.com/pricing/premium/) and [Ultimate](https://about.gitlab.com/pricing/ultimate/), this action adds a background job to mark a group for deletion. By default, the job schedules the deletion seven days in the future. You can modify this retention period through the [instance settings](../../administration/settings/visibility_and_access_controls.md#deletion-protection). In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion is removed from the group before the deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. @@ -160,6 +160,30 @@ Any group owner can approve or decline the request. If you change your mind before your request is approved, select **Withdraw Access Request**. +## View group members + +To view a group's members: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Manage > Members**. + +A table displays the member's: + +- **Account** name and username +- **Source** of their [membership](../project/members/index.md#membership-types). + For transparency, GitLab displays all membership sources of group members. + Members who have multiple membership sources are displayed and counted as separate members. + For example, if a member has been added to the group both directly and through inheritance, + the member is displayed twice in the **Members** table, with different sources, + and is counted as two individual members of the group. +- [**Max role**](../project/members/index.md#which-roles-you-can-assign) in the group +- **Expiration** date of their group membership +- **Activity** related to their account + +NOTE: +The display of group members' **Source** might be inconsistent. +For more information, see [issue 414557](https://gitlab.com/gitlab-org/gitlab/-/issues/414557). + ## Filter and sort members in a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. @@ -187,7 +211,7 @@ In lists of group members, entries can display the following badges: ### Search a group -You can search for members by name, username, or email. +You can search for members by name, username, or [public email](../profile/index.md#set-your-public-email). 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. 1. Select **Manage > Members**. @@ -283,4 +307,4 @@ To change the role that can create projects under a group: 1. Select the desired option in the **Roles allowed to create projects** dropdown list. 1. Select **Save changes**. -To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). +To change this setting globally, see [Default project creation protection](../../administration/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 284fb8b3d7c..b7bdf236ff7 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -131,7 +131,7 @@ After sharing the `Frontend` group with the `Engineering` group: - The **Groups** tab lists the `Engineering` group. - The **Groups** tab lists a group regardless of whether it is a public or private group. - All direct members of the `Engineering` group have access to the `Frontend` group. Direct members of `Engineering` that gain access to the `Frontend` group keep their same access level as in `Engineering`, but up to the maximum access level selected when sharing the group. Inherited members of the `Engineering` group do not gain access to the `Frontend` group. -- All direct members of the `Engineering` group count towards the billable members of the `Frontend` group. +- Direct members of the `Engineering` group who have the **Group Invite** badge next to their profile on the group's usage quota page count towards the billable members of the `Frontend` group. ## Remove a shared group @@ -338,7 +338,7 @@ To enable group file templates: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372040) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) name `support_group_level_merge_checks_setting`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `support_group_level_merge_checks_setting`. On GitLab.com, this feature is not available. @@ -434,11 +434,8 @@ for the ability to set merge request approval rules for groups is tracked in WARNING: This feature is in [Beta](../../policy/experiment-beta-support.md#beta). -Due to high demand, this feature may have unscheduled downtime and Code Suggestions in IDEs may be delayed. -Code Suggestions may produce -[low-quality or incomplete suggestions](../project/repository/code_suggestions.md#model-accuracy-and-quality). Beta users should read about the [known limitations](../project/repository/code_suggestions.md#known-limitations). -We look forward to hearing your feedback. +We look forward to hearing your [feedback](../project/repository/code_suggestions.md#feedback). You can give all users in a group and its subgroups access to [Code Suggestions](../project/repository/code_suggestions.md). diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md index 1dde36c5c70..85fdeeb25c7 100644 --- a/doc/user/group/moderate_users.md +++ b/doc/user/group/moderate_users.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8. -This is the group-level documentation. For self-managed instances, see the [administration documentation](../admin_area/moderate_users.md). +This is the group-level documentation. For self-managed instances, see the [administration documentation](../../administration/moderate_users.md). A group Owner can moderate user access by banning and unbanning users. diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index ee8ac50f021..cde19531ed3 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -9,11 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [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 available. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. On GitLab.com, this feature is available. This is the group-level documentation. For self-managed instances, see the [administration documentation](../../admin_area/reporting/git_abuse_rate_limit.md). -Git abuse rate limiting is a feature to automatically ban users who download, clone, or fork more than a specified number of repositories of a group in a given time frame. Banned users cannot access the top-level group or any of its non-public subgroups via HTTP or SSH. The rate limit also applies to users who authenticate with a [personal](../../../user/profile/personal_access_tokens.md) or [group access token](../../../user/group/settings/group_access_tokens.md). Access to unrelated groups is unaffected. +Git abuse rate limiting is a feature to automatically ban users who download, clone, pull, fetch, or fork more than a specified number of repositories of a group in a given time frame. Banned users cannot access the top-level group or any of its non-public subgroups via HTTP or SSH. The rate limit also applies to users who authenticate with a [personal](../../../user/profile/personal_access_tokens.md) or [group access token](../../../user/group/settings/group_access_tokens.md). Access to unrelated groups is unaffected. Git abuse rate limiting does not apply to top-level group owners, [deploy tokens](../../../user/project/deploy_tokens/index.md), or [deploy keys](../../../user/project/deploy_keys/index.md). diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index e5ca41accfc..6f5f4905102 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -18,7 +18,7 @@ It is similar to [repository analytics for projects](../../analytics/repository_ > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in GitLab 13.7. -The **Analytics > Repositories** group page displays the overall test coverage of all your projects in your group. +The **Analyze > Repository analytics** group page displays the overall test coverage of all your projects in your group. In the **Overall activity** section, you can see: - The number of projects with coverage reports. @@ -29,7 +29,7 @@ In the **Overall activity** section, you can see: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in GitLab 13.9. -The **Analytics > Repositories** group page displays the average test coverage of all your projects in your group in a graph for the last 30 days. +The **Analyze > Repository analytics** group page displays the average test coverage of all your projects in your group in a graph for the last 30 days. ## Latest project test coverage list diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index f2db36e80b1..f6eb4ad539c 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -55,8 +55,13 @@ Attribute mapping:  -NOTE: -Using the **Group ID** source attribute requires users to enter the group ID or object ID when configuring SAML group links. If available, use the **sAMAccountName** source attribute for the friendly group name instead. +Using the **Group ID** source attribute requires users to enter the group ID or object ID when configuring SAML group links. + +If available, you can add user-friendly group names instead. When setting up Azure group claims: + +1. Select the **sAMAccountName** source attribute. +1. Enter a group name. You can specify a name up to 256 characters long. +1. To ensure the attribute is part of the assertion, select **Emit group names for cloud-only groups**. [Azure AD limits the number of groups that can be sent in a SAML response to 150](https://support.esri.com/en-us/knowledge-base/000022190). If a user is a member of more than 150 groups, Azure does not include that user's group claim in the SAML response. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 5838b9821de..7795aed5fd0 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -396,11 +396,10 @@ convert the information to XML. An example SAML response is shown here. By default, users provisioned with SAML or SCIM are sent a verification email to verify their identity. Instead, you can [configure GitLab with a custom domain](../../enterprise_user/index.md#set-up-a-verified-domain) and GitLab automatically confirms user accounts. Users still receive an -[enterprise user](../../enterprise_user/index.md) welcome email. Confirmation is -bypassed for users: +[enterprise user](../../enterprise_user/index.md) welcome email. Confirmation is bypassed if both of the following are true: -- That are provisioned with SAML or SCIM. -- That have an email address that belongs to the verified domain. +- The user is provisioned with SAML or SCIM. +- The user has an email address that belongs to the verified domain. ### Block user access @@ -490,6 +489,18 @@ When the **Enforce SSO-only authentication for web activity for this group** opt - For non-members or users who are not signed in: - SSO is not enforced when they access public group resources. - SSO is enforced when they access private group resources. +- For items in the organization's group hierarchy, dashboard visibility is as + follows: + - SSO is enforced when viewing your [To-Do List](../../todos.md). Your + to-do items are hidden if your SSO session has expired, and an + [alert is shown](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115254). + - SSO is enforced when viewing your list of assigned issues. Your issues are + hidden if your SSO session has expired. + [Issue 414475](https://gitlab.com/gitlab-org/gitlab/-/issues/414475) proposes to change this + behavior so that issues are visible. + - SSO is not enforced when viewing lists of merge requests where you are the + assignee or your review is requested. You can see merge requests even if + your SSO session has expired. SSO enforcement for web activity has the following effects when enabled: diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index e5d6c86a5ac..9096824cc2c 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -38,7 +38,6 @@ You can configure one of the following as an identity provider: - [Azure Active Directory](#configure-azure-active-directory). - [Okta](#configure-okta). -- [OneLogin](#configure-onelogin). NOTE: Other providers can work with GitLab but they have not been tested and are not supported. @@ -159,15 +158,6 @@ To configure Okta for SCIM: 1. Select **Save**. 1. Assign users in the **Assignments** tab. Assigned users are created and managed in your GitLab group. -### Configure OneLogin - -Prerequisites: - -- [GitLab is configured](#configure-gitlab). - -OneLogin provides a **GitLab (SaaS)** app in their catalog, which includes a SCIM integration. Contact OneLogin if you -encounter issues. - ## User access > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an [**Enterprise**](../../enterprise_user/index.md) badge in the **Members** view. @@ -183,7 +173,11 @@ The following diagram describes what happens when you add users to your SCIM app graph TD A[Add User to SCIM app] -->|IdP sends user info to GitLab| B(GitLab: Does the email exist?) B -->|No| C[GitLab creates user with SCIM identity] - B -->|Yes| D[GitLab sends message back 'Email exists'] + B -->|Yes| D(GitLab: Is the user part of the group?) + D -->|No| E(GitLab: Is SSO enforcement enabled?) + E -->|No| G + E -->|Yes| F[GitLab sends message back:\nThe member's email address is not linked to a SAML account] + D -->|Yes| G[Associate SCIM identity to user] ``` During provisioning: diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index 33343c9b339..e4531882fc1 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -38,7 +38,7 @@ The following are possible solutions for problems where users cannot sign in: To check if a user's SAML `NameId` matches their SCIM `externalId`: -- Administrators can use the Admin Area to [list SCIM identities for a user](../../admin_area/index.md#user-identities). +- Administrators can use the Admin Area to [list SCIM identities for a user](../../../administration/admin_area.md#user-identities). - Group owners can see the list of users and the identifier stored for each user in the group SAML SSO Settings page. - You can use the [SCIM API](../../../api/scim.md) to manually retrieve the `external_uid` GitLab has stored for users and compare the value for each user from the [SAML API](../../../api/saml.md) . - Have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools) and compare the `external_uid` to @@ -182,7 +182,7 @@ In your Okta SCIM application, check that the SCIM **Base URL** is correct and p SCIM API endpoint URL. Check the following documentation to find information on this URL for: - [GitLab.com groups](scim_setup.md#configure-gitlab). -- [Self-managed GitLab instances](../../admin_area/settings/scim_setup.md#configure-gitlab). +- [Self-managed GitLab instances](../../../administration/settings/scim_setup.md#configure-gitlab). For self-managed GitLab instances, ensure that GitLab is publicly available so Okta can connect to it. If needed, you can [allow access to Okta IP addresses](https://help.okta.com/en-us/Content/Topics/Security/ip-address-allow-listing.htm) diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index e264778062b..76aa77d026b 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -25,7 +25,7 @@ Group access tokens are similar to [project access tokens](../../project/setting and [personal access tokens](../../profile/personal_access_tokens.md), except they are associated with a group rather than a project or user. -In self-managed instances, group access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. +In self-managed instances, group access tokens are subject to the same [maximum lifetime limits](../../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. WARNING: The ability to create group access tokens without an expiry date was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0. In GitLab 16.0 and later, existing group access tokens without an expiry date are automatically given an expiry date 365 days later than the current date. The automatic adding of an expiry date occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry date occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change. @@ -35,13 +35,13 @@ You can use group access tokens: - On GitLab SaaS: If you have the Premium or Ultimate license tier. Group access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). - On self-managed instances: With any license tier. If you have the Free tier: - Review your security and compliance policies around - [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). + [user self-enrollment](../../../administration/settings/sign_up_restrictions.md#disable-new-sign-ups). - Consider [disabling group access tokens](#enable-or-disable-group-access-token-creation) to lower potential abuse. You cannot use group access tokens to create other group, project, or personal access tokens. -Group access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) +Group access tokens inherit the [default prefix setting](../../../administration/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. ## Create a group access token using UI @@ -64,7 +64,7 @@ To create a group access token: - The token expires on that date at midnight UTC. - If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date. - By default, this date can be a maximum of 365 days later than the current date. - - An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. + - An instance-wide [maximum lifetime](../../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-group-access-token). 1. Select **Create group access token**. @@ -148,6 +148,7 @@ The scope determines the actions you can perform when you authenticate with a gr | `write_registry` | Grants write access (push) to the [Container Registry](../../packages/container_registry/index.md). | | `read_repository` | Grants read access (pull) to all repositories within a group. | | `write_repository` | Grants read and write access (pull and push) to all repositories within a group. | +| `create_runner` | Grants permission to create runners in a group. | ## Enable or disable group access token creation diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 81e972bf73b..84902a5cbe9 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -77,7 +77,7 @@ Prerequisites: - 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. + [disabled by an Administrator](../../../administration/admin_area.md#prevent-a-user-from-creating-groups) in the user's settings. NOTE: You cannot host a GitLab Pages subgroup website with a top-level domain name. For example, `subgroupname.example.io`. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 952552fc648..dba7a507fef 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -45,8 +45,8 @@ Value stream analytics offers different features at the project and group level |Total time chart|Yes|Yes|No| |Task by type chart|Yes|No|No| |DORA Metrics|Yes|Yes|No| -|Cycle time and lead time summary (Key metrics)|Yes|Yes|No| -|New issues, commits, and deploys (Key metrics)|Yes, excluding commits|Yes|Yes| +|Cycle time and lead time summary (Lifecycle metrics)|Yes|Yes|No| +|New issues, commits, and deploys (Lifecycle metrics)|Yes, excluding commits|Yes|Yes| |Uses aggregated backend|Yes|Yes|No| |Date filter behavior|Filters items [finished within the date range](https://gitlab.com/groups/gitlab-org/-/epics/6046)|Filters items by creation date.|Filters items by creation date.| |Authorization|At least reporter|At least reporter|Can be public| @@ -253,9 +253,9 @@ For the "Tasks by type" chart, only the Date range and Project selector filters The **Overview** page in value stream analytics displays key metrics of the DevSecOps lifecycle performance for projects and groups. -### Key metrics +### Lifecycle metrics -Value stream analytics includes the following key metrics: +Value stream analytics includes the following lifecycle metrics: - **Lead time**: Median time from when the issue was created to when it was closed. - **Cycle time**: Median time from first commit to issue closed. GitLab measures cycle time from the earliest commit of a @@ -290,21 +290,21 @@ NOTE: In GitLab 13.9 and later, deployment frequency metrics are calculated based on when the deployment was finished. In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on when the deployment was created. -## View key and DORA metrics +## View lifecycle and DORA metrics Prerequisite: - To view deployment metrics, you must have a [production environment configured](#how-value-stream-analytics-identifies-the-production-environment). -To view key lifecycle metrics: +To view lifecycle metrics: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Analyze > Value stream analytics**. - Key metrics display below the **Filter results** text box. + Lifecycle metrics display below the **Filter results** text box. 1. Optional. Filter the results: 1. Select the **Filter results** text box. - Based on the filter you select, the dashboard automatically aggregates key metrics and displays the status of the value stream. + Based on the filter you select, the dashboard automatically aggregates lifecycle metrics and displays the status of the value stream. 1. Select a parameter. 1. Select a value or enter text to refine the results. 1. To adjust the date range: @@ -315,7 +315,7 @@ To view the [Value Streams Dashboard](../../analytics/value_streams_dashboard.md 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. 1. Select **Analyze > Value stream analytics**. -1. Below the **Filter results** text box, in the **Key metrics** row, select **Value Streams Dashboard / DORA**. +1. Below the **Filter results** text box, in the **Lifecycle metrics** row, select **Value Streams Dashboard / DORA**. 1. Optional. To open the new page, append this path `/analytics/dashboards/value_streams_dashboard` to the group URL (for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards/value_streams_dashboard`). diff --git a/doc/user/img/award_emoji_votes_sort_options.png b/doc/user/img/award_emoji_votes_sort_options.png Binary files differdeleted file mode 100644 index dc02d5169e0..00000000000 --- a/doc/user/img/award_emoji_votes_sort_options.png +++ /dev/null diff --git a/doc/user/img/custom_emoji_reactions_v16_2.png b/doc/user/img/custom_emoji_reactions_v16_2.png Binary files differnew file mode 100644 index 00000000000..a4d18edf8a5 --- /dev/null +++ b/doc/user/img/custom_emoji_reactions_v16_2.png diff --git a/doc/user/img/objective_two_column_view_v16_2.png b/doc/user/img/objective_two_column_view_v16_2.png Binary files differnew file mode 100644 index 00000000000..d3f4f733e7e --- /dev/null +++ b/doc/user/img/objective_two_column_view_v16_2.png diff --git a/doc/user/img/rich_text_editor_01_v16_2.png b/doc/user/img/rich_text_editor_01_v16_2.png Binary files differnew file mode 100644 index 00000000000..7242f7169d5 --- /dev/null +++ b/doc/user/img/rich_text_editor_01_v16_2.png diff --git a/doc/user/img/rich_text_editor_02_v16_2.png b/doc/user/img/rich_text_editor_02_v16_2.png Binary files differnew file mode 100644 index 00000000000..b99f540cb60 --- /dev/null +++ b/doc/user/img/rich_text_editor_02_v16_2.png diff --git a/doc/user/img/rich_text_editor_03_v16_2.png b/doc/user/img/rich_text_editor_03_v16_2.png Binary files differnew file mode 100644 index 00000000000..5ee560fe79e --- /dev/null +++ b/doc/user/img/rich_text_editor_03_v16_2.png diff --git a/doc/user/img/rich_text_editor_04_v16_2.png b/doc/user/img/rich_text_editor_04_v16_2.png Binary files differnew file mode 100644 index 00000000000..70f89754f92 --- /dev/null +++ b/doc/user/img/rich_text_editor_04_v16_2.png diff --git a/doc/user/img/task_two_column_view_v16_2.png b/doc/user/img/task_two_column_view_v16_2.png Binary files differnew file mode 100644 index 00000000000..8ca87f55f8a --- /dev/null +++ b/doc/user/img/task_two_column_view_v16_2.png diff --git a/doc/user/img/todos_add_okrs_v16_0.png b/doc/user/img/todos_add_okrs_v16_0.png Binary files differdeleted file mode 100644 index 45c04e647e2..00000000000 --- a/doc/user/img/todos_add_okrs_v16_0.png +++ /dev/null diff --git a/doc/user/img/todos_add_todo_sidebar_v14_1.png b/doc/user/img/todos_add_todo_sidebar_v14_1.png Binary files differdeleted file mode 100644 index 65120beca29..00000000000 --- a/doc/user/img/todos_add_todo_sidebar_v14_1.png +++ /dev/null diff --git a/doc/user/img/todos_mark_done_okrs_v16_0.png b/doc/user/img/todos_mark_done_okrs_v16_0.png Binary files differdeleted file mode 100644 index 545b3569ed5..00000000000 --- a/doc/user/img/todos_mark_done_okrs_v16_0.png +++ /dev/null diff --git a/doc/user/img/todos_mark_done_sidebar_v14_1.png b/doc/user/img/todos_mark_done_sidebar_v14_1.png Binary files differdeleted file mode 100644 index 628fe65a7c1..00000000000 --- a/doc/user/img/todos_mark_done_sidebar_v14_1.png +++ /dev/null diff --git a/doc/user/infrastructure/clusters/connect/new_aks_cluster.md b/doc/user/infrastructure/clusters/connect/new_aks_cluster.md new file mode 100644 index 00000000000..24933875d48 --- /dev/null +++ b/doc/user/infrastructure/clusters/connect/new_aks_cluster.md @@ -0,0 +1,132 @@ +--- +stage: Deploy +group: Environments +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 +--- + +# Create an Azure AKS cluster + +You can create a cluster on Azure Kubernetes Service (AKS) through +[Infrastructure as Code (IaC)](../../index.md). This process uses the Azure and +Kubernetes Terraform providers to create AKS clusters. You connect the clusters to GitLab +by using the GitLab agent for Kubernetes. + +**Prerequisites:** + +- A Microsoft Azure account, with a set of configured + [security credentials](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli). +- [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline. + +**Steps:** + +1. [Import the example project](#import-the-example-project). +1. [Register the agent for Kubernetes](#register-the-agent). +1. [Configure your project](#configure-your-project). +1. [Provision your cluster](#provision-your-cluster). + +## Import the example project + +To create a cluster from GitLab using Infrastructure as Code, you must +create a project to manage the cluster from. In this tutorial, you start with +a sample project and modify it according to your needs. + +Start by [importing the example project by URL](../../../project/import/repo_by_url.md). + +To import the project: + +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Import project**. +1. Select **Repository by URL**. +1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/ci-cd/deploy-stage/environments-group/examples/gitlab-terraform-aks.git`. +1. Complete the fields and select **Create project**. + +This project provides you with: + +- An [Azure Kubernetes Service (AKS)](https://gitlab.com/gitlab-org/ci-cd/deploy-stage/environments-group/examples/gitlab-terraform-aks/-/blob/main/aks.tf) cluster. +- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/ci-cd/deploy-stage/environments-group/examples/gitlab-terraform-aks/-/blob/main/agent.tf) installed in the cluster. + +## Register the agent + +To create a GitLab agent for Kubernetes: + +1. On the left sidebar, select **Operate > Kubernetes clusters**. +1. Select **Connect a cluster (agent)**. +1. From the **Select an agent** dropdown list, select `aks-agent` and select **Register an agent**. +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. + +## Configure your project + +Use CI/CD environment variables to configure your project. + +**Required configuration:** + +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Variables**. +1. Set the variable `AZURE_CLIENT_ID` to your Azure client ID. +1. Set the variable `AZURE_CLIENT_SECRET` to your Azure client secret. +1. Set the variable `AZURE_TENANT_ID` to your service principal. +1. Set the variable `TF_VAR_agent_token` to the agent token displayed in the previous task. +1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task. + +**Optional configuration:** + +The file [`variables.tf`](https://gitlab.com/gitlab-org/ci-cd/deploy-stage/environments-group/examples/gitlab-terraform-aks/-/blob/main/variables.tf) +contains other variables that you can override according to your needs: + +- `TF_VAR_location`: Set your cluster's region. +- `TF_VAR_cluster_name`: Set your cluster's name. +- `TF_VAR_kubernetes_version`: Set the version of Kubernetes. +- `TF_VAR_create_resource_group`: Allow to enable or disable the creation of a new resource group. (Default set to true). +- `TF_VAR_resource_group_name`: Set the name of resource group. +- `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent. + +See the [Azure Terraform provider](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options. + +## Provision your cluster + +After configuring your project, manually trigger the provisioning of your cluster. In GitLab: + +1. On the left sidebar, select **Build > Pipelines**. +1. Next to **Play** (**{play}**), select the dropdown list icon (**{chevron-lg-down}**). +1. Select **Deploy** to manually trigger the deployment job. + +When the pipeline finishes successfully, you can view the new cluster: + +- In Azure: From the [Azure portal](https://portal.azure.com/#home), select **Kubernetes services > View**. +- In GitLab: On the left sidebar, select **Operate > Kubernetes clusters**. + +## Use your cluster + +After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: + +1. On the left sidebar, select **Operate > Kubernetes clusters**. +1. In the list, view the **Connection status** column. + +For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). + +## Remove the cluster + +A cleanup job is not included in your pipeline by default. To remove all created resources, you +must modify your GitLab CI/CD template before running the cleanup job. + +To remove all resources: + +1. Add the following to your `.gitlab-ci.yml` file: + + ```yaml + stages: + - init + - validate + - test + - build + - deploy + - cleanup + + destroy: + extends: .terraform:destroy + needs: [] + ``` + +1. On the left sidebar, select **Build > Pipelines** and select the most recent pipeline. +1. For the `destroy` job, select **Play** (**{play}**). diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index 7c8065b6143..91429e203f3 100644 --- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -52,7 +52,7 @@ This project provides you with: To create a GitLab agent for Kubernetes: -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. Select **Connect a cluster (agent)**. 1. From the **Select an agent** dropdown list, select `civo-agent` and select **Register an agent**. 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. @@ -91,20 +91,20 @@ Refer to the [Civo Terraform provider](https://registry.terraform.io/providers/c After configuring your project, manually trigger the provisioning of your cluster. In GitLab: -1. On the left sidebar, go to **CI/CD > Pipelines**. +1. On the left sidebar, go to **Build > Pipelines**. 1. Next to **Play** (**{play}**), select the dropdown list icon (**{chevron-lg-down}**). 1. Select **Deploy** to manually trigger the deployment job. When the pipeline finishes successfully, you can see your new cluster: - In Civo dashboard: on your Kubernetes tab. -- In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**. +- In GitLab: from your project's sidebar, select **Operate > Kubernetes clusters**. ## Use your cluster After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. In the list, view the **Connection status** column. For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). @@ -131,7 +131,7 @@ To remove all resources: needs: [] ``` -1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline. +1. On the left sidebar, select **Build > Pipelines** and select the most recent pipeline. 1. For the `destroy` job, select **Play** (**{play}**). ## Civo support diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 19bcce581e9..ef51db097d9 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -55,7 +55,7 @@ In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `ce To create a GitLab agent for Kubernetes: -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. Select **Connect a cluster (agent)**. 1. From the **Select an agent** dropdown list, select `eks-agent` and select **Register an agent**. 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. @@ -139,20 +139,20 @@ View the [AWS Terraform provider](https://registry.terraform.io/providers/hashic After configuring your project, manually trigger the provisioning of your cluster. In GitLab: -1. On the left sidebar, go to **CI/CD > Pipelines**. +1. On the left sidebar, go to **Build > Pipelines**. 1. Next to **Play** (**{play}**), select the dropdown list icon (**{chevron-lg-down}**). 1. Select **Deploy** to manually trigger the deployment job. When the pipeline finishes successfully, you can view the new cluster: - In AWS: From the [EKS console](https://console.aws.amazon.com/eks/home), select **Amazon EKS > Clusters**. -- In GitLab: On the left sidebar, select **Infrastructure > Kubernetes clusters**. +- In GitLab: On the left sidebar, select **Operate > Kubernetes clusters**. ## Use your cluster After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. In the list, view the **Connection status** column. For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). @@ -180,5 +180,5 @@ To remove all resources: needs: [] ``` -1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline. +1. On the left sidebar, select **Build > Pipelines** and select the most recent pipeline. 1. For the `destroy` job, select **Play** (**{play}**). diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 25a0a7149e0..3d717e0f473 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -62,7 +62,7 @@ In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `ce To create a GitLab agent for Kubernetes: -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. Select **Connect a cluster (agent)**. 1. From the **Select an agent** dropdown list, select `gke-agent` and select **Register an agent**. 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. @@ -117,20 +117,20 @@ Refer to the [Google Terraform provider](https://registry.terraform.io/providers After configuring your project, manually trigger the provisioning of your cluster. In GitLab: -1. On the left sidebar, go to **CI/CD > Pipelines**. +1. On the left sidebar, go to **Build > Pipelines**. 1. Next to **Play** (**{play}**), select the dropdown list icon (**{chevron-lg-down}**). 1. Select **Deploy** to manually trigger the deployment job. When the pipeline finishes successfully, you can see your new cluster: - In GCP: on your [GCP console's Kubernetes list](https://console.cloud.google.com/kubernetes/list). -- In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**. +- In GitLab: from your project's sidebar, select **Operate > Kubernetes clusters**. ## Use your cluster After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. In the list, view the **Connection status** column. For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). @@ -158,5 +158,5 @@ To remove all resources: needs: [] ``` -1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline. +1. On the left sidebar, select **Build > Pipelines** and select the most recent pipeline. 1. For the `destroy` job, select **Play** (**{play}**). diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index 50185966267..4c55a87a52c 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -4,11 +4,15 @@ group: Environments 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 --- -# Tracking cluster resources managed by GitLab **(FREE)** +# Tracking cluster resources managed by GitLab (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3. +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/406545) in GitLab 16.2. +To manage cluster resources with GitOps, you should use the [Flux integration](../../../clusters/agent/gitops.md). + GitLab uses an inventory object to track the resources you deploy to your cluster. The inventory object is a `ConfigMap` that contains a list of controlled objects. The managed resources use the `cli-utils.sigs.k8s.io/inventory-id` annotation. 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 3084cc28c9b..e23f5e8745c 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -25,15 +25,22 @@ For GitLab Runner to function, you _must_ specify the following in your - `gitlabUrl`: The GitLab server full URL (for example, `https://gitlab.example.com`) to register the Runner against. -- `runnerRegistrationToken`: The registration token for adding new runners to GitLab. - This must be [retrieved from your GitLab instance](../../../../../ci/runners/index.md). +- Runner token: This must be [retrieved](../../../../../ci/runners/index.md) from your GitLab instance. You can use + either of the following tokens: + + - `runnerToken`: The runner authentication token for the runner configuration [created in the GitLab UI](../../../../../ci/runners/runners_scope.md). + - `runnerRegistrationToken` ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102681) in GitLab 15.6 and scheduled to be removed in GitLab 17.0): The registration token for used to add new runners to GitLab. These values can be specified using [CI/CD variables](../../../../../ci/variables/index.md): - `CI_SERVER_URL` is used for `gitlabUrl`. If you are using GitLab.com, you don't need to set this variable. -- `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` +- `GITLAB_RUNNER_TOKEN` is used for `runnerToken`. +- `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` (deprecated). + +The methods of specifying these values are mutually exclusive. You can either: -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`. +- Specify the variables `GITLAB_RUNNER_TOKEN` and `CI_SERVER_URL` as CI variables (recommended). +- Provide values for `runnerToken:` 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#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. diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index a21c7271e7a..614e0f5a7e5 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -70,7 +70,7 @@ In your Auto DevOps project, you can use the GitLab agent to connect with your K - Add a key called `KUBE_NAMESPACE` with a value of the Kubernetes namespace for your deployments to target. Set the same environment scope. 1. Select **Add variable**. -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. From the certificate-based clusters section, open the cluster that serves the same environment scope. 1. Select the **Details** tab and disable the cluster. 1. Edit your `.gitlab-ci.yml` file and ensure it's using the Auto DevOps template. For example: @@ -85,7 +85,7 @@ In your Auto DevOps project, you can use the GitLab agent to connect with your K KUBE_NAMESPACE: "demo-agent" ``` -1. To test your pipeline, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. +1. To test your pipeline, on the left sidebar, select **Build > Pipelines** and then **Run pipeline**. For an example, [view this project](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service). diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 12ad207e4f8..f27f1306c31 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -54,7 +54,7 @@ If you use earlier versions of GitLab, you might face incompatibility errors between the GitLab version and the template version. In this case, you can opt to use one of these templates: -- [The stable template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) with an skeleton that you can built on top of. +- [The stable template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) with a skeleton that you can built on top of. - [The advanced template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) to fully customize your setup. NOTE: diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index b2e02cd7375..26bb1d16510 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -95,19 +95,17 @@ To manually configure a GitLab Terraform Report artifact: ```yaml default: image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - cache: key: example-production paths: - ${TF_ROOT}/.terraform + before_script: + - cd ${TF_ROOT} variables: TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production -before_script: - - cd ${TF_ROOT} - stages: - prepare - validate @@ -161,7 +159,6 @@ default: entrypoint: - '/usr/bin/env' - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' - cache: paths: - .terraform diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 455f2ce19e8..31c4ad757c8 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -321,7 +321,7 @@ curl --header "Private-Token: <your_access_token>" --request DELETE "https://git If you have at least the Maintainer role, you can remove a state file. -1. On the left sidebar, select **Infrastructure > Terraform states**. +1. On the left sidebar, select **Operate > Terraform states**. 1. In the **Actions** column, select **Actions** (**{ellipsis_v}**) and then **Remove state file and versions**. ### Remove a state file by using the API diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 401fe0bcb09..c3e4f77411c 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -58,7 +58,7 @@ Features not found in standard Markdown: - [Color chips written in `HEX`, `RGB` or `HSL`](#colors) - [Diagrams and flowcharts](#diagrams-and-flowcharts) -- [Emoji](#emojis) +- [Emoji](#emoji) - [Front matter](#front-matter) - [Inline diffs](#inline-diff) - [Math equations and symbols written in LaTeX](#math) @@ -207,9 +207,9 @@ installation of GitLab, a GitLab administrator [must enable it](../administratio To make Kroki available in GitLab, a GitLab administrator must enable it. For more information, see the [Kroki integration](../administration/integration/kroki.md) page. -### Emojis +### Emoji -[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emojis). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emoji). ::Tabs @@ -250,13 +250,13 @@ for a list of all supported emoji codes. :thumbsup: ::EndTabs -#### Emojis and your operating system +#### Emoji and your operating system -The previous emoji example uses hard-coded images. Rendered emojis +The previous emoji example uses hard-coded images. Rendered emoji in GitLab may be different depending on the OS and browser used. -Most emojis are natively supported on macOS, Windows, iOS, Android, and fall back on image-based -emojis where there is no support. +Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based +emoji where there is no support. <!-- vale gitlab.Spelling = NO --> @@ -266,7 +266,7 @@ this font installed by default. <!-- vale gitlab.Spelling = YES --> -To learn more about adding custom emojis, see [Custom emojis](award_emojis.md#custom-emojis). +To learn more about adding custom emoji, see [Custom emoji](award_emojis.md#custom-emoji). ### Front matter @@ -569,13 +569,13 @@ This example links to `<wiki_root>/miscellaneous.md`: In wikis, you can use the [diagrams.net](https://www.diagrams.net/) editor to create diagrams. You can also edit diagrams created with the diagrams.net editor. The diagram editor is available in both -the Markdown editor and the content editor. +the plain text editor and the rich text editor. For more information, see [Diagrams.net](../administration/integration/diagrams_net.md). -##### Markdown editor +##### Plain text editor -To create a diagram in the Markdown editor: +To create a diagram in the plain text editor: 1. In the editor's toolbar, select **Insert or edit diagram** (**{diagram}**). 1. Use the diagrams.net editor to create the diagram. @@ -583,20 +583,20 @@ To create a diagram in the Markdown editor: A Markdown image reference to the diagram is inserted in the wiki content. -To edit a diagram in the Markdown editor: +To edit a diagram in the plain text editor: -1. Place the Markdown editor's text field cursor in a Markdown image reference +1. Place the plain text editor's text field cursor in a Markdown image reference that contains the diagram. -1. Select **Insert or edit diagram** (**{diagram}**) in the Markdown editor. +1. Select **Insert or edit diagram** (**{diagram}**) in the plain text editor. 1. Use the diagrams.net editor to edit the diagram. 1. Select **Save & exit**. A Markdown image reference to the diagram is inserted in the wiki content, replacing the previous diagram. -##### Content editor +##### Rich text editor -To create a diagram in the content editor: +To create a diagram in the rich text editor: 1. In the editor's toolbar, select **More options** (**{plus}**). 1. In the dropdown list, select **Create or edit diagram**. @@ -605,7 +605,7 @@ To create a diagram in the content editor: The diagram as visualized in the diagrams.net editor is inserted in the wiki content. -To edit a diagram in the content editor: +To edit a diagram in the rich text editor: 1. Select the diagram that you want to edit. 1. In the floating toolbar, select **Edit diagram** (**{diagram}**). @@ -1082,6 +1082,8 @@ The following codeblock uses HTML to skip the Vale ReferenceLinks test. Do not change it back to a markdown codeblock. --> +<!-- markdownlint-disable proper-names --> + <pre class="highlight"><code>Inline-style (hover to see title text):  @@ -1093,6 +1095,8 @@ Reference-style (hover to see title text): [logo]: img/markdown_logo.png "Title Text" </code></pre> +<!-- markdownlint-enable proper-names --> + <!-- DO NOT change the name of markdown_logo.png. This file is used for a test in spec/controllers/help_controller_spec.rb. diff --git a/doc/user/okrs.md b/doc/user/okrs.md index 2abaf9f8008..6579ecbadbc 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -12,7 +12,7 @@ OKRs are an [Experiment](../policy/experiment-beta-support.md#experiment). 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 per project, ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `okrs_mvc`. +On self-managed GitLab, by default this feature is not available. To make it available per project, an administrator can [enable the featured flag](../administration/feature_flags.md) named `okrs_mvc`. On GitLab.com, this feature is not available. The feature is not ready for production use. @@ -353,3 +353,18 @@ Prerequisites: By default, child OKRs are ordered by creation date. To reorder them, drag them around. + +## Two-column layout + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `work_items_mvc_2`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +When enabled, OKRs use a two-column layout, similar to issues. +The description and threads are on the left, and attributes, such as labels +or assignees, on the right. + + diff --git a/doc/user/organization/index.md b/doc/user/organization/index.md index f5af26250f6..2a33543fea5 100644 --- a/doc/user/organization/index.md +++ b/doc/user/organization/index.md @@ -24,7 +24,7 @@ everything you do as a GitLab administrator, including: - Aggregating data from all your groups, subgroups, and projects. 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: +[Admin Area settings](../../administration/settings/index.md) moving to either: - Groups. Available in the Organization, and subgroups. - Hardware Controls. For functionality that does not apply to groups, Hardware Controls are only diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index b990cf1f09b..3f8b0761188 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -76,7 +76,7 @@ To publish the package with a deploy token: - `<tag>` is the Git tag name of the version you want to publish. To publish a branch, use `branch=<branch>` instead of `tag=<tag>`. -You can view the published package by going to **Packages and registries > Package Registry** and +You can view the published package by going to **Deploy > Package Registry** and selecting the **Composer** tab. ## Publish a Composer package by using CI/CD @@ -99,13 +99,13 @@ You can publish a Composer package to the Package Registry as part of your CI/CD 1. Run the pipeline. -To view the published package, go to **Packages and registries > Package Registry** and select the **Composer** tab. +To view the published package, go to **Deploy > Package Registry** and select the **Composer** tab. ### Use a CI/CD template A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` template: -1. On the left sidebar, select **Project information**. +1. On the left sidebar, select **Project overview**. 1. Above the file list, select **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**. 1. From the **Apply a template** list, select **Composer**. @@ -142,7 +142,7 @@ To install a package: - Connect to the Package Registry for your group: ```shell - composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/ + composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json ``` - Set the required package version: @@ -159,7 +159,7 @@ To install a package: "repositories": { "<group_id>": { "type": "composer", - "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/" + "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }, ... }, @@ -243,7 +243,7 @@ To install a package: { ... "repositories": [ - { "type": "composer", "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/" } + { "type": "composer", "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json" } ], "config": { ... diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index f06a7d83f92..1ebd59d18fa 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -295,7 +295,7 @@ There are two ways to remove a Conan package from the GitLab Package Registry. - From the GitLab user interface: - Go to your project's **Packages and registries > Package Registry**. Remove the + Go to your project's **Deploy > Package Registry**. Remove the package by selecting **Remove repository** (**{remove}**). ## Search for Conan packages in the Package Registry diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md index 31337d19d59..6a7c92fd924 100644 --- a/doc/user/packages/container_registry/authenticate_with_container_registry.md +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -21,7 +21,7 @@ To authenticate with the Container Registry, you can use a: 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`. +- For write (push) access, to be `write_registry` and `read_registry`. To authenticate, run the `docker login` command. For example: diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md index aa86b87660b..4d74e029cdd 100644 --- a/doc/user/packages/container_registry/build_and_push_images.md +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -152,9 +152,12 @@ registry and used by subsequent stages, downloading the container image when nee `latest` and deployed using an application-specific deploy script: ```yaml -image: docker:20.10.16 -services: - - docker:20.10.16-dind +default: + image: docker:20.10.16 + services: + - docker:20.10.16-dind + before_script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY stages: - build @@ -169,9 +172,6 @@ variables: 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: diff --git a/doc/user/packages/container_registry/delete_container_registry_images.md b/doc/user/packages/container_registry/delete_container_registry_images.md index b645dc3a3e6..148fa65d8c7 100644 --- a/doc/user/packages/container_registry/delete_container_registry_images.md +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -45,7 +45,7 @@ To delete container images using the GitLab UI: by selecting the red **{remove}** **Trash** icon next to the tag you want to delete. -1. In the dialog box, select **Remove tag**. +1. On the dialog, select **Remove tag**. ## Use the GitLab API diff --git a/doc/user/packages/container_registry/troubleshoot_container_registry.md b/doc/user/packages/container_registry/troubleshoot_container_registry.md index 729f4919188..34c86a90d49 100644 --- a/doc/user/packages/container_registry/troubleshoot_container_registry.md +++ b/doc/user/packages/container_registry/troubleshoot_container_registry.md @@ -125,5 +125,5 @@ This error happens when your authentication token expires before the image push the Container Registry on self-managed GitLab instances expire every five minutes. On GitLab.com, the token expiration time is set to 15 minutes. -If you are using self-managed GitLab, you can ask an administrator to +If you are using self-managed GitLab, an administrator can [increase the token duration](../../../administration/packages/container_registry.md#increase-token-duration). diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index 2bff6f79a27..21468b9d3bb 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -71,4 +71,4 @@ To remove the Harbor Registry for a project: 1. Clear the **Active** checkbox under **Enable integration**. 1. Select **Save changes**. -The **Packages and registries > Harbor Registry** entry is removed from the sidebar. +The **Operate > Harbor Registry** entry is removed from the sidebar. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index bcc55af65bc..f06db7ef1ac 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -490,7 +490,7 @@ Your changes are automatically saved. ### Request forwarding to Maven Central FLAG: -By default this feature is not available for self-managed. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. +By default this feature is not available for self-managed. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. This feature is not available for SaaS users. When a Maven package is not found in the Package Registry, the request is forwarded diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 91186e6c159..d06b1ababb8 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -26,7 +26,7 @@ Learn how to use the GitLab Package Registry to build your own custom package wo You can view packages for your project or group. 1. Go to the project or group. -1. Go to **Packages and registries > Package Registry**. +1. Go to **Deploy > Package Registry**. You can search, sort, and filter packages on this page. You can share your search results by copying and pasting the URL from your browser. @@ -131,7 +131,7 @@ You can also remove the Package Registry for your project specifically: **Packages** feature. 1. Select **Save changes**. -The **Packages and registries > Package Registry** entry is removed from the sidebar. +The **Deploy > Package Registry** entry is removed from the sidebar. ## Package Registry visibility permissions @@ -161,7 +161,7 @@ Registry disables all Package Registry operations. FLAG: On self-managed GitLab, by default this feature is available. To disable it, -ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `package_registry_access_level`. +an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `package_registry_access_level`. If you want to allow anyone (everyone on the internet) to pull from the Package Registry, no matter what the project visibility is, you can use the additional toggle `Allow anyone to pull from Package Registry` that appears when the project visibility is Private or Internal. 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 020cad5ac14..4882753d6cf 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -29,7 +29,7 @@ You can delete packages by using [the API](../../../api/packages.md#delete-a-pro To delete a package in the UI, from your group or project: -1. Go to **Packages and registries > Package Registry**. +1. Go to **Deploy > Package Registry**. 1. Find the name of the package you want to delete. 1. Select **Delete**. @@ -46,7 +46,7 @@ You can delete packages by using [the API](../../../api/packages.md#delete-a-pac To delete package assets in the UI, from your group or project: -1. Go to **Packages and registries > Package Registry**. +1. Go to **Deploy > Package Registry**. 1. Find the name of the package you want to delete. 1. Select the package to view additional details. 1. Find the name of the assets you would like to delete. diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md index ca174c43565..d2ee5645fc1 100644 --- a/doc/user/packages/package_registry/supported_functionality.md +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -57,12 +57,12 @@ Requests for packages not found in your GitLab project are forwarded to the publ | Package type | Supports request forwarding | |-------------------------------------------------------|-----------------------------| -| [Maven (with `mvn`)](../maven_repository/index.md) | [Yes (disabled by default)](../../admin_area/settings/continuous_integration.md#maven-forwarding) | -| [Maven (with `gradle`)](../maven_repository/index.md) | [Yes (disabled by default)](../../admin_area/settings/continuous_integration.md#maven-forwarding) | -| [Maven (with `sbt`)](../maven_repository/index.md) | [Yes (disabled by default)](../../admin_area/settings/continuous_integration.md#maven-forwarding) | -| [npm](../npm_registry/index.md) | [Yes](../../admin_area/settings/continuous_integration.md#npm-forwarding) | +| [Maven (with `mvn`)](../maven_repository/index.md) | [Yes (disabled by default)](../../../administration/settings/continuous_integration.md#maven-forwarding) | +| [Maven (with `gradle`)](../maven_repository/index.md) | [Yes (disabled by default)](../../../administration/settings/continuous_integration.md#maven-forwarding) | +| [Maven (with `sbt`)](../maven_repository/index.md) | [Yes (disabled by default)](../../../administration/settings/continuous_integration.md#maven-forwarding) | +| [npm](../npm_registry/index.md) | [Yes](../../../administration/settings/continuous_integration.md#npm-forwarding) | | [NuGet](../nuget_repository/index.md) | N | -| [PyPI](../pypi_repository/index.md) | [Yes](../../admin_area/settings/continuous_integration.md#pypi-forwarding) | +| [PyPI](../pypi_repository/index.md) | [Yes](../../../administration/settings/continuous_integration.md#pypi-forwarding) | | [Generic packages](../generic_packages/index.md) | N | | [Terraform](../terraform_module_registry/index.md) | N | | [Composer](../composer_repository/index.md) | N | @@ -86,7 +86,7 @@ To reduce the associated security risks, before deleting a package you can: - Verify the package is not being actively used. - Disable request forwarding: - - Instance administrators can disable forwarding in the [**Continuous Integration** section](../../admin_area/settings/continuous_integration.md#package-registry-configuration) of the Admin Area. + - Instance administrators can disable forwarding in the [**Continuous Integration** section](../../../administration/settings/continuous_integration.md#package-registry-configuration) of the Admin Area. - Group owners can disable forwarding in the **Packages and Registries** section of the group settings. ## Allow or prevent duplicates **(FREE)** diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index d7f33dd9e79..3a3409daa6a 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -19,7 +19,7 @@ projects. To view Terraform modules in your project: 1. Go to the project. -1. On the left sidebar, select **Packages and registries > Terraform modules**. +1. On the left sidebar, select **Operate > Terraform modules**. You can search, sort, and filter modules on this page. @@ -162,7 +162,7 @@ Prerequisites: - You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. -Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: +Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` or `%APPDATA%/terraform.rc` file: ```terraform credentials "gitlab.com" { @@ -186,7 +186,7 @@ Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the To download a Terraform module: -1. On the left sidebar, select **Packages and registries > Terraform modules**. +1. On the left sidebar, select **Operate > Terraform modules**. 1. Select the name of the module you want to download. 1. In the **Activity** section, select the name of the module you want to download. @@ -217,7 +217,7 @@ You can delete modules by using [the packages API](../../../api/packages.md#dele To delete a module in the UI, from your project: -1. On the left sidebar, select **Packages and registries > Terraform modules**. +1. On the left sidebar, select **Operate > Terraform modules**. 1. Find the name of the package you want to delete. 1. Select **Delete**. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 7bff6cf8234..1df244cf0c6 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -35,7 +35,7 @@ of each package management system to publish different package types to the same Let's take a look at how you might create one project to host all of your packages: 1. Create a new project in GitLab. The project doesn't require any code or content. -1. On the left sidebar, select **Project information**, and note the project ID. +1. On the left sidebar, select **Project overview**, and note the project ID. 1. Create an access token for authentication. All package types in the Package Registry can be published by using: - A [personal access token](../../profile/personal_access_tokens.md). diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 0b02de59ab4..cf859174c10 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -58,11 +58,11 @@ The following table lists project permissions available for each role: | Action | Guest | Reporter | Developer | Maintainer | Owner | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|----------| | [Analytics](analytics/index.md):<br>View [issue analytics](analytics/issue_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [value stream analytics](group/value_stream_analytics/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | | [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/proxy-based.md#on-demand-scans) | | | ✓ | ✓ | ✓ | @@ -223,7 +223,7 @@ The following table lists project permissions available for each role: <!-- markdownlint-disable MD029 --> -1. On self-managed GitLab instances, users with the Guest role 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. Users with the Guest role on GitLab.com are only able to perform this action on public projects because internal visibility is not available. +1. On self-managed GitLab instances, users with the Guest role are able to perform this action only on public and internal projects (not on private projects). [External users](../administration/external_users.md) must be given explicit access (at least the **Reporter** role) 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. @@ -401,13 +401,13 @@ The following table lists group permissions available for each role: | View group [Usage Quotas](usage_quotas.md) page | | | | | ✓ (3) | | Manage group runners | | | | | ✓ | | [Migrate groups](group/import/index.md) | | | | | ✓ | -| Manage [subscriptions, and purchase storage and units of compute](../subscriptions/gitlab_com/index.md) | | | | | ✓ | +| Manage [subscriptions, and purchase storage and compute minutes](../subscriptions/gitlab_com/index.md) | | | | | ✓ | <!-- markdownlint-disable MD029 --> 1. Groups can be set to allow either Owners, or Owners and users with the Maintainer role, to [create subgroups](group/subgroups/index.md#create-a-subgroup). 2. Default project creation role can be changed at: - - The [instance level](admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). + - The [instance level](../administration/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). - The [group level](group/index.md#specify-who-can-add-projects-to-a-group). 3. Does not apply to subgroups. 4. Developers can push commits to the default branch of a new project only if the [default branch protection](group/manage.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 0d97c008561..e04c61b2c00 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -13,12 +13,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Snowplow integration introduced in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `product_analytics_snowplow_support`. 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 `product_analytics_dashboards`. +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. On GitLab.com, this feature is not available. This feature is not ready for production use. FLAG: -On self-managed GitLab, by default the Snowplow integration 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 `product_analytics_snowplow_support`. +On self-managed GitLab, by default the Snowplow integration is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_snowplow_support`. On GitLab.com, this feature is not available. This feature is not ready for production use. @@ -66,7 +66,7 @@ flowchart TB > - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. 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 flags](../../administration/feature_flags.md) named `product_analytics_dashboards` and `product_analytics_admin_settings`. +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flags](../../administration/feature_flags.md) named `product_analytics_dashboards` and `product_analytics_admin_settings`. On GitLab.com, this feature is not available. This feature is not ready for production use. @@ -114,7 +114,7 @@ To instrument code to collect data, use one or more of the existing SDKs: > - `product_analytics_internal_preview` replaced with `product_analytics_dashboards` in GitLab 15.11. 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 `product_analytics_dashboards`. +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. On GitLab.com, this feature is not available. This feature is not ready for production use. @@ -125,6 +125,29 @@ The `cube_analytics` data type connects to the Cube instance defined when [produ All filters and queries are sent to the Cube instance and the returned data is processed by the product analytics data source to be rendered by the appropriate visualizations. +### Filling missing data + +- Introduced in GitLab 16.3 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_dashboards`. Disabled by default. + +When [exporting data](#raw-data-export) or [viewing dashboards](../analytics/analytics_dashboards.md#view-project-dashboards), +if there is no data for a given day, the missing data is autofilled with `0`. + +This approach has the following benefits: + +- The visualization's day axis matches the selected date range, removing ambiguity about missing data. +- Data exports have rows for the entire date range, making data analysis easier. + +However, this approach also has the following limitations: + +- The `day` [granularity](https://cube.dev/docs/product/apis-integrations/rest-api/query-format) must be used. + All other granularities are not supported at this time. +- It only fills a date range defined by the [`inDateRange`](https://cube.dev/docs/product/apis-integrations/rest-api/query-format#indaterange) filter. + - The date selector in the UI already uses this filter. +- The filling of data ignores the query-defined limit. If you set a limit of 10 data points over 20 days, it + returns 20 data points, with the missing data filled by `0`. + +[Issue 417231](https://gitlab.com/gitlab-org/gitlab/-/issues/417231) proposes a solution to this limitation. + ## Funnel analysis Use funnel analysis to understand the flow of users through your application, and where @@ -246,3 +269,10 @@ POST /api/v4/projects/PROJECT_ID/product_analytics/request/load?queryType=multi ``` If the request is successful, the returned JSON includes an array of rows of results. + +## Troubleshooting + +### No events are collected + +Check your [instrumentation details](#enable-product-analytics), +and make sure product analytics is enabled and set up correctly. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index c367498f66e..b27658e5e41 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -20,7 +20,7 @@ Deleting a user deletes all projects in that user namespace. > Delay between a user deleting their own account and deletion of the user record introduced in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `delay_delete_own_user`. Enabled by default on GitLab.com. 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 `delay_delete_own_user`. On GitLab.com, this feature is available. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `delay_delete_own_user`. On GitLab.com, this feature is available. As a user, to delete your own account: @@ -30,9 +30,7 @@ As a user, to delete your own account: 1. Select **Delete account**. NOTE: -On GitLab.com, there is a seven day delay between a user deleting their own account and deletion of the user record. During this time, that user is [blocked](../../admin_area/moderate_users.md#block-a-user) and a new account with the same email address or username cannot be created. - -Unblocking the account does not undo the deletion because the account will still be in the deletion queue, and there is no quick method to reverse this process. +On GitLab.com, there is a seven day delay between a user deleting their own account and deletion of the user record. During this time, that user is [blocked](../../../administration/moderate_users.md#block-a-user) and a new account with the same email address or username cannot be created. Unblocking the account does not undo the deletion because the account will still be in the deletion queue, and will be deleted. Accounts with no issues, comments, notes, merge requests, or snippets are deleted immediately. Accounts under paid namespaces are deleted immediately. ## Delete users and user contributions **(FREE SELF)** @@ -71,9 +69,9 @@ When deleting users, you can either: - Personal access tokens. - Snippets. -An alternative to deleting is [blocking a user](../../admin_area/moderate_users.md#block-a-user). +An alternative to deleting is [blocking a user](../../../administration/moderate_users.md#block-a-user). -When a user is deleted from an [abuse report](../../admin_area/review_abuse_reports.md) or spam log, these associated +When a user is deleted from an [abuse report](../../../administration/review_abuse_reports.md) or spam log, these associated records are always removed. The deleting associated records option can be requested in the [API](../../../api/users.md#user-deletion) as well as @@ -91,7 +89,7 @@ ERROR: null value in column "user_id" violates not-null constraint ``` The error can be found in the [PostgreSQL log](../../../administration/logs/index.md#postgresql-logs) and -in the **Retries** section of the [background jobs view](../../admin_area/index.md#background-jobs) in the Admin Area. +in the **Retries** section of the [background jobs view](../../../administration/admin_area.md#background-jobs) in the Admin Area. If the user being deleted used the [iterations](../../group/iterations/index.md) feature, such as adding an issue to an iteration, you must use diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index b856366bb58..33888e4f06e 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -90,7 +90,7 @@ in a safe place. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `forti_authenticator`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to +On self-managed GitLab, by default this feature is not available. To make it available per user, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `forti_authenticator`. On GitLab.com, this feature is not available. @@ -218,7 +218,7 @@ On your GitLab server: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7 [with a flag](../../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to +On self-managed GitLab, by default this feature is not available. To make it available per user, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `forti_token_cloud`. On GitLab.com, this feature is not available. The feature is not ready for production use. @@ -277,13 +277,13 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: > - Optional one-time password authentication for WebAuthn devices [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378844) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `webauthn_without_topt`. [Enabled on GitLab.com and self-managed by default](https://gitlab.com/gitlab-org/gitlab/-/issues/232671). FLAG: -On self-managed GitLab, by default, WebAuthn devices are available. To disable the feature, ask an administrator to +On self-managed GitLab, by default, WebAuthn devices are available. To disable the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature. On GitLab.com, WebAuthn devices are available. FLAG: -On self-managed GitLab, by default, optional one-time password authentication for WebAuthn devices is not available. To enable the feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `webauthn_without_totp`. +On self-managed GitLab, by default, optional one-time password authentication for WebAuthn devices is not available. To enable the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `webauthn_without_totp`. On GitLab.com, this feature is available. WebAuthn is [supported by](https://caniuse.com/#search=webauthn) the following: @@ -465,7 +465,7 @@ a GitLab global administrator disable 2FA for your account: ## Information for GitLab administrators **(FREE SELF)** -- Take care that 2FA keeps working after [restoring a GitLab backup](../../../raketasks/backup_restore.md). +- Take care that 2FA keeps working after [restoring a GitLab backup](../../../administration/backup_restore/index.md). - To ensure 2FA authorizes correctly with a time-based one-time password (TOTP) server, synchronize your GitLab server's time using a service like NTP. Otherwise, authorization can always fail because of time differences. - The GitLab WebAuthn implementation does _not_ work when the GitLab instance is accessed from multiple hostnames @@ -501,7 +501,7 @@ This error occurs in the following scenarios: - You do not have 2FA enabled but an administrator has enabled the [enforce 2FA for all users](../../../security/two_factor_authentication.md#enforce-2fa-for-all-users) setting. - You do not have 2FA enabled, but an administrator has disabled the - [password authentication enabled for Git over HTTP(S)](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled) + [password authentication enabled for Git over HTTP(S)](../../../administration/settings/sign_in_restrictions.md#password-authentication-enabled) setting. Instead you can authenticate: diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md index 4e3248ceb10..a90144beb1b 100644 --- a/doc/user/profile/achievements.md +++ b/doc/user/profile/achievements.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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 `achievements`. +an administrator can [enable the feature flag](../../administration/feature_flags.md) named `achievements`. The feature is not ready for production use. Achievements are a way to reward users for their activity on GitLab. @@ -109,6 +109,23 @@ mutation achievementsCreate($file: Upload!) { } ``` +To supply the avatar file, call the mutation using `curl`: + +```shell +curl "https://gitlab.com/api/graphql" \ + -H "Authorization: Bearer <your-pat-token>" \ + -H "Content-Type: multipart/form-data" \ + -F operations='{ "query": "mutation ($file: Upload!) { achievementsCreate(input: { namespaceId: \"gid://gitlab/Namespace/<namespace-id>\", name: \"<name>\", description: \"<description>\", avatar: $file }) { achievement { id name description avatarUrl } } }", "variables": { "file": null } }' \ + -F map='{ "0": ["variables.file"] }' \ + -F 0='@/path/to/your/file.jpg' +``` + +When successful, the response returns the achievement ID: + +```shell +{"data":{"achievementsCreate":{"achievement":{"id":"gid://gitlab/Achievements::Achievement/1","name":"<name>","description":"<description>","avatarUrl":"https://gitlab.com/uploads/-/system/achievements/achievement/avatar/1/file.jpg"}}}} +``` + ## Update an achievement You can change the name, description, and avatar of an achievement at any time. diff --git a/doc/user/profile/comment_templates.md b/doc/user/profile/comment_templates.md index 4157fc852b7..a9db2d268fe 100644 --- a/doc/user/profile/comment_templates.md +++ b/doc/user/profile/comment_templates.md @@ -12,7 +12,7 @@ type: howto > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119468) in GitLab 16.0. 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 `saved_replies`. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `saved_replies`. On GitLab.com, this feature is available. With comment templates, create and reuse text for any text area in: diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index 7adf653606e..e7f7211aeae 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -101,6 +101,6 @@ To reset your feed token: 1. On the left sidebar, select **Access Tokens**. 1. Scroll down. In the **Feed token** section, select the **reset this token** link. -1. On the confirmation box, select **OK**. +1. On the confirmation dialog, select **OK**. A new token is generated. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 958acaa61a9..32ea9dd2c23 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -39,7 +39,7 @@ Prerequisites: - Have a project that hosts [GitLab Pages](../project/pages/index.md). For more information, see [changing your username in the GitLab Team Handbook](https://about.gitlab.com/handbook/tools-and-tips/#change-your-username-at-gitlabcom). - Your username must be between 2 and 255 characters in length, and must not: - - Contain special characters or emojis. + - Contain special characters or emoji. - End with `.<reserved file extension>`, for example `jon.png`. However, `jonpng` is valid. To change your username: @@ -90,7 +90,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), +If the [public level is restricted](../../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels), user profiles are only visible to authenticated users. ## Add details to your profile with a README @@ -104,7 +104,7 @@ the README file with information, it's included on your profile page. To create a new project and add its README to your profile: -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, enter the name for your new project. @@ -250,7 +250,7 @@ Your primary email is used by default. To change your commit email: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Commit email** dropdown list, select an email address. 1. Select **Update profile settings**. @@ -261,7 +261,7 @@ Your primary email is the default email address for your login, commit email, an To change your primary email: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Email** field, enter your new email address. 1. Select **Update profile settings**. @@ -271,7 +271,7 @@ To change your primary email: You can select one of your [configured email addresses](#add-emails-to-your-user-profile) to be displayed on your public profile: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. In the **Public email** field, select one of the available email addresses. 1. Select **Update profile settings**. @@ -354,7 +354,7 @@ By default, you are signed out of GitLab after seven days (10080 minutes) of ina window, whichever comes first. GitLab administrators can -[change this default](../admin_area/settings/account_and_limit_settings.md#customize-the-default-session-duration). +[change this default](../../administration/settings/account_and_limit_settings.md#customize-the-default-session-duration). ### Stay signed in indefinitely @@ -365,7 +365,7 @@ To remain signed in indefinitely, select the **Remember me** checkbox on the Git You remain signed in because, although the server sets a session time of one week, your browser stores a secure token that enables automatic reauthentication. -GitLab administrators can [turn off the **Remember me** setting](../admin_area/settings/account_and_limit_settings.md#session-duration) for environments +GitLab administrators can [turn off the **Remember me** setting](../../administration/settings/account_and_limit_settings.md#session-duration) for environments that require sessions to expire periodically for security or compliance purposes. ### Cookies used for sign-in diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index cc0b67eed52..f378b0ae301 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -14,7 +14,7 @@ Stay informed about what's happening in GitLab with email notifications. You can receive updates about activity in issues, merge requests, epics, and designs. For the tool that GitLab administrators can use to send messages to users, read -[Email from GitLab](../admin_area/email_from_gitlab.md). +[Email from GitLab](../../administration/email_from_gitlab.md). ## Who receives notifications @@ -46,7 +46,7 @@ anyone else. To edit your notification settings: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Edit the desired global, group, or project notification settings. @@ -99,7 +99,7 @@ You can select a notification level and email address for each group. To select a notification level for a group, use either of these methods: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Groups** section. @@ -118,7 +118,7 @@ Or: You can select an email address to receive notifications for each group you belong to. You can use group notifications, for example, if you work freelance, and want to keep email about clients' projects separate. -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Groups** section. @@ -130,7 +130,7 @@ To help you stay up to date, you can select a notification level for each projec To select a notification level for a project, use either of these methods: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Projects** section. @@ -152,7 +152,7 @@ These emails are enabled by default. To opt out: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Clear the **Receive product marketing emails** checkbox. @@ -290,7 +290,7 @@ To always receive notifications on your own issues, merge requests, and so on, t NOTE: This feature is enabled by default for self-managed instances. Administrators may disable this feature -through the [Sign-in restrictions](../admin_area/settings/sign_in_restrictions.md#email-notification-for-unknown-sign-ins) section of the UI. +through the [Sign-in restrictions](../../administration/settings/sign_in_restrictions.md#email-notification-for-unknown-sign-ins) section of the UI. The feature is always enabled on GitLab.com. When a user successfully signs in from a previously unknown IP address or device, @@ -335,7 +335,7 @@ The participants are: If you no longer wish to receive any email notifications: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Clear the **Receive product marketing emails** checkbox. @@ -345,7 +345,7 @@ If you no longer wish to receive any email notifications: **Disabled**. On self-managed installations, even after doing this, your instance administrator -[can still email you](../admin_area/email_from_gitlab.md). +[can still email you](../../administration/email_from_gitlab.md). To unsubscribe, select the unsubscribe link in one of these emails. ## Email headers you can use to filter email diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index bda92ce8388..a8231460045 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -48,7 +48,7 @@ Use impersonation tokens to automate authentication as a specific user. You can create as many personal access tokens as you like. -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. Enter a name and expiry date for the token. @@ -79,17 +79,15 @@ for guidance on managing personal access tokens (for example, setting a short ex At any time, you can revoke a personal access token. -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, select **Revoke**. ## View the last time a token was used -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/414945) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `update_personal_access_token_usage_information_every_10_minutes`. 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 `update_personal_access_token_usage_information_every_10_minutes`. On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33162) in GitLab 13.2. Token usage information is updated every 24 hours. +> - The frequency of token usage information updates [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/410168) in GitLab 16.1 from 24 hours to 10 minutes. Token usage information is updated every 10 minutes. GitLab considers a token used when the token is used to: @@ -98,7 +96,7 @@ Token usage information is updated every 10 minutes. GitLab considers a token us To view the last time a token was used: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, view the **Last Used** date. @@ -119,7 +117,8 @@ 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.) | +| `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.) | +| `create_runner` | Grants permission to create runners. | WARNING: If you enabled [external authorization](../admin_area/settings/external_authorization.md), personal access tokens cannot access container or package registries. If you use personal access tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use personal access tokens with container or package registries. @@ -131,7 +130,8 @@ Personal access tokens expire on the date you define, at midnight UTC. - GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that expire in the next seven days. The owners of these tokens are notified by email. - GitLab runs a check at 02:00 AM UTC every day to identify personal access tokens that expire on the current date. The owners of these tokens are notified by email. - In GitLab Ultimate, administrators can - [limit the lifetime of access tokens](../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens). + [limit the allowable lifetime of access tokens](../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens). If not set, the maximum allowable lifetime of a personal access token is 365 days. +- In GitLab Free and Premium, the maximum allowable lifetime of a personal access token is 365 days. ## Create a personal access token programmatically **(FREE SELF)** @@ -157,11 +157,11 @@ To create a personal access token programmatically: The token must be 20 characters long. The scopes must be valid and are visible [in the source code](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/auth.rb). - For example, to create a token that belongs to a user with username `automation-bot`: + For example, to create a token that belongs to a user with username `automation-bot` and expires in a year: ```ruby user = User.find_by_username('automation-bot') - token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token') + token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now) token.set_token('token-string-here123') token.save! ``` @@ -170,7 +170,7 @@ This code can be shortened into a single-line shell command by using the [Rails runner](../../administration/operations/rails_console.md#using-the-rails-runner): ```shell -sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token'); token.set_token('token-string-here123'); token.save!" +sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now); token.set_token('token-string-here123'); token.save!" ``` ## Revoke a personal access token programmatically **(FREE SELF)** diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index bcfe323a5fe..17dea99e5ef 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -12,14 +12,13 @@ of GitLab to their liking. To navigate to your profile's preferences: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. ## Navigation theme The GitLab navigation theme setting allows you to personalize your GitLab experience. -You can choose from several color themes that add unique colors to the top navigation -and left side navigation. +You can choose from several color themes that add unique colors to the left sidebar. Using individual color themes might help you differentiate between your different GitLab instances. @@ -158,7 +157,7 @@ You can choose one of the following options as the first day of the week: - Sunday - Monday -If you select **System Default**, the [instance default](../admin_area/settings/index.md#default-first-day-of-the-week) setting is used. +If you select **System Default**, the [instance default](../../administration/settings/index.md#default-first-day-of-the-week) setting is used. ## Time preferences diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md index 50624a43893..c57a81c00bf 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -67,7 +67,7 @@ By default GitLab enforces the following password requirements: Self-managed installations can configure the following additional password requirements: - [Password minimum and maximum length limits](../../security/password_length_limits.md). -- [Password complexity requirements](../admin_area/settings/sign_up_restrictions.md#password-complexity-requirements). +- [Password complexity requirements](../../administration/settings/sign_up_restrictions.md#password-complexity-requirements). ## Block weak passwords diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 8ea762777ac..c4ef6a647db 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -121,7 +121,7 @@ or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md To use your [deploy board](../../user/project/deploy_boards.md): -1. Go to **Deployments > Environments** for your project. +1. Go to **Operate > Environments** for your project. 1. Set the new weight with the dropdown list on the right side. 1. Confirm your selection. @@ -134,7 +134,7 @@ Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql mutation { environmentsCanaryIngressUpdate(input:{ id: "gid://gitlab/Environment/29", # Your Environment ID. You can get the ID from the URL of the environment page. - weight: 45 # The new traffic weight. e.g. If you set `45`, 45% of traffic goes to a canary deployment and 55% of traffic goes to a stable deployment. + weight: 45 # The new traffic weight. for example, If you set `45`, 45% of traffic goes to a canary deployment and 55% of traffic goes to a stable deployment. }) { errors } diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 87554e786ab..9a30cbe94e2 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -54,7 +54,7 @@ To create new a EKS cluster for your project, group, or instance, through cluster certificates: 1. Go to your: - - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. + - Project's **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - **Main menu > Admin > Kubernetes**, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. @@ -213,7 +213,7 @@ Otherwise, the deployed app isn't externally available outside of the cluster. GitLab creates a new pipeline, which begins to build, test, and deploy the app. After the pipeline has finished, your app runs in EKS, and is available -to users. Select **CI/CD > Environments**. +to users. Select **Operate > Environments**.  diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index bb85662d442..aaaa72d282e 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -66,7 +66,7 @@ to grant access. To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. + 1. Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. 1. **Main menu > Admin > Kubernetes** page, for an instance-level cluster. 1. On the **Kubernetes clusters** page, select the **Connect with a certificate** option from the **Actions** dropdown list. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index c6561fffa0b..09dbd70d1bb 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -60,7 +60,7 @@ To create new Kubernetes clusters to your project, group, or instance, through cluster certificates: 1. Navigate to your: - - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level + - Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index bba05f1e724..470daf499be 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -17,7 +17,7 @@ To create and manage a new cluster use [Infrastructure as Code](../../infrastruc When you successfully connect an existing cluster using cluster certificates, the cluster connection to GitLab becomes enabled. To disable it: 1. Go to your: - - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. + - Project's **{cloud-gear}** **Operate > Kubernetes clusters** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select the name of the cluster you want to disable. diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index b321646d8d8..537b38dd547 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -17,7 +17,7 @@ To connect your cluster to GitLab, use the [GitLab agent](../../../user/clusters To manage applications, use the [Cluster Project Management Template](../../../user/clusters/management_project_template.md). 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 `certificate_based_clusters`. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `certificate_based_clusters`. You can choose to allow GitLab to manage your cluster for you. If your cluster is managed by GitLab, resources for your projects are automatically created. See @@ -45,7 +45,7 @@ your cluster. This can cause deployment jobs to fail. To clear the cache: -1. Navigate to your project's **Infrastructure > Kubernetes clusters** page, and select your cluster. +1. Navigate to your project's **Operate > Kubernetes clusters** page, and select your cluster. 1. Expand the **Advanced settings** section. 1. Select **Clear cluster cache**. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 09a443614d0..8f64fe7dd7d 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -24,7 +24,7 @@ This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/e to add this functionality to the [agent](../index.md). 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 `certificate_based_clusters`. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `certificate_based_clusters`. GitLab deploy boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -127,7 +127,7 @@ To display the deploy boards for a specific [environment](../../ci/environments/  Once all of the above are set up and the pipeline has run at least once, -navigate to the environments page under **Deployments > Environments**. +go to the environments page under **Operate > Environments**. Deploy boards are visible by default. You can explicitly select the triangle next to their respective environment name to hide them. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 5bd19fec0ba..4e380d485a8 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -40,7 +40,6 @@ A deploy key is given a permission level when it is created: You can change a deploy key's permission level after creating it. Changing a project deploy key's permissions only applies for the current project. -Although a deploy key is a secret that isn't associated with a specific user, GitLab authorizes the creator of the deploy key if the Git-command triggers additional processes. For example: - When a deploy key is used to push a commit to a [protected branch](../protected_branches.md), @@ -58,6 +57,9 @@ For human interactions, use credentials tied to users such as Personal Access To To help detect a potential secret leak, you can use the [Audit Event](../../../administration/audit_event_streaming/examples.md#example-payloads-for-ssh-events-with-deploy-key) feature. +WARNING: +Deploy keys work even if the user who created them is removed from the group or project. + ## View deploy keys To view the deploy keys available to a project: @@ -128,6 +130,20 @@ To grant a public deploy key access to a project: 1. In the key's row, select **Edit** (**{pencil}**). 1. Select the **Grant write permissions to this key** checkbox. +### Edit project access permissions of a deploy key + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To edit the project access permissions of a deploy key: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Repository**. +1. Expand **Deploy keys**. +1. In the key's row, select **Edit** (**{pencil}**). +1. Select or clear the **Grant write permissions to this key** checkbox. + ## Revoke project access of a deploy key To revoke a deploy key's access to a project, you can disable it. Any service that relies on @@ -159,8 +175,10 @@ What happens to the deploy key when it is disabled depends on the following: There are a few scenarios where a deploy key fails to push to a [protected branch](../protected_branches.md). -- The owner associated to a deploy key does not have access to the protected branch. - The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. +- The owner associated to a deploy key has [project membership permissions](../../../user/permissions.md#project-members-permissions) lower than required to **View project code**. +- The deploy key does not have [read-write permissions for the project](#edit-project-access-permissions-of-a-deploy-key). +- The deploy key has been [revoked](#revoke-project-access-of-a-deploy-key). - **No one** is selected in [the **Allowed to push and merge** section](../protected_branches.md#add-protection-to-existing-branches) of the protected branch. All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 11e538964a2..3fb338a75ec 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -16,7 +16,7 @@ You might want to use these templates: - For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. - For every issue or merge request for a specific project, so the layout is consistent. -- For a [Service Desk email template](service_desk.md#use-a-custom-template-for-service-desk-issues). +- For a [Service Desk email template](service_desk.md#use-a-custom-template-for-service-desk-tickets). For description templates to work, they must be: diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 71b4bff41d1..4c77323778c 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -147,7 +147,7 @@ permissions to the project: git lfs unlock --id=123 --force ``` -You can normally push files to GitLab whether they're locked or unlocked. +You can push files to GitLab whether they're locked or unlocked. NOTE: Although multi-branch file locks can be created and managed through the Git LFS @@ -209,11 +209,13 @@ To lock a file: 1. Open the file or directory in GitLab. 1. In the upper-right corner, above the file, select **Lock**. -1. On the confirmation dialog box, select **OK**. +1. On the confirmation dialog, select **OK**. If you do not have permission to lock the file, the button is not enabled. -To view the user who locked the file (if it was not you), hover over the button. +To view the user who locked a directory (if it was not you), hover over the button. Reinstatement of +similar functionality for locked files is discussed in +[issue 376222](https://gitlab.com/gitlab-org/gitlab/-/issues/376222). ### View and remove existing locks diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index dc17a3646a8..b957ff93a4c 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -36,7 +36,7 @@ When importing: - [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. -- [Bitbucket Cloud import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your +- [Bitbucket Cloud import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. @@ -70,7 +70,7 @@ For user contributions to be mapped, each user must complete the following befor > Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. 1. Sign in to GitLab. -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **Bitbucket Cloud**. 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index fce9ca7d147..6226e4c1296 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -31,7 +31,7 @@ You can import Bitbucket repositories to GitLab. > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. -- [Bitbucket Server import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Bitbucket Server import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Server import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. @@ -41,7 +41,7 @@ You can import Bitbucket repositories to GitLab. To import your Bitbucket repositories: 1. Sign in to GitLab. -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **Bitbucket Server**. 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. @@ -93,7 +93,7 @@ repository imports under the namespace of the user who started the import proces FLAG: On self-managed GitLab and GitLab.com, by default this feature is not available. To make it -available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) +available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. This feature is not ready for production use. With this feature enabled, the importer tries to find a user in the GitLab user database with the diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 30c4249e0d6..18758ba99e6 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -19,7 +19,7 @@ users. > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. -- [FogBugz import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [FogBugz import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The FogBugz import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. @@ -29,7 +29,7 @@ users. To import your project from FogBugz: 1. Sign in to GitLab. -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. Select **FogBugz**. 1. Enter your FogBugz URL, email address, and password. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 62cda62c2fe..22c89084c56 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -32,7 +32,7 @@ on the issue about the original Gitea author. > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. - Gitea version 1.0.0 or later. -- [Gitea import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Gitea import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Gitea import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 509029a3099..afc36f309be 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -35,7 +35,7 @@ When importing projects: - The organization the repository belongs to must not impose restrictions of a [third-party application access policy](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) on the GitLab instance you import to. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of the import process, see [Migrating from GitHub to GitLab](https://youtu.be/VYOXuOg9tQI). +For an overview of the import process, see [How to migrate from GitHub to GitLab including Actions](https://www.youtube.com/watch?v=0Id5oMl1Kqs). ## Prerequisites @@ -43,7 +43,7 @@ For an overview of the import process, see [Migrating from GitHub to GitLab](htt To import projects from GitHub: -- [GitHub import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [GitHub import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The GitHub import source is enabled by default on GitLab.com. - You must have at least the Maintainer role on the destination group to import to. @@ -68,7 +68,7 @@ If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable the [GitHub integration](../../../integration/github.md). - GitHub must be enabled as an import source in the - [Admin Area](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources). + [Admin Area](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources). - For GitLab 15.10 and earlier, you must add `github.com` and `api.github.com` entries in the [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains). @@ -78,7 +78,7 @@ If you are importing from GitHub.com to a self-managed GitLab instance: - You don't need to enable the [GitHub integration](../../../integration/github.md). - GitHub must be enabled as an import source in the - [Admin Area](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources). + [Admin Area](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources). ## Import your GitHub repository into GitLab @@ -96,9 +96,11 @@ NOTE: If you are using a self-managed GitLab instance or if you are importing from GitHub Enterprise, this process requires that you have configured [GitHub integration](../../../integration/github.md). -1. From the top navigation bar, select **+** and select **New project**. -1. Select the **Import project** tab and then select **GitHub**. -1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Import project** and then **GitHub**. +1. Now you can either: + - Add a personal access token and select **Authenticate**. + - If GitHub is [configured](../../../integration/github.md) for the instance, select **Authorize with GitHub**. 1. Select **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. 1. Continue on to [selecting which repositories to import](#select-which-repositories-to-import). diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 9fdb8eed5aa..6f9c64b73cb 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -92,7 +92,7 @@ over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve an ## Migrate between two self-managed GitLab instances To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, -you should [back up](../../../raketasks/backup_restore.md) +you should [back up](../../../administration/backup_restore/index.md) the existing instance and restore it on the new instance. For example, you could use this method to migrate a self-managed instance from an old server to a new server. The backups produced don't depend on the operating system running GitLab. You can therefore use @@ -114,7 +114,7 @@ You can view all project imports created by you. This list includes the followin To view project import history: 1. Sign in to GitLab. -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Import project**. 1. In the upper-right corner, select **History**. 1. If there are any errors for a particular import, you can see them by selecting **Details**. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 7b3550d2dc9..980c051eac7 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -19,7 +19,7 @@ repositories like the Android Open Source Project (AOSP). > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. -- [Manifest import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Manifest import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Manifest import source is enabled by default on GitLab.com. - GitLab must use PostgreSQL for its database, because [subgroups](../../group/subgroups/index.md) are needed for the manifest import diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 230113581f8..c3c516042f7 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -12,7 +12,7 @@ You can import your existing repositories by providing the Git URL. > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. -- [Repository by URL import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) +- [Repository by URL import source](../../../administration/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your GitLab administrator to enable it. The Repository by URL import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 67b96efe9a4..b7bdf47ae49 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -12,7 +12,7 @@ You can create a project in many ways in GitLab. To create a blank project: -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. @@ -41,7 +41,7 @@ Anyone can [contribute a built-in template](../../development/project_templates. To create a project from a built-in template: -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. From the list of templates: @@ -68,10 +68,10 @@ For this reason, the creation date of imported objects can be older than the cre Custom project templates are available at: -- The [instance-level](../../user/admin_area/custom_project_templates.md) +- The [instance-level](../../administration/custom_project_templates.md) - The [group-level](../../user/group/custom_project_templates.md) -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Instance** or **Group** tab. 1. From the list of templates: @@ -96,7 +96,7 @@ HIPAA Audit Protocol published by the U.S Department of Health and Human Service To create a project from the HIPAA Audit Protocol template: -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. Locate the **HIPAA Audit Protocol** template: diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 5ca6fcebdd6..533824dd58a 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -28,6 +28,13 @@ To view project insights: 1. Select **Analyze > Insights**. 1. To view a report, select the **Select report** dropdown list. +### Access Insights reports with deep links + +You can direct users to a specific report in Insights by using the deep-linked URL. + +To create a deep link, append the report key to the end of the Insights report URL. +For example, a GitLab report with the key `bugsCharts` has the deep link URL `https://gitlab.com/gitlab-org/gitlab/insights/#/bugsCharts`. + ## Configure project insights Prerequisites: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 8790c7213e5..bfa8a905699 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -4,95 +4,110 @@ group: Import and Integrate 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 for Slack app **(FREE SAAS)** +# GitLab for Slack app **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for self-managed instances in GitLab 16.2. NOTE: -This feature is only configurable on GitLab.com. -For self-managed GitLab instances, use -[Slack slash commands](slack_slash_commands.md) and [Slack notifications](slack.md) instead. -For more information about our plans to make this feature configurable for all GitLab installations, -see [epic 1211](https://gitlab.com/groups/gitlab-org/-/epics/1211). +This page contains information about configuring the GitLab for Slack app on GitLab.com. For administrator documentation, see [GitLab for Slack app administration](../../admin_area/settings/slack_app.md). + +The GitLab for Slack app is a native Slack app that provides [slash commands](#slash-commands) and [notifications](#slack-notifications) +in your Slack workspace. GitLab links your Slack user with your GitLab user so that any command +you run in Slack is run by your linked GitLab user. + +## Install the GitLab for Slack app -Slack provides a native application that you can enable with your project's -integrations on GitLab.com. +Prerequisites: -## Installation +- You must have the [appropriate permissions to add apps to your Slack workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). +- On self-managed GitLab, an administrator must [enable the integration](../../admin_area/settings/slack_app.md). In GitLab 15.0 and later, the GitLab for Slack app uses [granular permissions](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). Although functionality has not changed, you should [reinstall the app](#update-the-gitlab-for-slack-app). -### Through the Slack App Directory +### From project integration settings -To enable the GitLab for Slack app for your workspace, -install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) -from the [Slack App Directory](https://slack.com/apps). +To install the GitLab for Slack app from project integration settings: -On the [GitLab for Slack app landing page](https://gitlab.com/-/profile/slack/edit), -you can select a GitLab project to link with your Slack workspace. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **GitLab for Slack app**. +1. Select **Install GitLab for Slack app**. +1. On the Slack confirmation page, select **Allow**. -### Through GitLab project settings +To update the app in your Slack workspace to the latest version, +you can also select **Reinstall GitLab for Slack app**. -Alternatively, you can configure the GitLab for Slack app with your project's -integration settings. +### From the Slack App Directory **(FREE SAAS)** -You must have the appropriate permissions for your Slack -workspace to be able to install a new application. See -[Add apps to your Slack workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). +On GitLab.com, you can also install the GitLab for Slack app from the +[Slack App Directory](https://slack-platform.slack.com/apps/A676ADMV5-gitlab). -To enable the GitLab integration for your Slack workspace: +To install the GitLab for Slack app from the Slack App Directory: -1. Go to your project's **Settings > Integration > GitLab for Slack app** (only - visible on GitLab.com). -1. Select **Install GitLab for Slack app**. -1. Select **Allow** on Slack's confirmation screen. +1. Go to the [GitLab for Slack page](https://gitlab.com/-/profile/slack/edit). +1. Select a GitLab project to link with your Slack workspace. -To update the app in your Slack workspace to the latest version, -you can also select **Reinstall GitLab for Slack app**. +## Update the GitLab for Slack app + +When GitLab releases new features for the GitLab for Slack app, you might have to manually update your app to use the new features. + +To update your GitLab for Slack app: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for + which the GitLab for Slack app is configured. +1. Select **Settings > Integrations**. +1. Select **GitLab for Slack app**. +1. Select **Reinstall GitLab for Slack app**. + +The GitLab for Slack app is updated for all projects that use the integration. + +Alternatively, you can [configure the integration](https://about.gitlab.com/solutions/slack/) again. ## Slash commands -After installing the GitLab for Slack app, everyone in your Slack workspace can use slash commands. +You can use slash commands to run common GitLab operations. Replace `<project>` with a project full path. + +**For the GitLab for Slack app**: + +- You must authorize your Slack user on GitLab.com when you run your first slash command. +- You can [create a shorter project alias](#create-a-project-alias-for-slash-commands) for slash commands. + +**For [Slack slash commands](slack_slash_commands.md) on self-managed GitLab, [Mattermost slash commands](mattermost_slash_commands.md), and [ChatOps](../../../ci/chatops/index.md)**, replace `/gitlab` with the slash command trigger name configured for your integration. -Replace `<project>` with the project full path, or create a shorter [project alias](#create-a-project-alias-for-slash-commands) for the slash commands. +The following slash commands are available: -| Command | Effect | -| ------- | ------ | +| Command | Description | +| ------- | ----------- | | `/gitlab help` | Shows all available slash commands. | -| `/gitlab <project> issue new <title> <shift+return> <description>` | Creates a new issue with the title `<title>` and description `<description>`. | +| `/gitlab <project> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Creates a new issue with the title `<title>` and description `<description>`. | | `/gitlab <project> issue show <id>` | Shows the issue with the ID `<id>`. | | `/gitlab <project> issue close <id>` | Closes the issue with the ID `<id>`. | -| `/gitlab <project> issue search <query>` | Shows up to 5 issues matching `<query>`. | +| `/gitlab <project> issue search <query>` | Shows up to five issues matching `<query>`. | | `/gitlab <project> issue move <id> to <project>` | Moves the issue with the ID `<id>` to `<project>`. | -| `/gitlab <project> issue comment <id> <shift+return> <comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | +| `/gitlab <project> issue comment <id>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | | `/gitlab <project> deploy <from> to <to>` | [Deploys](#the-deploy-slash-command) from the `<from>` environment to the `<to>` environment. | | `/gitlab <project> run <job name> <arguments>` | Executes the [ChatOps](../../../ci/chatops/index.md) job `<job name>` on the default branch. | -| `/gitlab incident declare` | **Beta** Opens modal to [create a new incident](../../../operations/incident_management/slack.md). | +| `/gitlab incident declare` | Opens a dialog to [create a new incident from Slack](../../../operations/incident_management/slack.md) (Beta). | -### The deploy slash command +### The `deploy` slash command -To deploy to an environment, GitLab tries to find a deployment -manual action in the pipeline. +To deploy to an environment, GitLab tries to find a deployment manual action in the pipeline. -If there's only one action for a given environment, it is triggered. -If more than one action is defined, GitLab finds an action -name that matches the environment name to deploy to. +If only one action is defined for a given environment, it is triggered. +If more than one action is defined, GitLab tries to find an action name +that matches the environment name to deploy to. The command returns an error if no matching action is found. -### User authorization - -When you perform your first slash command, you must -authorize your Slack user on GitLab.com. - ### Create a project alias for slash commands -By default, slash commands expect a project full path. To use a shorter alias -instead: +By default, slash commands expect a project full path. To create a shorter project alias in the GitLab for Slack app: -1. Go to your project's home page. -1. Go to **Settings > Integrations** (only visible on GitLab.com). -1. On the **Integrations** page, select **GitLab for Slack app**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **GitLab for Slack app**. 1. The current **Project Alias**, if any, is displayed. To edit this value, select **Edit**. 1. Enter your desired alias, and select **Save changes**. @@ -101,19 +116,19 @@ instead: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381012) in GitLab 15.9. -With Slack notifications, GitLab can send messages to Slack workspace channels for certain GitLab [events](#events-for-slack-notifications) (for example, when an issue is created). +With Slack notifications, GitLab can send messages to Slack workspace channels for certain GitLab [events](#notification-events). ### Configure notifications To configure Slack notifications: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for - which the GitLab for Slack app has been [installed](#installation). + which the GitLab for Slack app is [installed](#install-the-gitlab-for-slack-app). 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. In the **Trigger** section, select the checkbox for each GitLab event you want to receive a notification for in Slack. For a full list, see - [Events for Slack notifications](#events-for-slack-notifications). + [Notification events](#notification-events). 1. For each checkbox you select, enter the name of the channel that receives the notifications (for example, `#my-channel`). - To send notifications to multiple Slack channels, enter up to 10 channel names separated by commas (for example, `#channel-one, #channel-two`). @@ -136,7 +151,7 @@ To receive notifications to a private Slack channel, you must add the GitLab for 1. Mention the app in the channel by typing `@GitLab` and pressing <kbd>Enter</kbd>. 1. Select **Add to Channel**. -### Events for Slack notifications +### Notification events The following events are available for Slack notifications: @@ -153,25 +168,17 @@ The following events are available for Slack notifications: | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | +| **Group mention in public** | A group is mentioned in a public context. | +| **Group mention in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting -### Update the GitLab for Slack app - -New releases of the app might require permissions to be authorized before some features work in your Slack workspace. You should ensure the app is up to date in your Slack workspace to enjoy all the latest features. +### GitLab for Slack app does not appear in the list of integrations -To update your GitLab for Slack app: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for - which the GitLab for Slack app has been configured. -1. Select **Settings > Integrations**. -1. Select **GitLab for Slack app**. -1. Select **Reinstall GitLab for Slack app**. - -The GitLab for Slack app is updated for all projects that use the integration. +The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../admin_area/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. -Alternatively, you can [configure a new Slack integration](https://about.gitlab.com/solutions/slack/). +The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). ### Project or alias not found @@ -186,7 +193,11 @@ As a workaround, ensure: - The project full path is correct. - If using a [project alias](#create-a-project-alias-for-slash-commands), the alias is correct. -- The GitLab for Slack app integration is [enabled for the project](#through-gitlab-project-settings). +- The GitLab for Slack app is [enabled for the project](#from-project-integration-settings). + +### Slash commands return `/gitlab failed with the error "dispatch_failed"` in Slack + +Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../admin_area/settings/slack_app.md) on your self-managed instance. ### Notifications are not received to a channel diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index c70a58a24d2..fd59f54a066 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -72,7 +72,6 @@ You can configure the following integrations. | Packagist | Keep your PHP dependencies updated on Packagist. | **{check-circle}** Yes | | [Pipelines emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | | [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | -| [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | | [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index a8d8323a651..6a09a1cfbcd 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -6,12 +6,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Mattermost slash commands **(FREE)** -You can use slash commands to run common GitLab operations, like creating an issue, -from a [Mattermost](https://mattermost.com/) chat environment. +You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations, +like creating an issue, from a [Mattermost](https://mattermost.com/) chat environment. GitLab can also send events (such as `issue created`) to Mattermost as part of the separately configured [Mattermost notifications](mattermost.md). +For a list of available slash commands, see [Slash commands](gitlab_slack_application.md#slash-commands). + ## Configuration options GitLab provides different ways to configure Mattermost slash commands. For any of these options, @@ -109,7 +111,7 @@ Your slash command can now communicate with your GitLab project. Prerequisite: -- To run [slash commands](#available-slash-commands), you must have +- To run [slash commands](gitlab_slack_application.md#slash-commands), you must have [permission](../../permissions.md#project-members-permissions) to perform the action in the GitLab project. @@ -120,21 +122,10 @@ To interact with GitLab using Mattermost slash commands: You can see all authorized chat accounts in your Mattermost profile page under **Chat**. -## Available slash commands - -The available slash commands for Mattermost are: - -| Command | Description | Example | -| ------- | ----------- | ------- | -| `/<trigger> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | -| `/<trigger> issue show <issue-number>` | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | -| `/<trigger> deploy <environment> to <environment>` | Start the CI/CD job that deploys from one environment to another (for example, `staging` to `production`). CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | -| `/<trigger> help` | View a list of available slash commands. | `/gitlab help` | - ## Related topics -- [Mattermost slash commands](https://developers.mattermost.com/integrate/slash-commands/) -- [Linux package Mattermost](../../../integration/mattermost/index.md) +- [Mattermost Linux package](../../../integration/mattermost/index.md) +- [Slash commands at Mattermost](https://developers.mattermost.com/integrate/slash-commands/) ## Troubleshooting diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md index cffa2649cc8..ce092d10d20 100644 --- a/doc/user/project/integrations/mlflow_client.md +++ b/doc/user/project/integrations/mlflow_client.md @@ -1,104 +1,11 @@ --- -stage: Create -group: Incubation -info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. +redirect_to: '../ml/experiment_tracking/mlflow_client.md' +remove_date: '2023-10-12' --- -# MLflow client integration **(FREE)** +This document was moved to [another location](../ml/experiment_tracking/mlflow_client.md). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. - -NOTE: -Model experiment tracking is an [experimental feature](../../../policy/experiment-beta-support.md). -Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. - -[MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning Experiment Tracking. -GitLab works as a backend to the MLflow Client, [logging experiments](../ml/experiment_tracking/index.md). -Setting up your integrations requires minimal changes to existing code. - -GitLab plays the role of a MLflow server. Running `mlflow server` is not necessary. - -## Enable MLflow client integration - -Prerequisites: - -- A [personal access token](../../../user/profile/personal_access_tokens.md) for the project, with minimum access level of `api`. -- The project ID. To find the project ID: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Settings > General**. - -To enable MLflow client integration: - -1. Set the tracking URI and token environment variables on the host that runs the code. - This can be your local environment, CI pipeline, or remote host. For example: - - ```shell - export MLFLOW_TRACKING_URI="http://<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow" - export MLFLOW_TRACKING_TOKEN="<your_access_token>" - ``` - -1. If your training code contains the call to `mlflow.set_tracking_uri()`, remove it. - -When running the training code, MLflow creates experiments, runs, log parameters, metrics, metadata -and artifacts on GitLab. - -After experiments are logged, they are listed under `/<your project>/-/ml/experiments`. -Runs are registered as: - -- Model Candidates, which can be explored by selecting an experiment. -- Tags, which are registered as metadata. - -## Associating a candidate to a CI/CD job - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119454) in GitLab 16.1. - -If your training code is being run from a CI/CD job, GitLab can use that information to enhance -candidate metadata. To do so, add the following snippet to your training code within the run -execution context: - -```python -with mlflow.start_run(run_name=f"Candidate {index}"): - # Your training code - - # Start of snippet to be included - if os.getenv('GITLAB_CI'): - mlflow.set_tag('gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID')) - # End of snippet to be included -``` - -## Supported MLflow client methods and caveats - -GitLab supports these methods from the MLflow client. Other methods might be supported but were not -tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). - -| Method | Supported | Version Added | Comments | -|--------------------------|------------------|----------------|----------| -| `get_experiment` | Yes | 15.11 | | -| `get_experiment_by_name` | Yes | 15.11 | | -| `set_experiment` | Yes | 15.11 | | -| `get_run` | Yes | 15.11 | | -| `start_run` | Yes | 15.11 | | -| `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. -| `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. -| `log_batch` | Yes | 15.11 | | -| `log_metric` | Yes | 15.11 | | -| `log_metrics` | Yes | 15.11 | | -| `log_param` | Yes | 15.11 | | -| `log_params` | Yes | 15.11 | | -| `log_figure` | Yes | 15.11 | | -| `log_image` | Yes | 15.11 | | -| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. -| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. -| `set_tag` | Yes | 15.11 | | -| `set_tags` | Yes | 15.11 | | -| `set_terminated` | Yes | 15.11 | | -| `end_run` | Yes | 15.11 | | -| `update_run` | Yes | 15.11 | | -| `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. - -## Limitations - -- The API GitLab supports is the one defined at MLflow version 1.28.0. -- API endpoints not listed above are not supported. -- During creation of experiments and runs, ExperimentTags are stored, even though they are not displayed. -- MLflow Model Registry is not supported. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- 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/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 14183a47625..55000a0a992 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -79,6 +79,8 @@ The following triggers are available for Slack notifications: | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | +| **Group mention in public** | A group is mentioned in a public context. | +| **Group mention in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 74bd12561fb..c1e04f2aa63 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -10,16 +10,18 @@ NOTE: This feature is only configurable on self-managed GitLab instances. For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. -If you want to control and view GitLab content while you're -working in Slack, you can use Slack slash commands. -To use Slack slash commands, you must configure both Slack and GitLab. +You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations, +like creating an issue, from a [Slack](https://slack.com/) chat environment. +To use slash commands in Slack, you must configure both Slack and GitLab. -GitLab can also send events (for example, `issue created`) to Slack as notifications. -The [Slack notifications integration](slack.md) is configured separately. +GitLab can also send events (such as `issue created`) to Slack as part of the +separately configured [Slack notifications](slack.md). -## Configure GitLab and Slack +For a list of available slash commands, see [Slash commands](gitlab_slack_application.md#slash-commands). -Slack slash command integrations are scoped to a project. +## Configure the integration + +Slack slash commands are scoped to a project. To configure Slack slash commands: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. @@ -35,7 +37,3 @@ Slack slash command integrations are scoped to a project. 1. On the Slack configuration page, select **Save Integration** and copy the **Token**. 1. Go back to the GitLab configuration page and paste in the **Token**. 1. Ensure the **Active** checkbox is selected and select **Save changes**. - -## Slash commands - -You can now use the available [Slack slash commands](../../../integration/slash_commands.md). diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index dfff537e4a1..8d66f3e48dd 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -24,6 +24,7 @@ Event type | Trigger [Subgroup event](#subgroup-events) | A subgroup is created or removed from a group. [Feature flag event](#feature-flag-events) | A feature flag is turned on or off. [Release event](#release-events) | A release is created or updated. +[Emoji event](#emoji-events) | An emoji is awarded or revoked. NOTE: If an author has no public email listed in their @@ -61,6 +62,7 @@ Payload example: "before": "95790bf891e76fee5e1747ab589903a6a1f80f22", "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "ref": "refs/heads/master", + "ref_protected": true, "checkout_sha": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "user_id": 4, "user_name": "John Smith", @@ -151,6 +153,7 @@ Payload example: "before": "0000000000000000000000000000000000000000", "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", "ref": "refs/tags/v1.0.0", + "ref_protected": true, "checkout_sha": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", "user_id": 1, "user_name": "John Smith", @@ -1468,13 +1471,8 @@ 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` [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. +> - `retries_count` [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 16.2. `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. @@ -1850,3 +1848,149 @@ Payload example: } } ``` + +## Emoji events + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123952) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `emoji_webhooks`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `emoji_webhooks`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +NOTE: +To have the `emoji_webhooks` flag enabled on GitLab.com, see [issue 417288](https://gitlab.com/gitlab-org/gitlab/-/issues/417288). + +An emoji event is triggered when an emoji is awarded or revoked on: + +- Issues +- Merge requests +- Project snippets +- Comments on: + - Issues + - Merge requests + - Project snippets + - Commits + +The available values for `object_attributes.action` in the payload are: + +- `award` +- `revoke` + +Request header: + +```plaintext +X-Gitlab-Event: Emoji Hook +``` + +Payload example: + +```json +{ + "object_kind": "emoji", + "event_type": "award", + "user": { + "id": 1, + "name": "Blake Bergstrom", + "username": "root", + "avatar_url": "http://example.com/uploads/-/system/user/avatar/1/avatar.png", + "email": "[REDACTED]" + }, + "project_id": 6, + "project": { + "id": 6, + "name": "Flight", + "description": "Velit fugit aperiam illum deleniti odio sequi.", + "web_url": "http://example.com/flightjs/Flight", + "avatar_url": null, + "git_ssh_url": "ssh://git@example.com/flightjs/Flight.git", + "git_http_url": "http://example.com/flightjs/Flight.git", + "namespace": "Flightjs", + "visibility_level": 20, + "path_with_namespace": "flightjs/Flight", + "default_branch": "master", + "ci_config_path": null, + "homepage": "http://example.com/flightjs/Flight", + "url": "ssh://git@example.com/flightjs/Flight.git", + "ssh_url": "ssh://git@example.com/flightjs/Flight.git", + "http_url": "http://example.com/flightjs/Flight.git" + }, + "object_attributes": { + "user_id": 1, + "created_at": "2023-07-04 20:44:11 UTC", + "id": 1, + "name": "thumbsup", + "awardable_type": "Note", + "awardable_id": 363, + "updated_at": "2023-07-04 20:44:11 UTC", + "action": "award", + "awarded_on_url": "http://example.com/flightjs/Flight/-/issues/42#note_363" + }, + "note": { + "attachment": null, + "author_id": 1, + "change_position": null, + "commit_id": null, + "created_at": "2023-07-04 15:09:55 UTC", + "discussion_id": "c3d97fd471f210a5dc8b97a409e3bea95ee06c14", + "id": 363, + "line_code": null, + "note": "Testing 123", + "noteable_id": 635, + "noteable_type": "Issue", + "original_position": null, + "position": null, + "project_id": 6, + "resolved_at": null, + "resolved_by_id": null, + "resolved_by_push": null, + "st_diff": null, + "system": false, + "type": null, + "updated_at": "2023-07-04 19:58:46 UTC", + "updated_by_id": null, + "description": "Testing 123", + "url": "http://example.com/flightjs/Flight/-/issues/42#note_363" + }, + "issue": { + "author_id": 1, + "closed_at": null, + "confidential": false, + "created_at": "2023-07-04 14:59:43 UTC", + "description": "Issue description!", + "discussion_locked": null, + "due_date": null, + "id": 635, + "iid": 42, + "last_edited_at": null, + "last_edited_by_id": null, + "milestone_id": null, + "moved_to_id": null, + "duplicated_to_id": null, + "project_id": 6, + "relative_position": 18981, + "state_id": 1, + "time_estimate": 0, + "title": "New issue!", + "updated_at": "2023-07-04 15:09:55 UTC", + "updated_by_id": null, + "weight": null, + "health_status": null, + "url": "http://example.com/flightjs/Flight/-/issues/42", + "total_time_spent": 0, + "time_change": 0, + "human_total_time_spent": null, + "human_time_change": null, + "human_time_estimate": null, + "assignee_ids": [ + 1 + ], + "assignee_id": 1, + "labels": [ + + ], + "state": "opened", + "severity": "unknown" + } +} +``` diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 5c8fc5703dd..9f24f3b49ff 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -126,7 +126,7 @@ Endpoints should follow these best practices: > - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/390157) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`. 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 `auto_disabling_web_hooks`. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`. On GitLab.com, this feature is available. Project or group webhooks that fail four consecutive times are automatically disabled. @@ -279,6 +279,7 @@ For more information about supported events for webhooks, see [webhook events](w > - `X-Gitlab-Event-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8. > - `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5. +> - `X-Gitlab-Webhook-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230830) in GitLab 16.2. Webhook requests to your endpoint include the following headers: @@ -286,6 +287,7 @@ Webhook requests to your endpoint include the following headers: | ------ | ------ | ------ | | `User-Agent` | In the format `"Gitlab/<VERSION>"`. | `"GitLab/15.5.0-pre"` | | `X-Gitlab-Instance` | Hostname of the GitLab instance that sent the webhook. | `"https://gitlab.com"` | +| `X-Gitlab-Webhook-UUID` | Unique ID per webhook. If a webhook request fails and retries, the second request has a new ID. | `"02affd2d-2cba-4033-917d-ec22d5dc4b38"` | | `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | | `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index f5d0382ccd8..bca1ee5245c 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -422,7 +422,7 @@ Prerequisites: To set a WIP limit for a list, in an issue board: -1. On the top of the list you want to edit, select **List actions** (**{ellipsis_v}**) **> Edit list settings**. +1. On the top of the list you want to edit, select **Edit list settings** (**{settings}**). The list settings sidebar opens on the right. 1. Next to **Work in progress limit**, select **Edit**. 1. Enter the maximum number of issues. @@ -499,10 +499,10 @@ Prerequisites: To remove a list from an issue board: -1. On the top of the list you want to remove, select **List actions** (**{ellipsis_v}**). +1. On the top of the list you want to remove, select **Edit list settings** (**{settings}**). The list settings sidebar opens on the right. -1. Select **Remove list**. A confirmation dialog appears. -1. Select **Remove list** again. +1. Select **Remove list**. +1. On the confirmation dialog, select **Remove list** again. ### Add issues to a list diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 7e5f26d3526..6c2e6cb2132 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -26,7 +26,7 @@ When you create a confidential issue in a project, the project becomes listed in To create a confidential issue: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. On the left sidebar, at the top, select **Create new...** (**{plus}**). +1. On the left sidebar, at the top, select **Create new** (**{plus}**). 1. From the dropdown list, select **New issue**. 1. Complete the [fields](create_issues.md#fields-in-the-new-issue-form). - Select the **This issue is confidential...** checkbox. diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 3e7cfc12da7..8cc9ab71ca7 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -99,16 +99,16 @@ Prerequisites: To create an issue from a project issue board: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Issues > Boards**. -1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. +1. Select **Plan > Issue boards**. +1. At the top of a board list, select **Create new issue** (**{plus-square}**). 1. Enter the issue's title. 1. Select **Create issue**. To create an issue from a group issue board: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. -1. Select **Issues > Boards**. -1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. +1. Select **Plan > Issue boards**. +1. At the top of a board list, select **Create new issue** (**{plus-square}**). 1. Enter the issue's title. 1. Under **Projects**, select the project in the group that the issue should belong to. 1. Select **Create issue**. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 9c04a40cb32..6013abc4892 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -202,12 +202,12 @@ Archived designs are not permanently lost. You can browse ## Markdown and rich text editors for descriptions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375172) in GitLab 16.2. 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 `content_editor_on_issues`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +On self-managed GitLab, by default the rich text editor is available. To hide it, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `content_editor_on_issues`. +On GitLab.com, this feature is available. When this feature is enabled, you can use the Markdown and rich text editor in design descriptions. It's the same editor you use for comments across GitLab. @@ -251,7 +251,7 @@ Prerequisites: To delete a comment from a design: 1. On the comment you want to delete, select **More actions** **{ellipsis_v}** **> Delete comment**. -1. On the confirmation dialog box, select **Delete comment**. +1. On the confirmation dialog, select **Delete comment**. ## Resolve a discussion thread on a design diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index a43dd65ed74..b2cc555d3b7 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -16,7 +16,7 @@ You can use issues for many purposes, customized to your needs and workflow. - Accept feature proposals, questions, support requests, or bug reports. - Elaborate on code implementations. -For more information about using issues, see the GitLab blog post: +For more information about issues, see the GitLab blog post: [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). Issues are always associated with a specific project. If you have multiple diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 6f1c14b2b80..6bf8e2eeb97 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -155,7 +155,7 @@ Prerequisites: To do it: -1. Optional (but recommended). [Create a backup](../../../raketasks/backup_restore.md) before +1. Optional (but recommended). [Create a backup](../../../administration/backup_restore/index.md) before attempting any changes in the console. 1. Open the [Rails console](../../../administration/operations/rails_console.md). 1. Run the following script. Make sure to change `project`, `admin_user`, and `target_project` to @@ -215,9 +215,8 @@ To close an issue, you can either: 1. Select **Plan > Issues**, then select your issue to view it. 1. At the top of the issue, select **Close issue**. -<!-- Delete when the `moved_mr_sidebar` feature flag is removed --> If you don't see this action at the top of an issue, your project or instance might have -enabled a feature flag for [moved actions](../merge_requests/index.md#move-sidebar-actions). +enabled a feature flag to [moved it in the actions menu](#move-the-close-button-into-the-actions-menu). ### Reopen a closed issue @@ -228,6 +227,9 @@ Prerequisites: To reopen a closed issue, at the top of the issue, select **Reopen issue**. A reopened issue is no different from any other open issue. +If you don't see this action at the top of an issue, your project or instance might have +enabled a feature flag to [moved it in the actions menu](#move-the-close-button-into-the-actions-menu). + ### Closing issues automatically You can close issues automatically by using certain words, called a _closing pattern_, @@ -328,6 +330,24 @@ Prerequisites: Learn how to change the default [issue closing pattern](../../../administration/issue_closing_pattern.md). of your installation. +<!-- Delete when the `move_close_into_dropdown` feature flag is removed +and update steps for closing and reopening issues, incidents, and epics --> +### Move the close button into the actions menu + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125173) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `move_close_into_dropdown`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `move_close_into_dropdown`. +On GitLab.com, this feature is not available. + +When this feature flag is enabled, in the upper-right corner, +**Issue actions** (**{ellipsis_v}**) contains the **Close issue** and **Reopen issue** actions. + +In GitLab 16.2 and later, similar action menus are also available on incidents and epics. + +When this feature flag is disabled, **Close issue** and **Reopen issue** are +on the top bar, outside of the actions menu. + ## Change the issue type Prerequisites: @@ -445,9 +465,6 @@ To filter the list of issues: 1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical `AND`. -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 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. @@ -456,7 +473,7 @@ GitLab displays the results on-screen, but you can also 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 `or_issuable_queries`. +To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `or_issuable_queries`. On GitLab.com, this feature is available. When this feature is enabled, you can use the OR operator (**is one of: `||`**) diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 829e44eae9a..4c0566c2386 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -76,6 +76,10 @@ When you sort by **Popularity**, the issue order changes to sort descending by t number of upvotes ([emoji reactions](../../award_emojis.md) with the "thumbs up") on each issue. You can use this to identify issues that are in high demand. +The total number of votes is not summed up. An issue with 18 upvotes and 5 +downvotes is considered more popular than an issue with 17 upvotes and no +downvotes. + ## Sorting by priority When you sort by **Priority**, the issue order changes to sort in this order: diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 7a1d9d6e6e3..37b24cda5aa 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -69,7 +69,7 @@ If a user is: ### Membership and visibility rights -Depending on their membership type, members of groups or projects are granted different visibility levels +Depending on their membership type, members of groups or projects are granted different [visibility levels](../../../user/public_access.md) and rights into the group or project. | Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member | @@ -80,7 +80,7 @@ and rights into the group or project. | View milestones of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | | Be shared into other groups | ✓ | | | | | Be shared into other projects | ✓ | ✓ | | | -| Share the group with other members | ✓ | | | | +| Share the group with other members | ✓ | ✓ | ✓ | ✓ | In the following example, `User` is a: @@ -235,7 +235,7 @@ To remove a member from a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Manage > Members**. 1. Next to the project member you want to remove, select **Remove member**. -1. Optional. In the confirmation box, select the +1. Optional. On the confirmation dialog, select the **Also unassign this user from related issues and merge requests** checkbox. 1. To prevent leaks of sensitive information from private projects, verify the member has not forked the private repository or created webhooks. Existing forks continue to receive diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index aadc27fb2d3..15c5935648f 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -76,6 +76,7 @@ In addition: - On the group's page, the project is listed on the **Shared projects** tab. - On the project's **Members** page, the group is listed on the **Groups** tab. - Each user is assigned a maximum role. +- Members who have the **Project Invite** badge next to their profile on the usage quota page count towards the billable members of the shared project's top-level group. ## Maximum role diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index d5851050fd4..4cc8f50dd70 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -109,5 +109,5 @@ To see the pipeline status from the merge request page of a forked project going back to the original project: 1. Create a group containing all the upstream members. -1. Go to the **Project information > Members** page in the forked project and invite the newly-created +1. Go to the **Manage > Members** page in the forked project and invite the newly-created group to the forked project. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 68d5665139a..0dcf5f37d65 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -109,23 +109,22 @@ Without the approvals, the work cannot merge. Required approvals enable multiple > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/389905) in GitLab 15.11 [with a flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. Disabled by default. -> - [Enabled by default on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/405023) in GitLab 16.1. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/405023) in GitLab 16.2. Feature flag `invalid_scan_result_policy_prevents_merge` removed. 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 `invalid_scan_result_policy_prevents_merge`. +an administrator can [disable the feature flag](../../../../administration/feature_flags.md) named `invalid_scan_result_policy_prevents_merge`. -Whenever an approval rule cannot be satisfied, the rule is displayed as **(!) Auto approved**. This applies to the following conditions: +Whenever an approval rule cannot be satisfied, the rule is displayed as **Auto approved**. This applies to the following conditions: - The only eligible approver is the author of the merge request. - No eligible approvers (either groups or users) have been assigned to the approval rule. - The number of required approvals is more than the number of eligible approvers. -These rules are automatically approved to unblock their respective merge requests, -unless they were created through a security policy. - -Invalid approval rules created through a security policy are presented with **(!) Action Required** -and are not automatically approved, blocking their respective merge requests. +These rules are automatically approved to unblock their respective merge requests, unless they were +created through a [scan result policy](../../../application_security/policies/scan-result-policies.md). +Invalid approval rules created through a scan result policy are presented with +**Action required** and are not automatically approved, blocking their respective merge requests. ## Related topics diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index bc5d4353ffc..169c7a09875 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -42,7 +42,7 @@ To add a merge request approval rule: - 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. + creates a required rule. Maximum number of required approvals is `100`. 1. To add users or groups as approvers, search for users or groups that are [eligible to approve](#eligible-approvers), and select **Add**. GitLab suggests approvers based on previous authors of the files changed by the merge request. @@ -261,7 +261,12 @@ For more information, see [Coverage check approval rule](../../../../ci/testing/ ## Security Approvals **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. +> - Bot comment for approvals [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/411656) in GitLab 16.2 [with a flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. Enabled by default. + +FLAG: +On self-managed GitLab, by default the bot comment for approvals is available. To hide the feature, an administrator can [disable the feature flag](../../../../administration/feature_flags.md) named `security_policy_approval_notification`. +On GitLab.com, the bot comment for approvals is available. You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. @@ -269,6 +274,8 @@ Details for each security policy is shown in the Security Approvals section of y The security approval rules are applied to all merge requests until the pipeline is complete. The application of the security approval rules prevents users from merging in code before the security scans run. After the pipeline is complete, the security approval rules are checked to determine if the security approvals are still required. +In case the scanners in the pipeline identify an issue and security approvals are required, a bot comment is generated +on the merge request to indicate which steps are needed to proceed.  diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 6c079dc9319..eed8cbcd94d 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -112,7 +112,7 @@ permission enables an electronic signature for approvals, such as the one define [Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)): 1. Enable password authentication for the web interface, as described in the - [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). + [sign-in restrictions documentation](../../../../administration/settings/sign_in_restrictions.md#password-authentication-enabled). 1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval settings** and select **Require user password to approve**. diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 94f506ba556..79599580f3e 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -51,7 +51,7 @@ clear your browser's cookies or change this behavior again. To view one file at a time for all of your merge requests: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. Scroll to the **Behavior** section and select the **Show one file at a time on merge request's Changes tab** checkbox. 1. Select **Save changes**. @@ -146,11 +146,8 @@ per conflicted file on the merge request diff: ## Add a comment to a merge request file -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121429) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `comment_on_files`. 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 `comment_on_files`. -On GitLab.com, this feature is not available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123515) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `comment_on_files`. Enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125130) in GitLab 16.2. You can add comments to a merge request diff file. These comments persist across rebases and file changes. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 6f309d2db24..ff5421d5785 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -59,7 +59,7 @@ when you mark a merge request as ready, notifications are triggered to When viewing or searching in your project's merge requests list, you can include or exclude draft merge requests: -1. Go to your project and select **Merge requests**. +1. Go to your project and select **Code > Merge requests**. 1. In the navigation bar, select **Open**, **Merged**, **Closed**, or **All** to filter by merge request status. 1. Select the search box to display a list of filters and select **Draft**, or diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 38125f623eb..dfa62628e46 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -77,7 +77,7 @@ or: or: -1. On the left sidebar, at the top, select **Merge requests** (**{merge-request}**). +1. On the left sidebar, select **Code > Merge requests** (**{merge-request}**). 1. From the dropdown list, select **Assigned**. ## Filter the list of merge requests @@ -111,9 +111,6 @@ To filter the list of merge requests: 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). - ### By environment or deployment date > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. @@ -263,13 +260,9 @@ after merging does not retarget open merge requests. This improvement is <!-- When the `moved_mr_sidebar` feature flag is removed, delete this topic and update the steps for these actions like in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87727/diffs?diff_id=522279685#5d9afba799c4af9920dab533571d7abb8b9e9163 --> -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85584) in GitLab 14.10 [with a flag](../../../administration/feature_flags.md) named `moved_mr_sidebar`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85584) in GitLab 14.10 [with a flag](../../../administration/feature_flags.md) named `moved_mr_sidebar`. Enabled by default. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/373757) to also move actions on issues, incidents, and epics in GitLab 16.0. -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 `moved_mr_sidebar`. -On GitLab.com, this feature is enabled in the following projects: `gitlab-org/gitlab`, `gitlab-com/www-gitlab-com`, and `gitlab-org/customers-gitlab-com`. - When this feature flag is enabled, in the upper-right corner, **Merge request actions** (**{ellipsis_v}**) contains the following actions: @@ -317,7 +310,7 @@ For a web developer writing a webpage for your company's website: FLAG: On self-managed GitLab, by default this feature is not available. -To make it available per user, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `mr_activity_filters` for individual or groups of users. +To make it available per user, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `mr_activity_filters` for individual or groups of users. On GitLab.com, this feature is enabled for GitLab team members only. To understand the history of a merge request, filter its activity feed to show you diff --git a/doc/user/project/merge_requests/reviews/img/suggest_changes_v16_2.png b/doc/user/project/merge_requests/reviews/img/suggest_changes_v16_2.png Binary files differnew file mode 100644 index 00000000000..3465085c311 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggest_changes_v16_2.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 86468af06a2..54ebfd9eecb 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -218,7 +218,7 @@ When bulk-editing merge requests in a project, you can edit the following attrib To update multiple project merge requests at the same time: -1. In a project, go to **Merge requests**. +1. In a project, go to **Code > Merge requests**. 1. Select **Bulk edit**. A sidebar on the right-hand side of your screen appears with editable fields. 1. Select the checkboxes next to each merge request you want to edit. @@ -236,7 +236,7 @@ When bulk editing merge requests in a group, you can edit the following attribut To update multiple group merge requests at the same time: -1. In a group, go to **Merge requests**. +1. In a group, go to **Code > Merge requests**. 1. Select **Bulk edit**. A sidebar on the right-hand side of your screen appears with editable fields. 1. Select the checkboxes next to each merge request you want to edit. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 24197c5c313..f949dba85dd 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -7,9 +7,6 @@ type: index, reference # Suggest changes **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. Feature flag `suggestions_custom_commit` removed. - Reviewers can suggest code changes with a Markdown syntax in merge request diff threads. The merge request author (or other users with the appropriate role) can apply any or all of the suggestions from the GitLab UI. Applying suggestions adds a commit to the @@ -43,8 +40,6 @@ merge request, authored by the user who suggested the changes. ### Multi-line suggestions -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/232339) in GitLab 13.11: suggestions in multi-line comments also become multi-line. - When you review a merge request diff, you can propose changes to multiple lines (up to 200) in a single suggestion, by either: @@ -72,6 +67,23 @@ Suggestions for multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line. This allows for up to 200 changed lines per suggestion. +#### Using the rich text editor + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388449) in GitLab 16.1 [with a flag](../../../../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375172) in GitLab 16.2. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../../administration/feature_flags.md) named `content_editor_on_issues`. +On GitLab.com, this feature is available. + +When you insert suggestions, you can use the WYSIWYG +[rich text editor](https://about.gitlab.com/direction/plan/knowledge/content_editor/) to move +up and down the source file's line numbers in the UI. + +To add or subtract changed lines, next to **From line**, select **+** or **-**. + + + ## Apply suggestions Prerequisites: @@ -155,10 +167,7 @@ For example, to customize the commit message to output ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) with a flag named `batch_suggestions`, disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. To reduce the number of commits added to your branch, you can apply multiple suggestions in a single commit. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index c7ed6069cb6..59b11e78622 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -32,12 +32,14 @@ For an overview, check the video demonstration on [Mapping work versus time with To view a project's burndown chart: -1. In a project, navigate to **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Milestones**. 1. Select a milestone from the list. To view a group's burndown chart: -1. In a group, navigate to **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Milestones**. 1. Select a milestone from the list. ### Use cases for burndown charts @@ -110,12 +112,14 @@ Burnup charts show the assigned and completed work for a milestone. To view a project's burnup chart: -1. In a project, navigate to **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Plan > Milestones**. 1. Select a milestone from the list. To view a group's burnup chart: -1. In a group, navigate to **Issues > Milestones**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Plan > Milestones**. 1. Select a milestone from the list. ### How burnup charts work diff --git a/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png b/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png Binary files differnew file mode 100644 index 00000000000..fb4f8d5dc66 --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/candidate_detail_ci_v16_12.png diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index 81c4bc20301..4e9e736f067 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -6,14 +6,18 @@ info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering pr # Machine learning model experiments **(FREE)** -FLAG: -On self-managed GitLab, model experiment tracking is disabled by default. -To enable the feature, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. -On GitLab.com, this feature is in private testing only. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9341) in GitLab 15.11 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. To enable the feature, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 16.2. NOTE: Model experiment tracking is an [experimental feature](../../../../policy/experiment-beta-support.md). Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. +ACCESS LEVEL: +Model experiments [visibility level](../../../public_access.md) can be set to public, private or disabled. This options can +be configured under `Settings > General > Visibility, project features, permissions > Model experiments`. Users must have +at least [Reporter role](../../../permissions.md#roles) to modify or delete experiments +and candidate data. + When creating machine learning models, data scientists often experiment with different parameters, configurations, and feature engineering to improve the performance of the model. Keeping track of all this metadata and the associated artifacts so that the data scientist can later replicate the experiment is not trivial. Machine learning experiment @@ -58,16 +62,12 @@ Some example parameters: ## Track new experiments and candidates Experiment and trials can only be tracked through the -[MLflow](https://www.mlflow.org/docs/latest/tracking.html) client integration. -See [MLflow client integration](../../integrations/mlflow_client.md) for more information +[MLflow](https://www.mlflow.org/docs/latest/tracking.html) client compatibility. +See [MLflow client compatibility](mlflow_client.md) for more information on how to use GitLab as a backend for the MLflow Client. ## Explore model candidates -Prerequisites: - -- You must have at least the Developer role to view experiment data. - To list the current active experiments, either go to `https/-/ml/experiments` or: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. @@ -82,6 +82,14 @@ limitations. After an artifact is logged for a candidate, all artifacts logged f package registry. The package name for a candidate is `ml_experiment_<experiment_id>`, where the version is the candidate IID. The link to the artifacts can also be accessed from the **Experiment Candidates** list or **Candidate detail**. +## View CI information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119788) in 16.1 + +Candidates can be associated to the CI job that created them, allowing quick links to the merge request, pipeline, and user that triggered the pipeline: + + + ## Related topics - Development details in [epic 8560](https://gitlab.com/groups/gitlab-org/-/epics/8560). diff --git a/doc/user/project/ml/experiment_tracking/mlflow_client.md b/doc/user/project/ml/experiment_tracking/mlflow_client.md new file mode 100644 index 00000000000..7fd5c7cca92 --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md @@ -0,0 +1,109 @@ +--- +stage: Create +group: Incubation +info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. +--- + +# MLflow client compatibility **(FREE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. + +NOTE: +Model experiment tracking is an [experimental feature](../../../../policy/experiment-beta-support.md). +Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. + +[MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning Experiment Tracking. +GitLab [Model experiment tracking](index.md) is compatible with MLflow Client, +[logging experiments](index.md). The setup requires minimal changes to existing code. + +GitLab plays the role of a MLflow server. Running `mlflow server` is not necessary. + +## Enable MLflow client integration + +Prerequisites: + +- A [personal](../../../../user/profile/personal_access_tokens.md), [project](../../../../user/project/settings/project_access_tokens.md), or [group](../../../../user/group/settings/group_access_tokens.md) access token with at least the Developer role and the `api` permission. +- The project ID. To find the project ID: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Settings > General**. + +To use MLflow client compatibility from a local environment: + +1. Set the tracking URI and token environment variables on the host that runs the code. + This can be your local environment, CI pipeline, or remote host. For example: + + ```shell + export MLFLOW_TRACKING_URI="<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow" + export MLFLOW_TRACKING_TOKEN="<your_access_token>" + ``` + +1. If your training code contains the call to `mlflow.set_tracking_uri()`, remove it. + +When running the training code, MLflow creates experiments, runs, log parameters, metrics, metadata +and artifacts on GitLab. + +After experiments are logged, they are listed under `/<your project>/-/ml/experiments`. +Runs are registered as: + +- Model Candidates, which can be explored by selecting an experiment. +- Tags, which are registered as metadata. + +## Associating a candidate to a CI/CD job + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119454) in GitLab 16.1. + +If your training code is being run from a CI/CD job, GitLab can use that information to enhance +candidate metadata. To associate a candidate to a CI/CD job: + +1. In the [Project CI variables](../../../../ci/variables/index.md), include the following variables: + - `MLFLOW_TRACKING_URI`: `"<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow"` + - `MLFLOW_TRACKING_TOKEN`: `<your_access_token>` + +1. In your training code within the run execution context, add the following code snippet: + + ```python + with mlflow.start_run(run_name=f"Candidate {index}"): + # Your training code + + # Start of snippet to be included + if os.getenv('GITLAB_CI'): + mlflow.set_tag('gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID')) + # End of snippet to be included + ``` + +## Supported MLflow client methods and caveats + +GitLab supports these methods from the MLflow client. Other methods might be supported but were not +tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). + +| Method | Supported | Version Added | Comments | +|--------------------------|------------------|----------------|----------| +| `get_experiment` | Yes | 15.11 | | +| `get_experiment_by_name` | Yes | 15.11 | | +| `set_experiment` | Yes | 15.11 | | +| `get_run` | Yes | 15.11 | | +| `start_run` | Yes | 15.11 | | +| `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. +| `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. +| `log_batch` | Yes | 15.11 | | +| `log_metric` | Yes | 15.11 | | +| `log_metrics` | Yes | 15.11 | | +| `log_param` | Yes | 15.11 | | +| `log_params` | Yes | 15.11 | | +| `log_figure` | Yes | 15.11 | | +| `log_image` | Yes | 15.11 | | +| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. +| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. +| `set_tag` | Yes | 15.11 | | +| `set_tags` | Yes | 15.11 | | +| `set_terminated` | Yes | 15.11 | | +| `end_run` | Yes | 15.11 | | +| `update_run` | Yes | 15.11 | | +| `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. + +## Limitations + +- The API GitLab supports is the one defined at MLflow version 1.28.0. +- API endpoints not listed above are not supported. +- During creation of experiments and runs, ExperimentTags are stored, even though they are not displayed. +- MLflow Model Registry is not supported. 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 606f0474cb1..0601e236a08 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 @@ -54,10 +54,7 @@ this document for an [overview on DNS records](dns_concepts.md). To add your custom domain to GitLab Pages: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../index.md#menu-position-test). +1. On the left sidebar, select **Deploy > Pages**. 1. In the upper-right corner, select **New Domain**. 1. In **Domain**, enter the domain name. 1. Optional. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). You can also add the certificate and key later. @@ -168,10 +165,7 @@ If you're using Cloudflare, check After you have added all the DNS records: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../index.md#menu-position-test). +1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). @@ -263,10 +257,7 @@ meet these requirements. - To add the certificate at the time you add a new domain: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../index.md#menu-position-test). + 1. On the left sidebar, select **Deploy > Pages**. 1. In the upper-right corner, select **New Domain**. 1. In **Domain**, enter the domain name. 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). @@ -275,17 +266,11 @@ meet these requirements. - To add the certificate to a domain previously added: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../index.md#menu-position-test). + 1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). 1. Select **Save changes**. -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) @@ -309,10 +294,7 @@ domain (as long as you've set a valid certificate for it). To enable this setting: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../index.md#menu-position-test). +1. On the left sidebar, select **Deploy > Pages**. 1. Select the **Force HTTPS (requires valid certificates)** checkbox. 1. Select **Save changes**. 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 15152efb80c..878613c3b9c 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 @@ -43,10 +43,7 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../index.md#menu-position-test). +1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. Turn on the **Automatic certificate management using Let's Encrypt** toggle. @@ -73,10 +70,7 @@ 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. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../index.md#menu-position-test). +1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). 1. If you're still getting the same error: @@ -91,10 +85,7 @@ 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. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../index.md#menu-position-test). +1. On the left sidebar, select **Deploy > Pages**. 1. Next to the domain name, select **Remove**. 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 167c72fdc89..02e662d15b3 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 @@ -25,12 +25,10 @@ these steps, you may have to do additional configuration for the Pages site to g If everything is configured correctly, the site can take approximately 30 minutes to deploy. -To view the pipeline, go to **CI/CD > Pipelines**. +To view the pipeline, go to **Build > Pipelines**. -When the pipeline is finished, go to **Settings > Pages** to find the link to +When the pipeline is finished, go to **Deploy > Pages** to find the link to your Pages website. -If this path is not visible, select **Deployments > Pages**. -[This location is part of an experiment](../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 e8de80ac137..8332d96d99e 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 @@ -20,14 +20,12 @@ To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. 1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#create-a-fork). 1. In the upper-right corner, select **Fork**, then choose a namespace to fork to. -1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. +1. For your project, on the left sidebar, select **Build > Pipelines** and then **Run pipeline**. 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 +When the pipeline is finished, go to **Deploy > Pages** to find the link to your Pages website. -If this path is not visible, select **Deployments > Pages**. -[This location is part of an experiment](../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 c62ead69216..51f53860fee 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -174,12 +174,10 @@ After you have completed the preceding steps, 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 is finished, go to **Settings > Pages** to find the link to +1. Go to **Build > Pipelines** to watch the pipeline. +1. When the pipeline is finished, go to **Deploy > Pages** to find the link to your Pages website. - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../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 GitLab Pages daemon. GitLab runs it in the background and doesn't use a runner. 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 cb1da3fb21f..ae0dd9507ad 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 @@ -12,21 +12,19 @@ You can create a new project from a template and run the CI/CD pipeline to gener Use a template when you want to test GitLab Pages or start a new project that's already configured to generate a Pages site. -1. From the top navigation, select the **+** button and select **New project**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create from Template**. 1. Next to one of the templates starting with **Pages**, select **Use template**.  1. Complete the form and select **Create project**. -1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** +1. On the left sidebar, select **Build > Pipelines** and select **Run pipeline** to trigger GitLab CI/CD to build and deploy your site. -When the pipeline is finished, go to **Settings > Pages** to find the link to +When the pipeline is finished, go to **Deploy > Pages** to find the link to your Pages website. -If this path is not visible, select **Deployments > Pages**. -[This location is part of an experiment](../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 16d5cfcca4a..94dab9dfd17 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -34,10 +34,8 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. +1. On the left sidebar, select **Deploy > Pages**. - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](../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. @@ -54,7 +52,7 @@ To complete the setup and generate a GitLab Pages deployment: 1. For **Step 4**, add a commit message and select **Commit**. This commit triggers your first GitLab Pages deployment. -To view the running pipeline, go to **CI/CD > Pipelines**. +To view the running pipeline, go to **Build > Pipelines**. To view the artifacts that were created during the deployment, view the job, and on the right side, select **Download artifacts**. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 9b299b46f75..e3a32a9afe9 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -34,13 +34,6 @@ Pages does not support dynamic server-side processing, for instance, as `.php` a For more information, see [Static vs 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/pages/introduction.md b/doc/user/project/pages/introduction.md index 73bfe018a7d..d00af81c10e 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -23,8 +23,6 @@ In brief, this is what you need to upload your website in GitLab Pages: 1. Domain of the instance: domain name that is used for GitLab Pages (ask your administrator). 1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/index.md#pages) in the root directory of your repository. -1. A directory called `public` in your site's repository containing the content - to be published. 1. GitLab Runner enabled for the project. ## GitLab Pages on GitLab.com @@ -67,10 +65,7 @@ You can configure redirects for your site using a `_redirects` file. For more in To remove your pages: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. - - If this path is not visible, select **Deployments > Pages**. - [This location is part of an experiment](index.md#menu-position-test). +1. On the left sidebar, select **Deploy > Pages**. 1. Select **Remove pages**. ## Subdomains of subdomains @@ -97,19 +92,14 @@ you can create your project first and access it under `http(s)://namespace.examp ## Enable unique domains > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9347) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `pages_unique_domain`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/388151) in GitLab 15.11. - -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 `pages_unique_domain`. -On GitLab.com, by default this feature is available. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/388151) in GitLab 15.11. By default, every project in a group shares the same domain, for example, `group.gitlab.io`. This means that cookies are also shared for all projects in a group. To ensure your project uses a unique Pages domain, enable the unique domains feature for the project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Settings > Pages**. +1. On the left sidebar, select **Deploy > Pages**. 1. Select the **Use unique domain** checkbox. 1. Select **Save changes**. @@ -278,6 +268,35 @@ instead. Here are some examples of what happens given the above Pages site: When `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. +## Customize the default folder + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/859) in GitLab 16.1 with a Pages flag named `FF_CONFIGURABLE_ROOT_DIR`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1073) in GitLab 16.1. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/890) in GitLab 16.2. + +By default, the [artifact](../../../ci/jobs/job_artifacts.md) folder +that contains the static files of your site needs to have the name `public`. + +To change that folder name to any other value, add a `publish` property to your +`pages` job configuration in `.gitlab-ci.yml`. + +The following example publishes a folder named `dist` instead: + +```yaml +pages: + script: + - npm run build + artifacts: + paths: + - dist + publish: dist +``` + +If you're using a folder name other than `public`you must specify +the directory to be deployed with Pages both as an artifact, and under the +`publish` property. The reason you need both is that you can define multiple paths +as artifacts, and GitLab doesn't know which one you want to deploy. + ## Known issues For a list of known issues, see the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 6ee8ea17aee..68023b87560 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages public folder **(FREE)** -All the files that should be accessible by the browser must be in a root-level folder called `public`. +> With GitLab 16.1 we introduced the ability to configure the published folder in `.gitlab-ci.yml`, so you longer need to change your framework config. For more information, see how to [set a custom folder to be deployed with Pages](introduction.md#customize-the-default-folder). Follow these instructions to configure the `public` folder for the following frameworks. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 6958b69061a..78384249abc 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -116,7 +116,7 @@ The protected branch displays in the list of protected branches. FLAG: On self-managed GitLab, by default this feature is not available. -To make it available, ask an administrator to +To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `group_protected_branches`. On GitLab.com, this feature is not available. @@ -360,8 +360,7 @@ branches by using the GitLab web interface: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Code > Branches**. 1. Next to the branch you want to delete, select **Delete** (**{remove}**). -1. On the confirmation dialog, type the branch name. -1. Select **Yes, delete protected branch**. +1. On the confirmation dialog, enter the branch name and select **Yes, delete protected branch**. Protected branches can only be deleted by using GitLab either from the UI or API. This prevents accidentally deleting a branch through local Git commands or diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 368a59e69b0..2dfdb77df9c 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -37,6 +37,7 @@ You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | | `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). This does not skip pipelines for CI integrations, such as Jenkins. | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | | `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. Only passes variables to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | +| `integrations.skip_ci` | Skip push events for CI integrations, such as Atlassian Bamboo, Buildkite, Drone, Jenkins, and JetBrains TeamCity. | [16.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123837) | An example of using `ci.skip`: @@ -50,6 +51,12 @@ An example of passing some CI/CD variables for a pipeline: git push -o ci.variable="MAX_RETRIES=10" -o ci.variable="MAX_TIME=600" ``` +An example of using `integrations.skip_ci`: + +```shell +git push -o integrations.skip_ci +``` + ## Push options for merge requests You can use Git push options to perform certain actions for merge requests at the same diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 3e8ce009740..066da445eeb 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -163,8 +163,10 @@ The following quick actions can be applied through the description field when ed | `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. -| `/type` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `Issue`, `Task`, `Objective` and `Key Result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. +| `/type` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Converts work item to specified type. Available options for `<type>` include `issue`, `task`, `objective` and `key result`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385227) in GitLab 16.0. | `/promote_to <type>` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | Promotes work item to specified type. Available options for `<type>`: `issue` (promote a task) and `objective` (promote a key result). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412534) in GitLab 16.1. +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item as done. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412277) in GitLab 16.2. ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 6bcc57d5916..40fb6969def 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -38,7 +38,7 @@ When you create a release, or after, you can: To view a list of releases: -- On the left sidebar, select **Deployments > Releases**, or +- On the left sidebar, select **Deploy > Releases**, or - On the project's overview page, if at least one release exists, select the number of releases. @@ -75,7 +75,7 @@ Prerequisites: To create a release in the Releases page: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. On the left sidebar, select **Build > Releases** and select **New release**. +1. On the left sidebar, select **Deploy > Releases** and select **New release**. 1. From the [**Tag name**](release_fields.md#tag-name) dropdown list, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release results in a validation error. @@ -194,7 +194,7 @@ Prerequisites: In the UI: -1. On the left sidebar, select **Deployments > Releases**. +1. On the left sidebar, select **Deploy > Releases**. 1. In the upper-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. On the **Edit Release** page, change the release's details. 1. Select **Save changes**. @@ -236,17 +236,17 @@ the [Releases API](../../../api/releases/index.md#create-a-release). In the user interface, to associate milestones to a release: -1. On the left sidebar, select **Deployments > Releases**. +1. On the left sidebar, select **Deploy > Releases**. 1. In the upper-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. From the **Milestones** list, select each milestone you want to associate. You can select multiple milestones. 1. Select **Save changes**. -On the **Deployments > Releases** page, the **Milestone** is listed in the top +On the **Deploy > Releases** page, the **Milestone** is listed in the top section, along with statistics about the issues in the milestones.  -Releases are also visible on the **Issues > Milestones** page, and when you select a milestone +Releases are also visible on the **Plan > Milestones** page, and when you select a milestone on this page. Here is an example of milestones with no releases, one release, and two releases. @@ -266,7 +266,7 @@ You can be notified by email when a new release is created for your project. To subscribe to notifications for releases: -1. On the left sidebar, select **Project information**. +1. On the left sidebar, select **Project overview**. 1. Select **Notification setting** (the bell icon). 1. In the list, select **Custom**. 1. Select the **New release** checkbox. @@ -302,8 +302,8 @@ deploy_to_production: To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with the Maintainer role. -1. On the left sidebar, select **Project information**. -1. In the left navigation menu, go to **Settings > CI/CD**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Select **Expand** to see the deploy freeze table. 1. Select **Add deploy freeze** to open the deploy freeze modal. diff --git a/doc/user/project/releases/release_evidence.md b/doc/user/project/releases/release_evidence.md index 3269bf8f44b..990945b1a2b 100644 --- a/doc/user/project/releases/release_evidence.md +++ b/doc/user/project/releases/release_evidence.md @@ -97,7 +97,7 @@ Evidence collection snapshots are visible on the Releases page, along with the t When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. -Although job artifacts normally expire, artifacts included in release evidence do not expire. +Although job artifacts usually expire, artifacts included in release evidence do not expire. To enable job artifact collection you must specify both: diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md index f981918c0ea..53c5d342f74 100644 --- a/doc/user/project/remote_development/connect_machine.md +++ b/doc/user/project/remote_development/connect_machine.md @@ -26,7 +26,7 @@ To connect a remote machine to the Web IDE, you must: To generate Let's Encrypt certificates: -1. Create an `A` record to point a domain to your remote machine (for example, from `example.remote.gitlab.dev` to `1.2.3.4`). +1. Create an `A` record to point a domain to your remote machine (for example, from `example.remote.gitlab.dev` to `10.0.2.2`). 1. Install [Certbot](https://certbot.eff.org/) to enable HTTPS: ```shell diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 6a9d0c73e9a..ccb1745d490 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. 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 `vscode_web_ide`. On GitLab.com, this feature is available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable 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. WARNING: This feature is in [Beta](../../../policy/experiment-beta-support.md#beta) and subject to change without notice. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 100450aefe7..ae978e2123d 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -96,7 +96,7 @@ unless a subgroup configuration overrides it. ## Protect initial default branches **(FREE SELF)** -> Full protection after initial push [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118729) in GitLab 16.0. +> Full protection after initial push [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118729) in GitLab 16.0. GitLab administrators and group owners can define [branch protections](../../../project/protected_branches.md) to apply to every repository's [default branch](#default-branch) diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index e43efca600a..3e9957806c8 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -128,7 +128,7 @@ On this page, you can: > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.11 FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../feature_flags.md) named `branch_rules`. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../feature_flags.md) named `branch_rules`. On GitLab.com, this feature is available. Branches in your repository can be [protected](../../protected_branches.md) in multiple ways. You can: diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md index dd1fa3f4c8b..95d5873a535 100644 --- a/doc/user/project/repository/code_suggestions.md +++ b/doc/user/project/repository/code_suggestions.md @@ -5,191 +5,232 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Code Suggestions (Beta) **(FREE SAAS)** +# Code Suggestions (Beta) **(FREE)** -> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](/ee/policy/experiment-beta-support.md#beta) for early access Ultimate customers. -> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](/ee/policy/experiment-beta-support.md#beta). +> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](../../../policy/experiment-beta-support.md#beta) for early access Ultimate customers on GitLab.com. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](../../../policy/experiment-beta-support.md#beta). > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1. -> - [Default to third-party AI services](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. +> - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../policy/experiment-beta-support.md#beta) on self-managed GitLab. +> - Code suggestions in the GitLab WebIDE enabled for all GitLab-hosted customers. +> - [Removed support for GitLab native model](https://gitlab.com/groups/gitlab-org/-/epics/10752) in GitLab 16.2. WARNING: -This feature is in [Beta](/ee/policy/experiment-beta-support.md#beta). -Due to high demand, this feature may have unscheduled downtime and Code Suggestions in IDEs may be delayed. -Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). -Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your feedback. +This feature is in [Beta](../../../policy/experiment-beta-support.md#beta). +Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your [feedback](#feedback). -Code Suggestions use generative AI to suggest code while you're developing. -Use Code Suggestions to write code more efficiently by viewing Code Suggestions -as you type. Depending on the cursor position, the extension either: +Write code more efficiently by using generative AI to suggest code while you're developing. -- Provides entire code snippets, like generating functions. -- Completes the current line. +Code Suggestions are available: -To accept a suggestion, press <kbd>Tab</kbd>. +- To users of GitLab SaaS (by default) and self-managed GitLab Enterprise Edition (when requested). Code Suggestions are not available for GitLab Community Edition. +- In VS Code and Microsoft Visual Studio when you have the corresponding GitLab extension installed. +- In the GitLab WebIDE -Code Suggestions are available in Visual Studio Code when you have the GitLab Workflow extension installed. [Additional IDE extension support](https://gitlab.com/groups/gitlab-org/-/epics/10542) is planned for the near future. +<div class="video-fallback"> + <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">View an end-to-end demo of Code Suggestions in VS Code</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> +</figure> + +Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). +Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). ## Supported languages -Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). +The best results from Code Suggestions are expected [for languages the Google Vertex AI Codey APIs](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_coding_languages) directly support: -Language support varies depending on which AI model serves Code Suggestions. To use Code Suggestions entirely within GitLab cloud infrastructure, disable third-party AI services. To receive higher quality suggestions, [enable third-party AI services](#third-party-ai-services-controls). +- C++ +- C# +- Go +- Google SQL +- Java +- JavaScript +- Kotlin +- PHP +- Python +- Ruby +- Rust +- Scala +- Swift +- TypeScript -The best results from Code Suggestions are expected for these languages: + Supported [code infrastructure interfaces](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview#supported_code_infrastructure_interfaces) include: -- **Third-party AI services (Google Codey)**: Go, Google Cloud CLI, Google SQL, Java, JavaScript, Kubernetes Resource Model (KRM), Python, Terraform, TypeScript. -- **GitLab first-party AI model**: C/C++, C#, Go, Java, JavaScript, Python, PHP, Ruby, Rust, Scala, TypeScript. +- Google Cloud CLI +- Kubernetes Resource Model (KRM) +- Terraform -Suggestions may be mixed for other languages. Using natural language code comments to request completions may also not function as expected. +Suggestion quality for other languages and using natural language code comments to request completions may not yet result in high-quality suggestions. -Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. +## Enable Code Suggestions on GitLab SaaS **(FREE SAAS)** -We are making improvements to the Code Suggestions underlying AI model weekly to improve the quality of suggestions. Please remember that AI is non-deterministic, so you may not get the same suggestion week to week. +Code Suggestions can be enabled [for all members of a group](../../group/manage.md#enable-code-suggestions). -Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). +Each individual user must also choose to enable Code Suggestions. -## Enable Code Suggestions for an individual user +### Enable Code Suggestions for an individual user -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](/ee/policy/experiment-beta-support.md#beta). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../policy/experiment-beta-support.md#beta). Each user can enable Code Suggestions for themselves: 1. On the left sidebar, select your avatar. -1. On the left sidebar, select **Preferences**. -1. In the **Code Suggestions** section, select **Enable Code Suggestions**. +1. Select **Preferences**. +1. In the **Code Suggestions** section, select the **Enable Code Suggestions** checkbox. 1. Select **Save changes**. +If Code Suggestions is enabled for the group, the group setting overrides the user setting. + NOTE: -If Code Suggestions is [enabled for the group](../../group/manage.md#enable-code-suggestions), the group setting overrides the user setting. +This setting controls Code Suggestions for all IDEs. Support for [more granular control per IDE](https://gitlab.com/groups/gitlab-org/-/epics/10624) is proposed. -## Enable Code Suggestions in WebIDE +## Enable Code Suggestions on self-managed GitLab **(FREE SELF)** -Prerequisites: +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../policy/experiment-beta-support.md#beta). -- Code Suggestions must be [enabled for the top-level group](../../group/manage.md#enable-code-suggestions). -- Code Suggestions must be [enabled for your user account](#enable-code-suggestions-for-an-individual-user). -- You must be a GitLab team member. +To enable Code Suggestions on a self-managed GitLab EE instance, you must: -Code Suggestions work automatically in the [GitLab WebIDE](../../project/web_ide/index.md) if the above prerequisites are met. To disable Code Suggestions in the WebIDE, disable the user account setting. +- Be an administrator. +- Have a [GitLab SaaS account](https://gitlab.com/users/sign_up). +You do not need to have a GitLab SaaS subscription. -NOTE: -Disabling in the WebIDE will also disable in any other IDEs you use locally like VS Code. Support for [more granular control per IDE](https://gitlab.com/groups/gitlab-org/-/epics/10624) is proposed. +Then, you will: -## Enable Code Suggestions in VS Code +1. Enable Code Suggestions for your SaaS account. +1. Enable Code Suggestions for the instance. +1. [Request early access](#request-access-to-code-suggestions) to the Code Suggestions Beta. -Prerequisites: +### Enable Code Suggestions for your SaaS account -- Code Suggestions must be [enabled for the top-level group](../../group/manage.md#enable-code-suggestions). -- Code Suggestions must be [enabled for your user account](#enable-code-suggestions-for-an-individual-user). -- Completed the [setup instructions](https://gitlab.com/gitlab-org/gitlab-vscode-extension#setup) for the GitLab Visual Studio Code Extension. +To enable Code Suggestions for your GitLab SaaS account: -To enable Code Suggestions in VS Code: +1. Create a [personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) + with the `api` scope. +1. On the left sidebar, select your avatar. +1. Select **Preferences**. +1. In the **Code Suggestions** section, select **Enable Code Suggestions**. +1. Select **Save changes**. -1. Download and install the - [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) - for Visual Studio Code. -1. Complete the [setup instructions](https://gitlab.com/gitlab-org/gitlab-vscode-extension#setup) for the extension. -1. After your GitLab account connects successfully, in the left sidebar, select **Extensions**. -1. Find the **GitLab workflow** extension, select **Settings** (**{settings}**), and select **Extension Settings**. -1. Enable **GitLab > AI Assisted Code Suggestions**. +### Enable Code Suggestions for the instance -Start typing and receive suggestions for your GitLab projects. +You must enable Code Suggestions for the instance. When you do this, you: -<div class="video-fallback"> - See an end-to-end demo: <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">Get started with GitLab Code Suggestions in VS Code</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> -</figure> +- Agree to the [GitLab testing agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). +- Acknowledge that GitLab: + - Sends data from the instance, including personal data, to GitLab.com infrastructure. -## Enable Code Suggestions in other IDEs and editors +To enable Code Suggestions for your self-managed GitLab instance: -We have experimental support for Code Suggestions in Visual Studio, JetBrains, Neovim, Emacs, Sublime, etc. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Code Suggestions** and: + - Select **Turn on Code Suggestions for this instance**. + - In **Personal access token**, enter your GitLab SaaS personal access token. +1. Select **Save changes**. -More details in this [blog](https://about.gitlab.com/blog/2023/06/01/extending-code-suggestions/). +This setting is visible only in self-managed GitLab instances. -## Why aren't Code Suggestions displayed? +WARNING: +If you clear the **Turn on code suggestions for this instance** checkbox, the users in your instance can still use Code Suggestions for up to one hour, until the issued JSON web token (JWT) expires. -If Code Suggestions are not displayed, try the following troubleshooting steps. +### Request access to Code Suggestions -In GitLab, ensure Code Suggestions is enabled: +GitLab provisions access on a customer-by-customer basis for Code Suggestions +on self-managed instances. To request access: -- [For your user account](#enable-code-suggestions-for-an-individual-user). -- [For *all* top-level groups your account belongs to](../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. +1. Sign into your GitLab SaaS account. +1. Comment on [issue 415393](https://gitlab.com/gitlab-org/gitlab/-/issues/415393) + and tag your customer success manager. -In VS Code: +After GitLab has provisioned access to Code Suggestions for your instance, +the users in your instance can now enable Code Suggestions. -- Ensure [your IDE is configured properly](#enable-code-suggestions-in-vs-code). +## Enable Code Suggestions in other IDEs and editors -To confirm that your account is enabled, go to [https://gitlab.com/api/v4/ml/ai-assist](https://gitlab.com/api/v4/ml/ai-assist). A response of `user_is_allowed` should return `true`. +We have experimental support for Code Suggestions in JetBrains, Neovim, Emacs, Sublime, etc. -### Authentication troubleshooting +More details in this [blog](https://about.gitlab.com/blog/2023/06/01/extending-code-suggestions/). -If the above steps do not solve your issue, the problem may be related to the recent changes in authentication, specifically the token system. To resolve the issue, please follow these troubleshooting steps: +## Use Code Suggestions -- Remove the existing PAT from your GitLab account settings. -- Reauthorize your GitLab account in VSCode using OAuth. -- Test the code suggestions feature with different file extensions to verify if the issue is resolved. +Prerequisites: -## Third-party AI services controls +- For self-managed GitLab, Code Suggestions must be enabled [for the instance](#enable-code-suggestions-on-self-managed-gitlab). +- For GitLab SaaS, Code Suggestions must be enabled [for the top-level group](../../group/manage.md#enable-code-suggestions) and [for your user account](#enable-code-suggestions-for-an-individual-user). +- To use VS Code, ensure you have installed [the VS Code GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). +- To use Microsoft Visual Studio, ensure you have installed [the Visual Studio GitLab extension](https://marketplace.visualstudio.com/items?itemName=GitLab.GitLabExtensionForVisualStudio). -Organizations can opt to use Code Suggestions entirely within GitLab cloud infrastructure. This option can be controlled with the top-level group [Third-party AI setting](../../group/manage.md#enable-third-party-ai-features). +To use Code Suggestions: + +1. Author your code. As you type, suggestions are displayed. Depending on the cursor position, the extension either: -Having the third-party AI setting enabled will allow Code Suggestions to use third-party AI services, which is likely to produce higher quality results. Please note that language support varies between the two options and will change over time. + - Provides entire code snippets, like generating functions. + - Completes the current line. -To use Code Suggestions entirely within GitLab’s cloud infrastructure, disable third-party AI services. You can disable Code Suggestions entirely in [your user profile settings](#enable-code-suggestions-for-an-individual-user). +1. To accept a suggestion, press <kbd>Tab</kbd>. + +Suggestions are best when writing new code. Editing existing functions or 'fill in the middle' of a function may not perform as expected. -## Stability and performance +GitLab is making improvements to the Code Suggestions to improve the quality. AI is non-deterministic, so you may not get the same suggestion every time with the same input. -This feature is currently in [Beta](/ee/policy/experiment-beta-support.md#beta). -While the Code Suggestions inference API operates completely within the GitLab.com enterprise infrastructure, -we expect a high demand for this Beta feature, which may cause degraded performance or unexpected downtime -of the feature. We have built this feature to gracefully degrade and have controls in place to allow us to +This feature is currently in [Beta](../../../policy/experiment-beta-support.md#beta). +Code Suggestions depends on both Google Vertex AI Codey APIs and the GitLab Code Suggestions service. We have built this feature to gracefully degrade and have controls in place to allow us to mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. ## Code Suggestions data usage -Code Suggestions is a generative artificial intelligence (AI) model hosted on GitLab.com. +Code Suggestions is a generative artificial intelligence (AI) model. Your personal access token enables a secure API connection to GitLab.com. -This API connection securely transmits a context window from VS Code to the Code Suggestions ML model for inference, -and the generated suggestion is transmitted back to VS Code. +This API connection securely transmits a context window from your IDE/editor to the Code Suggestions GitLab hosted service which calls Google Vertex AI Codey APIs, +and the generated suggestion is transmitted back to your IDE/editor. -Depending on your settings, different ML models will be used to provide Code Suggestions. GitLab currently leverages [Google Cloud's Vertex AI Codey API models](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview) for third-party AI powered Code Suggestions. The sections below refer only to GitLab first-party AI Model. +GitLab currently leverages [Google Cloud's Vertex AI Codey API models](https://cloud.google.com/vertex-ai/docs/generative-ai/code/code-models-overview). ### Data privacy -This section applies only to customers who have third-party AI services disabled. +No new additional data is collected to enable this feature. Private non-public GitLab customer data is +not used as training data. -Code Suggestions operate completely in the GitLab.com infrastructure, providing the same level of -[security](https://about.gitlab.com/security/) as any other feature of GitLab.com, and processing any personal -data in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). +Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance) -No new additional data is collected to enable this feature. The content of your GitLab hosted source code is -not used as training data. Source code inference against the Code Suggestions model is not used to re-train the model. -Your data also never leaves GitLab.com. All training and inference is done in GitLab.com infrastructure. +### Inference window context -[Read more about the security of GitLab.com](https://about.gitlab.com/security/faq/). +Code Suggestions currently inferences against the currently opened file and has a context window of 2,048 tokens and 8,192 character limits. This limit includes content before and after the cursor, the file name, and the extension type. + +Learn more about Google Vertex AI [code-gecko](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). + +### Self-managed instance data privacy + +A self-managed GitLab instance does not generate the code suggestion. After successful +authentication to the self-managed instance, a token is generated. + +The IDE/editor then uses this token to securely transmit data directly to +GitLab.com's Code Suggestions service for processing. + +The Code Suggestion service then securely returns an AI-generated code suggestion. + +Neither GitLab nor Google Vertex AI Codey APIs have any visibility into a self-managed customer's code other than +what is sent to generate the code suggestion. ### Training data -This section applies only to customers who have third-party AI services disabled. +Code suggestions are routed through Google Vertex AI Codey APIs. Learn more about Google Vertex AI Codey APIs [Data Governance](https://cloud.google.com/vertex-ai/docs/generative-ai/data-governance) and [Responsible AI](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/responsible-ai). + +Google Vertex AI Codey APIs are not trained on private non-public GitLab customer or user data. -Code Suggestions uses open source pre-trained base models from the -[CodeGen family](https://openreview.net/forum?id=iaYcJKpY2B_) including CodeGen-MULTI and CodeGen-NL. -We then re-train and fine-tune these base models with a customized open source dataset to enable multi-language -support and additional use cases. This customized dataset contains non-preprocessed open source code in 13 -programming languages from [The Pile](https://pile.eleuther.ai/) and the -[Google BigQuery source code dataset](https://cloud.google.com/blog/topics/public-datasets/github-on-bigquery-analyze-all-the-open-source-code). -We then process this raw dataset against heuristics that aim to increase the quality of the dataset. +Google has [shared the following](https://ai.google/discover/foundation-models/) about the data Codey models are trained on: -The Code Suggestions model is not trained on GitLab customer or user data. +> Codey is our family of foundational coding models built on PaLM 2. Codey was fine-tuned on a large dataset of high quality, permissively licensed code from external sources ## Progressive enhancement -This feature is designed as a progressive enhancement to developers IDEs. +This feature is designed as a progressive enhancement to developer's IDEs. Code Suggestions offer a completion if the machine learning engine can generate a recommendation. In the event of a connection issue or model inference failure, the feature gracefully degrades. Code Suggestions do not prevent you from writing code in your IDE. @@ -203,25 +244,16 @@ To use Code Suggestions: - On GitLab.com, you must have an internet connection and be able to access GitLab. - In GitLab 16.1 and later, on self-managed GitLab, you must have an internet connection. -[Self-managed support via a proxy to GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/10528) has been proposed. - ### Model accuracy and quality -Regardless of whether third-party AI services are enabled, while in Beta, Code Suggestions can generate low-quality, incomplete, and possibly insecure code. +Code Suggestions can generate low-quality, incomplete, and possibly insecure code. We strongly encourage all beta users to leverage GitLab native [Code Quality Scanning](../../../ci/testing/code_quality.md) and [Security Scanning](../../application_security/index.md) capabilities. -GitLab uses a customized open source dataset to fine-tune the model to support multiple languages. -Based on the languages you code in, GitLab routes the request to a targeted inference and prompt engine -to get relevant suggestions. - -GitLab is actively refining these models to: - -- Improve the quality of recommendations. -- Add support for more languages. -- Add protections to limit personal data, insecure code, and other unwanted behavior - that the model may have learned from training data. +GitLab currently does not retrain Google Vertex AI Codey APIs. GitLab makes no claims +to the accuracy or quality of code suggestions generated by Google Vertex AI Codey API. +Read more about [Google Vertex AI foundation model capabilities](https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models). ## Known limitations @@ -243,3 +275,64 @@ We are also aware of specific situations that can produce unexpected or incohere ## Feedback Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). + +## Troubleshooting + +### Code Suggestions aren't displayed + +If Code Suggestions are not displayed, try the following troubleshooting steps. + +In GitLab, ensure Code Suggestions is enabled: + +- [For your user account](#enable-code-suggestions-for-an-individual-user). +- [For *all* top-level groups your account belongs to](../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. + +To confirm that your account is enabled, go to [https://gitlab.com/api/v4/ml/ai-assist](https://gitlab.com/api/v4/ml/ai-assist). A response of `user_is_allowed` should return `true`. + +#### Code Suggestions not displayed in VS Code or GitLab WebIDE + +Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-displayed) first. + +If you are a self-managed user, ensure that Code Suggestions for the [GitLab WebIDE](../../project/web_ide/index.md) are enabled. The same settings apply to VS Code as local IDE. + +1. On the left sidebar, select **Extensions > GitLab Workflow**. +1. Select **Settings** (**{settings}**), and then select **Extension Settings**. +1. In **GitLab > AI Assisted Code Suggestions**, select the **Enable code completion (Beta)** + checkbox. + +If the settings are enabled, but Code Suggestions are still not displayed, try the following steps: + +1. Enable the `Debug` checkbox in the GitLab Workflow **Extension Settings**. +1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Workflow** as the log filter. The command palette command is `GitLab: Show Extension Logs`. +1. Disable and re-enable the **Enable code completion (Beta)** checkbox. +1. Verify that the debug log contains similar output: + +```shell +2023-07-14T17:29:00:763 [debug]: Disabling code completion +2023-07-14T17:29:01:802 [debug]: Enabling code completion +2023-07-14T17:29:01:802 [debug]: AI Assist: Using server: https://codesuggestions.gitlab.com/v2/completions +``` + +#### Code Suggestions not displayed in Microsoft Visual Studio + +Check all the steps in [Code Suggestions aren't displayed](#code-suggestions-arent-displayed) first. + +1. Ensure you have properly [set up the extension](https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension#setup). +1. From the **Tools > Options** menu, find the **GitLab** option. Ensure **Log Level** is set to **Debug**. +1. Open the extension log in **View > Output** and change the dropdown list to **GitLab Extension** as the log filter. +1. Verify that the debug log contains similar output: + +```shell +14:48:21:344 GitlabProposalSource.GetCodeSuggestionAsync +14:48:21:344 LsClient.SendTextDocumentCompletionAsync("GitLab.Extension.Test\TestData.cs", 34, 0) +14:48:21:346 LS(55096): time="2023-07-17T14:48:21-05:00" level=info msg="update context" +``` + +### Authentication troubleshooting + +If the above steps do not solve your issue, the problem may be related to the recent changes in authentication, +specifically the token system. To resolve the issue: + +1. Remove the existing personal access token from your GitLab account settings. +1. Reauthorize your GitLab account in VS Code using OAuth. +1. Test the code suggestions feature with different file extensions to verify if the issue is resolved. diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index baac2a788be..235c1f34d1a 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -21,7 +21,7 @@ Prerequisites: To view the blame for a file: -1. Go to your project's **Repository > Files**. +1. Go to your project's **Code > Repository**. 1. Select the file you want to review. 1. In the upper-right corner, select **Blame**. diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index a9228b8cabd..edfcc4b1dc2 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -11,7 +11,7 @@ description: "Documentation on Git file history." Git file History provides information about the commit history associated with a file. To use it: -1. Go to your project's **Repository > Files**. +1. Go to your project's **Code > Repository**. 1. In the upper-right corner, select **History**. When you select **History**, this information is displayed: diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 839ab33808b..8d8639400bd 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -119,7 +119,7 @@ If you don't already have a GPG key, create one: To add a GPG key to your user settings: 1. Sign in to GitLab. -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. Select **GPG Keys** (**{key}**). 1. In **Key**, paste your _public_ key. @@ -230,7 +230,7 @@ You can review commits for a merge request, or for an entire project: 1. Select **Code > Commits**. 1. To review commits for a merge request: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Merge requests**, then select your merge request. + 1. Select **Code > Merge requests**, then select your merge request. 1. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** or **Unverified** badge, depending on the verification status of the GPG @@ -253,7 +253,7 @@ If a GPG key becomes compromised, revoke it. Revoking a key changes both future To revoke a GPG key: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. Select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. @@ -268,7 +268,7 @@ When you remove a GPG key from your GitLab account: To remove a GPG key from your account: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. Select **GPG Keys** (**{key}**). 1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. @@ -286,7 +286,7 @@ If you must unverify both future and past commits, - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) - - [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) + - [Review existing GPG keys in your instance](../../../../administration/credentials_inventory.md#review-existing-gpg-keys) ## Troubleshooting diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 9f0c46591b9..7383772a45b 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -132,7 +132,7 @@ change. This can occur, for example, if Git or a third-party library that GitLab ## Repository languages For the default branch of each repository, GitLab determines which programming languages -are used. This information is displayed on the **Project information** page. +are used. This information is displayed on the **Project overview** page.  @@ -140,7 +140,7 @@ When new files are added, this information can take up to five minutes to update ### Add repository languages -Not all files are detected and listed on the **Project information** page. Documentation, +Not all files are detected and listed on the **Project overview** page. Documentation, vendor code, and most markup languages are excluded. You can change this behavior by overriding the default settings. @@ -224,10 +224,10 @@ To render an OpenAPI file: FLAG: On self-managed GitLab, by default GitLab uses the `du -sk` command to determine the size of a repository. GitLab can use either `git-rev-list` (enabled with feature flag `gitaly_revlist_for_repo_size`) or `git-cat-file` (enabled with feature flag -`gitaly_catfile_repo_size`) instead. To switch between different calculation methods, ask an administrator to +`gitaly_catfile_repo_size`) instead. To switch between different calculation methods, an administrator can [enable or disable](../../../administration/feature_flags.md) these feature flags. -The **Project information** page shows the size of all files in the repository. The size is +The **Project overview** page shows the size of all files in the repository. The size is updated, at most, every 15 minutes. The file size includes repository files, artifacts, and LFS. The size can differ slightly from one instance to another due to compression, housekeeping, and other factors. @@ -237,7 +237,7 @@ Administrators can set a [repository size limit](../../admin_area/settings/accou ## Repository contributor statistics -All code contributors are displayed under your project's **Repository > Contributor statistics**. +All code contributors are displayed under your project's **Analyze > Contributor statistics**. The graph shows the contributor with the most commits to the fewest. @@ -248,7 +248,7 @@ The graph shows the contributor with the most commits to the fewest. A repository graph displays a visual history of the repository network, including branches and merges. This graph can help you visualize the Git flow strategy used in the repository. -Go to your project's **Repository > Graph**. +Go to your project's **Code > Repository graph**.  diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 733310a0b4d..58c6c343282 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -80,13 +80,7 @@ To use this option, select **Only mirror protected branches** when you create a > - 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. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0. - -FLAG: -On self-managed GitLab, by default the field `mirror_branch_regex` is available. -To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) -named `mirror_only_branches_match_regex`. -On GitLab.com, this feature is available. - +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/410354) in GitLab 16.2. Feature flag `mirror_only_branches_match_regex` removed. 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. @@ -101,6 +95,9 @@ You can also manually trigger an update: - According to [the pull mirroring interval limit](../../../../administration/instance_limits.md#pull-mirroring-interval) set by the administrator on self-managed instances. +NOTE: +[GitLab Silent Mode](../../../../administration/silent_mode/index.md) disables both push and pull updates. + ### Force an update While mirrors are scheduled to update automatically, you can force an immediate update unless: @@ -209,8 +206,8 @@ Older versions of SSH may require you to remove `-E md5` from the command. ## Related topics - Configure a [Pull Mirroring Interval](../../../../administration/instance_limits.md#pull-mirroring-interval) -- [Disable mirrors for a project](../../../admin_area/settings/visibility_and_access_controls.md#enable-project-mirroring) -- [Secrets file and mirroring](../../../../raketasks/backup_restore.md#when-the-secrets-file-is-lost) +- [Disable mirrors for a project](../../../../administration/settings/visibility_and_access_controls.md#enable-project-mirroring) +- [Secrets file and mirroring](../../../../administration/backup_restore/backup_gitlab.md#when-the-secrets-file-is-lost) ## Troubleshooting @@ -224,11 +221,16 @@ If you receive this message while mirroring to a GitHub repository: 13:Received RST_STREAM with error code 2 ``` -Your GitHub settings might be set to block pushes that expose your email address -used in commits. To fix this problem, either: +One of these issues might be occurring: -- Set your GitHub email address to public. -- Disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. +1. Your GitHub settings might be set to block pushes that expose your email address + used in commits. To fix this problem, either: + - Set your GitHub email address to public. + - Disable the [Block command line pushes that expose my email](https://github.com/settings/emails) + setting. +1. Your repository exceeds GitHub's file size limit of 100 MB. To fix this problem, + check the file size limit configured for on GitHub, and consider using + [Git Large File Storage](https://git-lfs.github.com) to manage large files. ### Deadline Exceeded @@ -320,7 +322,7 @@ fail nor succeed. They also do not leave a clear log. To check for this problem: end ``` -1. After you run the command, the [background jobs page](../../../admin_area/index.md#background-jobs) +1. After you run the command, the [background jobs page](../../../../administration/admin_area.md#background-jobs) should show new mirroring jobs being scheduled, especially when [triggered manually](#update-a-mirror). diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 1463e0de0f1..56e85157c03 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -15,13 +15,16 @@ branches, tags, and commits from an upstream repository to yours. Unlike [push mirrors](push.md), pull mirrors retrieve changes from an upstream (remote) repository on a scheduled basis. To prevent the mirror from diverging from the upstream repository, don't push commits directly to the downstream mirror. Push commits to -the upstream repository instead. Changes in the remote repository are pulled into the GitLab repository, either: +the upstream repository instead. Changes in the remote repository are pulled into the GitLab repository: -- Automatically in a certain period of time. Self-managed instances can - configure [pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval). +- Automatically, 30 minutes after a previous pull. This cannot be disabled. - When an administrator [force-updates the mirror](index.md#force-an-update). - When an [API call triggers an update](#trigger-an-update-by-using-the-api). +UI and API updates are subject to default +[pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) +of 5 minutes. This interval can be configured by self-managed instances. + By default, if any branch or tag on the downstream pull mirror diverges from the local repository, GitLab stops updating the branch. This prevents data loss. Deleted branches and tags in the upstream repository are not reflected in the @@ -52,13 +55,14 @@ After you configure a GitLab repository as a pull mirror: ## Configure pull mirroring -Prerequisite: +Prerequisites: - If your remote repository is on GitHub and you have [two-factor authentication (2FA) configured](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa), create a [personal access token for GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with the `repo` scope. If 2FA is enabled, this personal access token serves as your GitHub password. +- [GitLab Silent Mode](../../../../administration/silent_mode/index.md) is not enabled. 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Repository**. diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 9da8ce7acc5..26a60002f0e 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -30,6 +30,9 @@ it is deleted from the remote mirror on the next push. Branches with unmerged changes are kept. If a branch diverges, the **Mirroring repositories** section displays an error. +[GitLab Silent Mode](../../../../administration/silent_mode/index.md) disables pushing to, +and pulling from, remote mirrors. + ## Configure push mirroring To set up push mirroring for an existing project: @@ -77,8 +80,12 @@ through the [remote mirrors API](../../../../api/remote_mirrors.md). To configure a mirror from GitLab to GitHub: -1. Create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) - with `public_repo` selected. +1. Create a [GitHub fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) + with at least read and write permissions on the [repository contents](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens#repository-permissions-for-contents). If your + repository contains a `.github/workflows` directory, you must also grant + read and write access for the [Workflows](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens#repository-permissions-for-workflows). + For a more fine-grained access, you can configure your token to only apply + to the specific repository. 1. Enter a **Git repository URL** with this format, changing the variables as needed: ```plaintext diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index fbadc9b84a3..81896d64815 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -71,11 +71,13 @@ Use these rules for your commit messages. - **Require expression in commit messages**: Messages must match the expression. To allow any commit message, leave empty. - Uses multiline mode, which can be disabled by using `(?-m)`. + Uses multiline mode, which can be disabled by using `(?-m)`. Some validation examples: + + - `JIRA\-\d+` requires every commit to reference a Jira issue, like `Refactored css. Fixes JIRA-123`. + - `[[:^punct:]]\b$` rejects a commit if the final character is a punctuation mark. + The word boundary character (`\b`) prevents false negatives, because Git adds a + newline character (`\n`) to the end of the commit message. - For example, if every commit should reference a Jira issue - (like `Refactored css. Fixes JIRA-123.`), the regular expression would be - `JIRA\-\d+`. - **Reject expression in commit messages**: Commit messages must not match the expression. To allow any commit message, leave empty. Uses multiline mode, which can be disabled by using `(?-m)`. @@ -230,7 +232,7 @@ These examples use regex (regular expressions) string boundary characters to mat the beginning of a string (`^`), and its end (`$`). They also include instances where either the directory path or the filename can include `.` or `/`. Both of these special regex characters must be escaped with a backslash `\\` if you want -to use them as normal characters in a match condition. +to use them as standard characters in a match condition. - **Prevent pushing `.exe` files to any location in the repository** - This regex matches any filename that contains `.exe` at the end: 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 ce3a5ee9916..334db91cd82 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 @@ -235,8 +235,8 @@ When using repository cleanup, note: Repository size limits: -- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings). -- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md) on self-managed instances. +- Can [be set by an administrator](../../../administration/settings/account_and_limit_settings.md#account-and-limit-settings). +- Can [be set by an administrator](../../../administration/settings/account_and_limit_settings.md) on self-managed instances. - Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). When a project has reached its size limit, you cannot: diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index 8f29845fd9b..85a8917022e 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -169,7 +169,7 @@ If an SSH key becomes compromised, revoke it. Revoking a key changes both future To revoke an SSH key: -1. In the upper-right corner, select your avatar. +1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select (**{key}**) **SSH Keys**. 1. Select **Revoke** next to the SSH key you want to delete. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index b8e9de41062..4079f821064 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -49,7 +49,7 @@ Prerequisite: To create a requirement: -1. In a project, go to **Issues > Requirements**. +1. In a project, go to **Plan > Requirements**. 1. Select **New requirement**. 1. Enter a title and description and select **Create requirement**. @@ -124,7 +124,7 @@ You can search for a requirement from the requirements list page based on the fo To search for a requirement: -1. In a project, go to **Issues > Requirements > List**. +1. In a project, go to **Plan > Requirements > List**. 1. Select the **Search or filter results** field. A dropdown list appears. 1. Select the requirement author or status from the dropdown list or enter plain text to search by requirement title. 1. Press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -239,7 +239,7 @@ Before you import your file: To import requirements: -1. In a project, go to **Issues > Requirements**. +1. In a project, go to **Plan > Requirements**. - For a project with requirements, in the upper-right corner, select the import icon (**{import}**). - For a project without requirements, in the middle of the page, select **Import CSV**. @@ -300,7 +300,7 @@ Prerequisite: To export requirements: -1. In a project, go to **Issues > Requirements**. +1. In a project, go to **Plan > Requirements**. 1. In the upper-right corner, select **Export as CSV** (**{export}**). A confirmation modal appears. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 8d525965f96..b508fbcf676 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -43,8 +43,8 @@ Meanwhile: ## Configure Service Desk -To start using Service Desk for a project, you must first turn it on. -By default, Service Desk is turned off. +By default, Service Desk is active in new projects. +If it's not active, you can do it in the project's settings. Prerequisites: @@ -64,7 +64,7 @@ To enable Service Desk in your project: 1. Expand **Service Desk**. 1. Turn on the **Activate Service Desk** toggle. 1. Optional. Complete the fields. - - [Add a suffix](#configure-a-custom-email-address-suffix) to your Service Desk email address. + - [Add a suffix](#configure-a-suffix-for-service-desk-alias-email) to your Service Desk email address. - If the list below **Template to append to all Service Desk issues** is empty, create a [description template](description_templates.md) in your repository. 1. Select **Save changes**. @@ -81,81 +81,73 @@ To improve your Service Desk project's security, you should: - [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. Unblocked email spam can result in many spam issues being created. -### Create customized email templates +### Customize emails sent to the requester > - Moved from GitLab Premium to GitLab Free in 13.2. > - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. +> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. +> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. -An email is sent to the author when: - -- A user submits a new issue using Service Desk. -- A new note is created on a Service Desk issue. - -You can customize the body of these email messages with templates. +An email is sent to the requester when: -#### Email header and footer **(FREE SELF)** +- A requester submits a new ticket by emailing Service Desk. +- A new public comment is added on a Service Desk ticket. + - Editing a comment does not trigger a new email to be sent. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. +You can customize the body of these email messages with Service Desk email templates. The templates +can include [GitLab Flavored Markdown](../markdown.md) and [some HTML tags](../markdown.md#inline-html). +For example, you can format the emails to include a header and footer in accordance with your +organization's brand guidelines. You can also include the following placeholders to display dynamic +content specific to the Service Desk ticket or your GitLab instance. -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). +| Placeholder | `thank_you.md` | `new_note.md` | Description +| ---------------------- | ---------------------- | ---------------------- | ----------- +| `%{ISSUE_ID}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket IID. +| `%{ISSUE_PATH}` | **{check-circle}** Yes | **{check-circle}** Yes | Project path appended with the ticket IID. +| `%{ISSUE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). +| `%{ISSUE_DESCRIPTION}` | **{check-circle}** Yes | **{check-circle}** Yes | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify descriptions or your team is aware of the template design. +| `%{UNSUBSCRIBE_URL}` | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe URL. +| `%{NOTE_TEXT}` | **{dotted-circle}** No | **{check-circle}** Yes | The new comment added to the ticket by a user. Take care to include this placeholder in `new_note.md`. Otherwise, the requesters may never see the updates on their Service Desk ticket. #### Thank you email -> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. -> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. - -When a user submits an issue through Service Desk, GitLab sends a **thank you email**. +When a requester submits an issue through Service Desk, GitLab sends a **thank you email**. +Without additional configuration, GitLab sends the default thank you email. -To create a custom email template, in the `.gitlab/service_desk_templates/` -directory in your repository, create a file named `thank_you.md`. +To create a custom thank you email template: -You can use these placeholders to be automatically replaced in each email: +1. In the `.gitlab/service_desk_templates/` directory of your repository, create a file named `thank_you.md`. +1. Populate the Markdown file with text, [GitLab Flavored Markdown](../markdown.md), + [some selected HTML tags](../markdown.md#inline-html), and placeholders to customize the reply + to Service Desk requesters. -- `%{ISSUE_ID}`: Issue IID. -- `%{ISSUE_PATH}`: Project path appended with the issue IID. -- `%{ISSUE_URL}`: URL to the issue. External participants can only view the issue if the project is public - and issue is not confidential (Service Desk issues are confidential by default). -- `%{ISSUE_DESCRIPTION}`: Issue description based on the original email. -- `%{UNSUBSCRIBE_URL}`: Unsubscribe URL. -- `%{SYSTEM_HEADER}`: [System header message](../admin_area/appearance.md#system-header-and-footer-messages). -- `%{SYSTEM_FOOTER}`: [System footer message](../admin_area/appearance.md#system-header-and-footer-messages). -- `%{ADDITIONAL_TEXT}`: [Custom additional text](../admin_area/settings/email.md#custom-additional-text). +#### New note email -Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), -the response email does not contain the issue link. +When a Service Desk ticket has a new public comment, GitLab sends a **new note email**. +Without additional configuration, GitLab sends the content of the comment. -#### New note email +To keep your emails on brand, you can create a custom new note email template. To do so: -> - `%{ISSUE_DESCRIPTION}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223751) in GitLab 16.0. -> - `%{ISSUE_URL}` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408793) in GitLab 16.1. +1. In the `.gitlab/service_desk_templates/` directory in your repository, create a file named `new_note.md`. +1. Populate the Markdown file with text, [GitLab Flavored Markdown](../markdown.md), + [some selected HTML tags](../markdown.md#inline-html), and placeholders to customize the new note + email. Be sure to include the `%{NOTE_TEXT}` in the template to make sure the email recipient can + read the contents of the comment. -When a user-submitted issue receives a new comment, GitLab sends a **new note email**. +#### Instance-level email header, footer, and additional text **(FREE SELF)** -To create a custom email template, in the `.gitlab/service_desk_templates/` -directory in your repository, create a file named `new_note.md`. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344819) in GitLab 15.9. -You can use these placeholders to be automatically replaced in each email: +Instance administrators can add a header, footer or additional text to the GitLab instance and apply +them to all emails sent from GitLab. If you're using a custom `thank_you.md` or `new_note.md`, to include +this content, add `%{SYSTEM_HEADER}`, `%{SYSTEM_FOOTER}`, or `%{ADDITIONAL_TEXT}` to your templates. -- `%{ISSUE_ID}`: Issue IID. -- `%{ISSUE_PATH}`: Project path appended with the issue IID. -- `%{ISSUE_URL}`: URL to the issue. External participants can only view the issue if the project is public - and issue is not confidential (Service Desk issues are confidential by default). -- `%{ISSUE_DESCRIPTION}`: Issue description at the time email is generated. - If a user has edited the description, it might contain sensitive information that is not intended - to be delivered to external participants. Use this placeholder only if you never modify - descriptions or your team is aware of the template design. -- `%{NOTE_TEXT}`: Note text. -- `%{UNSUBSCRIBE_URL}`: Unsubscribe URL. -- `%{SYSTEM_HEADER}`: [System header message](../admin_area/appearance.md#system-header-and-footer-messages). -- `%{SYSTEM_FOOTER}`: [System footer message](../admin_area/appearance.md#system-header-and-footer-messages). -- `%{ADDITIONAL_TEXT}`: [Custom additional text](../admin_area/settings/email.md#custom-additional-text). +For more information, see [System header and footer messages](../../administration/appearance.md#system-header-and-footer-messages) and [custom additional text](../../administration/settings/email.md#custom-additional-text). -### Use a custom template for Service Desk issues +### Use a custom template for Service Desk tickets You can select one [description template](description_templates.md#create-an-issue-template) -**per project** to be appended to every new Service Desk issue's description. +**per project** to be appended to every new Service Desk ticket's description. You can set description templates at various levels: @@ -200,27 +192,26 @@ To edit the custom email display name: 1. Below **Email display name**, enter a new name. 1. Select **Save changes**. -### Use a custom email address **(FREE SELF)** +### Use an additional Service Desk alias email **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. -You can use a custom email address with Service Desk. +You can use an additional alias email address for Service Desk on an instance level. To do this, you must configure -a [custom mailbox](#configure-a-custom-mailbox). You can also configure a -[custom suffix](#configure-a-custom-email-address-suffix). +a [`service_desk_email`](#configure-service-desk-alias-email) in the instance configuration. You can also configure a +[custom suffix](#configure-a-suffix-for-service-desk-alias-email) that replaces the default `-issue-` portion on the sub-addressing part. -#### Configure a custom mailbox +#### Configure Service Desk alias email NOTE: -On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, you can still configure the -[custom suffix](#configure-a-custom-email-address-suffix) in project settings. +On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address. You can still configure the +[custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings. Service Desk uses the [incoming email](../../administration/incoming_email.md) -configuration by default. However, by using the `service_desk_email` configuration, -you can customize the mailbox used by Service Desk. This allows you to have -a separate email address for Service Desk by also configuring a [custom suffix](#configure-a-custom-email-address-suffix) +configuration by default. However, to have a separate email address for Service Desk, +configure `service_desk_email` with a [custom suffix](#configure-a-suffix-for-service-desk-alias-email) in project settings. Prerequisites: @@ -413,14 +404,19 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre ##### Microsoft Graph -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. > - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. +> - [Introduced for self-compiled (source) installs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116494) in GitLab 15.11. -Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft +`service_desk_email` can be configured to read Microsoft Exchange Online mailboxes with the Microsoft Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph [the same way as for incoming email](../../administration/incoming_email.md#microsoft-graph). -- Example for Linux package installations: +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, substituting + the values you want: ```ruby gitlab_rails['service_desk_email_enabled'] = true @@ -430,33 +426,200 @@ Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' gitlab_rails['service_desk_email_inbox_options'] = { - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), + configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: + + ```ruby + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional } ``` +:::TabTitle Helm chart (Kubernetes) + +1. Create the [Kubernetes Secret containing the OAuth 2.0 application client secret](https://docs.gitlab.com/charts/installation/secrets.html#microsoft-graph-client-secret-for-service-desk-emails): + + ```shell + kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET> + ``` + +1. Create the [Kubernetes Secret for the GitLab Service Desk email auth token](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-service-desk-email-auth-token). + Replace `<name>` with the name of the [Helm release name](https://helm.sh/docs/intro/using_helm/) for the GitLab installation: + + ```shell + kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64) + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + serviceDeskEmail: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: inbox + inboxMethod: microsoft_graph + azureAdEndpoint: https://login.microsoftonline.com + graphEndpoint: https://graph.microsoft.com + tenantId: "YOUR-TENANT-ID" + clientId: "YOUR-CLIENT-ID" + clientSecret: + secret: service-desk-email-client-secret + key: secret + deliveryMethod: webhook + authToken: + secret: <name>-service-desk-email-auth-token + key: authToken + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), +configure the `azureAdEndpoint` and `graphEndpoint` settings. These fields are case-sensitive: + + ```yaml + global: + appConfig: + serviceDeskEmail: + [..] + azureAdEndpoint: https://login.microsoftonline.us + graphEndpoint: https://graph.microsoft.us + [..] + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), -configure the `azure_ad_endpoint` and `graph_endpoint` settings. +configure the `azure_ad_endpoint` and `graph_endpoint` settings: -- Example for Microsoft Cloud for US Government: +1. Edit `docker-compose.yml`: -```ruby -gitlab_rails['service_desk_email_inbox_options'] = { - 'azure_ad_endpoint': 'https://login.microsoftonline.us', - 'graph_endpoint': 'https://graph.microsoft.us', - 'tenant_id': '<YOUR-TENANT-ID>', - 'client_id': '<YOUR-CLIENT-ID>', - 'client_secret': '<YOUR-CLIENT-SECRET>', - 'poll_interval': 60 # Optional -} -``` + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_enabled'] = true + gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com" + gitlab_rails['service_desk_email_email'] = "project_contact@example.onmicrosoft.com" + gitlab_rails['service_desk_email_mailbox_name'] = "inbox" + gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" + gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph' + gitlab_rails['service_desk_email_inbox_options'] = { + 'azure_ad_endpoint': 'https://login.microsoftonline.us', + 'graph_endpoint': 'https://graph.microsoft.us', + 'tenant_id': '<YOUR-TENANT-ID>', + 'client_id': '<YOUR-CLIENT-ID>', + 'client_secret': '<YOUR-CLIENT-SECRET>', + 'poll_interval': 60 # Optional + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) -The Microsoft Graph API is not yet supported in source installations. -For more information, see [issue 326169](https://gitlab.com/gitlab-org/gitlab/-/issues/326169). +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: "inbox" + delivery_method: webhook + log_path: "log/mailroom.log" + secret_file: .gitlab-mailroom-secret + inbox_method: "microsoft_graph" + inbox_options: + tenant_id: "<YOUR-TENANT-ID>" + client_id: "<YOUR-CLIENT-ID>" + client_secret: "<YOUR-CLIENT-SECRET>" + poll_interval: 60 # Optional + ``` + + For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), + configure the `azure_ad_endpoint` and `graph_endpoint` settings. For example: + + ```yaml + service_desk_email: + enabled: true + address: "project_contact+%{key}@example.onmicrosoft.com" + user: "project_contact@example.onmicrosoft.com" + mailbox: "inbox" + delivery_method: webhook + log_path: "log/mailroom.log" + secret_file: .gitlab-mailroom-secret + inbox_method: "microsoft_graph" + inbox_options: + azure_ad_endpoint: "https://login.microsoftonline.us" + graph_endpoint: "https://graph.microsoft.us" + tenant_id: "<YOUR-TENANT-ID>" + client_id: "<YOUR-CLIENT-ID>" + client_secret: "<YOUR-CLIENT-SECRET>" + poll_interval: 60 # Optional + ``` + +::EndTabs -#### Configure a custom email address suffix +#### Configure a suffix for Service Desk alias email You can set a custom suffix in your project's Service Desk settings. @@ -467,7 +630,7 @@ When configured, the custom suffix creates a new Service Desk email address, con Prerequisites: -- You must have configured a [custom mailbox](#configure-a-custom-mailbox). +- You must have configured a [Service Desk alias email](#configure-service-desk-alias-email). 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > General**. @@ -702,7 +865,7 @@ HTML emails show HTML formatting, such as: > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. 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 `service_desk_new_note_email_native_attachments`. +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. On GitLab.com, this feature is available. If a comment contains any attachments and their total size is less than or equal to 10 MB, these diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 6cc2b51f077..8330b8c14bc 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -79,7 +79,7 @@ For example: 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 +1. [Enable file exports](../../../administration/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. @@ -186,7 +186,7 @@ Items that are **not** exported include: - Links to related merge requests Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and -[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. +[instance](../../../administration/custom_project_templates.md) levels. Therefore, the list of exported items is the same. ## Import a project and its data @@ -243,7 +243,7 @@ If you have a larger project, consider [using a Rake task](../../../administrati Administrators can set the maximum import file size one of two ways: - With the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings). -- In the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md#max-import-size). +- In the [Admin Area UI](../../../administration/settings/account_and_limit_settings.md#max-import-size). The default is `0` (unlimited). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 8deb05c45ef..4a7e7d2fe7d 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -41,26 +41,16 @@ To assign topics to a project: 1. Select **Save changes**. 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). +[Admin Area's Topics page](../../../administration/admin_area.md#administering-topics). -## Add a compliance framework to a project **(PREMIUM)** - -[Compliance frameworks](../../group/compliance_frameworks.md) can be assigned to projects within group that has a -compliance framework using either: +NOTE: +The assigned topics are visible only to users 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. -- The GitLab UI: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Settings** > **General**. - 1. Expand **Compliance frameworks**. - 1. Select a compliance framework. - 1. Select **Save changes**. -- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) and later, using the - [GraphQL API](../../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework). If you create - compliance frameworks on subgroups with GraphQL, the framework is created on the root ancestor if the user has the - correct permissions. The GitLab UI presents a read-only view to discourage this behavior. +## Add a compliance framework to a project **(PREMIUM)** -NOTE: -Frameworks can not be added to projects in personal namespaces. +You can +[add compliance frameworks to projects](../../group/compliance_frameworks.md#add-a-compliance-framework-to-a-project) +in a group that has a compliance framework. ## Configure project visibility, features, and permissions @@ -94,7 +84,6 @@ Use the toggles to enable or disable features in the project. | **Wiki** | **{check-circle}** Yes | Enables a separate system for [documentation](../wiki/index.md). | **Snippets** | **{check-circle}** Yes | Enables [sharing of code and text](../../snippets.md). | **Pages** | **{check-circle}** Yes | Allows you to [publish static websites](../pages/index.md). -| **Metrics Dashboard** | **{check-circle}** Yes | Control access to [metrics dashboard](../integrations/prometheus.md). | **Releases** | **{check-circle}** Yes | Control access to [Releases](../releases/index.md). | **Environments** | **{check-circle}** Yes | Control access to [Environments and Deployments](../../../ci/environments/index.md). | **Feature flags** | **{check-circle}** Yes | Control access to [Feature flags](../../../operations/feature_flags.md). @@ -125,6 +114,23 @@ When you disable a feature, the following additional features are also disabled: - Metrics dashboard access requires reading project environments and deployments. Users with access to the metrics dashboard can also access environments and deployments. +### Manage project access through LDAP groups + +You can [use LDAP to manage group membership](../../group/access_and_permissions.md#manage-group-memberships-via-ldap). + +You cannot use LDAP groups to manage project access, but you can use the following +workaround. + +Prerequisites: + +- You must [integrate LDAP with GitLab](../../../administration/auth/ldap/index.md). +- You must be an administrator. + +1. [Create a group](../../group/index.md#create-a-group) to track membership of your project. +1. [Set up LDAP synchronization](../../../administration/auth/ldap/ldap_synchronization.md) for that group. +1. To use LDAP groups to manage access to a project, [add the LDAP-synchronized group as a member](../members/index.md#add-groups-to-a-project) + to the project. + ## Disable CVE identifier request in issues **(FREE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. @@ -272,7 +278,7 @@ To transfer a project: You are redirected to the project's new page and GitLab applies a redirect. For more information about repository redirects, see [What happens when a repository path changes](../repository/index.md#what-happens-when-a-repository-path-changes). NOTE: -If you are an administrator, you can also use the [administration interface](../../admin_area/index.md#administering-projects) +If you are an administrator, you can also use the [administration interface](../../../administration/admin_area.md#administering-projects) to move any project to any namespace. ### Transferring a GitLab SaaS project to a different subscription tier @@ -302,7 +308,7 @@ To delete a project: 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Delete this project** section, select **Delete project**. -1. In the confirmation message text field, enter the name of the project as instructed, and select **Yes, delete project**. +1. On the confirmation dialog, enter the project name and select **Yes, delete project**. This action deletes the project and all associated resources (such as issues and merge requests). @@ -338,7 +344,7 @@ To immediately delete a project marked for deletion: 1. Select **Settings > General**. 1. Expand **Advanced**. 1. In the **Delete this project** section, select **Delete project**. -1. In the confirmation message text field, enter the name of the project as instructed, as select **Yes, delete project**. +1. On the confirmation dialog, enter the project name and select **Yes, delete project**. ## Restore a project **(PREMIUM)** diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 7fd8fdf3a00..f4652d592f0 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -26,7 +26,7 @@ Use a project access token to authenticate: Project access tokens are similar to [group access tokens](../../group/settings/group_access_tokens.md) and [personal access tokens](../../profile/personal_access_tokens.md). -In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. +In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. WARNING: The ability to create project access tokens without expiry was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369122) in GitLab 15.4 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/392855) in GitLab 16.0. In GitLab 16.0 and later, existing project access tokens without an expiry date are automatically given an expiry date of 365 days later than the current date. The automatic adding of an expiry date occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry date occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change. @@ -39,7 +39,7 @@ You can use project access tokens: You cannot use project access tokens to create other group, project, or personal access tokens. -Project access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) +Project access tokens inherit the [default prefix setting](../../../administration/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. ## Create a project access token @@ -62,7 +62,7 @@ To create a project access token: - The token expires on that date at midnight UTC. - If you do not enter an expiry date, the expiry date is automatically set to 365 days later than the current date. - By default, this date can be a maximum of 365 days later than the current date. - - An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. + - An instance-wide [maximum lifetime](../../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-project-access-token). 1. Select **Create project access token**. @@ -81,14 +81,15 @@ To revoke a project access token: The scope determines the actions you can perform when you authenticate with a project access token. -| Scope | Description | -|:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `api` | Grants complete read and write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | +| Scope | Description | +|:-------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_registry` | Grants read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | | `write_registry` | Grants write access (push) to the [Container Registry](../../packages/container_registry/index.md). | -| `read_repository` | Grants read access (pull) to the repository. | -| `write_repository` | Grants read and write access (pull and push) to the repository. | +| `read_repository` | Grants read access (pull) to the repository. | +| `write_repository` | Grants read and write access (pull and push) to the repository. | +| `create_runner` | Grants permission to create runners in the project. | ## Enable or disable project access token creation diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 481eca5a890..45abcd867c0 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/115741) in GitLab 15.11. 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 `vscode_web_ide`. On GitLab.com, this feature is available. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. The Web IDE is an advanced editor with commit staging. You can use the Web IDE to make changes to multiple files directly from the GitLab UI. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 2271c33b5b4..41fd7e81db5 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -14,7 +14,6 @@ to ensure all group members have the correct access permissions to contribute. Group wikis are similar to [project wikis](index.md), with a few limitations: - [Git LFS](../../../topics/git/lfs/index.md) is not supported. -- Group wikis are not included in [global search](../../search/advanced_search.md). - Changes to group wikis don't show up in the [group's activity feed](../../group/manage.md#group-activity-analytics). For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 0d3782cfd09..4a53faeee73 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -37,7 +37,7 @@ To access a project wiki: - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> [wiki keyboard shortcut](../../shortcuts.md). -If **Wiki** is not listed in the left sidebar of your project, a project administrator +If **Plan > Wiki** is not listed in the left sidebar of your project, a project administrator has [disabled it](#enable-or-disable-a-project-wiki). ## Configure a default branch for your wiki @@ -310,11 +310,12 @@ Previously added wiki pages are preserved in case you want to re-enable the wiki. To re-enable it, repeat the process to disable the wiki but toggle it on (in blue). -## Content Editor +## Rich text editor > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345398) switching between editing experiences in GitLab 14.7 [with a flag](../../../administration/feature_flags.md) named `wiki_switch_between_content_editor_raw_markdown`. Enabled by default. > - Switching between editing experiences generally available in GitLab 14.10. [Feature flag `wiki_switch_between_content_editor_raw_markdown`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83760) removed. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/398152) from content editor to rich text editor in GitLab 16.2. GitLab provides a WYSIWYG editing experience for GitLab Flavored Markdown in wikis. @@ -327,12 +328,12 @@ Support includes: - Previewing Mermaid, PlantUML, and Kroki diagrams ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86701) in GitLab 15.2). - Creating and editing HTML comments ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104084) in GitLab 15.7). -### Use the Content Editor +### Use the rich text editor 1. [Create](#create-a-new-wiki-page) a new wiki page, or [edit](#edit-a-wiki-page) an existing one. 1. Select **Markdown** as your format. 1. Above **Content**, select **Edit rich text**. -1. Customize your page's content using the various formatting options available in the content editor. +1. Customize your page's content using the various formatting options available in the rich text editor. 1. Select **Create page** for a new page, or **Save changes** for an existing page. The rich text editing mode remains the default until you switch back to @@ -340,12 +341,12 @@ The rich text editing mode remains the default until you switch back to ### Switch back to the old editor -1. *If you're editing the page in the content editor,* scroll to **Content**. +1. *If you're editing the page in the rich text editor,* scroll to **Content**. 1. Select **Edit source**. ### GitLab Flavored Markdown support -Supporting all GitLab Flavored Markdown content types in the Content Editor is a work in progress. +Supporting all GitLab Flavored Markdown content types in the rich text editor is a work in progress. For the status of the ongoing development for CommonMark and GitLab Flavored Markdown support, read: - [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 5bd7c12ed31..472bbb81648 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -9,42 +9,62 @@ info: "To determine the technical writer assigned to the Stage/Group associated Most work in GitLab is done in a [project](../../user/project/index.md). Files and code are saved in projects, and most features are in the scope of projects. -## View projects +## View all projects for the instance -To view all your projects: +To view all projects for the GitLab instance: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. +1. Select **Explore**. + +On the left sidebar, **Projects** is selected. On the right, the list shows +all projects for the instance. + +If you are not authenticated, then the list shows public projects only. + +## View projects you are a member of -To browse all projects you can access: +To view projects you are a member of: 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **Explore**. +1. Select **Your work**. -### Who can view the Projects page +On the left sidebar, **Projects** is selected. On the list, on the **Yours** tab, +all the projects you are a member of are displayed. -When you select a project, the project landing page shows the project contents. +## View personal projects -For public projects, and members of internal and private projects -with [permissions to view the project's code](../permissions.md#project-members-permissions), -the project landing page shows: +Personal projects are projects created under your personal namespace. -- A [`README` or index file](repository/index.md#readme-and-index-files). -- A list of directories in the project's repository. +For example, if you create an account with the username `alex`, and create a project +called `my-project` under your username, the project is created at `https://gitlab.example.com/alex/my-project`. -For users without permission to view the project's code, the landing page shows: +To view your personal projects: -- The wiki homepage. -- The list of issues in the project. +1. On the left sidebar, select your avatar and then your username. +1. On the left sidebar, select **Personal projects**. + +## View starred projects -### Access a project page with the project ID +To view projects you have [starred](#star-a-project): -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. +1. On the left sidebar, select your avatar and then your username. +1. On the left sidebar, select **Starred projects**. + +## Organizing projects with topics + +Topics are labels that you can assign to projects to help you organize and find them. +A topic is typically a short name that describes the content or purpose of a project. +You can assign a topic to several projects. + +For example, you can create and assign the topics `python` and `hackathon` to all projects that use Python and are intended for Hackathon contributions. -To access a project from the GitLab UI using the project ID, -visit the `/projects/:id` URL in your browser or other tool accessing the project. +Topics assigned to a project are listed in the **Project overview**, below the project name and activity information. -## Explore topics +Only users with access to the project can see the topics assigned to that project, +but everyone (including unauthenticated users) can see the topics available on the GitLab instance. +Do not include sensitive information in the name of a topic. + +### Explore topics To explore project topics: @@ -53,47 +73,67 @@ To explore project topics: 1. On the left sidebar, select **Topics**. 1. To view projects associated with a topic, select a topic. -The **Explore topics** page shows a list of topics, sorted by the number of associated projects. +The **Explore topics** page shows a list of projects with this topic. -You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). +### Filter and sort topics -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). +You can filter the list of projects that have a certain topic by: -## Star a project +- Name +- Language +- Owner +- Archive status +- Visibility -You can add a star to projects you use frequently to make them easier to find. +You can sort the projects by: -To add a star to a project: +- Date created +- Date updated +- Name +- Number of stars -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. In the upper-right corner of the page, select **Star**. +### Subscribe to a topic -## View starred projects +If you want to know when new projects are added to a topic, you can use its RSS feed. -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. -1. Select the **Starred** tab. -1. GitLab displays information about your starred projects, including: +You can do this either from the **Explore topics** page or a project with topics. - - Project description, including name, description, and icon. - - Number of times this project has been starred. - - Number of times this project has been forked. - - Number of open merge requests. - - Number of open issues. +To subscribe to a topic: -## View personal projects +- From the **Explore topics** page: -Personal projects are projects created under your personal namespace. + 1. On the left sidebar, expand the top-most chevron ({**chevron-down**}). + 1. Select **Explore**. + 1. Select **Topics**. + 1. Select the topic you want to subscribe to. + 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). -For example, if you create an account with the username `alex`, and create a project -called `my-project` under your username, the project is created at `https://gitlab.example.com/alex/my-project`. +- From a project: -To view your personal projects: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. In the **Project overview** page, from the **Topics** list select the topic you want to subscribe to. + 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). -1. Select **View all your projects**. -1. In the **Yours** tab, select **Personal**. +The results are displayed as an RSS feed in Atom format. +The URL of the result contains a feed token and the list of projects that have the topic. You can add this URL to your feed reader. + +### Assign a topic to a project + +You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). + +### Administer topics + +Instance administrators can administer all project topics from the +[Admin Area's Topics page](../../administration/admin_area.md#administering-topics). + +## Star a project + +You can add a star to projects you use frequently to make them easier to find. + +To add a star to a project: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. In the upper-right corner of the page, select **Star**. ## Delete a project @@ -188,6 +228,34 @@ Prerequisite: 1. Use the toggle by each feature you want to turn on or off, or change access for. 1. Select **Save changes**. +## Access the Project overview page by using the project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. + +To access a project by using the project ID instead of its name, +go to `https://gitlab.example.com/projects/:id`. + +The project ID is displayed in the **Project overview** page, under the project name. + +For example, if in your personal namespace `alex` you have a project `my-project` with the ID `123456`, you can access the project +either at `https://gitlab.example.com/alex/my-project` or `https://gitlab.example.com/projects/123456`. + +## Who can view the Project overview page + +When you select a project, the **Project overview** page shows the project contents. + +For public projects, and members of internal and private projects +with [permissions to view the project's code](../permissions.md#project-members-permissions), +the project landing page shows: + +- A [`README` or index file](repository/index.md#readme-and-index-files). +- A list of directories in the project's repository. + +For users without permission to view the project's code, the landing page shows: + +- The wiki homepage. +- The list of issues in the project. + ## Leave a project When you leave a project: diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 002cb97dd93..57439a4595e 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -7,18 +7,24 @@ type: reference # Project and group visibility **(FREE)** -A project in GitLab can be private, internal, or public. +Projects and groups in GitLab can be private, internal, or public. + +The visibility level of the group or project has no influence on whether members within the group or project can see each other. +A group or project is an object to allow collaborative work. This is only possible if all members know about each other. + +Group or project members can see all members of the group or project they belong to. +Group or project owners can see the origin of membership (the original group or project) of all members. ## Private projects and groups -For private projects, only project members can: +For private projects, only members of the private project or group can: - Clone the project. - View the public access directory (`/public`). Users with the Guest role cannot clone the project. -Private groups can have private subgroups only. +Private groups can have only private subgroups. ## Internal projects and groups **(FREE SELF)** @@ -27,6 +33,8 @@ For internal projects, **any authenticated user**, including users with the Gues - Clone the project. - View the public access directory (`/public`). +Only internal members can view internal content. + [External users](admin_area/external_users.md) cannot clone the project. Internal groups can have internal or private subgroups. @@ -48,7 +56,7 @@ Public groups can have public, internal, or private subgroups. NOTE: If an administrator restricts the -[**Public** visibility level](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels), +[**Public** visibility level](../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels), then `/public` is visible only to authenticated users. ## Change project visibility @@ -91,7 +99,7 @@ Prerequisites: Administrators can restrict which visibility levels users can choose when they create a project or a snippet. This setting can help prevent users from publicly exposing their repositories by accident. -For more information, see [Restrict visibility levels](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels). +For more information, see [Restrict visibility levels](../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). ## Related topics diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index c4b9af28220..23a662ccfeb 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can report abuse from other GitLab users to GitLab administrators. -A GitLab administrator [can then choose](admin_area/review_abuse_reports.md) to: +A GitLab administrator [can then choose](../administration/review_abuse_reports.md) to: - Remove the user, which deletes them from the instance. - Block the user, which denies them access to the instance. @@ -66,4 +66,4 @@ A URL to the reported user's comment is pre-filled in the abuse report's ## Related topics -- [Abuse reports administration documentation](admin_area/review_abuse_reports.md) +- [Abuse reports administration documentation](../administration/review_abuse_reports.md) diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 6e8a7e7c1cf..bc9de9357f6 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -20,7 +20,7 @@ under the `TOP_LEVEL_ROUTES`, `PROJECT_WILDCARD_ROUTES` and `GROUP_ROUTES` lists ## Limitations on project and group names - Project or group names must start with a letter, digit, emoji, or "_". -- Project or group names can only contain letters, digits, emojis, "_", ".", "+", dashes, or spaces. +- Project or group names can only contain letters, digits, emoji, "_", ".", "+", dashes, or spaces. - Project or group slugs must start with a letter or digit. - Project or group slugs can only contain letters, digits, '_', '.', '+', or dashes. - Project or group slugs must not contain consecutive special characters. diff --git a/doc/user/rich_text_editor.md b/doc/user/rich_text_editor.md new file mode 100644 index 00000000000..ea85dfdbcb4 --- /dev/null +++ b/doc/user/rich_text_editor.md @@ -0,0 +1,134 @@ +--- +stage: Plan +group: Knowledge +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: index, reference +--- + +# Rich text editor **(FREE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) for [wikis](project/wiki/index.md#rich-text-editor) in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371931) for editing issue descriptions in GitLab 15.5 [with a flag](../administration/feature_flags.md) named `content_editor_on_issues`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382636) for [discussions](discussions/index.md), and creating and editing issues and merge requests in GitLab 15.11 with the same flag. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407507) for epics in GitLab 16.1 with the same flag. +> - Feature flag `content_editor_on_issues` enabled by default in GitLab 16.2. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator +can [disable the feature flag](../administration/feature_flags.md) named `content_editor_on_issues`. +On GitLab.com, this feature is available. + +The rich text editor is a "what you see is what you get" (WYSIWYG) editor so you can use +[GitLab Flavored Markdown](markdown.md) in descriptions and comments, even if you can't remember all +of its syntax. + + + +Rich text editor is available in: + +- [Wikis](project/wiki/index.md) +- Issues +- Epics +- Merge requests +- [Designs](project/issues/design_management.md) + +Features of the editor include: + +- Format text, including as bold, italics, block quotes, headings, and inline code. +- Format ordered lists, unordered lists, and checklists. +- Insert links, attachments, images, video, and audio. +- Create and edit a table structure. +- Insert and format code blocks with syntax highlighting. +- Preview Mermaid, PlantUML, and Kroki diagrams in real time. + +To track work on adding the rich text editor to more places across GitLab, see +[epic 7098](https://gitlab.com/groups/gitlab-org/-/epics/7098). + +## Switch to the rich text editor + +Use the rich text editor to edit descriptions, wiki pages, add comments. + +To switch to the rich text editor: In a text box, in the lower-left corner, select +**Switch to rich text editing**. + +## Switch to the plain text editor + +If you want to enter Markdown source in the text box, return to using the plain text editor. + +To switch to the plain text editor: In a text box, in the lower-left corner, select +**Switch to plain text editing**. + +## Compatibility with GitLab Flavored Markdown + +The rich text editor is fully compatible with [GitLab Flavored Markdown](markdown.md). +It means that you can switch between plain text and rich text modes without losing any data. + +### Input rules + +Rich text editor also supports input rules that let you work with rich content as if you were +typing Markdown. + +Supported input rules: + +| Input rule syntax | Content inserted | +| --------------------------------------------------------- | -------------------- | +| `# Heading 1` <br>... <br> `###### Heading 6` | Headings 1 through 6 | +| `**bold**` or `__bold__` | Bold text | +| `_italics_` or `*italics*` | Italicized text | +| `~~strike~~` | Strikethrough | +| `[link](url)` | Hyperlink | +| `code` | Inline code | +| <code>```rb</code> + <kbd>Enter</kbd> <br> <code>```js</code> + <kbd>Enter</kbd> | Code block | +| `* List item`, or<br> `- List item`, or<br> `+ List item` | Unordered list | +| `1. List item` | Numbered list | +| `<details>` | Collapsible section | + +## Tables + +Unlike in raw Markdown, you can use the rich text editor to insert block content paragraphs, +list items, diagrams (or even another table!) in table cells. + +### Insert a table + +To insert a table: + +1. Select **Insert table** **{table}**. +1. From the dropdown list, select the dimensions of the new table. + + + +### Edit a table + +Inside a table cell, you can use a menu to insert or delete rows or columns. + +To open the menu: In the upper-right corner of a cell, select the chevron **{chevron-down}**. + + + +### Operations on multiple cells + +Select multiple cells and merge or split them. + +To merge selected cells into one: + +1. Select multiple cells - select one and drag your cursor. +1. In the upper-right corner of a cell, select the chevron **{chevron-down}** **> Merge N cells**. + +To split merged cells: In the upper-right corner of a cell, select the chevron **{chevron-down}** **> Split cell**. + +## Insert diagrams + +Insert [Mermaid](https://mermaidjs.github.io/) and [PlantUML](https://plantuml.com/) diagrams and +preview them live as you type the diagram code. + +To insert a diagram: + +1. On the top bar of a text box, select **{plus}** **More options** and then **Mermaid diagram** or **PlantUML diagram**. +1. Enter the code for your diagram. The diagram preview appears in the text box. + + + +## Related topics + +- [Keyboard shortcuts](shortcuts.md#rich-text-editor) for rich text editor +- [GitLab Flavored Markdown](markdown.md) diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 1444e5385f9..5a9f75f1d6c 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -27,7 +27,7 @@ You can use advanced search in: - Code - Comments - Commits -- Project wikis (not [group wikis](../project/wiki/group.md)) +- Project and group wikis ## Enable advanced search diff --git a/doc/user/search/command_palette.md b/doc/user/search/command_palette.md new file mode 100644 index 00000000000..ab284bd6a5f --- /dev/null +++ b/doc/user/search/command_palette.md @@ -0,0 +1,30 @@ +--- +stage: Manage +group: Foundations +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 +--- + +# Command palette **(FREE)** + +> Introduced in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `command_palette`. Enabled by default. + +You can use command palette to narrow down the scope of your search or to +find an object more quickly. + +FLAG: +On self-managed GitLab, by default this feature is available. +To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `command_palette`. +On GitLab.com, this feature is available. + +## Open the command palette + +To open the command palette: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) or use the <kbd>/</kbd> key to enable. +1. Type one of the special characters: + + - <kbd>></kbd> - Create a new object or find a menu item. + - <kbd>@</kbd> - Search for a user. + - <kbd>:</kbd> - Search for a project. + - <kbd>/</kbd> - Search for project files in the default repository branch. diff --git a/doc/user/search/img/code_search_git_blame_v15_1.png b/doc/user/search/img/code_search_git_blame_v15_1.png Binary files differdeleted file mode 100644 index 426f829b186..00000000000 --- a/doc/user/search/img/code_search_git_blame_v15_1.png +++ /dev/null diff --git a/doc/user/search/img/project_search_general_settings_v13_8.png b/doc/user/search/img/project_search_general_settings_v13_8.png Binary files differdeleted file mode 100644 index 08395e0d4f9..00000000000 --- a/doc/user/search/img/project_search_general_settings_v13_8.png +++ /dev/null diff --git a/doc/user/search/img/project_search_sha_redirect.png b/doc/user/search/img/project_search_sha_redirect.png Binary files differdeleted file mode 100644 index 718a859d4af..00000000000 --- a/doc/user/search/img/project_search_sha_redirect.png +++ /dev/null diff --git a/doc/user/search/img/search_navbar_v15_7.png b/doc/user/search/img/search_navbar_v15_7.png Binary files differdeleted file mode 100644 index 775c7f32b37..00000000000 --- a/doc/user/search/img/search_navbar_v15_7.png +++ /dev/null diff --git a/doc/user/search/img/search_scope_v15_7.png b/doc/user/search/img/search_scope_v15_7.png Binary files differdeleted file mode 100644 index 96f6e985523..00000000000 --- a/doc/user/search/img/search_scope_v15_7.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 2278da9a714..fe5ee3a5e0a 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Searching in GitLab **(FREE)** -GitLab has two types of searches available: _basic_ and _advanced_. +GitLab has two types of searches available: **basic** and **advanced**. Both types of search are the same, except when you are searching through code. @@ -27,16 +27,15 @@ can limit the search scope by disabling the following [`ops` feature flags](../. | Issues | `global_search_issues_tab` | When enabled, global search includes issues. | | Merge requests | `global_search_merge_requests_tab` | When enabled, global search includes merge requests. | | Users | `global_search_users_tab` | When enabled, global search includes users. | -| Wiki | `global_search_wiki_tab` | When enabled, global search includes project wikis (not [group wikis](../project/wiki/group.md)). | +| Wiki | `global_search_wiki_tab` | When enabled, global search includes project and [group wikis](../project/wiki/group.md). | -All global search scopes are enabled by default on GitLab.com -and self-managed instances. +All global search scopes are enabled by default on self-managed instances. ## Global search validation Global search ignores and logs as abusive any search with: -- Fewer than 2 characters +- Fewer than two characters - A term longer than 100 characters (URL search terms must not exceed 200 characters) - A stop word only (for example, `the`, `and`, or `if`) - An unknown `scope` @@ -48,29 +47,36 @@ Global search only flags with an error any search that includes more than: - 4096 characters - 64 terms -## Perform a search +## Search in all GitLab -To start a search, in the upper-right corner of the screen, in the search bar, type your search query. -You must type at least two characters. +To search in all GitLab: - +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**). +1. Type your search query. You must type at least two characters. +1. Press <kbd>Enter</kbd> to search, or select from the list. -After the results are displayed, you can modify the search, select a different type of data to -search, or choose a specific group or project. +The results are displayed. To filter the results, on the left sidebar, select a filter. - +## Search in a project -## Search in code +To search in a project: -To search through code or other documents in a project: +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Search GitLab** (**{search}**) again and type the string you want to search for. +1. Press <kbd>Enter</kbd> to search, or select from the list. + +The results are displayed. To filter the results, on the left sidebar, select a filter. + +## Search for code + +To search for code in a project: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and type the string you want to search for. -1. Press **Enter**. +1. Select **Search GitLab** (**{search}**) again and type the code you want to search for. +1. Press <kbd>Enter</kbd> to search, or select from the list. Code search shows only the first result in the file. - -To search across all of GitLab, ask your administrator to enable [advanced search](advanced_search.md). +To search for code in all GitLab, ask your administrator to enable [advanced search](advanced_search.md). ### View Git blame from code search @@ -82,8 +88,6 @@ where the results were found. 1. From the code search result, hover over the line number. 1. On the left, select **View blame**. - - ### Filter code search results by language > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342651) in GitLab 15.10. @@ -93,87 +97,89 @@ To filter code search results by one or more languages: 1. On the code search page, on the left sidebar, select one or more languages. 1. On the left sidebar, select **Apply**. -## Search for projects by full path +## Exclude search results -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed. +### From archived projects -You can search for a project by entering its full path (including the namespace it belongs to) in the search box. -As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121981) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `search_projects_hide_archived`. Disabled by default. -For example, the search query: +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +an administrator can [enable the feature flag](../../administration/feature_flags.md) named `search_projects_hide_archived`. On GitLab.com, this feature is not available. -- `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. -- `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. +Archived projects are included in search results by default. To exclude archived projects, ensure the `search_projects_hide_archived` flag is enabled. -### Exclude archived projects from project search results +To include archived projects with `search_projects_hide_archived` enabled, you must add the parameter `include_archived=true` to the URL. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121981) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `search_projects_hide_archived`. Disabled by default. +### From issues in archived projects + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124846) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `search_issues_hide_archived_projects`. 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 `search_projects_hide_archived`. On GitLab.com, this feature is not available. +an administrator can [enable the feature flag](../../administration/feature_flags.md) named `search_issues_hide_archived_projects`. On GitLab.com, this feature is not available. -Archived projects are included in project search results by default. To exclude archived projects, ensure the `search_projects_hide_archived` flag is enabled. +Issues in archived projects are included in search results by default. To exclude issues in archived projects, ensure the `search_issues_hide_archived_projects` flag is enabled. -To include archived projects with `search_projects_hide_archived` enabled, you must add the parameter `include_archived=true` to the URL. +To include issues in archived projects with `search_issues_hide_archived_projects` enabled, you must add the parameter `include_archived=true` to the URL. -## Search for a SHA +## Search for a project by full path -You can search for a commit SHA. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed. + +You can search for a project by entering its full path (including the namespace it belongs to) in the search box. +As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. + +For example: + +- `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. +- `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. + +## Search for a commit SHA + +To search for a commit SHA: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) and type the SHA. +1. Select **Search GitLab** (**{search}**) again and type the commit SHA you want to search for. +1. Press <kbd>Enter</kbd> to search, or select from the list. If a single result is returned, GitLab redirects to the commit result and gives you the option to return to the search results page. - +## Search for specific terms -## Searching for specific terms - -> - [Removed support for partial matches in issue searches](https://gitlab.com/gitlab-org/gitlab/-/issues/273784) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `issues_full_text_search`. Disabled by default. -> - Feature flag [`issues_full_text_search` enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/273784) in GitLab 14.10. -> - Feature flag [`issues_full_text_search` enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/273784) in GitLab 15.2. +> - [Support for partial matches in issue search](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71913) removed in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `issues_full_text_search`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124703) in GitLab 16.2. Feature flag `issues_full_text_search` removed. You can filter issues and merge requests by specific terms included in titles or descriptions. - Syntax - Searches look for all the words in a query, in any order. For example: searching issues for `display bug` returns all issues matching both those words, in any order. - - To find the exact term, use double quotes: `"display bug"` + - To find the exact term, use double quotes: `"display bug"`. - Limitation - - For performance reasons, terms shorter than 3 chars are ignored. For example: searching + - For performance reasons, terms shorter than three characters are ignored. For example: searching issues for `included in titles` is same as `included titles` - Search is limited to 4096 characters and 64 terms per query. - When searching issues, partial matches are not allowed. For example: searching for `play` will not return issues that have the word `display`. But variations of words match, so searching for `displays` also returns issues that have the word `display`. -## Retrieve search results as feed - -> Feeds for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66336) in GitLab 14.3. - -GitLab provides RSS feeds of search results for your project. To subscribe to the -RSS feed of search results: +## Run a search from history -1. Go to your project's page. -1. On the left sidebar, select **Issues** or **Merge requests**. -1. Perform a search. -1. Select the feed symbol **{rss}** to display the results as an RSS feed in Atom format. - -The URL of the result contains both a feed token, and your search query. -You can add this URL to your feed reader. +You can run a search from history for issues and merge requests. Search history is stored locally +in your browser. To run a search from history: -## Search history +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. To view recent searches: -Search history is available for issues and merge requests, and is stored locally -in your browser. To run a search from history: + - For issues, on the left sidebar, select **Plan > Issues**. Above the list, to the left of the search box, select (**{history}**). + - For merge requests, on the left sidebar, select **Code > Merge requests**. Above the list, to the left of the search box, select **Recent searches**. -1. In the top menu, select **Issues** or **Merge requests**. -1. To the left of the search bar, select **Recent searches**, and select a search from the list. +1. From the dropdown list, select a search. -## Removing search filters +## Remove search filters Individual filters can be removed by selecting the filter's (x) button or backspacing. The entire search filter can be cleared by selecting the search box's (x) button or via <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd>. @@ -181,9 +187,9 @@ To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</ ## Autocomplete suggestions -In the search bar, you can view autocomplete suggestions for: +In the search box, you can view autocomplete suggestions for: -- [Projects](#search-for-projects-by-full-path) and groups +- [Projects](#search-for-a-project-by-full-path) and groups - Users - Various help pages (try and type **API help**) - Project feature pages (try and type **milestones**) @@ -195,13 +201,6 @@ In the search bar, you can view autocomplete suggestions for: ## Search settings -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8 [with a flag](../../administration/feature_flags.md) named `search_settings_in_page`. Disabled by default. -> - [Added](https://gitlab.com/groups/gitlab-org/-/epics/4842) to Group, Administrator, and User settings in GitLab 13.9. -> - [Feature flag `search_settings_in_page` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. - You can search inside a Project, Group, Administrator, or User's settings by entering a search term in the search box located at the top of the page. The search results appear highlighted in the sections that match the search term. - - diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index e195be5586a..ac3c6bace09 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -68,24 +68,24 @@ relatively quickly to work, and they take you to another page in the project. | Keyboard shortcut | Description | |-----------------------------|-------------| -| <kbd>g</kbd> + <kbd>o</kbd> | Go to the project overview page (**Project > Details**). | -| <kbd>g</kbd> + <kbd>v</kbd> | Go to the project activity feed (**Project > Activity**). | -| <kbd>g</kbd> + <kbd>r</kbd> | Go to the project releases list (**Project > Releases**). | -| <kbd>g</kbd> + <kbd>f</kbd> | Go to the [project files](#project-files) list (**Repository > Files**). | -| <kbd>t</kbd> | Go to the project file search page. (**Repository > Files**, select **Find Files**). | -| <kbd>g</kbd> + <kbd>c</kbd> | Go to the project commits list (**Repository > Commits**). | -| <kbd>g</kbd> + <kbd>n</kbd> | Go to the [repository graph](#repository-graph) page (**Repository > Graph**). | -| <kbd>g</kbd> + <kbd>d</kbd> | Go to repository charts (**Analytics > Repository Analytics**). | -| <kbd>g</kbd> + <kbd>i</kbd> | Go to the project issues list (**Issues > List**). | -| <kbd>i</kbd> | Go to the New Issue page (**Issues**, select **New Issue** ). | -| <kbd>g</kbd> + <kbd>b</kbd> | Go to the project issue boards list (**Issues > Boards**). | -| <kbd>g</kbd> + <kbd>m</kbd> | Go to the project [merge requests](project/merge_requests/index.md) list (**Merge Requests**). | -| <kbd>g</kbd> + <kbd>p</kbd> | Go to the CI/CD pipelines list (**CI/CD > Pipelines**). | -| <kbd>g</kbd> + <kbd>j</kbd> | Go to the CI/CD jobs list (**CI/CD > Jobs**). | -| <kbd>g</kbd> + <kbd>e</kbd> | Go to the project environments (**Deployments > Environments**). | -| <kbd>g</kbd> + <kbd>k</kbd> | Go to the project Kubernetes cluster integration page (**Infrastructure > Kubernetes clusters**). You must have at least [`maintainer` permissions](permissions.md) to access this page. | -| <kbd>g</kbd> + <kbd>s</kbd> | Go to the project snippets list (**Snippets**). | -| <kbd>g</kbd> + <kbd>w</kbd> | Go to the [project wiki](project/wiki/index.md) (**Wiki**), if enabled. | +| <kbd>g</kbd> + <kbd>o</kbd> | Go to the project overview page (**Project overview**). | +| <kbd>g</kbd> + <kbd>v</kbd> | Go to the project activity feed (**Manage > Activity**). | +| <kbd>g</kbd> + <kbd>r</kbd> | Go to the project releases list (**Deploy > Releases**). | +| <kbd>g</kbd> + <kbd>f</kbd> | Go to the [project files](#project-files) list (**Code > Repository**). | +| <kbd>t</kbd> | Go to the project file search page. (**Code > Repository**, select **Find Files**). | +| <kbd>g</kbd> + <kbd>c</kbd> | Go to the project commits list (**Code > Commits**). | +| <kbd>g</kbd> + <kbd>n</kbd> | Go to the [repository graph](#repository-graph) page (**Code > Repository graph**). | +| <kbd>g</kbd> + <kbd>d</kbd> | Go to repository charts (**Analyze > Repository analytics**). | +| <kbd>g</kbd> + <kbd>i</kbd> | Go to the project issues list (**Plan > Issues**). | +| <kbd>i</kbd> | Go to the New Issue page (**Pan > Issues**, select **New issue** ). | +| <kbd>g</kbd> + <kbd>b</kbd> | Go to the project issue boards list (**Plan > Issue boards**). | +| <kbd>g</kbd> + <kbd>m</kbd> | Go to the project [merge requests](project/merge_requests/index.md) list (**Code > Merge requests**). | +| <kbd>g</kbd> + <kbd>p</kbd> | Go to the CI/CD pipelines list (**Build > Pipelines**). | +| <kbd>g</kbd> + <kbd>j</kbd> | Go to the CI/CD jobs list (**Build > Jobs**). | +| <kbd>g</kbd> + <kbd>e</kbd> | Go to the project environments (**Operate > Environments**). | +| <kbd>g</kbd> + <kbd>k</kbd> | Go to the project Kubernetes cluster integration page (**Operate > Kubernetes clusters**). You must have at least [`maintainer` permissions](permissions.md) to access this page. | +| <kbd>g</kbd> + <kbd>s</kbd> | Go to the project snippets list (**Code > Snippets**). | +| <kbd>g</kbd> + <kbd>w</kbd> | Go to the [project wiki](project/wiki/index.md) (**Plan > Wiki**), if enabled. | | <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | ### Issues @@ -123,14 +123,14 @@ These shortcuts are available when viewing [merge requests](project/merge_reques ### Project files These shortcuts are available when browsing the files in a project (go to -**Repository > Files**): +**Code > Repository**): | Keyboard shortcut | Description | |-------------------|-------------| | <kbd>↑</kbd> | Move selection up. | | <kbd>↓</kbd> | Move selection down. | | <kbd>Enter</kbd> | Open selection. | -| <kbd>Escape</kbd> | Go back to file list screen (only while searching for files, **Repository > Files**, then select **Find File**). | +| <kbd>Escape</kbd> | Go back to file list screen (only while searching for files, **Code > Repository**, then select **Find File**). | | <kbd>y</kbd> | Go to file permalink (only while viewing a file). | | <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | @@ -219,7 +219,7 @@ These shortcuts are available when editing a file with the [Web IDE](project/web ### Repository graph These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-history-graph) -page (go to **Repository > Graph**): +page (go to **Code > Repository graph**): | Keyboard shortcut | Description | |--------------------------------------------------------------------|-------------| @@ -238,10 +238,10 @@ This shortcut is available when viewing a [wiki page](project/wiki/index.md): |-------------------|-----------------| | <kbd>e</kbd> | Edit wiki page. | -### Content editor +### Rich text editor These shortcuts are available when editing a file with the -[Content Editor](https://about.gitlab.com/direction/plan/knowledge/content_editor/): +[rich text editor](https://about.gitlab.com/direction/plan/knowledge/content_editor/): | macOS shortcut | Windows shortcut | Description | |----------------|------------------|-------------| @@ -261,6 +261,7 @@ These shortcuts are available when editing a file with the | <kbd>Command</kbd> + <kbd>i</kbd> | <kbd>Control</kbd> + <kbd>i</kbd> | Italic | | <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>x</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>x</kbd> | Strikethrough | | <kbd>Command</kbd> + <kbd>e</kbd> | <kbd>Control</kbd> + <kbd>e</kbd> | Code | +| <kbd>Command</kbd> + <kbd>k</kbd> | <kbd>Control</kbd> + <kbd>k</kbd> | Insert a link | | <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | Apply normal text style | | <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | Apply heading style 1 | | <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | Apply heading style 2 | diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 3ad003e4f4c..aace26b4bb0 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -38,19 +38,15 @@ visibility setting keep this setting. You can read more about the change in the You can create snippets in multiple ways, depending on whether you want to create a personal or project snippet: 1. Select the kind of snippet you want to create: - - **To create a personal snippet**: On the - [Snippets dashboard](https://gitlab.com/dashboard/snippets), select - **New snippet**, or: - - *If you're on a project's page,* select the plus icon (**{plus-square-o}**) - in the top navigation bar, and then select **New snippet** from the - **GitLab** section of the same dropdown list. - - *For all other pages,* select the plus icon (**{plus-square-o}**) - in the top navigation bar, then select **New snippet** from the dropdown list. + - **To create a personal snippet**, do one of the following: + - On the [Snippets dashboard](https://gitlab.com/dashboard/snippets), select + **New snippet**. + - From a project: On the left sidebar, select **Create new** (**{plus}**). Below **In GitLab**, select **New snippet**. + - From any other page: On the left sidebar, select **Create new** (**{plus}**) and then **New snippet**. - If you installed the [GitLab Workflow VS Code extension](project/repository/vscode.md), use the [`Gitlab: Create snippet` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet). - - **To create a project snippet**: Go to your project's page. Select the - plus icon (**{plus-square-o}**), and then select **New snippet** from the - **This project** section of the dropdown list. + - **To create a project snippet**: Go to your project's page. Select + **Create new** (**{plus}**). Below **In this project**, select **New snippet**. 1. Add a **Title** and **Description**. 1. Name your **File** with an appropriate extension, such as `example.rb` or `index.html`. Filenames with appropriate extensions display [syntax highlighting](#filenames). @@ -257,7 +253,7 @@ GitLab forwards the spam to Akismet. ### Reduce snippets repository size -Because versioned snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md), +Because versioned snippets are considered as part of the [namespace storage size](../administration/settings/account_and_limit_settings.md), it's recommended to keep snippets' repositories as compact as possible. For more information about tools to compact repositories, diff --git a/doc/user/ssh.md b/doc/user/ssh.md index a11f3c4dbd6..d92e3944521 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -76,7 +76,7 @@ must have [OpenSSH 8.2](https://www.openssh.com/releasenotes.html#8.2) or later Available documentation suggests ED25519 is more secure than RSA. -If you use an RSA key, the US National Institute of Science and Technology in +If you use an RSA key, the US National Institute of Standards and Technology in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf) recommends a key size of at least 2048 bits. The default key size depends on your version of `ssh-keygen`. Review the `man` page for your installed `ssh-keygen` command for details. @@ -336,7 +336,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: In: - GitLab 13.12 and earlier, the expiration date is informational only. It doesn't prevent you from using the key. Administrators can view expiration dates and use them for - guidance when [deleting keys](admin_area/credentials_inventory.md#delete-a-users-ssh-key). + guidance when [deleting keys](../administration/credentials_inventory.md#delete-a-users-ssh-key). - GitLab checks all SSH keys at 02:00 AM UTC every day. It emails an expiration notice for all SSH keys that expire on the current date. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.) - GitLab checks all SSH keys at 01:00 AM UTC every day. It emails an expiration notice for all SSH keys that are scheduled to expire seven days from now. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.11.) 1. Select **Add key**. diff --git a/doc/user/tasks.md b/doc/user/tasks.md index b14f4acca36..ecd5ef0c42f 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -18,7 +18,7 @@ For the latest updates, check the [Tasks Roadmap](https://gitlab.com/groups/gitl FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to [disable the feature flags](../administration/feature_flags.md) named `work_items`. +an administrator can [disable the feature flags](../administration/feature_flags.md) named `work_items`. On GitLab.com, this feature is available. Use tasks to track steps needed for the [issue](project/issues/index.md) to be closed. @@ -294,7 +294,7 @@ To set issue weight of a task: > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/367456) in GitLab 15.7. 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 `work_items_mvc`. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `work_items_mvc`. On GitLab.com, this feature is available. You can add a task to an [iteration](group/iterations/index.md). @@ -359,3 +359,18 @@ To copy the task's email address: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Plan > Issues**, then select your issue to view it. 1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy task email address**. + +## Two-column layout + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415077) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `work_items_mvc_2`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +When enabled, tasks use a two-column layout, similar to issues. +The description and threads are on the left, and attributes, such as labels +or assignees, on the right. + + diff --git a/doc/user/todos.md b/doc/user/todos.md index 95bc8a553c1..97f67c67671 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -69,7 +69,7 @@ To-do items aren't affected by [GitLab notification email settings](profile/noti FLAG: On self-managed GitLab, by default this feature is not available. To make it available per user, -ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `multiple_todos`. +an administrator can [enable the feature flag](../administration/feature_flags.md) named `multiple_todos`. On GitLab.com, this feature is not available. The feature is not ready for production use. @@ -81,7 +81,7 @@ When you enable this feature: ## Create a to-do item -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390549) in objectives, key results and, tasks in GitLab 16.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390549) in objectives, key results, and tasks in GitLab 16.0. You can manually add an item to your To-Do List. @@ -97,10 +97,6 @@ You can manually add an item to your To-Do List. 1. In the upper-right corner, select **Add a to do** (**{todo-add}**). -  - -  - ## Create a to-do item by mentioning someone You can create a to-do item by mentioning someone anywhere except for a code block. Mentioning a user many times in one message only creates one to-do item. @@ -158,10 +154,6 @@ There are two ways to do this: - In the To-Do List, to the right of the to-do item, select **Mark as done** (**{check}**). - In the upper-right corner of the resource (for example, issue or merge request), select **Mark as done** (**{todo-done}**). -  - -  - ## Mark all to-do items as done You can mark all your to-do items as done at the same time. diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index afbdcbcdf09..ae47a9156c7 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -73,7 +73,7 @@ Your account has been blocked. Fatal: Could not read from remote repository Your primary email address is not confirmed. ``` -You can assure your users that they have not been [Blocked](admin_area/moderate_users.md#block-and-unblock-users) by an administrator. +You can assure your users that they have not been [Blocked](../administration/moderate_users.md#block-and-unblock-users) by an administrator. When affected users see this message, they must confirm their email address before they can commit code. ## What do you need to know as an administrator of a GitLab self-managed Instance? @@ -83,7 +83,7 @@ You have the following options to help your users: - They can confirm their address through the email that they received. - They can confirm the subject email address themselves by navigating to `https://gitlab.example.com/users/confirmation/new`. -As an administrator, you may also confirm a user in the [Admin Area](admin_area/index.md#administering-users). +As an administrator, you may also confirm a user in the [Admin Area](../administration/admin_area.md#administering-users). ## What do you do if you are an administrator and you're locked out? diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 5c6c64a3485..d119044930a 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -181,7 +181,7 @@ Storage types that add to the total namespace storage are: - Git repository - Git LFS -- Artifacts +- Job artifacts - Container registry - Package registry - Dependency proxy diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index eb3ce1c5aff..a101e5f5f8c 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. 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 `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. WARNING: This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). @@ -19,6 +19,8 @@ A workspace is a virtual sandbox environment for your code in GitLab. You can us Each workspace includes its own set of dependencies, libraries, and tools, which you can customize to meet the specific needs of each project. Workspaces use the AMD64 architecture. +For a demo of this feature, see [GitLab Workspaces Demo](https://go.gitlab.com/qtu66q). + ## Set up a workspace ### Prerequisites @@ -60,6 +62,17 @@ To create a workspace: The workspace might take a few minutes to start. To access the workspace, under **Preview**, select the workspace link. You also have access to the terminal and can install any necessary dependencies. +## Deleting data associated with a workspace + +When you delete a project, agent, user, or token associated with a workspace: + +- The workspace is deleted from the user interface. +- In the Kubernetes cluster, the running workspace resources become orphaned. + +To clean up orphaned resources, an administrator must manually delete the workspace in Kubernetes. + +For more information about our plans to change the current behavior, see [issue 414384](https://gitlab.com/gitlab-org/gitlab/-/issues/414384). + ## Devfile A devfile is a file that defines a development environment by specifying the necessary tools, languages, runtimes, and other components for a GitLab project. @@ -159,3 +172,17 @@ You can provide your own container image, which can run as any Linux user ID. It GitLab uses the Linux root group ID permission to create, update, or delete files in a container. The container runtime used by the Kubernetes cluster must ensure all containers have a default Linux group ID of `0`. If you have a container image that does not support arbitrary user IDs, you cannot create, update, or delete files in a workspace. To create a container image that supports arbitrary user IDs, see the [OpenShift documentation](https://docs.openshift.com/container-platform/4.12/openshift_images/create-images.html#use-uid_create-images). + +## Troubleshooting + +When working with workspaces, you might encounter the following issues. + +### `Failed to renew lease` when creating a workspace + +You might not be able to create a workspace due to a known issue in the GitLab agent for Kubernetes. The following error message might appear in the agent's log: + +```plaintext +{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX} +``` + +This issue occurs when an agent instance cannot renew its leadership lease, which results in the shutdown of leader-only modules including the `remote_development` module. To resolve this issue, restart the agent instance. |
