diff options
Diffstat (limited to 'doc/user/project')
83 files changed, 1371 insertions, 1022 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 5d1d10fc37d..dc650bd9482 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -89,6 +89,8 @@ which are evaluated when displaying the badge. The following placeholders are available: - `%{project_path}`: Path of a project including the parent groups +- `%{project_title}`: Title of a project +- `%{project_name}`: Name of a project - `%{project_id}`: Database ID associated with a project - `%{default_branch}`: Default branch name configured for a project's repository - `%{commit_sha}`: ID of the most recent commit to the default branch of a diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 3e6a9acc304..95f38c7e354 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -68,7 +68,7 @@ Here's an example setup flow from scratch: If it isn't, follow the documentation to specify the image version. 1. [Run a new Auto DevOps pipeline](../../ci/pipelines/index.md#run-a-pipeline-manually) and make sure that the `production` job succeeds and creates a production environment. -1. Configure a [`canary` deployment job for Auto DevOps pipelines](../../topics/autodevops/customize.md#deploy-policy-for-canary-environments). +1. Configure a [`canary` deployment job for Auto DevOps pipelines](../../topics/autodevops/cicd_variables.md#deploy-policy-for-canary-environments). 1. [Run a new Auto DevOps pipeline](../../ci/pipelines/index.md#run-a-pipeline-manually) and make sure that the `canary` job succeeds and creates a canary deployment with Canary Ingress. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index b3d381c3148..52288af101a 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -195,7 +195,7 @@ If a default Storage Class doesn't already exist and is desired, follow Amazon's to create one. Alternatively, disable PostgreSQL by setting the project variable -[`POSTGRES_ENABLED`](../../../topics/autodevops/customize.md#cicd-variables) to `false`. +[`POSTGRES_ENABLED`](../../../topics/autodevops/cicd_variables.md#cicd-variables) to `false`. ## Deploy the app to EKS diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index c9b3596d92f..529e7a6da12 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -49,16 +49,16 @@ GitLab creates the following resources for RBAC clusters. | Name | Type | Details | Created when | |:----------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:-----------------------| | `gitlab` | `ServiceAccount` | `default` namespace | Creating a new cluster | -| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new cluster | +| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) role | Creating a new cluster | | `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new cluster | | Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | | Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | | Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | -| Environment namespace | `RoleBinding` | [`admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | +| Environment namespace | `RoleBinding` | [`admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) role | Deploying to a cluster | The environment namespace `RoleBinding` was [updated](https://gitlab.com/gitlab-org/gitlab/-/issues/31113) in GitLab 13.6 -to `admin` roleRef. Previously, the `edit` roleRef was used. +to `admin` role. Previously, the `edit` role was used. ## ABAC cluster resources diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 3dd6f14ea70..5f279ddda5b 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -216,19 +216,3 @@ Prerequisites: - A deploy token with `read_registry` and `write_registry` scopes. Follow the dependency proxy [authentication instructions](../../packages/dependency_proxy/index.md). - -## Troubleshooting - -### Error: `api error: Repository or object not found:` - -When using a group deploy token to clone from LFS objects, you might get `404 Not Found` responses -and this error message. This occurs because of a bug, documented in -[issue 235398](https://gitlab.com/gitlab-org/gitlab/-/issues/235398). - -```plaintext -api error: Repository or object not found: -https://<URL-with-token>.git/info/lfs/objects/batch -Check that it exists and that you have proper access to it -``` - -The workaround is to use a project deploy token. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 40c36236932..ffbe7447aa8 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -40,7 +40,7 @@ To create an issue description template: where `mytemplate` is the name of your issue template. 1. Commit to your default branch. -To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-an-issue) +To check if this has worked correctly, [create a new issue](issues/create_issues.md) and see if you can find your description template in the **Choose a template** dropdown list. ## Create a merge request template @@ -81,7 +81,23 @@ To discard any changes to the description you've made after selecting the templa NOTE: You can create shortcut links to create an issue using a designated template. -For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. Read more about [creating issues using a URL with prefilled values](issues/managing_issues.md#using-a-url-with-prefilled-values). +For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. Read more about [creating issues using a URL with prefilled values](issues/create_issues.md#using-a-url-with-prefilled-values). + +### Supported variables in merge request templates + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89810) in GitLab 15.7. + +When you save a merge request for the first time, GitLab replaces these variables in +your merge request template with their values: + +| Variable | Description | Output example | +|----------|-------------|----------------| +| `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100 KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.` | +| `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | +| `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | +| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | +| `%{source_branch}` | The name of the branch being merged. | `my-feature-branch` | +| `%{target_branch}` | The name of the branch that the changes are applied to. | `main` | ### Set instance-level description templates **(PREMIUM SELF)** diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 3f1a2dcfe2b..98b46650b42 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -104,7 +104,7 @@ current Bitbucket public name, and reconnect if there's a mismatch: 1. [Use the API to get the currently authenticated user](../../../api/users.md#for-normal-users-1). -1. In the API's response, the `identities` attribute contains the Bitbucket account that exists in +1. In the API response, the `identities` attribute contains the Bitbucket account that exists in the GitLab database. If the `extern_uid` doesn't match the current Bitbucket public name, the user should reconnect their Bitbucket account in the [GitLab profile service sign-in](https://gitlab.com/-/profile/account). diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 1f34c6d4ad9..d7fa1338c55 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -63,6 +63,10 @@ The following items are changed when they are imported: ## User assignment +Prerequisite: + +- Authentication token with administrator access. + When issues and pull requests are importing, the importer tries to find the author's email address with a confirmed email address in the GitLab user database. If no such user is available, the project creator is set as the author. The importer appends a note in the comment to mark the diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index c0b13c76322..07a21d8b941 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -59,11 +59,10 @@ their GitHub authors and assignees in the database of the GitLab instance. Pull GitLab. For this association to succeed, each GitHub author and assignee in the repository -must meet one of the following conditions prior to the import: - -- Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) - that matches their GitLab account's email address. +must have a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) +on GitHub that matches their GitLab email address (regardless of how the account was created). +If their email address from GitHub is set as their secondary email address in GitLab, it must be +confirmed. GitLab content imports that use GitHub accounts require that the GitHub public-facing email address is populated. This means all comments and contributions are properly mapped to the same user in GitLab. GitHub Enterprise does not require this @@ -73,10 +72,8 @@ field to be populated so you may have to add it on existing accounts. ### Use the GitHub integration -Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: - -- A GitLab account that has logged in using the GitHub icon. -- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) in the profile of the GitHub user +Before you begin, ensure that any GitHub user you want to map to a GitLab user has a GitLab email address that matches their +[publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) on GitHub. If you are importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). We do not recommend this method, as it does not associate all user activity (such as issues and pull requests) with matching GitLab users. @@ -96,7 +93,10 @@ If you are using a self-managed GitLab instance or if you are importing from Git ### Use a GitHub token -NOTE: +Prerequisite: + +- Authentication token with administrator access. + Using a personal access token to import projects is not recommended. If you are a GitLab.com user, you can use a personal access token to import your project from GitHub, but this method cannot associate all user activity (such as issues and pull requests) with matching GitLab users. @@ -222,21 +222,26 @@ References to pull requests and issues are preserved. Each imported repository m [visibility level is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. -### Branch protection rules +### Branch protection rules and project settings + +When they are imported, supported GitHub branch protection rules are mapped to either: + +- GitLab branch protection rules. +- Project-wide GitLab settings. -Supported GitHub branch protection rules are mapped to GitLab branch protection rules or project-wide GitLab settings when they are imported: +| GitHub rule | GitLab rule | Introduced in | +| :---------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | +| **Require conversation resolution before merging** for the project's default branch | **All threads must be resolved** [project setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) | +| **Require a pull request before merging** | **No one** option in the **Allowed to push** list of [branch protection settings](../protected_branches.md#configure-a-protected-branch) | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) | +| **Require signed commits** for the project's default branch | **Reject unsigned commits** GitLab [push rule](../repository/push_rules.md#prevent-unintended-consequences) **(PREMIUM)** | [GitLab 15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) | +| **Allow force pushes - Everyone** | **Allowed to force push** [branch protection setting](../protected_branches.md#allow-force-push-on-a-protected-branch) | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) | +| **Require a pull request before merging - Require review from Code Owners** | **Require approval from code owners** [branch protection setting](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) **(PREMIUM)** | [GitLab 15.6](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) | -- GitHub rule **Require conversation resolution before merging** for the project's default branch is mapped to the [**All threads must be resolved** GitLab setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) in GitLab 15.5. -- GitHub rule **Require a pull request before merging** is mapped to the **No one** option in the **Allowed to push** list of the branch protection rule. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) in GitLab 15.5. -- GitHub rule **Require a pull request before merging - Require review from Code Owners** is mapped to the - [**Code owner approval** branch protection rule](../protected_branches.md#require-code-owner-approval-on-a-protected-branch). Requires GitLab Premium or higher. - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/376683) in GitLab 15.6. -- GitHub rule **Require signed commits** for the project's default branch is mapped to the **Reject unsigned commits** GitLab push rule. Requires GitLab Premium or higher. - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) in GitLab 15.5. -- GitHub rule **Allow force pushes - Everyone** is mapped to the [**Allowed to force push** branch protection rule](../protected_branches.md#allow-force-push-on-a-protected-branch). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370943) in GitLab 15.6. -- GitHub rule **Allow force pushes - Specify who can force push** is proposed in issue [370945](https://gitlab.com/gitlab-org/gitlab/-/issues/370945). -- Support for GitHub rule **Require status checks to pass before merging** was proposed in issue [370948](https://gitlab.com/gitlab-org/gitlab/-/issues/370948). However, this rule cannot be translated during project import into GitLab due to technical difficulties. -You can still create [status checks](../merge_requests/status_checks.md) in GitLab yourself. +Mapping GitHub rule **Require status checks to pass before merging** to +[external status checks](../merge_requests/status_checks.md) was considered in issue +[370948](https://gitlab.com/gitlab-org/gitlab/-/issues/370948). However, this rule is not imported during project import +into GitLab due to technical difficulties. You can still create [external status checks](../merge_requests/status_checks.md) +manually. ## Alternative way to import notes and diff notes @@ -274,7 +279,7 @@ Feature.disable(:github_importer_lower_per_page_limit, group) ## Import from GitHub Enterprise on an internal network -If your GitHub Enterprise instance is on a internal network that is unaccessible to the internet, you can use a reverse proxy +If your GitHub Enterprise instance is on a internal network that is inaccessible to the internet, you can use a reverse proxy to allow GitLab.com to access the instance. The proxy needs to: diff --git a/doc/user/project/import/img/gitlab_import_history_page_v14_10.png b/doc/user/project/import/img/gitlab_import_history_page_v14_10.png Binary files differdeleted file mode 100644 index 812696a8faa..00000000000 --- a/doc/user/project/import/img/gitlab_import_history_page_v14_10.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 1b5a658d209..208bce90453 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -5,76 +5,59 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Migrate projects to a GitLab instance **(FREE)** - -See these documents to migrate to GitLab: - -- [From Bitbucket Cloud](bitbucket.md) -- [From Bitbucket Server (also known as Stash)](bitbucket_server.md) -- [From ClearCase](clearcase.md) -- [From CVS](cvs.md) -- [From FogBugz](fogbugz.md) -- [From GitHub.com or GitHub Enterprise](github.md) -- [From GitLab.com](gitlab_com.md) -- [From Gitea](gitea.md) -- [From Perforce](perforce.md) -- [From SVN](svn.md) -- [From TFVC](tfvc.md) -- [From repository by URL](repo_by_url.md) -- [By uploading a manifest file (AOSP)](manifest.md) -- [From Phabricator](phabricator.md) -- [From Jira (issues only)](jira.md) +# Import and migrate projects **(FREE)** -You can also import any Git repository through HTTP from the **New Project** page. Note that if the -repository is too large, the import can timeout. - -You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). +If you want to bring existing projects to GitLab or copy GitLab projects to a different location, you can: -## Project import history - -You can view all project imports created by you. This list includes the following: +- Import projects from external systems using one of the [available importers](#available-project-importers). +- Migrate GitLab projects: + - Between two GitLab self-managed instances. + - Between a self-managed instance and GitLab.com in both directions. + - In the same GitLab instance. -- Source (without credentials for security reasons) -- Destination -- Status -- Error details if the import failed +For any type of source and target, you can migrate projects: -To view project import history: +- As part of a [GitLab group migration](../../group/import/index.md). You can't migrate only chosen projects, + but you can migrate many projects at once within a group. +- Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network + connection between instances is required. -1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. -1. Select **Import project**. -1. Select **History**. +If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). However, you can't +import issues and merge requests this way. To retain metadata like issues and merge requests, either: - +- [Migrate projects with groups](../../group/import/index.md). +- Use [file exports](../settings/import_export.md) to import projects. -The history also includes projects created from [built-in](../working_with_projects.md#create-a-project-from-a-built-in-template) -or [custom](../working_with_projects.md#create-a-project-from-a-built-in-template) -templates. GitLab uses [import repository by URL](repo_by_url.md) -to create a new project from a template. +Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). +When migrating from self-managed to GitLab.com, user associations (such as comment author) +are changed to the user who is importing the projects. -## LFS authentication +## Available project importers -When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) -file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. +You can import projects from: -## Migrate from self-managed GitLab to GitLab.com +- [Bitbucket Cloud](bitbucket.md) +- [Bitbucket Server (also known as Stash)](bitbucket_server.md) +- [ClearCase](clearcase.md) +- [CVS](cvs.md) +- [FogBugz](fogbugz.md) +- [GitHub.com or GitHub Enterprise](github.md) +- [GitLab.com](gitlab_com.md) +- [Gitea](gitea.md) +- [Perforce](perforce.md) +- [From SVN](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Git-as-a-Client) +- [TFVC](tfvc.md) +- [Repository by URL](repo_by_url.md) +- [Uloading a manifest file (AOSP)](manifest.md) +- [Phabricator](phabricator.md) +- [Jira (issues only)](jira.md) -If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). -However, you can't import issues and merge requests this way. To retain all metadata like issues and -merge requests, use the [import/export feature](../settings/import_export.md) -to export projects from self-managed GitLab and import those projects into GitLab.com. All GitLab -user associations (such as comment author) are changed to the user importing the project. For more -information, see the prerequisites and important notes in these sections: +You can also import any Git repository through HTTP from the **New Project** page. Note that if the +repository is too large, the import can timeout. -- [Export a project and its data](../settings/import_export.md#export-a-project-and-its-data). -- [Import the project](../settings/import_export.md#import-a-project-and-its-data). +You can then [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). -NOTE: -When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md) -will be used. Creating users with the API is limited to self-managed instances as it requires -administrator access. +## Migrate using the API To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). Migrate the assets in this order: @@ -83,17 +66,9 @@ Migrate the assets in this order: 1. [Projects](../../../api/projects.md) 1. [Project variables](../../../api/project_level_variables.md) -Keep in mind the limitations of the [import/export feature](../settings/import_export.md#items-that-are-exported). - You must still migrate your [Container Registry](../../packages/container_registry/index.md) over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. -## Migrate from GitLab.com to self-managed GitLab - -The process is essentially the same as [migrating from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). -The main difference is that an administrator can create users on the self-managed GitLab instance -through the UI or the [users API](../../../api/users.md#user-creation). - ## Migrate between two self-managed GitLab instances To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, it's @@ -105,12 +80,36 @@ The backups produced don't depend on the operating system running GitLab. You ca the restore method to switch between different operating system distributions or versions, as long as the same GitLab version [is available for installation](../../../administration/package_information/supported_os.md). -To instead merge two self-managed GitLab instances together, use the instructions in -[Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). -This method is useful when both self-managed instances have existing data that must be preserved. +Also note that administrators can use the [Users API](../../../api/users.md) to migrate users. + +## View project import history + +You can view all project imports created by you. This list includes the following: + +- Paths of source projects if projects were imported from external systems, or import method if GitLab projects were migrated. +- Paths of destination projects. +- Start date of each import. +- Status of each import. +- Error details if any errors occurred. + +To view project import history: + +1. Sign in to GitLab. +1. On the top bar, select **Create new...** (**{plus-square}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **History** in the upper right corner. +1. If there are any errors for a particular import, you can see them by selecting **Details**. + +The history also includes projects created from [built-in](../working_with_projects.md#create-a-project-from-a-built-in-template) +or [custom](../working_with_projects.md#create-a-project-from-a-built-in-template) +templates. GitLab uses [import repository by URL](repo_by_url.md) +to create a new project from a template. + +## LFS authentication -Also note that administrators can use the [Users API](../../../api/users.md) -to migrate users. +When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) +file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. ## Project aliases **(PREMIUM SELF)** diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 1687d621e2e..6730ef862e6 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -1,91 +1,11 @@ --- -type: howto -stage: Manage -group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'index.md' +remove_date: '2023-03-15' --- -# Migrate from Subversion to GitLab **(FREE)** +This document was moved to [another location](index.md). -GitLab uses Git as its version control system. If you're using Subversion (SVN) as your version control system, -you can migrate to using a Git repository in GitLab using `svn2git`. - -You can follow the steps on this page to migrate to Git if your SVN repository: - -- Has a standard format (trunk, branches, and tags). -- Is not nested. - -For a non-standard repository see the [`svn2git` documentation](https://github.com/nirvdrum/svn2git). - -We recommend a hard cut over from SVN to Git and GitLab. Run the migration command once and then have all users use the -new GitLab repository immediately. - -## Install `svn2git` - -Install `svn2git` on a local workstation rather than the GitLab server: - -- On all systems you can install as a Ruby gem if you already have Ruby and Git installed: - - ```shell - sudo gem install svn2git - ``` - -- On Debian-based Linux distributions you can install the native packages: - - ```shell - sudo apt-get install git-core git-svn ruby - ``` - -## Prepare an authors file (recommended) - -Prepare an authors file so `svn2git` can map SVN authors to Git authors. If you choose not to create the authors file, -commits are not attributed to the correct GitLab user. - -To map authors, you must map every author present on changes in the SVN repository. If you don't, the -migration fails and you have to update the author file accordingly. - -1. Search through the SVN repository and output a list of authors: - - ```shell - svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq - ``` - -1. Use the output from the last command to construct the authors file. Create a file called `authors.txt` and add one - mapping per line. For example: - - ```plaintext - sidneyjones = Sidney Jones <sidneyjones@example.com> - ``` - -## Migrate SVN repository to Git repository - -`svn2git` supports excluding certain file paths, branches, tags, and more. See -the [`svn2git` documentation](https://github.com/nirvdrum/svn2git) or run `svn2git --help` for full documentation on all of -the available options. - -For each repository to migrate: - -1. Create a new directory and change into it. -1. For repositories that: - - - Don't require a username and password, run: - - ```shell - svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt - ``` - - - Do require a username and password, run: - - ```shell - svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt --username <username> --password <password> - ``` - -1. Create a new GitLab project for your migrated code. -1. Copy the SSH or HTTP(S) repository URL from the GitLab project page. -1. Add the GitLab repository as a Git remote and push all the changes. This pushes all commits, branches, and tags. - - ```shell - git remote add origin git@gitlab.example.com:<group>/<project>.git - git push --all origin - git push --tags origin - ``` +<!-- This redirect file can be deleted after <2023-03-15>. --> +<!-- 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 (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/bamboo.md b/doc/user/project/integrations/bamboo.md index fceec006a1a..db90bafaaa5 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -63,7 +63,7 @@ Bamboo. For example, `https://bamboo.example.com/browse/PROJ-PLAN`. ## Update Bamboo build status in GitLab -You can use a script that uses the [commit status API](../../../api/commits.md#post-the-build-status-to-a-commit) +You can use a script that uses the [commit status API](../../../api/commits.md#set-the-pipeline-status-of-a-commit) and Bamboo build variables to: - Update the commit with the build status. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 8d6fdf882b7..50b52421a5a 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -10,7 +10,7 @@ NOTE: The GitLab for Slack app is only configurable for GitLab.com. It does **not** work for on-premises installations where you can configure [Slack slash commands](slack_slash_commands.md) instead. See -[Slack application integration for self-managed instances](https://gitlab.com/gitlab-org/gitlab/-/issues/28164) +[Slack application integration for self-managed instances](https://gitlab.com/groups/gitlab-org/-/epics/1211) for our plans to make the app configurable for all GitLab installations. Slack provides a native application that you can enable with your project's @@ -36,12 +36,12 @@ workspace to be able to install a new application. See To enable the GitLab integration for your Slack workspace: -1. Go to your project's **Settings > Integration > Slack application** (only +1. Go to your project's **Settings > Integration > GitLab for Slack app** (only visible on GitLab.com). -1. Select **Install Slack app**. +1. Select **Install GitLab for Slack app**. 1. Select **Allow** on Slack's confirmation screen. -You can also select **Reinstall Slack app** to update the app in your Slack workspace +You can also select **Reinstall GitLab for Slack app** to update the app in your Slack workspace to the latest version. See [Version history](#version-history) for details. ## Create a project alias for Slack @@ -50,7 +50,7 @@ To create a project alias on GitLab.com for Slack integration: 1. Go to your project's home page. 1. Go to **Settings > Integrations** (only visible on GitLab.com). -1. On the **Integrations** page, select **Slack application**. +1. On the **Integrations** page, 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**. @@ -91,7 +91,7 @@ As a workaround, ensure your app is up to date. To update an existing Slack integration: 1. Go to your [chat settings](https://gitlab.com/-/profile/chat_names). -1. Next to your project, select **Slack application**. -1. Select **Reinstall Slack app**. +1. Next to your project, select **GitLab for Slack app**. +1. Select **Reinstall GitLab for Slack app**. Alternatively, you can [configure a new Slack integration](https://about.gitlab.com/solutions/slack/). diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 77444570499..769a45fc6ff 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -58,7 +58,6 @@ You can configure the following integrations. | [Emails on push](emails_on_push.md) | Send commits and diff of each push by email. | **{dotted-circle}** No | | [EWM](ewm.md) | Use IBM Engineering Workflow Management as the issue tracker. | **{dotted-circle}** No | | [External wiki](../wiki/index.md#link-an-external-wiki) | Link an external wiki. | **{dotted-circle}** No | -| [Flowdock](../../../api/integrations.md#flowdock) | Send notifications from GitLab to Flowdock flows. | **{dotted-circle}** No | | [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | | [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat. | **{dotted-circle}** No | | [Harbor](harbor.md) | Use Harbor as the container registry. | **{dotted-circle}** No | @@ -77,7 +76,7 @@ You can configure the following integrations. | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | | [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | -| [Slack application](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | +| [GitLab for Slack app](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | | [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md index 82bfd08e926..bd14021ab1c 100644 --- a/doc/user/project/integrations/mlflow_client.md +++ b/doc/user/project/integrations/mlflow_client.md @@ -19,9 +19,9 @@ Setting up your integrations requires minimal changes to existing code. GitLab plays the role of proxy server, both for artifact storage and tracking data. It reflects the MLFlow [Scenario 5](https://www.mlflow.org/docs/latest/tracking.html#scenario-5-mlflow-tracking-server-enabled-with-proxied-artifact-storage-access). -## Enable MFlow Client Integration +## Enable MLFlow Client Integration -Complete this task to enable MFlow Client Integration. +Complete this task to enable MLFlow Client Integration. Prerequisites: @@ -49,17 +49,17 @@ that can be explored by selecting an experiment. - 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, tags are ExperimentTags and RunTags are ignored. -- MLFLow Model Registry is not supported. +- During creation of experiments and runs, tags are ExperimentTags and RunTags are stored, even though they are not displayed. +- MLFlow Model Registry is not supported. ## Supported methods and caveats This is a list of methods we support 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). -### `set_experiment` +### `set_experiment()` -Accepts both experiment_name and experiment_id +Accepts both `experiment_name` and `experiment_id` ### `start_run()` diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index d34c558ebbc..2ded5799c23 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -36,10 +36,6 @@ to control GitLab from Slack. Slash commands are configured separately. - *To send messages to channels,* enter the Slack channel names, separated by commas. - *To send direct messages,* use the Member ID found in the user's Slack profile. - - NOTE: - Usernames and private channels are not supported. - 1. In **Webhook**, enter the webhook URL you copied in the [Slack configuration](#configure-slack) step. 1. Optional. In **Username**, enter the username of the Slack bot that sends diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 60187b9a682..63282d6ec6e 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1019,7 +1019,7 @@ Payload example: ``` NOTE: -The fields `assignee_id`, `state`, `merge_status` are deprecated. +The fields `assignee_id`, `state`, `merge_status` are [deprecated](../../../api/merge_requests.md). ## Wiki page events @@ -1171,7 +1171,7 @@ Payload example: "project":{ "id": 41, "web_url": "https://gitlab.example.com/gitlab-org/upstream-project", - "path_with_namespace": "gitlab-org/upstream-project", + "path_with_namespace": "gitlab-org/upstream-project" }, "pipeline_id": 30, "job_id": 3401 @@ -1475,6 +1475,8 @@ Payload example: "deployable_id": 796, "deployable_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/jobs/796", "environment": "staging", + "environment_slug": "staging", + "environment_external_url": "https://staging.example.com", "project": { "id": 30, "name": "test-deployment-webhooks", diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index ef6957ac2d8..3d45e947c4c 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w [Webhooks](https://en.wikipedia.org/wiki/Webhook) are custom HTTP callbacks that you define. They are usually triggered by an -event, such as pushing code to a repository or posting a comment on a blog. +event, such as pushing code to a repository or posting a comment on an issue. When the event occurs, the source app makes an HTTP request to the URI configured for the webhook. The action to take may be anything. For example, you can use webhooks to: @@ -52,7 +52,7 @@ specific to a group, including: ## Configure a webhook in GitLab -You can configure a webhook for a group or a project. +To configure a webhook for a project or group: 1. In your project or group, on the left sidebar, select **Settings > Webhooks**. 1. In **URL**, enter the URL of the webhook endpoint. @@ -62,6 +62,40 @@ You can configure a webhook for a group or a project. 1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](index.md#manage-ssl-verification). 1. Select **Add webhook**. +## Mask sensitive portions of webhook URLs + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/99995) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `webhook_form_mask_url`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/376106) in GitLab 15.6. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/376106) in GitLab 15.7. Feature flag `webhook_form_mask_url` removed. + +You can define and mask sensitive portions of webhook URLs and replace them +with configured values any number of times when webhooks are executed. +Sensitive portions do not get logged and are encrypted at rest in the database. + +To mask sensitive portions of the webhook URL: + +1. In your project or group, on the left sidebar, select **Settings > Webhooks**. +1. In **URL**, enter the full webhook URL. +1. Select **Mask portions of URL**. +1. In **Sensitive portion of URL**, enter the portion you want to mask. +1. In **How it looks in the UI**, enter the masking value. + +To interpolate sensitive portions for each webhook, use `url_variables`. +For example, if a webhook has the following URL: + +```plaintext +https://{subdomain}.example.com/{path}?key={value} +``` + +You must define the following variables: + +- `subdomain` +- `path` +- `value` + +Variable names can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). +You can define URL variables directly using the REST API. + ## Configure your webhook receiver endpoint Webhook receiver endpoints should be fast and stable. @@ -86,27 +120,22 @@ Endpoints should follow these best practices: ### Failing webhooks -> Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. 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 `web_hooks_disable_failed`. -On GitLab.com, this feature is not available. -The feature is not ready for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60837) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 15.7. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 15.7. Feature flag `web_hooks_disable_failed` removed. If a webhook fails repeatedly, it may be disabled automatically. Webhooks that return response codes in the `5xx` range are understood to be failing -intermittently, and are temporarily disabled. This lasts initially -for 10 minutes. If the hook continues to fail, the back-off period is -extended on each retry, up to a maximum disabled period of 24 hours. +intermittently and are temporarily disabled. These webhooks are initially disabled +for 1 minute, which is extended on each retry up to a maximum of 24 hours. -Webhooks that return failure codes in the `4xx` range are understood to be -misconfigured, and these are disabled until you manually re-enable -them. These webhooks are not automatically retried. +Webhooks that return response codes in the `4xx` range are understood to be +misconfigured and are permanently disabled until you manually re-enable +them yourself. -See [troubleshooting](#troubleshoot-webhooks) for information on -how to see if a webhook is disabled, and how to re-enable it. +See [Troubleshooting](#troubleshoot-webhooks) for more information on +disabled webhooks and how to re-enable them. ## Test a webhook @@ -190,10 +219,10 @@ You can filter push events by branch. Use one of the following options to filter - **All branches**: push events from all branches. - **Wildcard pattern**: push events from a branch that matches a wildcard pattern (for example, `*-stable` or `production/*`). -- **Regular expression**: push events from a branch that matches a regular expression (for example, `(feature|hotfix)/*`). +- **Regular expression**: push events from a branch that matches a regular expression (for example, `^(feature|hotfix)/`). -You can configure branch filtering -in the [webhook settings](#configure-a-webhook-in-gitlab) in your project. +To configure branch filtering for a project or group, see +[Configure a webhook in GitLab](#configure-a-webhook-in-gitlab). ## How image URLs are displayed in the webhook body @@ -302,13 +331,7 @@ GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#othe ### Re-enable disabled webhooks > - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default. -> - The [`web_hooks_disable_failed` flag](#failing-webhooks) must also be enabled for this feature to work. 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 flags](../../../administration/feature_flags.md) named `webhooks_failed_callout` and `web_hooks_disable_failed`. -On GitLab.com, this feature is not available. -The feature is not ready for production use. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed. If a webhook is failing, a banner displays at the top of the edit page explaining why it is disabled, and when it will be automatically re-enabled. For example: diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index c2952b23615..234faa893eb 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -463,6 +463,7 @@ You can edit the following issue attributes in the right sidebar: - Confidentiality - Due date - [Epic](../group/epics/index.md) +- [Health status](issues/managing_issues.md#health-status) - [Iteration](../group/iterations/index.md) - Labels - Milestone diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md new file mode 100644 index 00000000000..3c2e20c1250 --- /dev/null +++ b/doc/user/project/issues/create_issues.md @@ -0,0 +1,221 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Create an issue **(FREE)** + +When you create an issue, you are prompted to enter the fields of the issue. +If you know the values you want to assign to an issue, you can use +[quick actions](../quick_actions.md) to enter them. + +You can create an issue in many ways in GitLab: + +- [From a project](#from-a-project) +- [From a group](#from-a-group) +- [From another issue or incident](#from-another-issue-or-incident) +- [From an issue board](#from-an-issue-board) +- [By sending an email](#by-sending-an-email) +- [Using a URL with prefilled values](#using-a-url-with-prefilled-values) +- [Using Service Desk](#using-service-desk) + +## From a project + +Prerequisites: + +- You must have at least the Guest role for the project. + +To create an issue: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. Either: + + - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. + - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, + select **New issue**. + +1. Complete the [fields](#fields-in-the-new-issue-form). +1. Select **Create issue**. + +The newly created issue opens. + +## From a group + +Issues belong to projects, but when you're in a group, you can access and create issues that belong +to the projects in the group. + +Prerequisites: + +- You must have at least the Guest role for the project in the group. + +To create an issue from a group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Issues**. +1. In the top right corner, select **Select project to create issue**. +1. Select the project you'd like to create an issue for. The button now reflects the selected + project. +1. Select **New issue in `<project name>`**. +1. Complete the [fields](#fields-in-the-new-issue-form). +1. Select **Create issue**. + +The newly created issue opens. + +The project you selected most recently becomes the default for your next visit. +This can save you a lot of time, if you mostly create issues for the same project. + +## From another issue or incident + +> - New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. +> - **Relate to…** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198494) in GitLab 14.9. + +You can create a new issue from an existing one. The two issues can then be marked as related. + +Prerequisites: + +- You must have at least the Guest role for the project. + +To create an issue from another issue: + +1. In an existing issue, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **New related issue**. +1. Complete the [fields](#fields-in-the-new-issue-form). + The new issue form has a **Relate to issue #123** checkbox, where `123` is the ID of the + issue of origin. If you keep this checkbox checked, the two issues become + [linked](related_issues.md). +1. Select **Create issue**. + +The newly created issue opens. + +## From an issue board + +You can create a new issue from an [issue board](../issue_board.md). + +Prerequisites: + +- You must have at least the Guest role for the project. + +To create an issue from a project issue board: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. Select **Issues > Boards**. +1. At the top of a board list, select **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 top bar, select **Main menu > Groups** and find your group. +1. Select **Issues > Boards**. +1. At the top of a board list, select **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**. + +The issue is created and shows up in the board list. It shares the list's characteristic, so, for +example, if the list is scoped to a label `Frontend`, the new issue also has this label. + +## By sending an email + +> - Generated email address format changed in GitLab 11.7. +> - The older format is still supported, so existing aliases and contacts still work. + +You can send an email to create an issue in a project on the project's +**Issues List** page. + +Prerequisites: + +- Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) + configured. +- There must be at least one issue in the issue list. +- You must have at least the Guest role for the project. + +To email an issue to a project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. Select **Issues**. +1. At the bottom of the page, select **Email a new issue to this project**. +1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). +1. From your email client, send an email to this address. + The subject is used as the title of the new issue, and the email body becomes the description. + You can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md). + +A new issue is created, with your user as the author. +You can save this address as a contact in your email client to use it again. + +WARNING: +The email address you see is a private email address, generated just for you. +**Keep it to yourself**, because anyone who knows it can create issues or merge requests as if they +were you. + +To regenerate the email address: + +1. On the issues list, select **Email a new issue to this project**. +1. Select **reset this token**. + +## Using a URL with prefilled values + +> - Ability to use both `issuable_template` and `issue[description]` in the same URL [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80554) in GitLab 14.9. +> - Ability to specify `add_related_issue` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198494) in GitLab 14.9. + +To link directly to the new issue page with prefilled fields, use query +string parameters in a URL. You can embed a URL in an external +HTML page to create issues with certain fields prefilled. + +| Field | URL parameter | Notes | +| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Issue type | `issue[issue_type]` | Either `incident` or `issue`. | +| Description template | `issuable_template` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). If used in combination with `issuable_template` or a [default issue template](../description_templates.md#set-a-default-template-for-merge-requests-and-issues), the `issue[description]` value is appended to the template. | +| Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | +| Relate to… | `add_related_issue` | A numeric issue ID. If present, the issue form shows a [**Relate to…** checkbox](#from-another-issue-or-incident) to optionally link the new issue to the specified existing issue. | + +Adapt these examples to form your new issue URL with prefilled fields. +To create an issue in the GitLab project: + +- With a prefilled title and description: + + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Whoa%2C%20we%27re%20half-way%20there&issue[description]=Whoa%2C%20livin%27%20in%20a%20URL + ``` + +- With a prefilled title and description template: + + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Feature%20Proposal%20-%20basic + ``` + +- With a prefilled title, description, and marked as confidential: + + ```plaintext + https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true + ``` + +## Using Service Desk + +To offer email support, enable [Service Desk](../service_desk.md) for your project. + +Now, when your customer sends a new email, a new issue can be created in +the appropriate project and followed up from there. + +### Fields in the new issue form + +> - Adding the new issue to an epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in GitLab 13.1. +> - Iteration field [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233517) in GitLab 15.6. + +When you're creating a new issue, you can complete the following fields: + +- Title +- Type: either issue (default) or incident +- [Description template](../description_templates.md): overwrites anything in the Description text box +- Description: you can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) +- Checkbox to make the issue [confidential](confidential_issues.md) +- [Assignees](managing_issues.md#assignee) +- [Weight](issue_weight.md) +- [Epic](../../group/epics/index.md) +- [Due date](due_dates.md) +- [Milestone](../milestones/index.md) +- [Labels](../labels.md) +- [Iteration](../../group/iterations/index.md) diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 09067b69696..6c9a645d817 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -29,7 +29,7 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ ## Related topics -- [Create issues](managing_issues.md#create-an-issue) +- [Create issues](create_issues.md) - [Create an issue from a template](../../project/description_templates.md#use-the-templates) - [Edit issues](managing_issues.md#edit-an-issue) - [Move issues](managing_issues.md#move-an-issue) diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 1ba5a4415e0..d852ad3262b 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -36,7 +36,7 @@ When you change the weight of an issue, the new value overwrites the previous va ### When you create an issue -To set the issue weight when you [create an issue](managing_issues.md#create-an-issue), enter a +To set the issue weight when you [create an issue](create_issues.md), enter a number under **Weight**. ### From an existing issue diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 8cd211a51c7..ea90dda88f6 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -6,224 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Manage issues **(FREE)** -[GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and -planning work in GitLab. - -## Create an issue - -When you create an issue, you are prompted to enter the fields of the issue. -If you know the values you want to assign to an issue, you can use -[quick actions](../quick_actions.md) to enter them. - -You can create an issue in many ways in GitLab: - -- [From a project](#from-a-project) -- [From a group](#from-a-group) -- [From another issue or incident](#from-another-issue-or-incident) -- [From an issue board](#from-an-issue-board) -- [By sending an email](#by-sending-an-email) -- [Using a URL with prefilled values](#using-a-url-with-prefilled-values) -- [Using Service Desk](#using-service-desk) - -### From a project - -Prerequisites: - -- You must have at least the Guest role for the project. - -To create an issue: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. Either: - - - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. - - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, - select **New issue**. - -1. Complete the [fields](#fields-in-the-new-issue-form). -1. Select **Create issue**. - -The newly created issue opens. - -### From a group - -Issues belong to projects, but when you're in a group, you can access and create issues that belong -to the projects in the group. - -Prerequisites: - -- You must have at least the Guest role for the project in the group. - -To create an issue from a group: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues**. -1. In the top right corner, select **Select project to create issue**. -1. Select the project you'd like to create an issue for. The button now reflects the selected - project. -1. Select **New issue in `<project name>`**. -1. Complete the [fields](#fields-in-the-new-issue-form). -1. Select **Create issue**. - -The newly created issue opens. - -The project you selected most recently becomes the default for your next visit. -This can save you a lot of time, if you mostly create issues for the same project. - -### From another issue or incident - -> - New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. -> - **Relate to…** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198494) in GitLab 14.9. - -You can create a new issue from an existing one. The two issues can then be marked as related. - -Prerequisites: - -- You must have at least the Guest role for the project. - -To create an issue from another issue: - -1. In an existing issue, select the vertical ellipsis (**{ellipsis_v}**). -1. Select **New related issue**. -1. Complete the [fields](#fields-in-the-new-issue-form). - The new issue form has a **Relate to issue #123** checkbox, where `123` is the ID of the - issue of origin. If you keep this checkbox checked, the two issues become - [linked](related_issues.md). -1. Select **Create issue**. - -The newly created issue opens. - -### From an issue board - -You can create a new issue from an [issue board](../issue_board.md). - -Prerequisites: - -- You must have at least the Guest role for the project. - -To create an issue from a project issue board: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. Select **Issues > Boards**. -1. At the top of a board list, select **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 top bar, select **Main menu > Groups** and find your group. -1. Select **Issues > Boards**. -1. At the top of a board list, select **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**. - -The issue is created and shows up in the board list. It shares the list's characteristic, so, for -example, if the list is scoped to a label `Frontend`, the new issue also has this label. - -### By sending an email - -> - Generated email address format changed in GitLab 11.7. -> - The older format is still supported, so existing aliases and contacts still work. - -You can send an email to create an issue in a project on the project's -**Issues List** page. - -Prerequisites: - -- Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) - configured. -- There must be at least one issue in the issue list. -- You must have at least the Guest role for the project. - -To email an issue to a project: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. Select **Issues**. -1. At the bottom of the page, select **Email a new issue to this project**. -1. To copy the email address, select **Copy** (**{copy-to-clipboard}**). -1. From your email client, send an email to this address. - The subject is used as the title of the new issue, and the email body becomes the description. - You can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md). - -A new issue is created, with your user as the author. -You can save this address as a contact in your email client to use it again. - -WARNING: -The email address you see is a private email address, generated just for you. -**Keep it to yourself**, because anyone who knows it can create issues or merge requests as if they -were you. - -To regenerate the email address: - -1. On the issues list, select **Email a new issue to this project**. -1. Select **reset this token**. - -### Using a URL with prefilled values - -> - Ability to use both `issuable_template` and `issue[description]` in the same URL [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80554) in GitLab 14.9. -> - Ability to specify `add_related_issue` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198494) in GitLab 14.9. - -To link directly to the new issue page with prefilled fields, use query -string parameters in a URL. You can embed a URL in an external -HTML page to create issues with certain fields prefilled. - -| Field | URL parameter | Notes | -| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | -| Issue type | `issue[issue_type]` | Either `incident` or `issue`. | -| Description template | `issuable_template` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | -| Description | `issue[description]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). If used in combination with `issuable_template` or a [default issue template](../description_templates.md#set-a-default-template-for-merge-requests-and-issues), the `issue[description]` value is appended to the template. | -| Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | -| Relate to… | `add_related_issue` | A numeric issue ID. If present, the issue form shows a [**Relate to…** checkbox](#from-another-issue-or-incident) to optionally link the new issue to the specified existing issue. | - -Adapt these examples to form your new issue URL with prefilled fields. -To create an issue in the GitLab project: - -- With a prefilled title and description: - - ```plaintext - https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Whoa%2C%20we%27re%20half-way%20there&issue[description]=Whoa%2C%20livin%27%20in%20a%20URL - ``` - -- With a prefilled title and description template: - - ```plaintext - https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Feature%20Proposal%20-%20basic - ``` - -- With a prefilled title, description, and marked as confidential: - - ```plaintext - https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true - ``` - -### Using Service Desk - -To offer email support, enable [Service Desk](../service_desk.md) for your project. - -Now, when your customer sends a new email, a new issue can be created in -the appropriate project and followed up from there. - -### Fields in the new issue form - -> - Adding the new issue to an epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in GitLab 13.1. -> - Iteration field [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233517) in GitLab 15.6. - -When you're creating a new issue, you can complete the following fields: - -- Title -- Type: either issue (default) or incident -- [Description template](../description_templates.md): overwrites anything in the Description text box -- Description: you can use [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) -- Checkbox to make the issue [confidential](confidential_issues.md) -- [Assignees](#assignee) -- [Weight](issue_weight.md) -- [Epic](../../group/epics/index.md) -- [Due date](due_dates.md) -- [Milestone](../milestones/index.md) -- [Labels](../labels.md) -- [Iteration](../../group/iterations/index.md) +After you create an issue, you can start working with it. ## Edit an issue @@ -239,27 +22,7 @@ To edit an issue: 1. Edit the available fields. 1. Select **Save changes**. -### Reorder list items in the issue description - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.0. - -When you view an issue that has a list in the description, you can also reorder the list items. - -Prerequisites: - -- You must have at least the Reporter role for the project, be the author of the issue, or be - assigned to the issue. -- The issue's description must have an [ordered, unordered](../../markdown.md#lists), or - [task](../../markdown.md#task-lists) list. - -To reorder list items, when viewing an issue: - -1. Hover over the list item row to make the drag icon (**{drag-vertical}**) visible. -1. Select and hold the drag icon. -1. Drag the row to the new position in the list. -1. Release the drag icon. - -### Bulk edit issues from a project +## Bulk edit issues from a project > - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. > - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. @@ -283,7 +46,7 @@ To edit multiple issues at the same time: When bulk editing issues in a project, you can edit the following attributes: - Status (open or closed) -- [Assignees](#assignee) +- [Assignees](managing_issues.md#assignee) - [Epic](../../group/epics/index.md) - [Milestone](../milestones/index.md) - [Labels](../labels.md) @@ -396,6 +159,26 @@ To do it: 1. To exit the Rails console, enter `quit`. +## Reorder list items in the issue description + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.0. + +When you view an issue that has a list in the description, you can also reorder the list items. + +Prerequisites: + +- You must have at least the Reporter role for the project, be the author of the issue, or be + assigned to the issue. +- The issue's description must have an [ordered, unordered](../../markdown.md#lists), or + [task](../../markdown.md#task-lists) list. + +To reorder list items, when viewing an issue: + +1. Hover over the list item row to make the drag icon (**{drag-vertical}**) visible. +1. Select and hold the drag icon. +1. Drag the row to the new position in the list. +1. Release the drag icon. + ## Close an issue When you decide that an issue is resolved or no longer needed, you can close it. @@ -514,8 +297,7 @@ Prerequisites: - You must have [administrator access](../../../administration/index.md) to your GitLab instance. -To change the default issue closing pattern, edit the -[`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) +Learn how to change the default [issue closing pattern](../../../administration/issue_closing_pattern.md). of your installation. ## Change the issue type @@ -622,7 +404,7 @@ GitLab displays the results on-screen, but you can also ### Filter with the OR operator -> OR filtering for assignees was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. +> OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. @@ -633,7 +415,7 @@ When this feature is enabled, you can use the OR operator (**is one of: `||`**) when you [filter the list of issues](#filter-the-list-of-issues). `is one of` represents an inclusive OR. For example, if you filter by `Assignee is one of Sidney Jones` and -`Assignee is one of Zhang Wei`, GitLab shows issues where either Sidney, Zhang, or both of them are assignees. +`Assignee is one of Zhang Wei`, GitLab shows issues where either `Sidney`, `Zhang`, or both of them are assignees. ### Filter issues by ID @@ -674,22 +456,6 @@ To copy the issue's email address: 1. Go to the issue. 1. On the right sidebar, next to **Issue email**, select **Copy Reference** (**{copy-to-clipboard}**). -## Real-time sidebar - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/3413) in GitLab 13.9. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.5. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.9. Feature flags `real_time_issue_sidebar` and `broadcast_issue_updates` removed. - -Some sections of the right sidebar are updated in real time. -When you're viewing an issue and somebody changes one of the values, -you can see the change without having to refresh the page. - -The following sections are updated in real time: - -- [Assignee](#assignee) -- [Labels](../labels.md#assign-and-unassign-labels) - ## Assignee An issue can be assigned to one or [more users](multiple_assignees_for_issues.md). @@ -708,6 +474,8 @@ To change the assignee on an issue: 1. From the dropdown list, select the user to add as an assignee. 1. Select any area outside the dropdown list. +The assignee is changed without having to refresh the page. + ## Similar issues To prevent duplication of issues on the same topic, GitLab searches for similar issues diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 6a1a791645e..a2f90d5c444 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -101,6 +101,19 @@ title in this order: - Numbers - Letters: first Latin, then accented (for example, `ö`) +## Sorting by health status **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377841) in GitLab 15.7. + +When you sort by **Health**, the issue list changes to sort by the +[health status](managing_issues.md#health-status) of the issues +When in descending order, the issues are shown in the following order: + +1. **At risk** issues +1. **Needs attention** issues +1. **On track** issues +1. All other issues + ## Sorting by weight When you sort by **Weight**, the issue list changes to sort ascending by the diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index e8ec954df8f..a7627f12657 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -61,7 +61,7 @@ To add a user to a project: 1. Select **Invite members**. 1. Enter an email address and select a [role](../../permissions.md). 1. Optional. Select an **Access expiration date**. - From that date onwards, the user can no longer access the project. + From that date onward, the user can no longer access the project. 1. Select **Invite**. If the user has a GitLab account, they are added to the members list. @@ -110,7 +110,7 @@ To add a group to a project: 1. Select a group. 1. Select the highest [role](../../permissions.md) for users in the group. 1. Optional. Select an **Access expiration date**. - From that date onwards, the group can no longer access the project. + From that date onward, the group can no longer access the project. 1. Select **Invite**. The members of the group are not displayed on the **Members** tab. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 52cc9fc4f9b..b9887212be0 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -9,83 +9,77 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can share projects with other [groups](../../group/index.md). This makes it possible to add a group of users to a project with a single action. -## Groups as collections of users +For example, if `Project A` belongs to `Group 1`, the members of `Group 1` have access to the project. +If `Project A` already belongs to another `Group 2`, the owner of `Group 2` can share `Project A` +with `Group 1`, so that both members of `Group 1` and `Group 2` have access to the project. -Groups are used primarily to [create collections of projects](../../group/index.md), but you can also -take advantage of the fact that groups define collections of _users_, namely the group -members. +When a project is shared with a group: -## Share a project with a group of users - -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal - window [with a flag](../../feature_flags.md). Disabled by default. -> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) - in GitLab 14.8. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. - [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. - -You can share a project only with: - -- Groups for which you have an explicitly defined [membership](index.md). -- Groups that contain a nested subgroup or project for which you have an explicitly defined role. +- All group members, including members of subgroups or projects that belong to the group, +are assigned the same role in the project. +Each member's role is displayed in **Project information > Members > Max role**. +- The group is listed in the **Groups** tab. +- The project is listed on the group dashboard. -Administrators can share projects with any group in the instance. +Be aware of the restrictions that apply when you share projects with: -The primary mechanism to give a group of users, say 'Engineering', access to a project, -say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project -Acme'. But what if 'Project Acme' already belongs to another group, say 'Open Source'? -This is where the group sharing feature can be of use. +- [Groups with a more restrictive visibility level](#share-projects-with-groups-with-a-more-restrictive-visibility-level). +- [Restricted sharing](#prevent-project-sharing). -To share 'Project Acme' with the 'Engineering' group: +## Share projects with groups with a more restrictive visibility level -1. For 'Project Acme' use the left navigation menu to go to **Project information > Members**. -1. Select **Invite a group**. -1. Add the 'Engineering' group with the maximum access level of your choice. -1. Optional. Select an **Access expiration date**. -1. Select **Invite**. +You can share projects only down the group's organization structure. +This means you can share a project with a group that has a more restrictive +[visibility level](../../public_access.md#project-and-group-visibility) than the project, +but not with a group that has a less restrictive visibility level. -After sharing 'Project Acme' with 'Engineering': +For example, you can share: -- The group is listed in the **Groups** tab. -- The project is listed on the group dashboard. -- All members, including members from the ancestors of the 'Engineering' group, gain access to 'Project Acme' with an access level based on the outcome of [maximum access level](#maximum-access-level). +- A public project with a private group. +- A public project with an internal group. +- An internal project with a private group. -When you share a project, be aware of the following restrictions and outcomes: +This restriction applies to subgroups as well. For example, `group/subgroup01/project`: -- [Maximum access level](#maximum-access-level) -- [Sharing projects with groups of a higher restrictive visibility level](#sharing-projects-with-groups-of-a-higher-restrictive-visibility-level) -- [Sharing project with group lock](#share-project-with-group-lock) +- Can't be shared with `group`. +- Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. -## Maximum access level +When you share a project with a group that has a more restrictive visibility level than the project: -In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. - -### Share a project with a subgroup - -You can't share a project with a group that's an ancestor of a [subgroup](../../group/subgroups/index.md) the project is -in. That means you can only share down the hierarchy. For example, `group/subgroup01/project`: +- The group name is visible to all users that can view the project members page. +- Owners of the project have access to members of the group when they mention them in issues or merge requests. +- Project members who are direct or indirect members of the group can see +group members listed in addition to members of the project. -- Can not be shared with `group`. -- Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. +## Share a project with a group -## Sharing projects with groups of a higher restrictive visibility level +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal + window [with a flag](../../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) + in GitLab 14.8. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. -There are several outcomes you must be aware of when you share a project with a group that has a more restrictive [visibility level](../../public_access.md#project-and-group-visibility) than the project. For example, when you: +You can share a project only with groups: -- Share a public project with a private group. -- Share a public project with an internal group. -- Share an internal project with a private group. +- Where you have an explicitly defined [membership](index.md). +- That contain a nested subgroup or project you have an explicitly defined role for. +- You are an administrator of. -The following outcomes occur: +To share a project with a group: -- The group name is visible to all users that can view the project members page. -- Owners of the project have access to members of the group when they mention them in issues or merge requests. -- Project members who are direct or indirect members of the group can see group members listed in addition to members of the project. +1. On the top bar, select **Main menu > Projects** and find your project. +1. In the left navigation menu, select **Project information > Members**. +1. Select **Invite a group**. +1. **Select a group** you want to add to the project. +1. **Select a role** you want to assign to the group. +1. Optional. Select an **Access expiration date**. +1. Select **Invite**. -## Share project with group lock +## Prevent project sharing -It is possible to prevent projects in a group from +You can prevent members of a group from [sharing a project with another group](../members/share_project_with_groups.md). -This allows for tighter control over project access. +This restriction allows for tighter control over project access. -Learn more about [Share with group lock](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). +For more information, see [Prevent a project from being shared with groups](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index eb460225858..92ff78082e3 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -22,8 +22,10 @@ flexibility: - Specify a list of users who act as [code owners](../../code_owners.md) for specific files, and require their approval before work can merge. -You can configure merge request approvals on a per-project basis, and -[on the group level](../../../group/manage.md#group-merge-request-approval-settings). Administrators of +You can configure merge request approvals on a per-project basis, and some approvals can be configured +[on the group level](../../../group/manage.md#group-merge-request-approval-settings). Support for +group-level settings for merge request approval rules is tracked in this +[epic](https://gitlab.com/groups/gitlab-org/-/epics/4367). Administrators of [GitLab Premium](https://about.gitlab.com/pricing/) and [GitLab Ultimate](https://about.gitlab.com/pricing/) self-managed GitLab instances can also configure approvals diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index e09a1318981..5f81db10cf4 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -182,7 +182,7 @@ granting them push access: 1. [Create a new group](../../../group/manage.md#create-a-group). 1. [Add the user to the group](../../../group/manage.md#add-users-to-a-group), and select the Reporter role for the user. -1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group-of-users), +1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group), based on the Reporter role. 1. Go to your project and select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval rules**, and either: diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index a2a12b22c3b..a8acab3898b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -21,22 +21,24 @@ To view or edit merge request approval settings: ### Approval settings -These settings limit who can approve merge requests. - -| Setting | Description | -| ------ | ------ | -| [Prevent approval by author](#prevent-approval-by-author) | When enabled, the author of a merge request cannot approve it. | -| [Prevent approvals by users who add commits](#prevent-approvals-by-users-who-add-commits) | When enabled, users who have committed to a merge request cannot approve it. | -| [Prevent editing approval rules in merge requests](#prevent-editing-approval-rules-in-merge-requests) | When enabled, users can't override the project's approval rules on merge requests. | -| [Require user password to approve](#require-user-password-to-approve) | Force potential approvers to first authenticate with a password. | - -You can further define what happens to existing approvals when commits are added to the merge request. - -| Setting | Description | -| ------ | ------ | -| Keep approvals | Do not remove approvals. | -| [Remove all approvals](#remove-all-approvals-when-commits-are-added-to-the-source-branch) | Remove all existing approvals. | -| [Remove approvals by Code Owners if their files changed](#remove-approvals-by-code-owners-if-their-files-changed) | If a Code Owner has approved the merge request, and the commit changes files they are the Code Owner for, their approval is removed. | +These settings limit who can approve merge requests: + +- [**Prevent approval by author**](#prevent-approval-by-author): + Prevents the author of a merge request from approving it. +- [**Prevent approvals by users who add commits**](#prevent-approvals-by-users-who-add-commits): + Prevents users who add commits to a merge request from also approving it. +- [**Prevent editing approval rules in merge requests**](#prevent-editing-approval-rules-in-merge-requests): + Prevents users from overriding project level approval rules on merge requests. +- [**Require user password to approve**](#require-user-password-to-approve): + Force potential approvers to first authenticate with a password. +- Code Owner approval removals: Define what happens to existing approvals when + commits are added to the merge request. + - **Keep approvals**: Do not remove any approvals. + - [**Remove all approvals**](#remove-all-approvals-when-commits-are-added-to-the-source-branch): + Remove all existing approvals. + - [**Remove approvals by Code Owners if their files changed**](#remove-approvals-by-code-owners-if-their-files-changed): + If a Code Owner approves a merge request, and a later commit changes files + they are a Code Owner for, their approval is removed. ## Prevent approval by author diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 6e8b0cb1a75..f6e02dc0dfe 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -136,15 +136,10 @@ Files marked as viewed are not shown to you again unless either: - New changes are made to its content. - You clear the **Viewed** checkbox. -## Show merge request conflicts in diff **(FREE SELF)** +## Show merge request conflicts in diff -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `display_merge_conflicts_in_diff`. Disabled by default. - -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 `display_merge_conflicts_in_diff`. On GitLab.com, this feature is not available. -The feature is not ready for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `display_merge_conflicts_in_diff`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276918) in GitLab 15.7. To avoid displaying the changes that are already on target branch in the diff, we compare the merge request's source branch with HEAD of the target branch. diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 75c2bdffae8..a14d8bddd24 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -70,6 +70,7 @@ GitLab creates a squash commit message with this template: > - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) `url`, `approved_by`, and `merged_by` variables in GitLab 14.7. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) `all_commits` variable in GitLab 14.9. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/378352) `reviewed_by` variable in GitLab 15.7. Commit message templates support these variables: @@ -84,7 +85,8 @@ Commit message templates support these variables: | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | | `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | | `%{url}` | Full URL to the merge request. | `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1` | -| `%{approved_by}` | Line-separated list of the merge request approvers. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | +| `%{reviewed_by}` | Line-separated list of the merge request reviewers, based on users who submit a review via batch comments, in a `Reviewed-by` Git commit trailer format. | `Reviewed-by: Sidney Jones <sjones@example.com>` <br> `Reviewed-by: Zhang Wei <zwei@example.com>` | +| `%{approved_by}` | Line-separated list of the merge request approvers in a `Approved-by` Git commit trailer format. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | | `%{merged_by}` | User who merged the merge request. | `Alex Garcia <agarcia@example.com>` | | `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | | `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.`| diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index a6ae3ac80a5..a9f67c39ae8 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -1,56 +1,11 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +redirect_to: '../merge_requests/index.md' +remove_date: '2023-03-12' --- -# Commits tab in merge requests **(FREE)** +This document was removed. -The **Commits** tab in a merge request displays a sequential list of commits -to the Git branch your merge request is based on. From this page, you can review -full commit messages and copy a commit's SHA when you need to -[cherry-pick changes](cherry_pick_changes.md). - -## Merge requests commit navigation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. - -To seamlessly navigate among commits in a merge request: - -1. Select the **Commits** tab. -1. Select a commit to open it in the single-commit view. -1. Navigate through the commits by either: - - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - - - -## View merge request commits in context - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `context_commits`. Enabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.8. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.9. [Feature flag `context_commits`](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) removed. - -When reviewing a merge request, it helps to have more context about the changes -made. That includes unchanged lines in unchanged files, and previous commits -that have already merged that the change is built on. - -To add previously merged commits to a merge request for more context: - -1. Go to your merge request. -1. Select the **Commits** tab. -1. Scroll to the end of the list of commits, and select **Add previously merged commits**: - -  - -1. Select the commits that you want to add. -1. Select **Save changes**. - -To view the changes done on those previously merged commits: - -1. On your merge request, select the **Changes** tab. -1. Scroll to **(file-tree)** **Compare** and select **previously merged commits**: - -  +<!-- This redirect file can be deleted after <2023-03-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/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index 24f22924a08..6063d64a721 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -75,7 +75,7 @@ To resolve less-complex conflicts from the GitLab user interface: Resolving conflicts merges the target branch of the merge request into the source branch, using the version of the text you chose. If the source branch is `feature` and the target branch is `main`, these actions are similar to running -`git checkout feature; git merge main` locally. +`git switch feature; git merge main` locally. ## Resolve conflicts in the inline editor @@ -101,7 +101,7 @@ most control over each change: 1. Open the terminal and check out your feature branch. For example, `my-feature-branch`: ```shell - git checkout my-feature-branch + git switch my-feature-branch ``` 1. [Rebase your branch](../../../topics/git/git_rebase.md#regular-rebase) against the diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index df11d5a1d8d..eae4db2d4f7 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -102,7 +102,7 @@ You can create a merge request from your fork to contribute back to the main pro change the default target branch (which can be useful if you are working in a forked project). 1. Select **Compare branches and continue**. -1. Select **Submit merge request**. +1. Select **Create merge request**. After your work is merged, if you don't intend to make any other contributions to the upstream project, you can unlink your diff --git a/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png b/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png Binary files differdeleted file mode 100644 index e60e869f854..00000000000 --- a/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/commit_nav_v13_11.png b/doc/user/project/merge_requests/img/commit_nav_v13_11.png Binary files differdeleted file mode 100644 index a9bc8fa6bee..00000000000 --- a/doc/user/project/merge_requests/img/commit_nav_v13_11.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png b/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png Binary files differdeleted file mode 100644 index 4f49fad10ad..00000000000 --- a/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png +++ /dev/null diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md deleted file mode 100644 index 6242a77e931..00000000000 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'dependencies.md' -remove_date: '2022-11-22' ---- - -This document was moved to [another location](dependencies.md). - -<!-- This redirect file can be deleted after <2022-11-22>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index e72c927198e..249a98f1779 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -10,47 +10,107 @@ type: reference, concepts The merge method you select for your project determines how the changes in your merge requests are merged into an existing branch. +The examples on this page assume a `main` branch with commits A, C, and E, and a +`feature` branch with commits B and D: + +```mermaid +gitGraph + commit id: "A" + branch feature + commit id: "B" + commit id: "D" + checkout main + commit id: "C" + commit id: "E" +``` + ## Configure a project's merge method 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Merge requests**. -1. In the **Merge method** section, select your desired merge method. +1. Select your desired **Merge method** from these options: + - Merge commit + - Merge commit with semi-linear history + - Fast-forward merge +1. In **Squash commits when merging**, select the default behavior for handling commits: + - **Do not allow**: Squashing is never performed, and the user cannot change the behavior. + - **Allow**: Squashing is off by default, but the user can change the behavior. + - **Encourage**: Squashing is on by default, but the user can change the behavior. + - **Require**: Squashing is always performed, and the user cannot change the behavior. 1. Select **Save changes**. ## Merge commit -This setting is the default. It always creates a separate merge commit, -even when using [squash](../squash_and_merge.md). An example commit graph generated using this merge method: +By default, GitLab creates a merge commit when a branch is merged into `main`. +A separate merge commit is always created, regardless of whether or not commits +are [squashed when merging](../squash_and_merge.md). This strategy can result +in both a squash commit and a merge commit being added to your `main` branch. + +These diagrams show how the `feature` branch merges into `main` if you use the +**Merge commit** strategy. They are equivalent to the command `git merge --no-ff <feature>`, +and selecting `Merge commit` as the **Merge method** in the GitLab UI: + +The merge strategy: ```mermaid +%%{init: { 'gitGraph': {'logLevel': 'debug', 'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'main'}} }%% gitGraph - commit id: "Init" - branch mr-branch-1 - commit - checkout main - commit - branch mr-branch-2 - commit - checkout mr-branch-1 - commit - checkout main - branch squash-mr - commit id: "Squashed commits" - checkout main - merge squash-mr - merge mr-branch-1 - commit - merge mr-branch-2 + commit id: "A" + branch feature + commit id: "B" + commit id: "D" + checkout main + commit id: "C" + commit id: "E" + merge feature +``` + +After a feature branch is merged with the **Merge commit** method, your `main` branch +looks like this: + +```mermaid +%%{init: { 'gitGraph': {'logLevel': 'debug', 'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'main'}} }%% +gitGraph + commit id: "A" + commit id: "C" + commit id: "E" + commit id: "squash commit" + commit id: "merge commit" ``` -- For regular merges, it is equivalent to the command `git merge --no-ff <source-branch>`. -- For squash merges, it squashes all commits in the source branch before merging it normally. It performs actions similar to: +In comparison, a **squash merge** constructs a squash commit, a virtual copy of all commits +from the `feature` branch. The original commits (B and D) remain unchanged +on the `feature` branch, and the squash commit is placed on the `main` branch: + +```mermaid +%%{init: { 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'main'}} }%% +gitGraph + commit id:"A" + branch feature + checkout main + commit id:"C" + checkout feature + commit id:"B" + commit id:"D" + checkout main + commit id:"E" + commit id:"squash commit" type: HIGHLIGHT +``` + +The squash merge graph is equivalent to these settings in the GitLab UI: + +- **Merge method**: Merge commit. +- **Squash commits when merging** should be set to either: + - Require. + - Either Allow or Encourage, and squashing must be selected on the merge request. + +The squash merge graph is also equivalent to these commands: ```shell - git checkout `git merge-base <source-branch> <target-branch>` - git merge --squash <source-branch> + git checkout `git merge-base feature main` + git merge --squash <feature> SOURCE_SHA=`git rev-parse HEAD` - git checkout <target-branch> + git checkout <main> git merge --no-ff $SOURCE_SHA ``` @@ -58,7 +118,8 @@ gitGraph A merge commit is created for every merge, but the branch is only merged if a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build also succeeds after the merge. An example commit graph generated using this merge method: +succeeded, the target branch build also succeeds after the merge. An example +commit graph generated using this merge method: ```mermaid gitGraph @@ -113,8 +174,8 @@ This method is equivalent to `git merge --ff <source-branch>` for regular merges When the fast-forward merge ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting -is enabled, no merge commits are created and all merges are fast-forwarded, -which means that merging is only allowed if the branch can be fast-forwarded. +is enabled, no merge commits are created and all merges are fast-forwarded. +Merging is only allowed if the branch can be fast-forwarded. When a fast-forward merge is not possible, the user is given the option to rebase, see [Rebasing in (semi-)linear merge methods](#rebasing-in-semi-linear-merge-methods). @@ -136,11 +197,16 @@ In these merge methods, you can merge only when your source branch is up-to-date - Fast-forward merge. If a fast-forward merge is not possible but a conflict-free rebase is possible, -GitLab offers you the [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui), -and the ability to select **Rebase** from the user interface. +GitLab provides: + +- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). +- The option to select **Rebase** in the user interface. + +You must rebase the source branch locally before a fast-forward merge if both +conditions are true: -If the target branch is ahead of the source branch and a conflict-free rebase is -not possible, you must rebase the source branch locally before you can do a fast-forward merge. +- The target branch is ahead of the source branch. +- A conflict-free rebase is not possible.  diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index 3a3af7a24bc..f17015aef4e 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -27,7 +27,7 @@ This feature is designed as a progressive enhancement to the existing GitLab Rev ## Model Accuracy -Organizations use many different processes for code review. Some focus on senior engineers reviewing junior engineer's code, others have hierarchical organizational structure based reviews. Suggested Reviewers is focused on contextual reviewers based on historical merge request activity by users. While we will continue evolving the underlying ML model to better serve various code review use cases and processes Suggested Reviewers does not replace the usage of other code review features like Code Owners and [Approval Rules](../approvals/rules.md). Reviewer selection is highly subjective therefore, we do not expect Suggested Reviewers to provide perfect suggestions everytime. +Organizations use many different processes for code review. Some focus on senior engineers reviewing junior engineer's code, others have hierarchical organizational structure based reviews. Suggested Reviewers is focused on contextual reviewers based on historical merge request activity by users. While we will continue evolving the underlying ML model to better serve various code review use cases and processes Suggested Reviewers does not replace the usage of other code review features like Code Owners and [Approval Rules](../approvals/rules.md). Reviewer selection is highly subjective therefore, we do not expect Suggested Reviewers to provide perfect suggestions every time. Through analysis of beta customer usage, we find that the Suggested Reviewers ML model provides suggestions that are adopted in 60% of cases. We will be introducing a feedback mechanism into the Suggested Reviewers feature in the future to allow users to flag bad reviewer suggestions to help improve the model. Additionally we will be offering an opt-in feature in the future which will allow the model to use your project's data for training the underlying model. @@ -39,6 +39,6 @@ Suggested Reviewers is off by default and requires a Project Owner or Admin to e Suggested Reviewers operates completely within the GitLab.com infrastructure providing the same level of [privacy](https://about.gitlab.com/privacy/) and [security](https://about.gitlab.com/security/) of any other feature of GitLab.com. -No new additional data is collected to enable this feature. GitLab is inferencing your merge request against a trained machine learning model. The content of your source code is not used as training data. Your data also never leaves GitLab.com, all training and inference is done within GitLab.com infrastructure. +No new additional data is collected to enable this feature. GitLab infers your merge request against a trained machine learning model. The content of your source code is not used as training data. Your data also never leaves GitLab.com, all training and inference is done within GitLab.com infrastructure. [Read more about the security of GitLab.com](https://about.gitlab.com/security/faq/) diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png Binary files differdeleted file mode 100644 index 927b4f812a5..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 4c503211513..9a75c038dbc 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -71,6 +71,52 @@ if you [approve a merge request](../approvals/index.md#approve-a-merge-request) are shown in the reviewer list, a green check mark **{check-circle-filled}** displays next to your name. +### Download merge request changes as a diff + +To download the changes included in a merge request as a diff: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. +1. Select your merge request. +1. On the top right, select **Code > Plain diff**. + +If you know the URL of the merge request, you can also download the diff from +the command line by appending `.diff` to the URL. This example downloads the diff +for merge request `000000`: + +```plaintext +https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff +``` + +To download and apply the diff in a one-line CLI command: + +```shell +curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff" | git apply +``` + +### Download merge request changes as a patch file + +To download the changes included in a merge request as a patch file: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. +1. Select your merge request. +1. On the top right, select **Code > Email patches**. + +If you know the URL of the merge request, you can also download the patch from +the command line by appending `.patch` to the URL. This example downloads the patch +file for merge request `000000`: + +```plaintext +https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.patch +``` + +To download and apply the patch in a one-line CLI command using [`git am`](https://git-scm.com/docs/git-am): + +```shell +curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.patch" | git am +``` + ### Submit a review You can submit your completed review in multiple ways: diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 832f78d18a1..668dece9fda 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -74,7 +74,13 @@ To add a suggestion that includes a [fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks instead of three: - +~~~markdown +````suggestion:-0+2 +```shell +git config --global receive.advertisepushoptions true +``` +```` +~~~  diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index d330ccdefb6..74c3b3e24b6 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -6,7 +6,7 @@ type: reference, concepts disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html' --- -# External Status Checks **(ULTIMATE)** +# External status checks **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. diff --git a/doc/user/project/ml/experiment_tracking/img/candidate_v15_7.png b/doc/user/project/ml/experiment_tracking/img/candidate_v15_7.png Binary files differnew file mode 100644 index 00000000000..fb2e2e706d6 --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/candidate_v15_7.png diff --git a/doc/user/project/ml/experiment_tracking/img/candidates.png b/doc/user/project/ml/experiment_tracking/img/candidates.png Binary files differdeleted file mode 100644 index df70a01a2bd..00000000000 --- a/doc/user/project/ml/experiment_tracking/img/candidates.png +++ /dev/null diff --git a/doc/user/project/ml/experiment_tracking/img/candidates_v15_7.png b/doc/user/project/ml/experiment_tracking/img/candidates_v15_7.png Binary files differnew file mode 100644 index 00000000000..58dfe94a108 --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/candidates_v15_7.png diff --git a/doc/user/project/ml/experiment_tracking/img/experiments.png b/doc/user/project/ml/experiment_tracking/img/experiments.png Binary files differdeleted file mode 100644 index a6472406b90..00000000000 --- a/doc/user/project/ml/experiment_tracking/img/experiments.png +++ /dev/null diff --git a/doc/user/project/ml/experiment_tracking/img/experiments_v15_7.png b/doc/user/project/ml/experiment_tracking/img/experiments_v15_7.png Binary files differnew file mode 100644 index 00000000000..a7d4a3e559f --- /dev/null +++ b/doc/user/project/ml/experiment_tracking/img/experiments_v15_7.png diff --git a/doc/user/project/ml/experiment_tracking/index.md b/doc/user/project/ml/experiment_tracking/index.md index e274bd7f38e..a7096d633a0 100644 --- a/doc/user/project/ml/experiment_tracking/index.md +++ b/doc/user/project/ml/experiment_tracking/index.md @@ -16,9 +16,11 @@ engineering, and so on, to improve the performance of the model. Keeping track o artifacts so that the data scientist can later replicate the experiment is not trivial. Machine learning experiment tracking enables them to log parameters, metrics, and artifacts directly into GitLab, giving easy access later on. - + - + + + ## What is an experiment? @@ -53,18 +55,19 @@ integration. More information on how to use GitLab as a backend for MLFlow Clien ### Exploring model candidates To list the current active experiments, navigate to `https/-/ml/experiments`. To display all trials -that have been logged, along with their metrics and parameters, selecting an experiment. +that have been logged, along with their metrics and parameters, select an experiment. To display details for a candidate, +select **Details**. ### Logging artifacts Trial artifacts are saved as [generic packages](../../../packages/generic_packages/index.md), and follow all their conventions. After an artifact is logged for a candidate, all artifacts logged for the candidate are listed in the -package registry. The package name for a candidate is `ml_candidate_<candidate_id>`, with version `-`. +package registry. The package name for a candidate is `ml_candidate_<candidate_id>`, with version `-`. The link to the +artifacts can also be accessed from the **Experiment Candidates** list or **Candidate detail**. ### Limitations and future - Searching experiments, searching trials, visual comparison of trials, and creating, deleting and updating experiments and trials through GitLab UI is under development. -- No support for experiment and trial metadata that do not classify as parameters or metrics. ## Disabling or enabling the Feature @@ -73,4 +76,6 @@ On GitLab.com, this feature is currently on private testing. ## Feedback, roadmap and reports -For updates on the development, feedback and bug reports, refer to the [development epic](https://gitlab.com/groups/gitlab-org/-/epics/8560). +For updates on the development, refer to the [development epic](https://gitlab.com/groups/gitlab-org/-/epics/8560). + +For feedback, bug reports and feature requests, refer to the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/381660). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 1d32091b294..197524f2fc5 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -35,7 +35,7 @@ for the most popular hosting services: - [123-reg](https://www.123-reg.co.uk/support/domains/domain-name-server-dns-management-guide/) - [Amazon](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) - [Bluehost](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) -- [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) +- [Cloudflare](https://developers.cloudflare.com/fundamentals/get-started/setup/) - [cPanel](https://documentation.cpanel.net/display/84Docs/Edit+DNS+Zone) - [DigitalOcean](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/) - [DreamHost](https://help.dreamhost.com/hc/en-us/articles/360035516812) diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png Binary files differdeleted file mode 100644 index d92a981dc60..00000000000 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png +++ /dev/null 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 6378d962ffe..dc23540bd1b 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 @@ -52,15 +52,14 @@ this document for an [overview on DNS records](dns_concepts.md). #### 1. Add a custom domain -Navigate to your project's **Setting > Pages** and select **+ New domain** -to add your custom domain to GitLab Pages. You can choose whether to: +To add your custom domain to GitLab Pages: -- Add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). -- Leave it blank (it can be added later). - -Select **Create New Domain**. - - +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. +1. In the top right, select **New Domain**. +1. In **Domain**, enter your domain. +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. +1. Select **Create New Domain**. #### 2. Get the verification code @@ -292,8 +291,6 @@ meet these requirements. - To add the certificate to a domain previously added, go to your project's **Settings > Pages**, locate your domain name, select **Details** and **Edit** to add the certificate. - - 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) 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 caf98e8a8a4..339ab239588 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 @@ -26,13 +26,12 @@ 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. -You can watch the pipeline run by navigating to **CI/CD > Pipelines**. +To view the pipeline, go to **CI/CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. -To view the HTML and other assets that were created for the site, -go to the **Pipelines** tab, view the job, and on the right side, -select **Download artifacts**. - For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. + +To view the HTML and other assets that were created for the site, +[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). 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 69c60cab4b3..9841e52a089 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 @@ -29,32 +29,37 @@ When the pipeline is finished, go to **Settings > Pages** to find the link to yo For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. -To view the HTMl and other assets that were created for the site, -go to the **Pipelines** tab, view the job, and on the right side, -select **Download artifacts**. +## Remove the fork relationship -You can take some **optional** further steps: +If you want to contribute to the project you forked from, +you can keep the forked relationship. Otherwise: -- Remove the fork relationship. If you want to contribute to the project you forked from, - you can keep this relationship. Otherwise, go to your project's **Settings > General**, - expand **Advanced settings**, and scroll down to **Remove fork relationship**: +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced settings**. +1. Select **Remove fork relationship**. -  +## Change the URL -- Change the URL to match your namespace. If your Pages site is hosted on GitLab.com, - you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace - (the one you chose when you forked the project). +You can change the URL to match your namespace. +If your Pages site is hosted on GitLab.com, +you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace +(the one you chose when you forked the project). - - Go to your project's **Settings > General** and expand **Advanced**. Scroll down to - **Change path** and change the path to `<namespace>.gitlab.io`. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In **Change path**, update the path to `<namespace>.gitlab.io`. - For example, if your project's URL is `gitlab.com/gitlab-tests/jekyll`, your namespace is - `gitlab-tests`. + For example, if your project's URL is `gitlab.com/gitlab-tests/jekyll`, your namespace is + `gitlab-tests`. - If you set the repository path to `gitlab-tests.gitlab.io`, - the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`. + If you set the repository path to `gitlab-tests.gitlab.io`, + the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`. -  +  - - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-base-urls) - from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. +1. Open your SSG configuration file and change the [base URL](../getting_started_part_one.md#urls-and-base-urls) + from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. + +## Related topics + +- [Download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts) 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 c0a1e8f16e0..ebadf39a984 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -420,9 +420,8 @@ Now GitLab CI/CD not only builds the website, but also: - **Caches** dependencies installed with Bundler. - **Continuously deploys** every push to the `main` branch. -To view the HTMl and other assets that were created for the site, -go to the **Pipelines** tab, view the job, and on the right side, -select **Download artifacts**. +To view the HTML and other assets that were created for the site, +[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). ## Related topics 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 e4890954d13..a0f9753a40c 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 @@ -29,6 +29,5 @@ your Pages website. For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. -To view the HTMl and other assets that were created for the site, -go to the **Pipelines** tab, view the job, and on the right side, -select **Download artifacts**. +To view the HTML and other assets that were created for the site, +[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index ba97fcb8749..a6069b473e6 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -4,59 +4,69 @@ group: Incubation 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 --- -# Tutorial: Use the GitLab UI to deploy your static site **(FREE)** +# Create a Pages deployment for your static site **(FREE)** -This tutorial assumes you have a project that either: +If you already have a GitLab project that contains your static site or framework, +you can generate a GitLab Pages website from it. -- Generates static sites or a client-rendered single-page application (SPA), - such as [Eleventy](https://www.11ty.dev), [Astro](https://astro.build), or [Jekyll](https://jekyllrb.com). -- Contains a framework configured for static output, such as [Next.js](https://nextjs.org), - [Nuxt.js](https://nuxtjs.org), or [SvelteKit](https://kit.svelte.dev). +When you provide basic information in the UI, a `.gitlab-ci.yml` file is created +and a merge request opened. When you commit the merge request, +a pipeline deploys your Pages website. -## Update your app to output files to the `public` folder +## Prerequisites -GitLab Pages requires all files intended to be part of the published website to -be in a root-level folder called `public`. If you create this folder during the build -pipeline, committing it to Git is not required. +- Your app must [output files to the `public` folder](../public_folder.md). If you create + this folder during the build pipeline, you do not need to commit it to Git. -For detailed instructions, read [Configure the public files folder](../public_folder.md). + WARNING: + This step is important. Ensure your files are in a root-level `public` folder. -## Set up the `.gitlab-ci.yml` file +- You must have a project that either: + - Generates static sites or a client-rendered single-page application (SPA), + like [Eleventy](https://www.11ty.dev), [Astro](https://astro.build), or [Jekyll](https://jekyllrb.com). + - Contains a framework configured for static output, such as [Next.js](https://nextjs.org), + [Nuxt.js](https://nuxtjs.org), or [SvelteKit](https://kit.svelte.dev). +- GitLab Pages must be enabled for the project. (To enable, go to **Settings > General**, + expand **Visibility, project features, permissions**, and turn on the **Pages** toggle.) -GitLab helps you write the `.gitlab-ci.yml` needed to create your first GitLab Pages -deployment pipeline. Rather than building the file from scratch, it asks you to -provide the build commands, and creates the necessary boilerplate for you. +## Create the Pages deployment -To build your YAML file from the GitLab UI: +To complete the setup and generate a GitLab Pages deployment: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages** to display the friendly - interface **Get Started With Pages**. -1. If your framework's build process does not need one of the provided build - commands, you can either: +1. On the left sidebar, select **Settings > Pages**. A **Get Started with Pages** form appears. + If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). +1. For **Step 1**, enter an image name and verify that your files are in a `public` folder. +1. Select **Next**. +1. For **Step 2**, enter your installation steps. If your framework's build process does not + need one of the provided build commands, you can either: - Skip the step by selecting **Next**. - Enter `:` (the bash "do nothing" command) if you still want to incorporate that step's boilerplate into your `.gitlab-ci.yml` file. -1. Optional. Edit and adjust the generated `.gitlab-ci.yml` file as needed. -1. Commit your `.gitlab-ci.yml` to your repository. This commit triggers your first +1. Select **Next**. +1. For **Step 3**, enter scripts that indicate how to build your application. +1. Select **Next**. +1. Optional. Edit the generated `.gitlab-ci.yml` file as needed. +1. For **Step 4**, add a commit message and select **Commit**. This commit triggers your first GitLab Pages deployment. -To view the HTMl and other assets that were created for the site, -go to **CI/CD > Pipelines**, view the job, and on the right side, -select **Download artifacts**. +To view the running pipeline, go to **CI/CD > Pipelines**. + +To view the artifacts that were created during the deployment, view the job, +and on the right side, select **Download artifacts**. ## Troubleshooting -### If you can't see the "Get Started with Pages" interface +### If the `Get Started with Pages` form is not available -GitLab doesn't show this interface if you have either: +When you go to **Settings > Pages**, the form is not available if you: - Deployed a GitLab Pages site before. -- Committed a `.gitlab-ci.yml` through this interface at least once. +- Committed a `.gitlab-ci.yml` through the forms at least one time. -To fix this problem: +To fix this issue: -- If you see the message **Waiting for the Pages Pipeline to complete**, select - **Start over** to start the wizard again. +- If the message **Waiting for the Pages Pipeline to complete** appears, select + **Start over** to start the form again. - If your project has previously deployed GitLab Pages successfully, - [manually update](pages_from_scratch.md) your `.gitlab-ci.yml`. + [manually update](pages_from_scratch.md) your `.gitlab-ci.yml` file. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 588d94729e2..a0c8073d6eb 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -87,7 +87,7 @@ Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, whenever you publish a project website (`namespace.gitlab.io/project-name`), -you must look for this configuration (base URL) on your SSG's +you must look for this configuration (base URL) on your static site generator's documentation and set it up to reflect this pattern. For example, for a Jekyll site, the `baseurl` is defined in the Jekyll diff --git a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png b/doc/user/project/pages/img/remove_fork_relationship_v13_1.png Binary files differdeleted file mode 100644 index 84aa2e571c7..00000000000 --- a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png +++ /dev/null diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index a19e296b954..8c9f1cbec86 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -2,40 +2,39 @@ description: 'Learn how to configure the build output folder for the most common static site generators' stage: Create -group: Incubation +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the public files folder **(FREE)** -GitLab Pages requires all files you intend to be available in the published website to -be in a root-level folder called `public`. This page describe how -to set this up for some common static site generators. +All the files that should be accessible by the browser must be in a root-level folder called `public`. -## Guide by framework +Follow these instructions to configure the `public` folder +for the following frameworks. -### Eleventy +## Eleventy -For Eleventy, you should either: +For Eleventy, you should do one of the following: -1. Add the `--output=public` flag in Eleventy's build commands, for example: +- Add the `--output=public` flag in Eleventy's build commands, for example: - `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` + `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` -1. Add the following to your `.eleventy.js` file: +- Add the following to your `.eleventy.js` file: - ```javascript - // .eleventy.js - module.exports = function(eleventyConfig) { - return { - dir: { - output: "public" - } - } - }; - ``` + ```javascript + // .eleventy.js + module.exports = function(eleventyConfig) { + return { + dir: { + output: "public" + } + } + }; + ``` -### Astro +## Astro By default, Astro uses the `public` folder to store static assets. For GitLab Pages, rename that folder to a collision-free alternative first: @@ -65,11 +64,11 @@ rename that folder to a collision-free alternative first: }); ``` -### SvelteKit +## SvelteKit NOTE: GitLab Pages supports only static sites. For SvelteKit, -we recommend using [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites). +you can use [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites). When using `adapter-static`, add the following to your `svelte.config.js`: @@ -86,11 +85,11 @@ export default { }; ``` -### Next.js +## Next.js NOTE: -GitLab Pages supports only static sites. For Next.js, we -recommend using Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export) +GitLab Pages supports only static sites. For Next.js, you can use +Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export). Use the `-o public` flag after `next export` as the build command, for example: @@ -118,7 +117,7 @@ GitLab Pages supports only static sites. 1. Configure your Nuxt.js application for [Static Site Generation](https://nuxtjs.org/docs/features/deployment-targets/#static-hosting). -### Vite +## Vite Update your `vite.config.js` to include the following: @@ -131,7 +130,7 @@ export default { } ``` -### Webpack +## Webpack Update your `webpack.config.js` to include the following: @@ -147,9 +146,9 @@ module.exports = { ## Should you commit the `public` folder? Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks -for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. So +for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. If you set up a job that creates the `public` folder before deploy, such as by running `npm run build`, committing the folder isn't required. If you prefer to build your site locally, you can commit the `public` folder and -omit the build step during the job, instead. +omit the build step during the job instead. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 96de457c7f7..cf0c0dbff82 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -108,9 +108,8 @@ and an [HTTP status code](#http-status-codes): ## Rewrites -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. -> - Enabled on GitLab.com. -> - Disabled by default in self-managed GitLab behind the [`FF_ENABLE_PLACEHOLDERS` feature flag](#feature-flag-for-rewrites). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3 [with a flag](../../../administration/feature_flags.md) named `FF_ENABLE_PLACEHOLDERS`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/619) in GitLab 15.2. Provide a status code of `200` to serve the content of the `to` path when the request matches the `from`: @@ -267,28 +266,3 @@ However, there are some minor differences: - Netlify redirects to `/new/:placeholder` (with a literal `:placeholder`). - GitLab redirects to `/new/`. - -## Feature flag for rewrites - -FLAG: -Rewrites in GitLab Pages is under development, and is deployed behind a feature flag -that is **disabled by default**. - -To enable rewrites, for [Omnibus installations](../../../administration/pages/index.md), define the -`FF_ENABLE_PLACEHOLDERS` environment variable in the -[global settings](../../../administration/pages/index.md#global-settings). -Add the following line to `/etc/gitlab/gitlab.rb` and -[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure): - -```ruby -gitlab_pages['env']['FF_ENABLE_PLACEHOLDERS'] = 'true' -``` - -For [source installations](../../../administration/pages/source.md), define the -`FF_ENABLE_PLACEHOLDERS` environment variable, then -[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): - -```shell -export FF_ENABLE_PLACEHOLDERS="true" -/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf -``` diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index b31ef858d59..9e5413b020e 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -61,10 +61,10 @@ time as pushing changes: | `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch or upstream project, such as: `git push -o merge_request.target=project_path/branch` | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | | `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26752) | | `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | -| `merge_request.draft` | Mark the merge request as a draft. Ex: `git push -o merge_request.draft`. | [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/296673) | -| `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. Ex: `git push -o merge_request.milestone="3.0"`. | [14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960) | +| `merge_request.title="<title>"` | Set the title of the merge request. For example: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | +| `merge_request.description="<description>"` | Set the description of the merge request. For example: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | +| `merge_request.draft` | Mark the merge request as a draft. For example: `git push -o merge_request.draft`. | [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/296673) | +| `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. For example: `git push -o merge_request.milestone="3.0"`. | [14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960) | | `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904), support for usernames added in [15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276) | diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 7b7619cfeb5..a73a5329688 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -72,13 +72,13 @@ threads. Some quick actions might not be available to all subscription tiers. | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | | `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). Use for toggling the draft status ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.) | | `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. Also, mark both as related. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | | `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | | `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | | `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | | `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | -| `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | | `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | | `/link` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a link and description to [linked resources](../../operations/incident_management/linked_resources.md) in an incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5). | | `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 75a25678125..6d5378bddb7 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -184,20 +184,20 @@ is not available. ## Edit a release -Only users with at least the Developer role can edit releases. -Read more about [Release permissions](#release-permissions). +To edit the details of a release after it's created, you can use the +[Update a release API](../../../api/releases/index.md#update-a-release) or the UI. -To edit the details of a release: +Prerequisites: + +- You must have at least the Developer role. + +In the UI: 1. On the left sidebar, select **Deployments > Releases**. 1. In the top-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**. -You can edit the release title, notes, associated milestones, and asset links. -To change the release date use the -[Releases API](../../../api/releases/index.md#update-a-release). - ## Delete a release > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213862) in GitLab 15.2 @@ -209,11 +209,15 @@ Prerequisites: - You must have at least the Developer role. Read more about [Release permissions](#release-permissions). -To delete a release in the UI: +To delete a release, use either the +[Delete a release API](../../../api/releases/index.md#delete-a-release) or the UI. + +In the UI: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). +1. In the top-right corner of the release you want to delete, select **Edit this release** + (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. 1. Select **Delete release**. @@ -449,11 +453,11 @@ In the API: ## Release permissions -> [The permission model for create, update and delete actions was fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/327505) in GitLab 14.1. +> Fixes to the permission model for create, update and delete actions [were introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327505) in GitLab 14.1. ### View a release and download assets -> [Changes were made to the Guest role access](https://gitlab.com/gitlab-org/gitlab/-/issues/335209) in GitLab 14.5. +> Changes to the Guest role [were introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335209) in GitLab 14.5. - Users with at least the Reporter role have read and download access to the project releases. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 6801899160d..87caeee73e3 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -36,11 +36,15 @@ the [Git commands you need](#update-the-default-branch-name-in-your-repository) ## Change the default branch name for a project -To update the default branch name for an individual [project](../../index.md): +Prerequisites: -1. Sign in to GitLab with at least the Maintainer role. +- You have the Owner or Maintainer role in the project. + +To update the default branch for an individual [project](../../index.md): + +1. On the top bar, select **Main menu > Projects** and find your project. 1. In the left navigation menu, go to **Settings > Repository**. -1. Expand **Default branch**, and select a new default branch. +1. Expand **Default branch**. For **Initial default branch name**, select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close issues when a merge request [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically). @@ -66,8 +70,8 @@ groups and subgroups can override this instance-wide setting for their projects. 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. -1. Expand **Default initial branch name**. -1. Change the default initial branch to a custom name of your choice. +1. Expand **Default branch**. +1. For **Initial default branch name**, select a new default branch. 1. Select **Save changes**. Projects created on this instance after you change the setting use the @@ -78,11 +82,12 @@ overrides it. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. -Users with at least the Owner role of groups and subgroups can configure the default branch name for a group: +Users with the Owner role of groups and subgroups can configure the default branch name for a group: -1. Go to the group **Settings > Repository**. +1. On the top bar, select **Main menu > Group** and find your group. +1. On the left sidebar, select **Settings > Repository**. 1. Expand **Default branch**. -1. Change the default initial branch to a custom name of your choice. +1. For **Initial default branch name**, select a new default branch. 1. Select **Save changes**. Projects created in this group after you change the setting use the custom branch name, diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 6cc7394e7b3..a86e32b4721 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -101,10 +101,13 @@ This feature allows you to search and select branches quickly. Search results ap - Branches with names that matched search terms exactly. - Other branches with names that include search terms, sorted alphabetically. -Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following: +Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following operators: -- `^feature` matches only branch names that begin with 'feature'. -- `feature$` matches only branch names that end with 'feature'. +- `^` matches beginning of branch name, for example `^feat` would match `feat/user-authentication` +- `$` matches end of branch name, for example `widget$` would match `feat/search-box-widget` +- `*` wildcard matcher, for example `branch*cache*` would match `fix/branch-search-cache-expiration` + +These operators can be mixed, for example `^chore/*migration$` would match `chore/user-data-migration` ## Swap revisions @@ -116,14 +119,26 @@ The Swap revisions feature allows you to swap the Source and Target revisions. W  -<!-- ## Troubleshooting +## Troubleshooting + +### Error: ambiguous `HEAD` branch exists + +In versions of Git earlier than 2.16.0, you could create a branch named `HEAD`. +This branch named `HEAD` collides with the internal reference (also named `HEAD`) +Git uses to describe the active (checked out) branch. This naming collision can +prevent you from updating the default branch of your repository: + +```plaintext +Error: Could not set the default branch. Do you have a branch named 'HEAD' in your repository? +``` + +To fix this problem: -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. +1. Search for a branch named `HEAD`. +1. Make sure the branch has no uncommitted changes. +1. Select **Delete branch**, then **Yes, delete branch**. -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +Git versions [2.16.0 and later](https://github.com/git/git/commit/a625b092cc59940521789fe8a3ff69c8d6b14eb2), +prevent you from creating a branch with this name. diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index a1f57f51f26..6b67ffd0e59 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -4,7 +4,7 @@ group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Signing commits with GPG **(FREE)** +# Sign commits with GPG **(FREE)** You can sign the commits you make in a GitLab repository with a GPG ([GNU Privacy Guard](https://gnupg.org/)) key. When you add a cryptographic @@ -160,14 +160,6 @@ to use this key: git config --global user.signingkey <KEY ID> ``` -1. Optional. If Git uses `gpg` and you get errors like `secret key not available` - or `gpg: signing failed: secret key not available`, run this command to - use `gpg2` instead: - - ```shell - git config --global gpg.program gpg2 - ``` - ### Sign your Git commits After you [add your public key to your account](#add-a-gpg-key-to-your-account), @@ -246,6 +238,7 @@ If you must unverify both future and past commits, ## Related topics - [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) +- [Sign commits with SSH keys](../ssh_signed_commits/index.md) - [Commits API](../../../../api/commits.md) - GPG resources: - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) @@ -269,3 +262,27 @@ or a GPG key. The verification process for both methods can fail for multiple re | `UNVERIFIED_KEY` | The key associated with the GPG signature has no verified email address associated with the committer. | Add and verify the email to your GitLab profile, [update the GPG key to include the email address](https://security.stackexchange.com/a/261468), or amend the commit to use a different committer email address. | | `UNKNOWN_KEY` | The GPG key associated with the GPG signature for this commit is unknown to GitLab. | [Add the GPG key](#add-a-gpg-key-to-your-account) to your GitLab profile. | | `MULTIPLE_SIGNATURES` | Multiple GPG or X.509 signatures have been found for the commit. | Amend the commit to use only one GPG or X.509 signature. | + +### Secret key not available + +If you receive the errors `secret key not available` +or `gpg: signing failed: secret key not available`, try using `gpg2` instead of `gpg`: + +```shell +git config --global gpg.program gpg2 +``` + +If your GPG key is password protected and the password entry prompt does not appear, +add `export GPG_TTY=$(tty)` to your shell's `rc` file (commonly `~/.bashrc` or `~/.zshrc`) + +### GPG failed to sign the data + +If your GPG key is password protected and you receive the error: + +```shell +error: gpg failed to sign the data +fatal: failed to write commit object +``` + +If the password entry prompt does not appear, add `export GPG_TTY=$(tty)` to your shell's `rc` file +(commonly `~/.bashrc` or `~/.zshrc`) and restart your terminal. diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md new file mode 100644 index 00000000000..06affa54a51 --- /dev/null +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -0,0 +1,174 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Sign commits with SSH keys **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343879) in GitLab 15.7 [with a flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `ssh_commit_signatures`. +On GitLab.com, this feature is available. + +Use SSH keys to sign Git commits in the same manner as +[GPG signed commits](../gpg_signed_commits/index.md). When you sign commits +with SSH keys, GitLab uses the SSH public keys associated with your +GitLab account to cryptographically verify the commit signature. +If successful, GitLab displays a **Verified** label on the commit. + +You may use the same SSH keys for `git+ssh` authentication to GitLab +and signing commit signatures as long as their usage type is **Authentication & Signing**. +It can be verified on the page for [adding an SSH key to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account). + +To learn more about managing the SSH keys associated with your GitLab account, read +[use SSH keys to communicate with GitLab](../../../ssh.md). + +## Configure Git to sign commits with your SSH key + +After you [create an SSH key](../../../ssh.md#generate-an-ssh-key-pair) and +[add it to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) +or [generate it using a password manager](../../../ssh.md#generate-an-ssh-key-pair-with-a-password-manager), +configure Git to begin using the key. + +Prerequisites: + +- Git 2.34.0 or newer. +- OpenSSH 8.0 or newer. + + NOTE: + OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8. + +- A SSH key with the usage type of either **Authentication & Signing** or **Signing**. + The SSH key must be one of these types: + - [ED25519](../../../ssh.md#ed25519-ssh-keys) (recommended) + - [RSA](../../../ssh.md#rsa-ssh-keys) + +To configure Git to use your key: + +1. Configure Git to use SSH for commit signing: + + ```shell + git config --global gpg.format ssh + ``` + +1. Specify which SSH key should be used as the signing key, changing the filename + (here, `~/.ssh/examplekey`) to the location of your key. The filename may + differ, depending on how you generated your key: + + ```shell + git config --global user.signingkey ~/.ssh/examplekey + ``` + +## Sign commits with your SSH key + +Prerequisites: + +- You've [created an SSH key](../../../ssh.md#generate-an-ssh-key-pair). +- You've [added the key](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account) to your GitLab account. +- You've [configured Git to sign commits](#configure-git-to-sign-commits-with-your-ssh-key) with your SSH key. + +To sign a commit: + +1. Use the `-S` flag when signing your commits: + + ```shell + git commit -S -m "My commit msg" + ``` + +1. Optional. If you don't want to type the `-S` flag every time you commit, tell + Git to sign your commits automatically: + + ```shell + git config --global commit.gpgsign true + ``` + +1. If your SSH key is protected, Git prompts you to enter your passphrase. +1. Push to GitLab. +1. Check that your commits [are verified](#verify-commits). + Signature verification uses the `allowed_signers` file to associate emails and SSH keys. + For help configuring this file, read [Verify commits locally](#verify-commits-locally). + +## Verify commits + +You can review commits for a merge request, or for an entire project, to confirm +they are signed: + +1. To review commits for a project: + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Repository > Commits**. +1. To review commits for a merge request: + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **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 signature. + Unsigned commits do not display a badge. +1. To display the signature details for a commit, select **Verified**. GitLab shows + the SSH key's fingerprint. + +## Verify commits locally + +To verify commits locally, create an +[allowed signers file](https://man7.org/linux/man-pages/man1/ssh-keygen.1.html#ALLOWED_SIGNERS) +for Git to associate SSH public keys with users: + +1. Create an allowed signers file: + + ```shell + touch allowed_signers + ``` + +1. Configure the `allowed_signers` file in Git: + + ```shell + git config gpg.ssh.allowedSignersFile "$(pwd)/allowed_signers" + ``` + +1. Add your entry to the allowed signers file. Use this command to add your + email address and public SSH key to the `allowed_signers` file. Replace `<MY_KEY>` + with the name of your key, and `~/.ssh/allowed_signers` + with the location of your project's `allowed_signers` file: + + ```shell + # Modify this line to meet your needs. + # Declaring the `git` namespace helps prevent cross-protocol attacks. + echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/<MY_KEY>.pub)" >> ~/.ssh/allowed_signers + ``` + + The resulting entry in the `allowed_signers` file contains your email address, key type, + and key contents, like this: + + ```plaintext + example@gitlab.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmaTS47vRmsKyLyK1jlIFJn/i8wdGQ3J49LYyIYJ2hv + ``` + +1. Repeat the previous step for each user who you want to verify signatures for. + Consider checking this file in to your Git repository if you want to locally + verify signatures for many different contributors. + +1. Use `git log --show-signature` to view the signature status for the commits: + + ```shell + $ git log --show-signature + + commit e2406b6cd8ebe146835ceab67ff4a5a116e09154 (HEAD -> main, origin/main, origin/HEAD) + Good "git" signature for johndoe@example.com with ED25519 key SHA256:Ar44iySGgxic+U6Dph4Z9Rp+KDaix5SFGFawovZLAcc + Author: John Doe <johndoe@example.com> + Date: Tue Nov 29 06:54:15 2022 -0600 + + SSH signed commit + ``` + +## Revoke an SSH key for signing commits + +You can't revoke an SSH key used for signing commits. To learn more, read +[Add revocation for SSH keys](https://gitlab.com/gitlab-org/gitlab/-/issues/382984). + +## Related topics + +- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) +- [Sign commits with GPG](../gpg_signed_commits/index.md) +- [Commits API](../../../../api/commits.md) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 773662edb17..cc89ca0fb1a 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -73,7 +73,7 @@ To close the preview panel, do one of the following: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11 for self-managed instances. Web Editor enables you to highlight a single line by adding specially formatted -hash information to the URL's file path segment. For example, the file path segment +hash information to the file path segment of the URL. For example, the file path segment `MY_FILE.js#L3` instructs the Web Editor to highlight line 3. The Web Editor also enables you to highlight multiple lines using a similar pattern. In diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index e16f5e4defe..42f7be30822 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -160,6 +160,8 @@ can start signing your tags: ## Related topics - [Rake task for X.509 signatures](../../../../raketasks/x509_signatures.md) +- [Sign commits with GPG](../gpg_signed_commits/index.md) +- [Sign commits with SSH keys](../ssh_signed_commits/index.md) ## Troubleshooting diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 199f25f1122..0b52440d1e6 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -202,39 +202,52 @@ worker and it would not recognize `incoming_email` emails. To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: -- Example for installations from source: - - ```yaml - service_desk_email: - enabled: true - address: "project_contact+%{key}@example.com" - user: "project_contact@example.com" - password: "[REDACTED]" - host: "imap.gmail.com" - port: 993 - ssl: true - start_tls: false - log_path: "log/mailroom.log" - mailbox: "inbox" - idle_timeout: 60 - expunge_deleted: true - ``` +::Tabs -- Example for Omnibus GitLab installations: +:::TabTitle Linux package (Omnibus) - ```ruby - gitlab_rails['service_desk_email_enabled'] = true - gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" - gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" - gitlab_rails['service_desk_email_password'] = "[REDACTED]" - gitlab_rails['service_desk_email_mailbox_name'] = "inbox" - gitlab_rails['service_desk_email_idle_timeout'] = 60 - gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" - gitlab_rails['service_desk_email_host'] = "imap.gmail.com" - gitlab_rails['service_desk_email_port'] = 993 - gitlab_rails['service_desk_email_ssl'] = true - gitlab_rails['service_desk_email_start_tls'] = false - ``` +NOTE: +In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. +To use `webhook` on an Omnibus installation running GitLab 15.3, you must generate a secret file. +For more context, visit [Omnibus GitLab MR 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). +In GitLab 15.4, reconfiguring an Omnibus installation generates this secret file automatically, so no secret file configuration setting is needed. +For details, visit [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). + +```ruby +gitlab_rails['service_desk_email_enabled'] = true +gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com" +gitlab_rails['service_desk_email_email'] = "project_contact@gmail.com" +gitlab_rails['service_desk_email_password'] = "[REDACTED]" +gitlab_rails['service_desk_email_mailbox_name'] = "inbox" +gitlab_rails['service_desk_email_idle_timeout'] = 60 +gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log" +gitlab_rails['service_desk_email_host'] = "imap.gmail.com" +gitlab_rails['service_desk_email_port'] = 993 +gitlab_rails['service_desk_email_ssl'] = true +gitlab_rails['service_desk_email_start_tls'] = false +``` + +:::TabTitle Self-compiled (source) + +```yaml +service_desk_email: + enabled: true + address: "project_contact+%{key}@example.com" + user: "project_contact@example.com" + password: "[REDACTED]" + host: "imap.gmail.com" + delivery_method: webhook + secret_file: .gitlab-mailroom-secret + port: 993 + ssl: true + start_tls: false + log_path: "log/mailroom.log" + mailbox: "inbox" + idle_timeout: 60 + expunge_deleted: true +``` + +::EndTabs The configuration options are the same as for configuring [incoming email](../../administration/incoming_email.md#set-it-up). @@ -360,12 +373,17 @@ does not count toward the license limit count. ### Moving a Service Desk issue +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/372246) in GitLab 15.7: customers continue receiving notifications when a Service Desk issue is moved. + Service Desk issues can be moved like any other issue in GitLab. You can move a Service Desk issue the same way you [move a regular issue](issues/managing_issues.md#move-an-issue) in GitLab. -If a Service Desk issue is moved to a different project the customer who created the issue stops receiving emails. +If a Service Desk issue is moved to a different project with Service Desk enabled, +the customer who created the issue continues to receive email notifications. +Because a moved issue is first closed, then copied, the customer is considered to be a participant +in both issues. They continue to receive any notifications in the old issue and the new one. ## Troubleshooting Service Desk diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 3c12bb9b80f..d83a80ddb13 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -12,7 +12,22 @@ then imported into a new GitLab instance. You can also: - [Migrate groups](../../group/import/index.md) using the preferred method. - [Migrate groups using file exports](../../group/settings/import_export.md). -## Set up project import/export +GitLab maps user contributions correctly when an admin access token is used to perform the import. + +As a result, migrating projects using file exports does not map user contributions correctly when you are importing +projects from a self-managed instance to GitLab.com. + +Instead, all GitLab user associations (such as comment author) are changed to the user importing the project. For more +information, see the prerequisites and important notes in these sections: + +- [Export a project and its data](../settings/import_export.md#export-a-project-and-its-data). +- [Import the project](../settings/import_export.md#import-a-project-and-its-data). + +To preserve contribution history, [migrate using direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). + +If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. + +## Set up project to migrate using file exports Before you can import or export a project and its data, you must set it up. @@ -24,8 +39,7 @@ Before you can import or export a project and its data, you must set it up. ## Between CE and EE You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) -and vice versa. This assumes [version history](#version-history) -requirements are met. +and vice versa. This assumes [version history](#version-history) requirements are met. If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see @@ -37,8 +51,7 @@ Before you can import a project, you must export it. Prerequisites: -- Review the list of [items that are exported](#items-that-are-exported). - Not all items are exported. +- Review the list of [items that are exported](#items-that-are-exported). Not all items are exported. - You must have at least the Maintainer role for the project. To export a project and its data, follow these steps: @@ -134,7 +147,7 @@ To import a project: 1. Enter your project name and URL. Then select the file you exported previously. 1. Select **Import project** to begin importing. Your newly imported project page appears shortly. -To get the status of an import, you can query it through the [Project import/export API](../../../api/project_import_export.md#import-status). +To get the status of an import, you can query it through the [API](../../../api/project_import_export.md#import-status). As described in the API documentation, the query may return an import error or exceptions. ### Changes to imported items @@ -187,7 +200,7 @@ Imported users can be mapped by their public email addresses on self-managed ins For project migration imports performed over GitLab.com groups, preserving author information is possible through a [professional services engagement](https://about.gitlab.com/services/migration/). -## Rate Limits +## Rate limits To help avoid abuse, by default, users are rate limited to: @@ -197,9 +210,6 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 projects per minute | -GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) -from the defaults. - ## Version history ### 14.0+ @@ -211,8 +221,8 @@ is NDJSON. ### 13.0+ Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. -This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) -releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). +**This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) +releases**, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). For example: @@ -221,36 +231,9 @@ For example: | 13.0 | 13.0, 12.10, 12.9 | | 13.1 | 13.1, 13.0, 12.10 | -### 12.x - -Prior to 13.0 this was a defined compatibility table: - -| Exporting GitLab version | Importing GitLab version | -| -------------------------- | -------------------------- | -| 11.7 to 12.10 | 11.7 to 12.10 | -| 11.1 to 11.6 | 11.1 to 11.6 | -| 10.8 to 11.0 | 10.8 to 11.0 | -| 10.4 to 10.7 | 10.4 to 10.7 | -| 10.3 | 10.3 | -| 10.0 to 10.2 | 10.0 to 10.2 | -| 9.4 to 9.6 | 9.4 to 9.6 | -| 9.2 to 9.3 | 9.2 to 9.3 | -| 8.17 to 9.1 | 8.17 to 9.1 | -| 8.13 to 8.16 | 8.13 to 8.16 | -| 8.12 | 8.12 | -| 8.10.3 to 8.11 | 8.10.3 to 8.11 | -| 8.10.0 to 8.10.2 | 8.10.0 to 8.10.2 | -| 8.9.5 to 8.9.11 | 8.9.5 to 8.9.11 | -| 8.9.0 to 8.9.4 | 8.9.0 to 8.9.4 | - -Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. - -For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) -and the exports between them are compatible. - ## Related topics -- [Project import/export API](../../../api/project_import_export.md) -- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) -- [Group import/export](../../group/settings/import_export.md) -- [Group import/export API](../../../api/group_import_export.md) +- [Project import and export API](../../../api/project_import_export.md) +- [Project import and export administration Rake tasks](../../../administration/raketasks/project_import_export.md) +- [Migrating GitLab groups](../../group/import/index.md) +- [Group import and export API](../../../api/group_import_export.md) diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index a872a339433..a88427ab20b 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments' type: reference, index, howto --- @@ -75,41 +75,44 @@ To configure visibility, features, and permissions for a project: Use the toggles to enable or disable features in the project. -| Option | More access limit options | Description | -|:---------------------------------|:--------------------------|:--------------| -| **Issues** | ✓ | Activates the GitLab issues tracker. | -| **Repository** | ✓ | Enables [repository](../repository/index.md) functionality | +| Option | More access limit options | Description | +| :------------------------------- | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Issues** | ✓ | Activates the GitLab issues tracker. | +| **Repository** | ✓ | Enables [repository](../repository/index.md) functionality | | **Merge requests** | ✓ | Enables [merge request](../merge_requests/index.md) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). | -| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | -| **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | -| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | -| **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | -| **Container Registry** | | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. | -| **Analytics** | ✓ | Enables [analytics](../../analytics/index.md). | -| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | -| **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | -| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/index.md). | -| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | -| **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | -| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | -| **Releases** | ✓ | Control access to [Releases](../releases/index.md). | +| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | +| **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | +| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | +| **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | +| **Container Registry** | | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. | +| **Analytics** | ✓ | Enables [analytics](../../analytics/index.md). | +| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | +| **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | +| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/index.md). | +| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | +| **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | +| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | +| **Releases** | ✓ | Control access to [Releases](../releases/index.md). | | **Environments** | ✓ | Control access to [Environments and Deployments](../../../ci/environments/index.md). | | **Feature flags** | ✓ | Control access to [Feature Flags](../../../operations/feature_flags.md). | -| **Monitor** | ✓ | Control access to [Monitor](../../../operations/index.md) features. | -| **Infrastructure** | ✓ | Control access to [Infrastructure](../../infrastructure/index.md) features. | +| **Monitor** | ✓ | Control access to [Monitor](../../../operations/index.md) features. | +| **Infrastructure** | ✓ | Control access to [Infrastructure](../../infrastructure/index.md) features. | When you disable a feature, the following additional features are also disabled: - If you disable the **Issues** feature, project users cannot use: + - **Issue Boards** - **Service Desk** - Project users can still access **Milestones** from merge requests. - If you disable **Issues** and **Merge Requests**, project users cannot use: + - **Labels** - **Milestones** - If you disable **Repository**, project users cannot access: + - **Merge requests** - **CI/CD** - **Container Registry** @@ -236,10 +239,8 @@ Prerequisites: - You must have at least the Maintainer role for the [group](../../group/manage.md#create-a-group) to which you are transferring. - You must be the Owner of the project you transfer. - The group must allow creation of new projects. -- The project must not contain any [container images](../../packages/container_registry/index.md#limitations). - - If you transfer a project to a different root namespace, - the project must not contain any - [NPM packages](../../packages/npm_registry/index.md#limitations). +- The project must not contain any [container images](../../packages/container_registry/index.md#known-issues). +- Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. To transfer a project: @@ -262,7 +263,7 @@ When you transfer a project from a namespace licensed for GitLab SaaS Premium or - [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked - [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) -and [test cases](../../../ci/test_cases/index.md) are deleted. + and [test cases](../../../ci/test_cases/index.md) are deleted. ## Delete a project @@ -270,7 +271,7 @@ You can mark a project to be deleted. Prerequisite: -- You must have at least the Owner role for a project. +- You must have the Owner role for a project. To delete a project: @@ -308,7 +309,7 @@ If you don't want to wait, you can delete a project immediately. Prerequisites: -- You must have at least the Owner role for a project. +- You must have the Owner role for a project. - You have [marked the project for deletion](#delete-a-project). To immediately delete a project marked for deletion: @@ -361,11 +362,11 @@ Configure [alert integrations](../../../operations/incident_management/integrati #### Alert integration -Automatically [create](../../../operations/incident_management/incidents.md#create-incidents-automatically), [notify on](../../../operations/incident_management/paging.md#email-notifications-for-alerts), and [resolve](../../../operations/incident_management/incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. +Automatically [create](../../../operations/metrics/alerts.md#trigger-actions-from-alerts), [notify on](../../../operations/incident_management/paging.md#email-notifications-for-alerts), and [resolve](../../../operations/incident_management/manage_incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. #### PagerDuty integration -[Create incidents in GitLab for each PagerDuty incident](../../../operations/incident_management/incidents.md#create-incidents-via-the-pagerduty-webhook). +[Create incidents in GitLab for each PagerDuty incident](../../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook). #### Incident settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index f27672a1b07..cb7ba2a7df2 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -69,6 +69,11 @@ To create a project access token: A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you can't view it again. +WARNING: +Project access tokens are treated as [internal users](../../../development/internal_users.md). +If an internal user creates a project access token, that token is able to access +all projects that have visibility level set to [Internal](../../public_access.md). + ## Revoke a project access token To revoke a project access token: diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 71b8c911839..186ca0ba9f0 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -74,6 +74,25 @@ Prerequisites: - You must have at least the Reporter role for the project. +#### Using the user interface + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101563) in GitLab 15.7. + +To add a time entry using the user interface: + +1. In the **Time tracking** section of the sidebar, select **Add time entry** (**{plus}**). A modal opens. +1. Enter: + + - The amount of time spent. + - Optional. When it was spent. + - Optional. A summary. + +1. Select **Save**. + +The **Spent** total in the sidebar is updated and you can view all entries in a [time tracking report](#view-a-time-tracking-report). + +#### Using a quick action + To enter time spent, use the `/spend` [quick action](quick_actions.md), followed by the time. For example, if you need @@ -90,15 +109,10 @@ Draft MR and respond to initial comments /spend 30m ``` -### Add time spent on a specific date - -Prerequisites: - -- You must have at least the Reporter role for the project. +To log when time was spent, enter a date after the time, using the `YYYY-MM-DD` format. -You can log time in the past by providing a date after the time. For example, to log 1 hour of time spent on 31 January 2021, -type `/spend 1h 2021-01-31`. +enter `/spend 1h 2021-01-31`. If you type a future date, no time is logged. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 0200e9c4e7d..fb100986df9 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -10,6 +10,10 @@ The Web Integrated Development Environment (IDE) editor streamlines the process to contribute changes to your projects, by providing an advanced editor with commit staging. +NOTE: +The Web IDE is being updated to use VS Code. For details, +see [Web IDE Beta](../web_ide_beta/index.md). + ## Open the Web IDE Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md) to open the Web IDE. @@ -80,7 +84,7 @@ If you are missing Syntax Highlighting support for any language, we prepared a s > - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1. > - Full [Solarized Light](https://gitlab.com/gitlab-org/gitlab/-/issues/221035) and [Monokai](https://gitlab.com/gitlab-org/gitlab/-/issues/221034) Themes introduced in GitLab 13.6. -All the themes GitLab supports for syntax highlighting are applied to the Web IDE's entire screen. +All the themes GitLab supports for syntax highlighting are applied to the entire Web IDE screen. You can pick a theme from your [profile preferences](../../profile/preferences.md). | Solarized Dark Theme | Dark Theme | @@ -459,12 +463,3 @@ The Web IDE has a few limitations: - If the terminal displays **Connection Failure**, then the terminal could not connect to the runner. Try to stop and restart the terminal. If the problem persists, double check your runner configuration. - -## VSCode Reimplementation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. - -As announced in [this blog post](https://about.gitlab.com/blog/2022/05/23/the-future-of-the-gitlab-web-ide/), -the current implementation of the Web IDE will be replaced with a [VSCode inspired implementation](https://gitlab.com/groups/gitlab-org/-/epics/7683). - -This effort is currently under development. Follow [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7683) for updates and more information. diff --git a/doc/user/project/web_ide_beta/img/fuzzy_finder_v15_7.png b/doc/user/project/web_ide_beta/img/fuzzy_finder_v15_7.png Binary files differnew file mode 100644 index 00000000000..66ebae15e98 --- /dev/null +++ b/doc/user/project/web_ide_beta/img/fuzzy_finder_v15_7.png diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md new file mode 100644 index 00000000000..ef07cca465d --- /dev/null +++ b/doc/user/project/web_ide_beta/index.md @@ -0,0 +1,103 @@ +--- +stage: Create +group: Editor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Web IDE Beta **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95169) in GitLab 15.4 [with a flag](../../../administration/feature_flags.md) named `vscode_web_ide`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `vscode_web_ide`. On GitLab.com, this feature is available. + +As announced in [this blog post](https://about.gitlab.com/blog/2022/05/23/the-future-of-the-gitlab-web-ide/), +the current implementation of the Web IDE is being replaced with an +implementation inspired by Visual Studio Code. + +This effort is currently under development. For updates, +see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7683). + +## Enable the Web IDE Beta + +To use the Web IDE Beta on a self-managed GitLab instance, +ensure that the `vscode_web_ide` feature flag +[is enabled](../../../administration/feature_flags.md). + +On GitLab.com, this feature is available by default. However, you can +[stop using it if you choose](#stop-using-the-web-ide-beta). + +## Use the Web IDE Beta + +To open the Web IDE Beta from anywhere in the UI: + +- Use the <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md). + +You can also open the Web IDE Beta when viewing a file, the repository file list, +and from merge requests. + +### Use when viewing a file or the repository file list + +To open the Web IDE Beta from a file or the repository file list: + +- On the top right of the page, select **Open in Web IDE**. + +If **Open in Web IDE** is not visible: + +1. Next to **Edit** or **Gitpod**, select the down arrow (**{chevron-lg-down}**). +1. From the list, select **Open in Web IDE**. +1. Select **Open in Web IDE**. + +### Use when viewing a merge request + +To open the Web IDE Beta from a merge request: + +1. Go to your merge request. +1. In the upper right corner, select **Code > Open in Web IDE**. + +## Open a file in the Web IDE Beta + +To open any file by its name: + +1. Type **Command** + **`P`** (<kbd>⌘</kbd> + <kbd>P</kbd>). +1. Type the name of your file. + + + +## Search across files + +You can use VS Code to quickly search all files in the currently opened folder. + +To enter your search term: + +1. Type **Shift** + **Command** + **`F`** (<kbd>⇧</kbd> + <kbd>⌘</kbd> + <kbd>F</kbd>). +1. Enter your search term. + +In the Web IDE Beta, only partial results from opened files are displayed. +Full file search is planned for a later date. + +## View list of changed files + +To view the list of files you changed in the Web IDE Beta: + +- On the VS Code Activity Bar, on the left, select the Source Control icon: + +Your `CHANGES`, `STAGED CHANGES` and `MERGE CHANGES` are displayed. + +For details, see [the VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). + +## Known issues + +The [Web Terminal](../web_ide/index.md#interactive-web-terminals-for-the-web-ide) +and [Live Preview](../web_ide/index.md#live-preview) are not available in the Web IDE Beta. + +These features may become available at a later date. + +### Stop using the Web IDE Beta + +If you do not want to use the Web IDE Beta, you can change your personal preferences. + +1. On the top bar, in the top right corner, select your avatar. +1. Select **Preferences**. +1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. +1. Select **Save changes**. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 0e9b76e943d..53aaa41319b 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -16,8 +16,6 @@ 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). -- Group wikis are enabled by default for GitLab Premium and higher tiers. - You [can't turn them off from the GitLab user interface](https://gitlab.com/gitlab-org/gitlab/-/issues/208413). 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 eedc44be3f9..04a6f9bee80 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -14,7 +14,7 @@ to keep it in the same project as your code, you can use the wiki GitLab provide in each GitLab project. Every wiki is a separate Git repository, so you can create wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). -GitLab wikis support Markdown, RDoc, AsciiDoc, and Org for content. +GitLab wikis support Markdown, Rdoc, AsciiDoc, and Org for content. Wiki pages written in Markdown support all [Markdown features](../../markdown.md), and also provide some [wiki-specific behavior](../../markdown.md#wiki-specific-markdown) for links. @@ -338,11 +338,12 @@ GitLab provides a WYSIWYG editing experience for GitLab Flavored Markdown in wik Support includes: -- Text formatting options, including bold, italics, block quotes, headings, and inline code. -- List formatting for unordered, numbered, and checklists. -- Creating and editing the structure of tables. +- Formatting text, including using bold, italics, block quotes, headings, and inline code. +- Formatting ordered lists, unordered lists, and checklists. +- Creating and editing table structure. - Inserting and formatting code blocks with syntax highlighting. -- Live preview of Mermaid, PlantUML, and Kroki diagrams ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86701) in GitLab 15.2). +- 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 diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 067a0303277..77a7c48658e 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -347,10 +347,27 @@ You can sort projects by: You can also choose to hide or show archived projects. +## Change the visibility of individual features in a project + +You can change the visibility of individual features in a project. + +Prerequisite: + +- You must have the Owner role for the project. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Use the toggle by each feature you want to turn on or off, or change access for. +1. Select **Save changes**. + ## Leave a project -If you leave a project, you are no longer a project -member and cannot contribute. +When you leave a project: + +- You are no longer a project member and cannot contribute. +- All the issues and merge requests that were assigned + to you are unassigned. To leave a project: |
