diff options
Diffstat (limited to 'doc/user/project')
90 files changed, 1320 insertions, 760 deletions
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**. ![Deployed Environment](img/environment.png) 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/ ![deploy boards Kubernetes Label](img/deploy_boards_kubernetes_label.png) 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. ![Security Approvals](img/security_approvals_v15_0.png) 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 **-**. + +![Multi-line suggestion preview](img/suggest_changes_v16_2.png) + ## 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: + +![CI information in candidate detail](img/candidate_detail_ci_v16_12.png) + ## 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**. ![Project templates for Pages](../img/pages_project_templates_v13_1.png) 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. ![A Release with one associated milestone](img/release_with_milestone_v12_9.png) -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. ![Repository Languages bar](img/repository_languages_v15_2.png) @@ -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**. ![repository Git flow](img/repo_graph.png) 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: |