diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-02-20 16:49:51 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-02-20 16:49:51 +0300 |
| commit | 71786ddc8e28fbd3cb3fcc4b3ff15e5962a1c82e (patch) | |
| tree | 6a2d93ef3fb2d353bb7739e4b57e6541f51cdd71 /doc/user/project | |
| parent | a7253423e3403b8c08f8a161e5937e1488f5f407 (diff) | |
Add latest changes from gitlab-org/gitlab@15-9-stable-eev15.9.0-rc42
Diffstat (limited to 'doc/user/project')
134 files changed, 1875 insertions, 787 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index dc650bd9482..0ea1a80bc54 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,39 +1,145 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Badges **(FREE)** -Badges are a unified way to present condensed pieces of information about your -projects. They consist of a small image and a URL that the image -points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), -[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), [latest release](../../ci/pipelines/settings.md#latest-release-badge), or ways to contact the -project maintainers. +Badges are a unified way to present condensed pieces of information about your projects. +A badge consists of a small image and a URL that the image points to. +In GitLab, badges are displayed below the project description. +You can use badges at the [project](#project-badges) and [group](#group-badges) level.  +## Available badges + +GitLab provides the following pipeline badges: + +- [Pipeline status badge](#pipeline-status-badges) +- [Test coverage report badge](#test-coverage-report-badges) +- [Latest release badge](#latest-release-badges) + +GitLab also supports [custom badges](#customize-badges). + +## Pipeline status badges + +The pipeline status badge indicates the status of the latest pipeline in a project. +Depending on the status of your pipeline, the badge can have one of the following values: + +- `pending` +- `running` +- `passed` +- `failed` +- `skipped` +- `manual` +- `canceled` +- `unknown` + +You can access a pipeline status badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg +``` + +### Display only non-skipped status + +To make the pipeline status badge display only the last non-skipped status, use the `?ignore_skipped=true` query parameter: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true +``` + +## Test coverage report badges + +The test coverage report badge indicates the percentage of code that is tested in a project. +The value is calculated based on the latest successful pipeline. + +You can access a test coverage report badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg +``` + +You can define the regular expression for the [coverage report](../../ci/pipelines/settings.md#merge-request-test-coverage-results) +that each job log is matched against. +This means that each job in the pipeline can have the test coverage percentage value defined. + +To get the coverage report from a specific job, add the `job=coverage_job_name` parameter to the URL. +For example, you can use code similar to the following to add the test coverage report badge of the +`coverage` job to a Markdown file: + +```markdown + +``` + +### Test coverage report badge colors and limits + +The default colors and limits for the badge are as follows: + +- 95 up to and including 100% - good (`#4c1`) +- 90 up to 95% - acceptable (`#a3c51c`) +- 75 up to 90% - medium (`#dfb317`) +- 0 up to 75% - low (`#e05d44`) +- no coverage - unknown (`#9f9f9f`) + +NOTE: +*Up to* means up to, but not including, the upper bound. + +You can overwrite the limits by using the following additional parameters ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28317) in GitLab 14.4): + +- `min_good` (default 95, can use any value between 3 and 100) +- `min_acceptable` (default 90, can use any value between 2 and min_good-1) +- `min_medium` (default 75, can use any value between 1 and min_acceptable-1) + +If an invalid boundary is set, GitLab automatically adjusts it to be valid. For example, +if `min_good` is set `80`, and `min_acceptable` is set to `85` (too high), GitLab automatically +sets `min_acceptable` to `79` (`min_good` - `1`). + +## Latest release badges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33368) in GitLab 14.8. + +The latest release badge indicates the latest release tag name for your project. +If there is no release, it shows `none`. + +You can access a latest release badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/release.svg +``` + +By default, the badge fetches the release sorted using the [`released_at`](../../api/releases/index.md#create-a-release) +time with the `?order_by` query parameter. + +```plaintext +https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at +``` + ## Project badges Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. If you find that you have to add the same badges to several projects, you may want to add them at the [group level](#group-badges). +### Add a badge to a project + To add a new badge to a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. -1. Under "Link", enter the URL that the badges should point to and under - "Badge image URL" the URL of the image that should be displayed. +1. Under **Link**, enter the URL that the badges should point to. +1. Under **Badge image URL**, enter the URL of the image that should be displayed. 1. Select **Add badge**. -After adding a badge to a project, you can see it in the list below the form. -You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by -selecting **Delete** (**{remove}**). +After adding a badge to a project, you can see the badge in the list below the form. -Badges associated with a group can only be edited or deleted on the -[group level](#group-badges). +### Edit or delete a project badge + +To edit a badge, select **Edit** (**{pencil}**). + +To delete a badge, select **Delete** (**{remove}**). ### Example project badge: Pipeline Status @@ -66,6 +172,8 @@ If you need individual badges for each project, either: - Add the badge at the [project level](#project-badges). - Use [placeholders](#placeholders). +### Add a badge to a group + To add a new badge to a group: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -76,33 +184,70 @@ To add a new badge to a group: 1. Select **Add badge**. After adding a badge to a group, you can see it in the list below the form. -You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by -selecting **Delete** (**{remove}**). -Badges directly associated with a project can be configured on the -[project level](#project-badges). +### Edit or delete a group badge -## Placeholders +To edit a badge, select **Edit** (**{pencil}**). -Both the URL a badge points to and the image URL can contain placeholders -which are evaluated when displaying the badge. The following placeholders -are available: +To delete a badge, select **Delete** (**{remove}**). -- `%{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 - project's repository +Badges associated with a group can be edited or deleted only at the [group level](#group-badges). -NOTE: -Placeholders allow badges to expose otherwise-private information, such as the -default branch or commit SHA when the project is configured to have a private -repository. This is by design, as badges are intended to be used publicly. Avoid -using these placeholders if the information is sensitive. +## View the URL of pipeline badges + +You can view the exact link for your badges. +Then you can use the link to embed the badge in your HTML or Markdown pages. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. +1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. + + + +## Customize badges + +You can customize the following aspects of a badge: + +- Style +- Text +- Width +- Image + +### Customize badge style + +Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Two styles are available: + +- Flat (default): + + ```plaintext + https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat + ``` + +  + +- Flat square ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30120) in GitLab 11.8): -## Use custom badge images + ```plaintext + https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square + ``` + +  + +### Customize badge text + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17555) in GitLab 13.1. + +The text for a badge can be customized to differentiate between multiple coverage jobs that run in the same pipeline. +Customize the badge text and width by adding the `key_text=custom_text` and `key_width=custom_key_width` parameters to the URL: + +```plaintext +https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130 +``` + + + +### Customize badge image Use custom badge images in a project or a group if you want to use badges other than the default ones. @@ -118,7 +263,7 @@ Using placeholders, here is an example badge image URL referring to a raw image https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg ``` -To add a new badge to a group or project with a custom image: +To add a new badge with a custom image to a group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Settings > General**. @@ -129,11 +274,31 @@ To add a new badge to a group or project with a custom image: displayed. 1. Select **Add badge**. -To learn how to use custom images generated via a pipeline, see our documentation on +To learn how to use custom images generated through a pipeline, see the documentation on [accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts). -## API +## Placeholders + +Both the URL a badge points to and the image URL can contain placeholders, +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 + project's repository + +NOTE: +Placeholders allow badges to expose otherwise-private information, such as the +default branch or commit SHA when the project is configured to have a private +repository. This behavior is intentional, as badges are intended to be used publicly. Avoid +using these placeholders if the information is sensitive. + +## Configure badges through the API You can also configure badges via the GitLab API. As in the settings, there is -a distinction between endpoints for badges on the +a distinction between endpoints for badges at the [project level](../../api/project_badges.md) and [group level](../../api/group_badges.md). diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md new file mode 100644 index 00000000000..a64edd053b1 --- /dev/null +++ b/doc/user/project/changelogs.md @@ -0,0 +1,317 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +type: reference, api +--- + +# Changelogs + +Changelogs are generated based on commit titles and Git trailers. To be included +in a changelog, a commit must contain a specific Git trailer. Changelogs are generated +from commit titles, and categorized by Git trailer type. You can enrich changelog entries +with additional data, such as a link to the merge request or details about the +commit author. Changelog formats [can be customized](#customize-the-changelog-output) with a template. + +Each section in the default changelog has a title containing the version +number and release date, like this: + +````markdown +## 1.0.0 (2021-01-05) + +### Features (4 changes) + +- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123)) +- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) +- [Feature 3](gitlab-org/gitlab@234abc) by @steve +- [Feature 4](gitlab-org/gitlab@456) +```` + +The date format for sections can be customized, but the rest of the title cannot. +When adding new sections, GitLab parses these titles to determine where to place +the new information in the file. GitLab sorts sections according to their versions, +not their dates. + +Each section contains changes sorted by category (like **Features**), and the format +of these sections can be changed. The section names derive from the values of the +Git trailer used to include or exclude commits. + +Commits for changelogs can be retrieved when operating on a mirror. GitLab itself +uses this feature, because security releases can include changes from both public +projects and private security mirrors. + +## Add a trailer to a Git commit + +You can add trailers manually when you write a commit message. To include a commit +using the default trailer of `Changelog` and categorize it as a feature, add the +string `Changelog: feature` to your commit message, like this: + +```plaintext +<Commit message subject> + +<Commit message description> + +Changelog: feature +``` + +## Create a changelog + +To generate changelog data based on commits in a repository, see +[Add changelog data to a changelog file](../../api/repositories.md#add-changelog-data-to-a-changelog-file) +in the API documentation. + +The changelog output is formatted in Markdown, and [you can customize it](#customize-the-changelog-output). + +### Reverted commits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. + +To be treated as a revert commit, the commit message must contain the string +`This reverts commit <SHA>`, where `SHA` is the SHA of the commit to be reverted. + +When generating a changelog for a range, GitLab ignores commits both added and +reverted in that range. In this example, commit C reverts commit B. Because +commit C has no other trailer, only commit A is added to the changelog: + +```mermaid +graph LR + A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B] +``` + +However, if the revert commit (commit C) _also_ contains a changelog trailer, +both commits A and C are included in the changelog: + +```mermaid +graph LR + A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B<br>Changelog: changed] +``` + +Commit B is skipped. + +### Customize the changelog output + +To customize the changelog output, edit the changelog configuration file. The default +location for this configuration is `.gitlab/changelog_config.yml`. The file supports +these variables: + +- `date_format`: The date format, in `strftime` format, used in the title of the newly added changelog data. +- `template`: A custom template to use when generating the changelog data. +- `include_groups`: A list of group full paths containing users whose contributions + should be credited regardless of project membership. The user generating the changelog + must have access to each group for credit to be given. +- `categories`: A hash that maps raw category names to the names to use in the changelog. + To alter the names displayed in the changelog, add these lines to your configuration file + and edit them to meet your needs. This example renders the category titles as + `### Features`, `### Bug fixes`, and `### Performance improvements`: + + ```yaml + --- + categories: + feature: Features + bug: Bug fixes + performance: Performance improvements + ``` + +### Custom templates + +Category sections are generated using a template. The default template: + +```plaintext +{% if categories %} +{% each categories %} +### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %}) + +{% each entries %} +- [{{ title }}]({{ commit.reference }})\ +{% if author.credit %} by {{ author.reference }}{% end %}\ +{% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} + +{% end %} + +{% end %} +{% else %} +No changes. +{% end %} +``` + +The `{% ... %}` tags are for statements, and `{{ ... }}` is used for printing +data. Statements must be terminated using a `{% end %}` tag. Both the `if` and +`each` statements require a single argument. + +For example, for a variable called `valid`, you can display "yes" +when this value is true, and display "nope" otherwise by doing the following: + +```plaintext +{% if valid %} +yes +{% else %} +nope +{% end %} +``` + +The use of `else` is optional. A value is considered true when it's a non-empty +value or boolean `true`. Empty arrays and hashes are considered false. + +Looping is done using `each`, and variables inside a loop are scoped to it. +Referring to the current value in a loop is done using the variable tag +`{{ it }}`. Other variables read their value from the current loop value. Take +this template for example: + +```plaintext +{% each users %} +{{name}} +{% end %} +``` + +Assuming `users` is an array of objects, each with a `name` field, this would +then print the name of every user. + +Using variable tags, you can access nested objects. For example, +`{{ users.0.name }}` prints the name of the first user in the `users` variable. + +If a line ends in a backslash, the next newline is ignored. This allows you to +wrap code across multiple lines, without introducing unnecessary newlines in the +Markdown output. + +Tags that use `{%` and `%}` (known as expression tags) consume the newline that +directly follows them, if any. This means that this: + +```plaintext +--- +{% if foo %} +bar +{% end %} +--- +``` + +Compiles into this: + +```plaintext +--- +bar +--- +``` + +Instead of this: + +```plaintext +--- + +bar + +--- +``` + +You can specify a custom template in your configuration, like this: + +```yaml +--- +template: | + {% if categories %} + {% each categories %} + ### {{ title }} + + {% each entries %} + - [{{ title }}]({{ commit.reference }})\ + {% if author.credit %} by {{ author.reference }}{% end %} + + {% end %} + + {% end %} + {% else %} + No changes. + {% end %} +``` + +When specifying the template you should use `template: |` and not +`template: >`, as the latter doesn't preserve newlines in the template. + +### Template data + +At the top level, the following variable is available: + +- `categories`: an array of objects, one for every changelog category. + +In a category, the following variables are available: + +- `count`: the number of entries in this category. +- `entries`: the entries that belong to this category. +- `single_change`: a boolean that indicates if there is only one change (`true`), + or multiple changes (`false`). +- `title`: the title of the category (after it has been remapped). + +In an entry, the following variables are available (here `foo.bar` means that +`bar` is a sub-field of `foo`): + +- `author.contributor`: a boolean set to `true` when the author is not a project + member, otherwise `false`. +- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or + when `include_groups` is configured, and the author is a member of one of the + groups. +- `author.reference`: a reference to the commit author (for example, `@alice`). +- `commit.reference`: a reference to the commit, for example, + `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. +- `commit.trailers`: an object containing all the Git trailers that were present + in the commit body. +- `merge_request.reference`: a reference to the merge request that first + introduced the change (for example, `gitlab-org/gitlab!50063`). +- `title`: the title of the changelog entry (this is the commit title). + +The `author` and `merge_request` objects might not be present if the data +couldn't be determined. For example, when a commit is created without a +corresponding merge request, no merge request is displayed. + +### Customize the tag format when extracting versions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56889) in GitLab 13.11. + +GitLab uses a regular expression (using the +[re2](https://github.com/google/re2/) engine and syntax) to extract a semantic +version from tag names. The default regular expression is: + +```plaintext +^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +This regular expression is based on the official +[semantic versioning](https://semver.org/) regular expression, and also includes +support for tag names that start with the letter `v`. + +If your project uses a different format for tags, you can specify a different +regular expression. The regular expression used _must_ produce the following +capture groups. If any of these capture groups are missing, the tag is ignored: + +- `major` +- `minor` +- `patch` + +The following capture groups are optional: + +- `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate + tags and other pre-release tags are not considered when determining the range of + commits to generate a changelog for. +- `meta`: Optional. Specifies build metadata. + +Using this information, GitLab builds a map of Git tags and their release +versions. It then determines what the latest tag is, based on the version +extracted from each tag. + +To specify a custom regular expression, use the `tag_regex` setting in your +changelog configuration YAML file. For example, this pattern matches tag names +such as `version-1.2.3` but not `version-1.2`. + +```yaml +--- +tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$' +``` + +To test if your regular expression is working, you can use websites such as +[regex101](https://regex101.com/). If the regular expression syntax is invalid, +an error is produced when generating a changelog. + +## Related topics + +- [Changelog-related endpoints](../../api/repositories.md) in the Repositories API. +- Developer documentation for [changelog entries](../../development/changelog.md) in GitLab. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 7b010bf4478..b1c5bbfc4f7 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -72,8 +72,8 @@ cluster certificates: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP - console to host the Kubernetes cluster. Learn more about - [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + console to host the Kubernetes cluster. For more information, see + [Creating and managing projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 523a6fd65f6..d3048158958 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -29,7 +29,7 @@ When you successfully connect an existing cluster using cluster certificates, th > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26815) in GitLab 12.6, you can remove cluster integrations and resources. When you remove a cluster integration, you only remove the cluster relationship -to GitLab, not the cluster. To remove the cluster itself, visit your cluster's +to GitLab, not the cluster. To remove the cluster itself, go to your cluster's GKE or EKS dashboard to do it from their UI or use `kubectl`. You need at least Maintainer [permissions](../../permissions.md) to your diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 6e188a4923b..173f1f39a66 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -65,7 +65,7 @@ GitLab CI/CD build environment to deployment jobs. Deployment jobs have The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace to deployment jobs. It defaults to using project-environment specific namespaces of the form `<prefix>-<environment>`, where `<prefix>` is of the form -`<project_name>-<project_id>`. To learn more, read [Deployment variables](#deployment-variables). +`<project_name>-<project_id>`. For more information, see [Deployment variables](#deployment-variables). You can customize the deployment namespace in a few ways: diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index d5f9c225cde..3fec38a61a0 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -43,7 +43,7 @@ code_navigation: The generated LSIF file size may be limited by the [artifact application limits (`ci_max_artifact_size_lsif`)](../../administration/instance_limits.md#maximum-file-size-per-type-of-artifact), -default to 100MB (configurable by an instance administrator). +default to 100 MB (configurable by an instance administrator). After the job succeeds, code intelligence data can be viewed while browsing the code: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 641dff2766e..9de9d445965 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -15,6 +15,15 @@ files or directories in a repository. - You can set your merge requests so they must be approved by Code Owners before merge. - You can protect a branch and allow only Code Owners to approve changes to the branch. +<div class="video-fallback"> + Video introduction: <a href="https://www.youtube.com/watch?v=RoyBySTUSB0">Code Owners</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> +</figure> + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + Use Code Owners and approvers together with [approval rules](merge_requests/approvals/rules.md) to build a flexible approval workflow: @@ -34,18 +43,25 @@ For example: | Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. | | Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. | -## Set up Code Owners +## Code Owners file -Create a `CODEOWNERS` file to specify users or [shared groups](members/share_project_with_groups.md) +A `CODEOWNERS` file (with no extension) can specify users or [shared groups](members/share_project_with_groups.md) that are responsible for specific files and directories in a repository. Each repository -can have a single `CODEOWNERS` file. To create it: +can have a single `CODEOWNERS` file, and it must be found one of these three locations: + +- In the root directory of the repository. +- In the `.gitlab/` directory. +- In the `docs/` directory. + +A CODEOWNERS file in any other location is ignored. + +## Set up Code Owners -1. Choose the location where you want to specify Code Owners: - - In the root directory of the repository - - In the `.gitlab/` directory - - In the `docs/` directory +1. Create a file named `CODEOWNERS` (with no extension) in one of these locations: -1. In that location, create a file named `CODEOWNERS`. +- In the root directory of the repository +- In the `.gitlab/` directory +- In the `docs/` directory 1. In the file, enter text that follows one of these patterns: @@ -154,7 +170,20 @@ README.md @user1 The Code Owner for `README.md` would be `@user2`. -If you use sections, the last user _for each section_ is used. +If you use sections, the last pattern matching the file for each section is used. +For example, in a `CODEOWNERS` file using sections: + +```plaintext +[README Owners] +README.md @user1 @user2 +internal/README.md @user4 + +[README other owners] +README.md @user3 +``` + +The Code Owners for the `README.md` in the root directory are `@user1`, `@user2`, +and `@user3`. The Code Owners for `internal/README.md` are `@user4` and `@user3`. Only one CODEOWNERS pattern can match per file path. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index e87c5f57fc1..fc88535dc77 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -99,7 +99,7 @@ To create a public deploy key: 1. Select **New deploy key**. 1. Complete the fields. - Use a meaningful description for **Name**. For example, include the name of the external host - or application that will use the public deploy key. + or application that uses the public deploy key. You can modify only a public deploy key's name. @@ -148,7 +148,7 @@ What happens to the deploy key when it is disabled depends on the following: ### Deploy key cannot push to a protected branch -There are a few scenarios where a deploy key will fail to push to a +There are a few scenarios where a deploy key fails to push to a [protected branch](../protected_branches.md). - The owner associated to a deploy key does not have access to the protected branch. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5f279ddda5b..cfb382d73e2 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -6,10 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Deploy tokens **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** to **Settings > CI/CD** in GitLab 12.9. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) `write_registry` scope in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** to **Settings > Repository** in GitLab 12.10.1. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. +> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. You can use a deploy token to enable authentication of deployment tasks, independent of a user account. In most cases you use a deploy token from an external host, like a build server or CI/CD @@ -41,7 +38,9 @@ You can create deploy tokens at either the project or group level: By default, a deploy token does not expire. You can optionally set an expiry date when you create it. Expiry occurs at midnight UTC on that date. -Deploy tokens can't be used for Git operations and Package Registry operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. +WARNING: +You cannot use new or existing deploy tokens for Git operations and Package Registry operations if +[external authorization](../../admin_area/settings/external_authorization.md) is enabled. ## Scope @@ -185,7 +184,7 @@ nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/project nuget install mypkg.nupkg ``` -## Push packages to a package repository +## Push packages to a package registry > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 6d0d444497e..8d3446994e8 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -10,7 +10,7 @@ Preventing wasted work caused by unresolvable merge conflicts requires a different way of working. This means explicitly requesting write permissions, and verifying no one else is editing the same file before you start. -Although branching strategies usually work well enough for source code and +Although branching strategies typically work well enough for source code and plain text because different versions can be merged together, they do not work for binary files. @@ -73,7 +73,7 @@ you can skip this step. If you're unsure, re-installing it does no harm: git lfs install ``` -Check this document to learn more about [using Git LFS](../../topics/git/lfs/index.md#using-git-lfs). +For more information, see [Using Git LFS](../../topics/git/lfs/index.md#using-git-lfs). ### Configure Exclusive File Locks @@ -209,7 +209,7 @@ requests that modify locked files. Unlock the file to allow changes. To lock a file: 1. Open the file or directory in GitLab. -1. On the top right, above the file, select **Lock**. +1. In the upper right, above the file, select **Lock**. 1. On the confirmation dialog box, select **OK**. If you do not have permission to lock the file, the button is not enabled. diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 22ff234ac81..fbb6d1b329d 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -11,7 +11,7 @@ GitLab provides syntax highlighting on all files through [Highlight.js](https:// [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. -The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). +The paths here use the [`.gitattributes` interface](https://git-scm.com/docs/gitattributes) in Git. NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) diff --git a/doc/user/project/img/pipelines_settings_badges.png b/doc/user/project/img/pipelines_settings_badges.png Binary files differnew file mode 100644 index 00000000000..3bdc6374c15 --- /dev/null +++ b/doc/user/project/img/pipelines_settings_badges.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 29d29c12536..7114974d8db 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -46,8 +46,8 @@ the user is not found in the GitLab database, the project creator (most of the t user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket author is kept. -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's +The importer creates any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository is imported under the user's namespace that started the import process. ## Requirements for user-mapped contributions @@ -65,6 +65,8 @@ For user contributions to be mapped, each user must complete the following befor ## Import your Bitbucket repositories +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + 1. Sign in to GitLab. 1. On the top bar, select **New** (**{plus}**). 1. Select **New project/repository**. @@ -76,9 +78,11 @@ For user contributions to be mapped, each user must complete the following befor 1. Select the projects that you'd like to import or import all projects. You can filter projects by name and select the namespace - each project will be imported for. + each project is imported for. -  +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. ## Troubleshooting diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index db2a1d956ab..e6d2e3e00b6 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -24,6 +24,8 @@ created as private in GitLab as well. ## Import your Bitbucket repositories +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + Prerequisites: - An administrator must enable **Bitbucket Server** in **Admin > Settings > General > Visibility and access controls > Import sources**. @@ -40,6 +42,9 @@ To import your Bitbucket repositories: 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. 1. Select the projects to import, or import all projects. You can filter projects by name and select the namespace for which to import each project. +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. ### Items that are not imported diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index f8bbb2354fe..00aebb75a50 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -54,7 +54,7 @@ Wikipedia article on [comparing the different version control software](https:// CVS is old with no new release since 2008. Git provides more tools to work with (`git bisect` for one) which makes for a more productive workflow. -Migrating to Git/GitLab will benefit you: +Migrating to Git/GitLab benefits you: - **Shorter learning curve**, Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 08ee4c70dda..d9e03662434 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -7,6 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from FogBugz to GitLab **(FREE)** +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + Using the importer, you can import your FogBugz project to GitLab.com or to your self-managed GitLab instance. @@ -33,4 +35,6 @@ To import your project from FogBugz:  1. After the import finishes, select the link to go to the project dashboard. Follow the directions to push your existing repository. -  +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index fb64c902b38..404bb4c8600 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -70,8 +70,8 @@ From there, you can view the import statuses of your Gitea repositories: - Those that are being imported show a _started_ status. - Those already successfully imported are green with a _done_ status. -- Those that aren't yet imported have an **Import** button on the - right side of the table. +- Those that aren't yet imported have **Import** on the right side of the table. +- Those that are already imported have **Re-import** on the right side of the table. You also can: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index da3637541d9..9298dab6f64 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -7,14 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from GitHub to GitLab **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378267) in GitLab 15.9, GitLab instances behind proxies no longer require `github.com` and `api.github.com` entries in the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests). -You can import your GitHub repositories: - -- From either GitHub.com or GitHub Enterprise. -- To either GitLab.com or a self-managed GitLab instance. - -This process does not migrate or import any types of groups or organizations from GitHub to GitLab. +You can import your GitHub projects from either GitHub.com or GitHub Enterprise. Importing projects does not +migrate or import any types of groups or organizations from GitHub to GitLab. The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or `gitlab.com/customer-success`. You can use bulk actions in the rails console to move projects to @@ -24,22 +21,6 @@ If you are importing to a self-managed GitLab instance, you can use the [GitHub Rake task](../../../administration/raketasks/github_import.md) instead. This allows you to import projects without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. -NOTE: -If you are importing a project using the GitHub Rake task, GitLab still creates namespaces or groups that don't exist. - -If you are importing from GitHub Enterprise to a self-managed GitLab instance: - -- You must first enable [GitHub integration](../../../integration/github.md). -- To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). -- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests) - with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue - [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941). - -If you are importing from GitHub.com to a self-managed GitLab instance: - -- Setting up GitHub integration is not required. -- You can use the [Import API](../../../api/import.md). - When importing projects: - If a user referenced in the project is not found in the GitLab database, the project creator is set as the author and @@ -57,24 +38,41 @@ For an overview of the import process, see the video [Migrating from GitHub to G ## Prerequisites -At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was -[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +To import projects from GitHub: + +- You must have at least the Maintainer role on the destination group to import to. Using the Developer role for this + purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in + GitLab 16.0. +- Each GitHub author and assignee in the repository 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, they must confirm it. + + When issues and pull requests are being imported, the importer attempts to find their GitHub authors and assignees in + the database of the GitLab instance. Pull requests are called _merge requests_ in GitLab. For the importer to succeed, + matching email addresses are required. +- GitHub accounts must have a 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 field to be populated so you + may have to add it on existing accounts. -When issues and pull requests are being imported, the importer attempts to find -their GitHub authors and assignees in the database of the GitLab instance. Pull requests are called _merge requests_ in -GitLab. +See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional +prerequisites for those imports. -For this association to succeed, each GitHub author and assignee in the repository -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. +### Importing from GitHub Enterprise to self-managed GitLab + +If you are importing from GitHub Enterprise to a self-managed GitLab instance: -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 -field to be populated so you may have to add it on existing accounts. +- You must first enable the [GitHub integration](../../../integration/github.md). +- For GitLab 15.8 and earlier, you must add `github.com` and `api.github.com` entries in the + [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests). -See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional prerequisites for those imports. +### Importing from GitHub.com to self-managed GitLab + +If you are importing from GitHub.com to a self-managed GitLab instance: + +- You don't need to enable the [GitHub integration](../../../integration/github.md). +- GitHub must be enabled as an import source in the + [Admin Area](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources). ## Import your GitHub repository into GitLab @@ -145,7 +143,8 @@ You can choose to import these items, but this could significantly increase impo ### Select which repositories to import -> Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7. +> - Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7. +> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and your GitHub repositories are listed. @@ -167,6 +166,8 @@ If the import has already started, the imported files are kept. To open an repository in GitLab URL after it has been imported, select its GitLab path. +Completed imports can be re-imported by selecting **Re-import** and specifying new name. This creates a new copy of the source project. +  ## Mirror a repository and share pipeline status **(PREMIUM)** diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 3df6a543960..24748b2e89c 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -17,20 +17,22 @@ If you want to bring existing projects to GitLab or copy GitLab projects to a di Prerequisite: -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. For any type of source and target, you can migrate GitLab projects: -- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all - projects in a group at once. Migrating projects by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready - for production use. +- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), + which allows you to migrate all projects in a group simultaneously. Migrating projects by direct transfer is in + [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). However, you can't import issues and merge requests this way. To retain metadata like issues and merge requests, either: -- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. +- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). + This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). @@ -47,17 +49,15 @@ You can import projects from: - [CVS](cvs.md) - [FogBugz](fogbugz.md) - [GitHub.com or GitHub Enterprise](github.md) -- [GitLab.com](gitlab_com.md) - [Gitea](gitea.md) - [Perforce](perforce.md) - [TFVC](tfvc.md) - [Repository by URL](repo_by_url.md) -- [Uloading a manifest file (AOSP)](manifest.md) -- [Phabricator](phabricator.md) +- [Uploading a manifest file (AOSP)](manifest.md) - [Jira (issues only)](jira.md) -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 import any Git repository through HTTP from the **New Project** page. If the repository +is too large, the import can timeout. You can then [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). @@ -70,7 +70,7 @@ GitLab can not automatically migrate Subversion repositories to Git. Converting ## Migrate using the API -To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). +To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/rest/index.md). Migrate the assets in this order: 1. [Groups](../../../api/groups.md) @@ -91,7 +91,7 @@ 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). -Also note that administrators can use the [Users API](../../../api/users.md) to migrate users. +Administrators can use the [Users API](../../../api/users.md) to migrate users. ## View project import history @@ -119,7 +119,7 @@ to create a new project from a template. ## LFS authentication -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) +When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-config.adoc) 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/manifest.md b/doc/user/project/import/manifest.md index c125102b0c9..514a6a0cb5a 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -7,7 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import multiple repositories by uploading a manifest file **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. +> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. GitLab allows you to import all the required Git repositories based on a manifest file like the one used by the @@ -26,7 +27,7 @@ repositories like the Android Open Source Project (AOSP). A manifest must be an XML file. There must be one `remote` tag with a `review` attribute that contains a URL to a Git server, and each `project` tag must have -a `name` and `path` attribute. GitLab will then build the URL to the repository +a `name` and `path` attribute. GitLab then builds the URL to the repository by combining the URL from the `remote` tag with a project name. A path attribute is used to represent the project path in GitLab. @@ -59,6 +60,6 @@ To start the import: 1. Select a group you want to import to (you need to create a group first if you don't have one). 1. Select **List available repositories**. At this point, you are redirected to the import status page with projects list based on the manifest file. -1. Check the list and select **Import all repositories** to start the import. - -  +1. To import: + - All projects for the first time: Select **Import all repositories**. + - Individual projects again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index ca50a32836e..a96297b1a38 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -16,7 +16,7 @@ The following list illustrates the main differences between Perforce Helix and Git: - In general, the biggest difference is that Perforce branching is heavyweight - compared to Git's lightweight branching. When you create a branch in Perforce, + compared to Git lightweight branching. When you create a branch in Perforce, it creates an integration record in their proprietary database for every file in the branch, regardless how many were actually changed. With Git, however, a single SHA acts as a pointer to the state of the whole repository after the @@ -56,7 +56,7 @@ Here's a few links to get you started: - [`git-p4` example usage](https://git.wiki.kernel.org/index.php/Git-p4_Usage) - [Git book migration guide](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git#_perforce_import) -Note that `git p4` and `git filter-branch` are not very good at +`git p4` and `git filter-branch` are not very good at creating small and efficient Git pack files. So it might be a good idea to spend time and CPU to properly repack your repository before sending it for the first time to your GitLab server. See diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 09e7543bc4a..8a2dbba1343 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -36,7 +36,7 @@ Only the following basic fields are imported: The assignee and author of a user are deducted from a Task's owner and author: If a user with the same username has access to the namespace -of the project being imported into, then the user will be linked. +of the project being imported into, then the user is linked. ## Enable this feature diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 08caa62bcb2..decf3b071e7 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -16,8 +16,7 @@ To create a blank project: 1. On the right of the page, select **New project**. 1. Select **Create blank project**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -51,8 +50,7 @@ To create a project from a built-in template: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -61,6 +59,11 @@ To create a project from a built-in template: change the **Visibility Level**. 1. Select **Create project**. +NOTE: +A user who creates a project [from a template](#create-a-project-from-a-built-in-template) or [by import](settings/import_export.md#import-a-project-and-its-data) is displayed as the author of the imported objects (such as issues and merge requests), which keep the original timestamp from the template or import. +Imported objects are labeled as `By <username> on <timestamp> (imported from GitLab)`. +For this reason, the creation date of imported objects can be older than the creation date of the user's account. This can lead to objects appearing to have been created by a user before they even had an account. + ## Create a project from a custom template **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. @@ -78,8 +81,7 @@ Custom project templates are available at: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -105,8 +107,7 @@ To create a project from the HIPAA Audit Protocol template: - To view a preview of the template, select **Preview**. - To use the template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 62b25bf8191..1b41dd0b669 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Apple App Store integration **(FREE)** +# Apple App Store **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 97fb4e7c463..8bc1a984e3d 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Asana integration **(FREE)** +# Asana **(FREE)** This integration adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index db90bafaaa5..12039a70d0e 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Atlassian Bamboo integration **(FREE)** +# Atlassian Bamboo **(FREE)** You can automatically trigger builds in Atlassian Bamboo when you push changes to your project in GitLab. @@ -71,7 +71,7 @@ and Bamboo build variables to: For example: -1. Create an [access token](../../../api/index.md#personalprojectgroup-access-tokens) in GitLab with `:api` permissions. +1. Create an [access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) in GitLab with `:api` permissions. 1. Save the token as a `$GITLAB_TOKEN` variable in Bamboo. 1. Add the following script as a final task to the Bamboo plan's jobs: diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 9221250e17f..2933203c593 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Bugzilla service **(FREE)** +# Bugzilla **(FREE)** [Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing tool. @@ -37,8 +37,8 @@ After you configure and enable Bugzilla, a link appears on the GitLab project pages. This link takes you to the appropriate Bugzilla project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. -Learn more about the steps and consequences of disabling GitLab issues in -[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference Bugzilla issues in GitLab diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 9439e480484..0163bce3496 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Discord Notifications service **(FREE)** +# Discord Notifications **(FREE)** -The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. +The Discord Notifications integration sends event notifications from GitLab to the channel for which the webhook was created. To send GitLab event notifications to a Discord channel, [create a webhook in Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) and configure it in GitLab. @@ -24,7 +24,7 @@ and configure it in GitLab. ## Configure created webhook in GitLab -With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. +With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index ff255cbba51..c3134e986d3 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Enabling emails on push **(FREE)** +# Emails on push **(FREE)** -By enabling this service, you receive email notifications for every change +When you enable emails on push, you receive email notifications for every change that is pushed to your project. To enable emails on push: diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index d972509c0f6..c2371d32853 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -4,13 +4,13 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# IBM Engineering Workflow Management (EWM) Integration **(FREE)** +# Engineering Workflow Management (EWM) **(FREE)** -This service allows you to go from GitLab to EWM work items mentioned in merge request +This integration allows you to go from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link to the work item. -This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is compatible with all versions of RTC and EWM. +This IBM product was [formerly named Rational Team Concert (RTC)](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/). This integration is compatible with all versions of RTC and EWM. To enable the EWM integration, in a project: @@ -51,5 +51,5 @@ You can use the following keywords: - `work item` - `workitem` -Avoid using the keyword `#`. Learn more in the EWM documentation page +Avoid using the keyword `#`. For more information, see [Creating links from commit comments](https://www.ibm.com/docs/en/elm/7.0.0?topic=commits-creating-links-from-commit-comments). diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 603ed8b4c05..990d0839581 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitHub project integration **(PREMIUM)** +# GitHub **(PREMIUM)** You can update GitHub with pipeline status updates from GitLab. This integration can help you if you use GitLab for CI/CD. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 50b52421a5a..649b0c51818 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -7,16 +7,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab for Slack app **(FREE SAAS)** 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/groups/gitlab-org/-/epics/1211) -for our plans to make the app configurable for all GitLab installations. +This feature is only configurable on GitLab.com. +For self-managed GitLab instances, use +[Slack slash commands](slack_slash_commands.md) and [Slack notifications](slack.md) instead. +For more information about our plans to make this feature configurable for all GitLab installations, +see [epic 1211](https://gitlab.com/groups/gitlab-org/-/epics/1211). Slack provides a native application that you can enable with your project's integrations on GitLab.com. -## Slack App Directory +## Installation + +### Through the Slack App Directory To enable the GitLab for Slack app for your workspace, install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) @@ -25,7 +27,7 @@ from the [Slack App Directory](https://slack.com/apps). On the [GitLab for Slack app landing page](https://gitlab.com/-/profile/slack/edit), you can select a GitLab project to link with your Slack workspace. -## Configuration +### Through GitLab project settings Alternatively, you can configure the GitLab for Slack app with your project's integration settings. @@ -44,9 +46,44 @@ To enable the GitLab integration for 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 +## Slash commands + +After installing the GitLab for Slack app, everyone in your Slack workspace can use slash commands. + +Replace `<project>` with the project full path, or create a shorter [project alias](#create-a-project-alias-for-slash-commands) for the slash commands. + +| Command | Effect | +| ------- | ------ | +| `/gitlab help` | Shows all available slash commands. | +| `/gitlab <project> issue new <title> <shift+return> <description>` | Creates a new issue with the title `<title>` and description `<description>`. | +| `/gitlab <project> issue show <id>` | Shows the issue with the ID `<id>`. | +| `/gitlab <project> issue close <id>` | Closes the issue with the ID `<id>`. | +| `/gitlab <project> issue search <query>` | Shows up to 5 issues matching `<query>`. | +| `/gitlab <project> issue move <id> to <project>` | Moves the issue with the ID `<id>` to `<project>`. | +| `/gitlab <project> issue comment <id> <shift+return> <comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | +| `/gitlab <project> deploy <from> to <to>` | [Deploys](#the-deploy-slash-command) from the `<from>` environment to the `<to>` environment. | +| `/gitlab <project> run <job name> <arguments>` | Executes the [ChatOps](../../../ci/chatops/index.md) job `<job name>` on the default branch. | + +### The deploy slash command + +To deploy to an environment, GitLab tries to find a deployment +manual action in the pipeline. + +If there's only one action for a given environment, it is triggered. +If more than one action is defined, GitLab finds an action +name that matches the environment name to deploy to. + +The command returns an error if no matching action is found. + +### User authorization + +When you perform your first slash command, you must +authorize your Slack user on GitLab.com. + +### Create a project alias for slash commands -To create a project alias on GitLab.com for Slack integration: +By default, slash commands expect a project full path. To use a shorter alias +instead: 1. Go to your project's home page. 1. Go to **Settings > Integrations** (only visible on GitLab.com). @@ -55,43 +92,107 @@ To create a project alias on GitLab.com for Slack integration: select **Edit**. 1. Enter your desired alias, and select **Save changes**. -Some Slack commands require a project alias and fail with the following error -if the project alias is incorrect or missing from the command: +## Slack notifications -```plaintext -GitLab error: project or alias not found -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381012) in GitLab 15.9. -## Usage +With Slack notifications, GitLab can send messages to Slack workspace channels for certain GitLab [events](#events-for-slack-notifications) (for example, when an issue is created). -After installing the app, everyone in your Slack workspace can -use the [slash commands](../../../integration/slash_commands.md). -When you perform your first slash command, you are asked to -authorize your Slack user on GitLab.com. +### Configure notifications -The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) -is that you must prefix all commands with the `/gitlab` keyword. For example, -to show the issue number `1001` under the `gitlab-org/gitlab` -project, you must run the following command: +To configure Slack notifications: -```plaintext -/gitlab gitlab-org/gitlab issue show 1001 -``` +1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been [installed](#installation). +1. On the left sidebar, select **Settings > Integrations**. +1. Select **GitLab for Slack app**. +1. In the **Trigger** section, select the checkbox for each GitLab + event you want to receive a notification for in Slack. For a full list, see + [Events for Slack notifications](#events-for-slack-notifications). +1. For each checkbox you select, enter the name of the channel that receives the notifications (for example, `#my-channel`). + - To send notifications to multiple Slack channels, enter up to 10 channel names separated by commas (for example, `#channel-one, #channel-two`). -## Version history + NOTE: + If the channel is private, you must also [add the GitLab for Slack app to the private channel](#receive-notifications-to-a-private-channel). + +1. Select the **Notify only broken pipelines** checkbox to notify only on failures. +1. From the **Branches for which notifications are to be sent** dropdown list, select which branches you want to receive notifications (if relevant to your events). +1. Leave the **Labels to be notified** text box blank to receive all notifications, or + add labels the issue or merge request must have to trigger a + notification. +1. Select **Save changes**. + +Your Slack workspace can now start receiving GitLab event notifications. + +### Receive notifications to a private channel -In GitLab 15.0 and later, the GitLab for Slack app is updated to [Slack's new granular permissions model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). While there is no change in functionality, you should reinstall the app. +To receive notifications to a private Slack channel, you must add the GitLab for Slack app to the channel: + +1. Mention the app in the channel by typing `@GitLab` and pressing <kbd>Enter</kbd>. +1. Select **Add to Channel**. + +### Events for Slack notifications + +The following events are available for Slack notifications: + +| Event name | Description | +|--------------------------------------------------------------------------|------------------------------------------------------| +| **Push** | A push to the repository. | +| **Issue** | An issue is created, updated, or closed. | +| **Confidential issue** | A confidential issue is created, updated, or closed. | +| **Merge request** | A merge request is created, updated, or merged. | +| **Note** | A comment is added. | +| **Confidential note** | A confidential note is added. | +| **Tag push** | A new tag is pushed to the repository. | +| **Pipeline** | A pipeline status changed. | +| **Wiki page** | A wiki page is created or updated. | +| **Deployment** | A deployment starts or finishes. | +| **Alert** | A new, unique alert is recorded. | +| [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting -When you work with the GitLab for Slack app, the -[App Home](https://api.slack.com/start/overview#app_home) might not display properly. -As a workaround, ensure your app is up to date. +### Update the GitLab for Slack app + +New releases of the app might require permissions to be authorized before some features work in your Slack workspace. You should ensure the app is up to date in your Slack workspace to enjoy all the latest features. -To update an existing Slack integration: +To update your GitLab for Slack app: -1. Go to your [chat settings](https://gitlab.com/-/profile/chat_names). -1. Next to your project, select **GitLab for Slack app**. +1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been configured. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **GitLab for Slack app**. 1. Select **Reinstall GitLab for Slack app**. +The GitLab for Slack app is updated for all projects that use the integration. + Alternatively, you can [configure a new Slack integration](https://about.gitlab.com/solutions/slack/). + +### Project or alias not found + +Some Slack commands must have a project full path or alias and fail with the following error +if the project cannot be found: + +```plaintext +GitLab error: project or alias not found +``` + +As a workaround, ensure: + +- The project full path is correct. +- If using a [project alias](#create-a-project-alias-for-slash-commands), the alias is correct. +- The GitLab for Slack app integration is [enabled for the project](#through-gitlab-project-settings). + +### Notifications are not received to a channel + +If you're not receiving notifications to a Slack channel, ensure: + +- The channel name you configured is correct. +- If the channel is private, you've [added the GitLab for Slack app to the channel](#receive-notifications-to-a-private-channel). + +### The App Home does not display properly + +If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](#update-the-gitlab-for-slack-app). + +## Version history + +In GitLab 15.0 and later, the GitLab for Slack app is updated to [Slack's new granular permissions model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). +Although there is no change in functionality, you should [reinstall the app](#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index c6e102b1d74..3537033902d 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Google Chat integration **(FREE)** +# Google Chat **(FREE)** Integrate your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (former Google @@ -28,7 +28,7 @@ notifications to Google Chat: To enable the integration in Google Chat: 1. Enter the room where you want to receive notifications from GitLab. -1. Open the room dropdown list on the top-left and select **Manage webhooks**. +1. Open the room dropdown list in the upper left and select **Manage webhooks**. 1. Enter the name for your webhook, for example "GitLab integration". 1. Optional. Add an avatar for your bot. 1. Select **Save**. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index d75f10e0e11..596821ba12b 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Harbor container registry integration **(FREE)** +# Harbor **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 769a45fc6ff..57947e21736 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -90,7 +90,7 @@ You can configure a project webhook to listen for specific events like pushes, issues, or merge requests. When the webhook is triggered, GitLab sends a POST request with data to a specified webhook URL. -Learn more [about webhooks](webhooks.md). +For more information, see [Webhooks](webhooks.md). ## Push hooks limit @@ -104,7 +104,7 @@ You can change the number of supported branches or tags by changing the ## Troubleshooting integrations -Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). Learn more about [troubleshooting integration hooks](webhooks.md#troubleshoot-webhooks). +Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). For more information, see [Troubleshooting webhooks](webhooks.md#troubleshoot-webhooks). ### `Test Failed. Save Anyway` error diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 70f48e4647a..23525c33e84 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,10 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# irker IRC Gateway **(FREE)** +# irker (IRC gateway) **(FREE)** GitLab provides a way to push update messages to an irker server. When -configured, pushes to a project trigger the service to send data directly +configured, pushes to a project trigger the integration to send data directly to the irker server. See also the [irker integration API documentation](../../../api/integrations.md). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 39b89cd87a9..fcc364724b7 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Mattermost notifications service **(FREE)** +# Mattermost notifications **(FREE)** -Use the Mattermost notifications service to send notifications for GitLab events +Use the Mattermost notifications integration to send notifications for GitLab events (for example, `issue created`) to Mattermost. You must configure both [Mattermost](#configure-mattermost-to-receive-gitlab-notifications) and [GitLab](#configure-gitlab-to-send-notifications-to-mattermost). @@ -36,6 +36,8 @@ Display name override is not enabled by default, you need to ask your administra ## Configure GitLab to send notifications to Mattermost +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Mattermost channels to 10 per event. + After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index cedb5af144f..fc5d4d3cc80 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Microsoft Teams service **(FREE)** +# Microsoft Teams notifications **(FREE)** -You can integrate Microsoft Teams with GitLab, and display notifications about GitLab projects +You can integrate Microsoft Teams notifications with GitLab and display notifications about GitLab projects in Microsoft Teams. To integrate the services, you must: 1. [Configure Microsoft Teams](#configure-microsoft-teams) to enable a webhook diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 64ee4521ce4..ae1737f8d3f 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -4,10 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Mock CI Service **(FREE)** +# Mock CI **(FREE)** NOTE: -This service is only listed if you are in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration)! +This integration only appears if you're in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration). To set up the mock CI service server, respond to the following endpoints diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 79a00725470..034be8ab3d8 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Pivotal Tracker service **(FREE)** +# Pivotal Tracker **(FREE)** -This service adds commit messages as comments to Pivotal Tracker stories. +This integration adds commit messages as comments to Pivotal Tracker stories. Once enabled, commit messages are checked for square brackets containing a hash mark followed by the story ID (for example, `[#555]`). Every story ID found gets the commit comment added to it. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index dfa5a4593d8..cd92e49cada 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -4,7 +4,7 @@ group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Prometheus integration **(FREE)** +# Prometheus **(FREE)** GitLab offers powerful integration with [Prometheus](https://prometheus.io) for monitoring key metrics of your apps, directly in GitLab. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 4ef3a847ef1..afefe80271e 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -35,7 +35,7 @@ GitLab retrieves performance data from the configured Prometheus server, and attempts to identifying the presence of known metrics. Once identified, GitLab then needs to be able to map the data to a particular environment. -In order to isolate and only display relevant metrics for a given environment, +To isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 0795c110deb..34a6823f007 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -42,7 +42,7 @@ Prometheus needs to be deployed into the cluster and configured properly to gath ## Specifying the Environment -In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. +To isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/index.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index e6f2ac2753a..f8057866592 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -42,6 +42,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +To isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index e9752d7ce6c..0a399d3481f 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Redmine service **(FREE)** +# Redmine **(FREE)** Use [Redmine](https://www.redmine.org/) as the issue tracker. @@ -37,8 +37,8 @@ For example, this is a configuration for a project named `gitlab-ci`: - New issue URL: `https://redmine.example.com/projects/gitlab-ci/issues/new` You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. -Learn more about the steps and consequences of disabling GitLab issues in -[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference Redmine issues in GitLab diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index fcc8db7cb87..a34655c8e35 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# ServiceNow integration **(FREE)** +# ServiceNow **(FREE)** ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index 28cb53f8bf6..ca09de06dc6 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -4,7 +4,14 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Shimo Workspace integration **(FREE)** +<!--- start_remove The following content will be removed on remove_date: '2023-05-22' --> + +# Shimo (deprecated) **(FREE)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7 +and is planned for removal in 16.0. +This change is a breaking change. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 with a feature flag named `shimo_integration`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. @@ -14,11 +21,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Configure settings in GitLab -To enable the Shimo Workspace integration for your group or project: +To enable the Shimo integration for your group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Settings > Integrations**. -1. In **Add an integration**, select **Shimo Workspace**. +1. In **Add an integration**, select **Shimo**. 1. In **Enable integration**, ensure the **Active** checkbox is selected. 1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). 1. Select **Save changes**. @@ -32,3 +39,5 @@ To view the Shimo Workspace from your group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Shimo**. 1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. + +<!--- end_remove --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5c1006b9044..09e7189d4f5 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -4,7 +4,13 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Slack notifications integration **(FREE)** +# Slack notifications **(FREE)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) on GitLab.com +in GitLab 15.9 and is [planned for removal](https://gitlab.com/groups/gitlab-org/-/epics/8673). +For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. +For self-managed GitLab instances, you can continue to use this feature. The Slack notifications integration enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up @@ -22,6 +28,8 @@ to control GitLab from Slack. Slash commands are configured separately. ## Configure GitLab +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Slack notifications**. @@ -58,13 +66,13 @@ The following triggers are available for Slack notifications: | Trigger name | Trigger event | |--------------------------------------------------------------------------|------------------------------------------------------| | **Push** | A push to the repository. | -| **Issue** | An issue is created, updated, or closed. | -| **Incident** | An incident is created, updated, or closed. | -| **Confidential issue** | A confidential issue is created, updated, or closed. | -| **Merge request** | A merge request is created, updated, or merged. | +| **Issue** | An issue is created, closed, or reopened. | +| **Incident** | An incident is created, closed, or reopened. | +| **Confidential issue** | A confidential issue is created, closed, or reopened.| +| **Merge request** | A merge request is created, merged, closed, or reopened.| | **Note** | A comment is added. | -| **Confidential note** | A confidential note is added. | -| **Tag push** | A new tag is pushed to the repository. | +| **Confidential note** | An internal note or comment on a confidential issue is added.| +| **Tag push** | A new tag is pushed to the repository or removed. | | **Pipeline** | A pipeline status changed. | | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index f4c789239f3..2563cec2b05 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Slack slash commands **(FREE SELF)** +NOTE: +This feature is only configurable on self-managed GitLab instances. +For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. + If you want to control and view GitLab content while you're working in Slack, you can use Slack slash commands. To use Slack slash commands, you must configure both Slack and GitLab. @@ -13,9 +17,6 @@ To use Slack slash commands, you must configure both Slack and GitLab. GitLab can also send events (for example, `issue created`) to Slack as notifications. The [Slack notifications service](slack.md) is configured separately. -NOTE: -For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. - ## Configure GitLab and Slack Slack slash command integrations diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 77530b4b417..d465b4e50f0 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Unify Circuit service **(FREE)** +# Unify Circuit **(FREE)** -The Unify Circuit service sends notifications from GitLab to a Circuit conversation. +The Unify Circuit integration sends notifications from GitLab to a Circuit conversation. ## Set up Unify Circuit service diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index be4528ba70d..233209966aa 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Webex Teams service **(FREE)** +# Webex Teams **(FREE)** You can configure GitLab to send notifications to a Webex Teams space: diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 0f462ad41b0..53177004888 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1784,7 +1784,7 @@ Payload example: "links": [ { "id": 1, - "external": true, + "external": true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type": "other", "name": "Changelog", "url": "https://example.net/changelog" diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 3d45e947c4c..3d971af5c2a 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -258,15 +258,17 @@ For more information about supported events for Webhooks, go to [Webhook events] ## Delivery headers -> `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5. +> - `X-Gitlab-Event-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8. +> - `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5. Webhook requests to your endpoint include the following headers: | Header | Description | Example | | ------ | ------ | ------ | | `User-Agent` | In the format `"Gitlab/<VERSION>"`. | `"GitLab/15.5.0-pre"` | -| `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | | `X-Gitlab-Instance` | Hostname of the GitLab instance that sent the webhook. | `"https://gitlab.com"` | +| `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | +| `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | ## Troubleshoot webhooks @@ -287,7 +289,7 @@ To view the table: 1. Each [failing webhook](#failing-webhooks) has a badge listing it as: - **Failed to connect** if it is misconfigured, and needs manual intervention to re-enable it. - - **Fails to connect** if it is temporarily disabled and will retry later. + - **Fails to connect** if it is temporarily disabled and is retrying later.  @@ -334,9 +336,9 @@ GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#othe > - [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: +why it is disabled, and when it is automatically re-enabled. For example: - + In the case of a failed webhook, an error banner is displayed: diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index fb6807aeeb0..a020cc61533 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# YouTrack service **(FREE)** +# YouTrack **(FREE)** JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project management platform. @@ -28,8 +28,8 @@ After you configure and enable YouTrack, a link appears on the GitLab project pages. This link takes you to the appropriate YouTrack project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. -Learn more about the steps and consequences of disabling GitLab issues in -[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference YouTrack issues in GitLab diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index 17727ba22b1..ca25c1214b7 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -4,7 +4,14 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# ZenTao product integration **(PREMIUM)** +<!--- start_remove The following content will be removed on remove_date: '2023-05-22' --> + +# ZenTao (deprecated) **(PREMIUM)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377825) in GitLab 15.7 +and is planned for removal in 16.0. +This change is a breaking change. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338178) in GitLab 14.5. @@ -47,3 +54,5 @@ Complete these steps in GitLab: 1. To verify the ZenTao connection is working, select **Test settings**. 1. Select **Save changes**. + +<!--- end_remove --> diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 3c2e20c1250..5ebb2fc2e1c 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -31,7 +31,7 @@ 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 left sidebar, select **Issues**, and then, in the upper-right corner, select **New issue**. - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, select **New issue**. @@ -53,7 +53,7 @@ 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. In the upper-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>`**. @@ -127,7 +127,7 @@ You can send an email to create an issue in a project on the project's Prerequisites: - Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) - configured. + configured with [email sub-addressing or catch-all mailbox](../../../administration/incoming_email.md#requirements). - There must be at least one issue in the issue list. - You must have at least the Guest role for the project. @@ -165,10 +165,10 @@ 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). | +| Title | `issue[title]` | Must be [URL-encoded](../../../api/rest/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. | +| Description template | `issuable_template` | Must be [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Must be [URL-encoded](../../../api/rest/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. | diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 0b5605bb767..52da1acd32a 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -24,6 +24,13 @@ add `#xxx` to the commit message, where `xxx` is the issue number. git commit -m "this is my commit message. Ref #xxx" ``` +Since commit messages cannot usually begin with a `#` character, you may use +the alternative `GL-xxx` notation as well: + +```shell +git commit -m "GL-xxx: this is my commit message" +``` + If they are in different projects, but in the same group, add `projectname#xxx` to the commit message. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 83265d3e954..9b131372672 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -15,9 +15,6 @@ notification email address as an attachment. collected from issues into a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) file, which stores tabular data in plain text. -> _CSVs are a way of getting data from one program to another where one -program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) - <!-- vale gitlab.Spelling = NO --> CSV files can be used with any plotter or spreadsheet-based program, such as diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index d01f22d03c9..8a6683a55b5 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -36,7 +36,7 @@ To import issues: 1. Go to your project's Issues list page. 1. Open the import feature, depending if the project has issues: - - Existing issues are present: Select the import icon at the top right, next to **Edit issues**. + - Existing issues are present: Select the import icon in the upper right, next to **Edit issues**. - Project has no issues: Select **Import CSV** in the middle of the page. 1. Select the file you want to import, and then select **Import issues**. @@ -50,7 +50,7 @@ To import issues, GitLab requires CSV files have a specific format: | Element | Format | |------------------------|--------| | header row | CSV files must include the following headers: `title` and `description`. The case of the headers does not matter. | -| columns | Data from columns beyond `title` and `description` are not imported. | +| columns | Data from columns outside of `title`, `description`, and `due_date` are not imported. | | separators | The column separator is detected from the header row. Supported separator characters are commas (`,`), semicolons (`;`), and tabs (`\t`). The row separator can be either `CRLF` or `LF`. | | double-quote character | The double-quote (`"`) character is used to quote fields, enabling the use of the column separator in a field (see the third line in the sample CSV data below). To insert a double-quote (`"`) in a quoted field use two double-quote characters in succession (`""`). | | data rows | After the header row, following rows must use the same column order. The issue title is required, but the description is optional. | @@ -58,12 +58,16 @@ To import issues, GitLab requires CSV files have a specific format: If you have special characters (for example, `,` or `\n`) or multiple lines in a field (for example, when using [quick actions](../quick_actions.md)), surround the characters with double quotes (`"`). -When using [quick actions](../quick_actions.md), each action must be on a separate line. +Also when using [quick actions](../quick_actions.md): + +- Each action must be on a separate line. +- For quick actions like `/label` and `/milestone`, the label or milestone must already exist in the project. +- The user you assign the issue to must be a member of the project. Sample CSV data: ```plaintext -title,description,due date +title,description,due_date My Issue Title,My Issue Description,2022-06-28 Another Title,"A description, with a comma", "One More Title","One More Description", diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 27d935d0ed1..f43f87119a6 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -92,12 +92,12 @@ The design you selected opens. You can then [zoom in](#zoom-in-on-a-design) on i When viewing a design, you can move to other designs. To do so, either: -- In the top-right corner, select **Go to previous design** (**{chevron-lg-left}**) or **Go to next design** (**{chevron-lg-right}**). +- In the upper-right corner, select **Go to previous design** (**{chevron-lg-left}**) or **Go to next design** (**{chevron-lg-right}**). - Press <kbd>Left</kbd> or <kbd>Right</kbd> on your keyboard. To return to the issue view, either: -- In the top-left corner, select the close icon (**{close}**). +- In the upper-left corner, select the close icon (**{close}**). - Press <kbd>Esc</kbd> on your keyboard. When a design is added, a green icon (**{plus-square}**) is displayed on the image @@ -186,7 +186,7 @@ Prerequisites: To archive a single design: 1. Select the design to view it enlarged. -1. In the top right corner, select **Archive design** (**{archive}**). +1. In the upper-right corner, select **Archive design** (**{archive}**). 1. Select **Archive designs**. To archive multiple designs at once: @@ -235,7 +235,7 @@ When you're done discussing part of a design, you can resolve the discussion thr To mark a thread as resolved or unresolved, either: -- In the top-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**). +- In the upper-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**). - Add a new comment to the thread and select or clear the **Resolve thread** checkbox. Resolving a discussion thread also marks any pending [to-do items](../../todos.md) related to notes diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a5399b70c8f..953d08ea903 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -22,6 +22,28 @@ To edit an issue: 1. Edit the available fields. 1. Select **Save changes**. +### Remove a task list item + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `work_items_mvc`. 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 `work_items_mvc`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the project, or be the author or assignee of the issue. + +In an issue description with task list items: + +1. Hover over a task list item and select the options menu (**{ellipsis_v}**). +1. Select **Delete**. + +The task list item is removed from the issue description. +Any nested task list items are moved up a nested level. + ## Bulk edit issues from a project > - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. @@ -150,7 +172,7 @@ To do it: issues.each do |issue| if issue.state != "closed" && issue.moved_to.nil? - Issues::MoveService.new(project: project, current_user: admin_user).execute(issue, target_project) + Issues::MoveService.new(container: project, current_user: admin_user).execute(issue, target_project) else puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" end @@ -174,10 +196,10 @@ Prerequisites: 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. Hover over the list item row to make the grip icon (**{grip}**) visible. +1. Select and hold the grip icon. 1. Drag the row to the new position in the list. -1. Release the drag icon. +1. Release the grip icon. ## Close an issue @@ -204,9 +226,11 @@ A reopened issue is no different from any other open issue. ### Closing issues automatically -You can close issues automatically by using certain words in the commit message or MR description. +You can close issues automatically by using certain words, called a _closing pattern_, +in a commit message or merge request description. Administrators of self-managed GitLab instances +can [change the default closing pattern](../../../administration/issue_closing_pattern.md). -If a commit message or merge request description contains text matching the [defined pattern](#default-closing-pattern), +If a commit message or merge request description contains text matching the [closing pattern](#default-closing-pattern), all issues referenced in the matched text are closed when either: - The commit is pushed to a project's [**default** branch](../repository/branches/default.md). @@ -218,7 +242,7 @@ description: - Issues `#4` and `#6` are closed automatically when the MR is merged. - Issue `#5` is marked as a [related issue](related_issues.md), but it's not closed automatically. -Alternatively, when you [create a merge request from an issue](../merge_requests/getting_started.md#merge-requests-to-close-issues), +Alternatively, when you [create a merge request from an issue](../merge_requests/creating_merge_requests.md#from-an-issue), it inherits the issue's milestone and labels. For performance reasons, automatic issue closing is disabled for the very first @@ -382,7 +406,7 @@ To view all issues assigned to you: Or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>i</kbd>. -- On the top bar, on the top right, select **{issues}** **Issues**. +- On the top bar, in the upper right, select **{issues}** **Issues**. ## Filter the list of issues @@ -413,11 +437,12 @@ GitLab displays the results on-screen, but you can also > - OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. > - OR filtering for label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104292) in GitLab 15.9. FLAG: -On self-managed GitLab, by default this feature is not available. -To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `or_issuable_queries`. -The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `or_issuable_queries`. +On GitLab.com, this feature is available. 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) by: @@ -460,7 +485,7 @@ Read more about issue references in [GitLab-Flavored Markdown](../../markdown.md You can create a comment in an issue by sending an email. Sending an email to this address creates a comment that contains the email body. -To learn more about creating comments by sending an email and the necessary configuration, see +For more information about creating comments by sending an email and the necessary configuration, see [Reply to a comment by sending email](../../discussions/index.md#reply-to-a-comment-by-sending-email). To copy the issue's email address: diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 1a8f19b80ba..43acaaf9c2f 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -15,7 +15,7 @@ The relationship only shows up in the UI if the user can see both issues. When y issue that has open blockers, a warning is displayed. NOTE: -To manage linked issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). +To manage linked issues through our API, see [Issue links API](../../../api/issue_links.md). ## Add a linked issue @@ -57,7 +57,7 @@ them categorized so their relationships can be better understood visually.  You can also add a linked issue from a commit message or the description in another issue or MR. -[Learn more about crosslinking issues](crosslinking_issues.md). +For more information, see [Crosslinking issues](crosslinking_issues.md). ## Remove a linked issue diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 0b0184db14c..c7d45b0bd15 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -10,12 +10,16 @@ Members are the users and groups who have access to your project. Each member gets a role, which determines what they can do in the project. -Project members can: +## Membership types -1. Be [direct members](#add-users-to-a-project) of the project. -1. [Inherit membership](#inherited-membership) of the project from the project's group. -1. Be a member of a group that was [shared](share_project_with_groups.md) with the project. -1. Be a member of a group that was [shared with the project's group](../../group/manage.md#share-a-group-with-another-group). +Users can become members of a group or project in different ways, which define their membership type. + +| Membership type | Membership process | +| --------------------------------------------- | ------------------ | +| [Direct](#add-users-to-a-project) | The user is added directly to the current group or project. | +| [Inherited](#inherited-membership) | The user is a member of an ancestor group or project that is added to the current group or project. | +| [Direct shared](share_project_with_groups.md) | The user is a member of a group or project that is shared into the current group or project. | +| [Inherited shared](../../group/manage.md#share-a-group-with-another-group) | The user is a member of an ancestor of a group or project that is shared into the current group or project. | ```mermaid flowchart RL @@ -41,13 +45,71 @@ flowchart RL G-->|Group C shared with Project A|E ``` +### Inherited membership + +When your project belongs to a group, project members inherit their role +from the group. + + + +In this example: + +- Three members have access to the project. +- **User 0** is a Reporter and has inherited their role in the project from the **demo** group, + which contains the project. +- **User 1** belongs directly to the project. In the **Source** column, they are listed + as a **Direct member**. +- **Administrator** is the [Owner](../../permissions.md) and member of all groups. + They have inherited their role in the project from the **demo** group. + +If a user is: + +- A direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. +- An inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. + +### Membership and visibility rights + +Depending on their membership type, members of groups or projects are granted different visibility levels +and rights into the group or project. + +| Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member | +| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | +| Generate boards | ✓ | ✓ | ✓ | ✓ | +| View issues of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| View labels of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| View milestones of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| Be shared into other groups | ✓ | | | | +| Be shared into other projects | ✓ | ✓ | | | +| Share the group with other members | ✓ | | | | + +In the following example, `User` is a: + +- Direct member of `subgroup`. +- Inherited member of `subsubgroup`. +- Indirect member of `subgroup-2` and `subgroup-3`. +- Indirect inherited member of `subsubgroup-2` and `subsubgroup-3`. + +```mermaid +graph TD + classDef user stroke:green,color:green; + + root --> subgroup --> subsubgroup + root-2 --> subgroup-2 --> subsubgroup-2 + root-3 --> subgroup-3 --> subsubgroup-3 + subgroup -. shared .-> subgroup-2 -. shared .-> subgroup-3 + + User-. member .- subgroup + + class User user +``` + ## Add users to a project > - [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. -Add users to a project so they become members and have permission +Add users to a project so they become direct members and have permission to perform actions. Prerequisite: @@ -59,7 +121,12 @@ To add a user to a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Invite members**. -1. Enter an email address and select a [role](../../permissions.md). +1. If the user: + + - Has a GitLab account, enter their username. + - Doesn't have a GitLab account, enter their email address. + +1. Select a [role](../../permissions.md). 1. Optional. Select an **Access expiration date**. From that date onward, the user can no longer access the project. @@ -69,16 +136,12 @@ To add a user to a project: to extend their own time in the Maintainer role. 1. Select **Invite**. + If you invited the user using their: -If the user has a GitLab account, they are added to the members list. -If you used an email address, the user receives an email. - -If the invitation is not accepted, GitLab sends reminder emails two, -five, and ten days later. Unaccepted invites are automatically -deleted after 90 days. - -If the user does not have a GitLab account, they are prompted to create an account -using the email address the invitation was sent to. + - GitLab username, they are added to the members list. + - Email address, an invitation is sent to their email address, and they are prompted to create an account. + If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. + Unaccepted invites are automatically deleted after 90 days. ### Which roles you can assign @@ -97,14 +160,14 @@ The Owner [role](../../permissions.md#project-members-permissions) can be added > - 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. -When you add a group to a project, each user in the group gets access to the project. -Each user's access is based on: +When you add a group to a project, every group member (direct or inherited) gets access to the project. +Each member's access is based on the: -- The role they're assigned in the group. -- The maximum role you choose when you invite the group. +- Role they're assigned in the group. +- Maximum role you choose when you invite the group. -If a user has a group role with fewer permissions than the maximum project role, the user keeps the permissions of their group role. -For example, if you add a user with the Guest role to a project with a maximum role of Maintainer, the user has only the permissions of the Guest role. +If a group member has a role in the group with fewer permissions than the maximum project role, the member keeps the permissions of their group role. +For example, if you add a member with the Guest role to a project with a maximum role of Maintainer, the member has only the permissions of the Guest role in the project. Prerequisites: @@ -128,10 +191,10 @@ The **Members** tab shows: - Members who are directly assigned to the project. - If the project was created in a group [namespace](../../namespace/index.md), members of that group. -## Import users from another project +## Import members from another project -You can import another project's users to your own project. Users -retain the same permissions as the project you import them from. +You can import another project's members to your own project. +Imported project members retain the same permissions as the project you import them from. Prerequisite: @@ -147,37 +210,16 @@ To import users: After the success message displays, refresh the page to view the new members. -## Inherited membership - -When your project belongs to a group, group members inherit their role -from the group. - - - -In this example: - -- Three members have access to the project. -- **User 0** is a Reporter and has inherited their role from the **demo** group, - which contains the project. -- **User 1** belongs directly to the project. In the **Source** column, they are listed - as a **Direct member**. -- **Administrator** is the [Owner](../../permissions.md) and member of all groups. - They have inherited their role from the **demo** group. - -If a user is a: - -- Direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. -- Inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. - ## Remove a member from a project -If a user is a direct member of a project, you can remove them. -If membership is inherited from a parent group, then the member can be removed only from the parent -group itself. +If a user is: + +- A direct member of a project, you can remove them directly from the project. +- An inherited member from a parent group, you can only remove them from the parent group itself. Prerequisites: -- To remove direct members with the: +- To remove direct members that have the: - Maintainer, Developer, Reporter, or Guest role, you must have the Maintainer role. - Owner role, you must have the Owner role. - Optional. Unassign the member from all issues and merge requests that @@ -191,7 +233,7 @@ To remove a member from a project: 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. 1. To prevent leaks of sensitive information from private projects, verify the - user has not forked the private repository or created webhooks. Existing forks continue to receive + member has not forked the private repository or created webhooks. Existing forks continue to receive changes from the upstream project, and webhooks continue to receive updates. You may also want to configure your project to prevent projects in a group [from being forked outside their group](../../group/access_and_permissions.md#prevent-project-forking-outside-group). diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index d1ee42f723d..4dda68a6d08 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -4,60 +4,41 @@ group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Share projects with other groups **(FREE)** +# Share a project with a group **(FREE)** -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. +When you want a group to have access to your project, +you can invite [a group](../../group/index.md) to the project. +The group's members get access to the project, which becomes a *shared project*. -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. +## Example -When a project is shared with a group: +For a project that was created by `Group 1`: -- 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**, in the **Max role** column. - When sharing a project with a group, a user's assigned **Max role** is the lowest - of either: +- The members of `Group 1` have access to the project. +- The owner of `Group 1` can invite `Group 2` to the project. +This way, members of both `Group 1` and `Group 2` have access to the shared project. - - The role assigned in the group membership. - - The maximum role selected when sharing the project with the group. +## Prerequisites - Assigning a higher maximum role to the group doesn't give group users higher roles than - the roles already assigned to them in the group. -- The group is listed in the **Groups** tab. -- The project is listed on the group dashboard. +To invite a group to a project, you must be at least one of the following: -Be aware of the restrictions that apply when you share projects with: +- Explicitly defined as a [member](index.md) of the project. +- Explicitly defined as a member of a group or subgroup that has access to the project. +- An administrator. -- [Groups with a more restrictive visibility level](#share-projects-with-groups-with-a-more-restrictive-visibility-level). -- [Restricted sharing](#prevent-project-sharing). +In addition: -## Share projects with groups with a more restrictive visibility level +- The group you're inviting must have a more restrictive + [visibility level](../../public_access.md#project-and-group-visibility) + than the project. For example, you can invite: + - A private group to a public project. + - An internal group to a public project. + - A private group to an internal project. -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. - -For example, you can share: - -- A public project with a private group. -- A public project with an internal group. -- An internal project with a private group. - -This restriction applies to subgroups as well. For example, `group/subgroup01/project`: - -- Can't be shared with `group`. -- Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. - -When you share a project with a group that has a more restrictive visibility level than the 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. +- The group or subgroup must be in the project's [namespace](../../namespace/index.md). + For example, a project in the namespace `group/subgroup01/project`: + - Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. + - Cannot be shared with `group`. ## Share a project with a group @@ -68,22 +49,57 @@ group members listed in addition to members of the project. > - [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: +You can share a project with a group by inviting that group to the project. -- 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. - -To share a project with a group: +To invite a group to a 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. On the left sidebar, 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**. -## Prevent project sharing +All group members, members of subgroups, and members of other projects the group has access to +are given access to the project. In addition: + +- On the group's page, the project is listed on the **Shared projects** tab. +- On the project's **Members** page, the group is listed on the **Groups** tab. +- Each user is assigned a maximum role. + +## Maximum role + +When multiple groups contain the same members, and the groups +have access to the same project, the group members are +given the most restrictive role for the project. + +This most restrictive role is called the *maximum role*, or **Max role**. + +The member's **Max role** is the more restrictive of: + +- The role the user is assigned for the group. +- The role you chose when you invited the group to the project. + +### View the member's Max role + +To view the maximum role assigned to a member: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. +1. In the **Max role** column, view the user's maximum assigned role. + +## View a group's shared projects + +In a group, a shared project is a project to which the group members gained access through the [**Invite group**](#share-a-project-with-a-group) action. + +To view a group's shared projects: + +1. On the top bar, select **Main menu > Group** and find your group. +1. On the group page, select the **Shared projects** tab. + +A list of shared projects is displayed. + +## Related topics -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). +- [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/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index d3d95a5bf61..0729e024df4 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Collaborate on merge requests across forks **(FREE)** -When you open a merge request from your fork, you can allow upstream +When you open a merge request from your [fork](../repository/forking_workflow.md), you can allow upstream members to collaborate with you on your branch. When you enable this option, members who have permission to merge to the target branch get permission to write to the merge request's source branch. @@ -15,7 +15,7 @@ The members of the upstream project can then make small fixes or rebase branches before merging. This feature is available for merge requests across forked projects that are -publicly accessible. +[publicly accessible](../../public_access.md). ## Allow commits from upstream members diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 92ff78082e3..21e2055cb61 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -8,8 +8,6 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/appro # Merge request approvals **(FREE)** -> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. - You can configure your merge requests so that they must be approved before they can be merged. While [GitLab Free](https://about.gitlab.com/pricing/) allows all users with Developer or greater [permissions](../../../permissions.md) to diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 51f7254bfda..0a5e7c29860 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -254,6 +254,15 @@ the API. For more information about this validation error, read [issue 285129](https://gitlab.com/gitlab-org/gitlab/-/issues/285129). +### Groups need explicit or inherited Developer role on a project + +A group created to handle approvals may be created in a different area of the +project hierarchy than the project requiring review. If this happens, the approvals group +isn't recognized as a valid Code Owner for the project, nor does it display in the +project's **Approvals** list. To fix this problem, add the approval group as a shared group +high enough in the shared hierarchy so the project requiring review inherits this +group of users. + ## Security Approvals **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index a8acab3898b..1ab564c108b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -87,8 +87,7 @@ to a merge request may or may not be able to approve the work: [code owners](../../code_owners.md) who commit to a merge request cannot approve it, when the merge request affects files they own. -To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), -read the official Git documentation for an explanation. +For more information, see the [official Git documentation](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). ## Prevent editing approval rules in merge requests @@ -121,13 +120,17 @@ permission enables an electronic signature for approvals, such as the one define ## Remove all approvals when commits are added to the source branch -By default, an approval on a merge request remains in place, even if you add more changes -after the approval. If you want to remove all existing approvals on a merge request -when more changes are added to it: +By default, an approval on a merge request is removed when you add more changes +after the approval. In GitLab Premium and higher tiers, to keep existing approvals +after more changes are added to the merge request: 1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval settings** and - select **Remove all approvals**. + clear the **Remove all approvals** checkbox. + + NOTE: + This setting is not available in GitLab Free. + 1. Select **Save changes**. Approvals aren't removed when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods) @@ -155,7 +158,7 @@ To do this: You can require specific approvals if a merge request would result in a decline in code test coverage. -To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). +For more information, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). ## Settings cascading diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 07ee2ef90c4..8f6b1a32424 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -57,7 +57,7 @@ clear your browser's cookies or change this behavior again. To view one file at a time for all of your merge requests: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. Scroll to the **Behavior** section and select the **Show one file at a time on merge request's Changes tab** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 388c6fb55ac..9fac872ac4b 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -55,7 +55,7 @@ by the merge request: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**, and find your merge request. 1. Scroll to the merge request reports section, and find the **Merged by** report. -1. In the top right, select **Cherry-pick**: +1. In the upper right, select **Cherry-pick**:  1. In the modal window, select the project and branch to cherry-pick into. @@ -87,7 +87,7 @@ list of commits included in a merge request: 1. On the left sidebar, select **Merge requests**, and find your merge request. 1. In the merge request's secondary menu, select **Commits** to display the commit details page. 1. Select the title of the commit you want to cherry-pick. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. 1. Select **Cherry-pick**. @@ -101,7 +101,7 @@ when you view that file in your project's Git repository: 1. On the left sidebar, select **Repository > Files** and go to the file changed by the commit. 1. Select **History**, then select the title of the commit you want to cherry-pick. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. 1. Select **Cherry-pick**. @@ -115,7 +115,7 @@ You can cherry-pick merge requests from the same project, or forks of the same project, from the GitLab user interface: 1. In the merge request's secondary menu, select **Commits** to display the commit details page. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  1. Optional. Select **Start a new merge request** if you're ready to create a merge request. diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index a14d8bddd24..f8c24e4067b 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -89,7 +89,7 @@ Commit message templates support these variables: | `%{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.`| +| `%{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.`| Any line containing only an empty variable is removed. If the line to be removed is both preceded and followed by an empty line, the preceding empty line is also removed. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index 6063d64a721..932eec5e631 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -59,7 +59,8 @@ in the user interface, and you can also resolve conflicts locally through the co To resolve less-complex conflicts from the GitLab user interface: -1. Go to your merge request. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. The conflicts are @@ -83,7 +84,8 @@ Some merge conflicts are more complex, requiring you to manually modify lines to resolve their conflicts. Use the merge conflict resolution editor to resolve complex conflicts in the GitLab interface: -1. Go to your merge request. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 542edc11c44..875312bbb7c 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -19,7 +19,7 @@ You can create a merge request from the list of merge requests. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. -1. In the top right, select **New merge request**. +1. In the upper right, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. @@ -35,14 +35,14 @@ If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. After merging the merge request, the issue is closed automatically, unless [automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown below the issue description. +You can see a **Create merge request** dropdown list below the issue description. NOTE: In GitLab 14.8 and later, selecting **Create merge request** [redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) instead of immediately creating the merge request. -The **Create merge request** button doesn't display if: +**Create merge request** doesn't display if: - A branch with the same name already exists. - A merge request already exists for this branch. @@ -54,15 +54,14 @@ To make this button appear, one possible workaround is to After removal, the fork relationship cannot be restored. This project can no longer be able to receive or send merge requests to the source project, or other forks. -This dropdown contains the options **Create merge request and branch** and **Create branch**. +The dropdown list contains the options **Create merge request and branch** and **Create branch**. After selecting one of these options, a new branch or branch and merge request is created based on your project's [default branch](../repository/branches/default.md). -The branch name is based on an internal ID, and the issue title. The example -screenshot above creates a branch named -`2-make-static-site-auto-deploy-and-serve`. +The branch name is based on your project's branch name template. The default template +is `%{id}-%{title}`. Supported variables for branch name templates are `%{id}` and `%{title}`. -When you select the **Create branch** button in an empty +When you select **Create branch** in an empty repository project, GitLab performs these actions: - Creates a default branch. @@ -82,7 +81,7 @@ merge request is merged. You can create a merge request when you add, edit, or upload a file to a repository. -1. Add, edit, or upload a file to the repository. +1. [Add, edit, or upload](../repository/web_editor.md) a file to the repository. 1. In the **Commit message**, enter a reason for the commit. 1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars). 1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only @@ -172,7 +171,7 @@ To create a merge request by sending an email: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. -1. In the top right, select **Email a new merge request to this project**. +1. In the upper right, select **Email a new merge request to this project**. An email address is displayed. Copy this address. Ensure you keep this address private. 1. Open an email and compose a message with the following information: diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 662189c5e40..9028a9411ea 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -14,7 +14,7 @@ To export merge requests to a CSV file: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** . -1. Add any searches or filters. This can help you keep the size of the CSV file under the 15MB limit. The limit ensures +1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures the file can be emailed to a variety of email providers. 1. Select **Export as CSV** (**{export}**). 1. Confirm the correct number of merge requests are to be exported. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 0bc9b337e3b..62820988701 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -21,12 +21,13 @@ the **Merge** button until you remove the **Draft** flag: > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/228685) all support for using **WIP** in GitLab 14.8. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. > `/draft` quick action as a toggle [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108073) the draft status to use a checkbox in GitLab 15.8. There are several ways to flag a merge request as a draft: -- **Viewing a merge request**: In the top right corner of the merge request, select **Mark as draft**. +- **Viewing a merge request**: In the upper-right corner of the merge request, select **Mark as draft**. - **Creating or editing a merge request**: Add `[Draft]`, `Draft:` or `(Draft)` to - the beginning of the merge request's title, or select **Start the title with Draft:** + the beginning of the merge request's title, or select **Mark as draft** below the **Title** field. - **Commenting in an existing merge request**: Add the `/draft` [quick action](../quick_actions.md#issues-merge-requests-and-epics) @@ -40,14 +41,14 @@ There are several ways to flag a merge request as a draft: When a merge request is ready to be merged, you can remove the `Draft` flag in several ways: -- **Viewing a merge request**: In the top right corner of the merge request, select **Mark as ready**. +- **Viewing a merge request**: In the upper-right corner of the merge request, select **Mark as ready**. Users with at least the Developer role can also scroll to the bottom of the merge request description and select **Mark as ready**:  - **Editing an existing merge request**: Remove `[Draft]`, `Draft:` or `(Draft)` - from the beginning of the title, or select **Remove the Draft: prefix from the title** + from the beginning of the title, or clear **Mark as draft** below the **Title** field. - **Commenting in an existing merge request**: Add the `/ready` [quick action](../quick_actions.md#issues-merge-requests-and-epics) diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 58750cdf5bc..4125d8e8fdb 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,147 +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 -description: "Getting started with merge requests." +redirect_to: 'index.md' +remove_date: '2023-03-31' --- -# Getting started with merge requests **(FREE)** +This document was moved to [another location](index.md). -A merge request (**MR**) is the basis of GitLab as a tool for code -collaboration and version control. - -When working in a Git-based platform, you can use branching -strategies to collaborate on code. - -A repository is composed by its _default branch_, which contains -the major version of the codebase, from which you create minor -branches, also called _feature branches_, to propose changes to -the codebase without introducing them directly into the major -version of the codebase. - -Branching is especially important when collaborating with others, -avoiding changes to be pushed directly to the default branch -without prior reviews, tests, and approvals. - -When you create a new feature branch, change the files, and push -it to GitLab, you have the option to create a **merge request**, -which is essentially a _request_ to merge one branch into another. - -The branch you added your changes into is called _source branch_ -while the branch you request to merge your changes into is -called _target branch_. - -The target branch can be the default or any other branch, depending -on the branching strategies you choose. - -In a merge request, beyond visualizing the differences between the -original content and your proposed changes, you can execute a -[significant number of tasks](#what-you-can-do-with-merge-requests) -before concluding your work and merging the merge request. - -You can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for -a quick overview of working with merge requests. - -## What you can do with merge requests - -When you start a new merge request, you can immediately include the following -options. You can also add them later by either selecting **Edit** on the merge -request's page at the top-right side, or by using -[keyboard shortcuts for merge requests](../../shortcuts.md#merge-requests): - -- [Assign](index.md#assign-a-user-to-a-merge-request) the merge request to a colleague for review. With [multiple assignees](index.md#assign-multiple-users), you can assign it to more than one person at a time. -- Set a [milestone](../milestones/index.md) to track time-sensitive changes. -- Add [labels](../labels.md) to help contextualize and filter your merge requests over time. -- [Require approval](approvals/index.md#required-approvals) from your team. -- [Close issues automatically](#merge-requests-to-close-issues) when they are merged. -- Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. -- Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. -- Set the merge request as a [**Draft**](drafts.md) to avoid accidental merges before it is ready. - -After you have created the merge request, you can also: - -- [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. -- [Perform inline code reviews](reviews/index.md). -- Add [merge request dependencies](dependencies.md) to restrict it to be merged only when other merge requests have been merged. -- Preview continuous integration [pipelines on the merge request widget](widgets.md). -- Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). -- [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](reviews/index.md) to create multiple comments on a diff and publish them when you're ready. -- Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. -- Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). - -Many of these options can be set: - -- From the merge request page, with [keyboard shortcuts](../../shortcuts.md#merge-requests). -- When pushing changes from the command line, with [Git push options](../push_options.md). - -See also other [features associated to merge requests](reviews/index.md#associated-features). - -### Reviewer - -WARNING: -Requesting a code review is an important part of contributing code. However, deciding who should review -your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and -reviewers makes it hard for others to determine who's doing what on a merge request. - -The merge request Reviewers feature enables you to request a review of your work, and -see the status of the review. Reviewers help distinguish the roles of the users -involved in the merge request. In comparison to an **Assignee**, who is directly -responsible for creating or merging a merge request, a **Reviewer** is a team member -who may only be involved in one aspect of the merge request, such as a peer review. - -To request a review of a merge request, expand the **Reviewers** select box in -the right-hand sidebar. Search for the users you want to request a review from. -When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. - -To learn more, read [Review a merge request](reviews/index.md). - -### Merge requests to close issues - -To create a merge request to close an issue when it's merged, you can either: - -- [Add a note in the MR description](../issues/managing_issues.md#closing-issues-automatically). -- In the issue, select **Create a merge request**. Then, you can either: - - - Create a new branch and [a draft merge request](../merge_requests/drafts.md) - in one action. The branch is named `issuenumber-title` by default, but you can - choose any name, and GitLab verifies that it's not already in use. The merge request - inherits the milestone and labels of the issue, and is set to automatically - close the issue when it is merged. - - Create a [new branch](creating_merge_requests.md#from-an-issue) - only, with its name starting with the issue number. - -If the issue is [confidential](../issues/confidential_issues.md), -you may want to use a different workflow for -[merge requests for confidential issues](confidential.md) -to prevent confidential information from being exposed. - -### Deleting the source branch - -When creating a merge request, select the -**Delete source branch when merge request accepted** option, and the source -branch is deleted when the merge request is merged. To make this option -enabled by default for all new merge requests, enable it in the -[project's settings](../settings/index.md#configure-merge-request-settings-for-a-project). - -This option is also visible in an existing merge request next to -the merge request button and can be selected or cleared before merging. -It is only visible to users with the Maintainer role -in the source project. - -If the user viewing the merge request does not have the correct -permissions to delete the source branch and the source branch -is set for deletion, the merge request widget displays the -**Deletes source branch** text. - - - -## Recommendations and best practices for merge requests - -- When working locally in your branch, add multiple commits and only push when - you're done, so GitLab runs only one pipeline for all the commits pushed - at once. By doing so, you save CI/CD minutes. -- Delete feature branches on merge or after merging them to keep your repository clean. -- Take one thing at a time and ship the smallest changes possible. By doing so, - reviews are faster and your changes are less prone to errors. -- Do not use capital letters nor special chars in branch names. +<!-- This redirect file can be deleted after <2023-03-31>. --> +<!-- 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/index.md b/doc/user/project/merge_requests/index.md index 21651fd645c..a633366cc62 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -7,8 +7,9 @@ type: index, reference # Merge requests **(FREE)** -Merge requests (MRs) are the way you check source code changes into a branch. -When you open a merge request, you can visualize and collaborate on the code changes before merge. +To incorporate changes from a source branch to a target branch, you use a *merge request* (MR). + +When you open a merge request, you can visualize and collaborate on the changes before merge. Merge requests include: - A description of the request. @@ -17,7 +18,9 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. -Read more about [how to get started](getting_started.md). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a quick overview of merge requests, +view [this GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE). ## Create a merge request @@ -62,7 +65,7 @@ or: or: -1. On the top bar, on the top right, select **{merge-request-open}** **Merge requests**. +1. On the top bar, in the upper right, select **{merge-request-open}** **Merge requests**. 1. From the dropdown list, select **Assigned to you**. ## Filter the list of merge requests @@ -205,6 +208,15 @@ To delete a merge request: 1. Go to the merge request you want to delete, and select **Edit**. 1. Scroll to the bottom of the page, and select **Delete merge request**. +### Delete the source branch on merge + +You can delete the source branch for a merge request: + +- When you create a merge request, by selecting **Delete source branch when merge request accepted**. +- When you merge a merge request, if you have the Maintainer role, by selecting **Delete source branch**. + +An administrator can make this option the default in the project's settings. + ### Update merge requests when target branch merges **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. @@ -243,10 +255,10 @@ like in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87727/diffs?diff_i FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `moved_mr_sidebar`. -On GitLab.com, this feature is not available. +On GitLab.com, this feature is enabled in the following projects: `gitlab-org/gitlab`, `gitlab-com/www-gitlab-com`, and `gitlab-org/customers-gitlab-com`. When this feature flag is enabled, you can find the following actions in -**Merge request actions** (**{ellipsis_v}**) on the top right: +**Merge request actions** (**{ellipsis_v}**) in the upper right: - The [notifications](../../profile/notifications.md#edit-notification-settings-for-issues-merge-requests-and-epics) toggle - Mark merge request as ready or [draft](../merge_requests/drafts.md) @@ -366,5 +378,5 @@ with a backup of the instance ready to be restored, just in case. u = User.find_by_username('<username>') p = Project.find_by_full_path('<namespace/project>') m = p.merge_requests.find_by(iid: <iid>) -Issuable::DestroyService.new(project: m.project, current_user: u).execute(m) +Issuable::DestroyService.new(container: m.project, current_user: u).execute(m) ``` diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index b1d07a740bf..1f7e15ee982 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -199,7 +199,7 @@ In these merge methods, you can merge only when your source branch is up-to-date If a fast-forward merge is not possible but a conflict-free rebase is possible, GitLab provides: -- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). +- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#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 diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 76f351f1346..5878873f209 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -62,7 +62,7 @@ To do this: 1. If you don't know the merge request the commit originated from: 1. On the left sidebar, select **Repository > Commits**. 1. Select the title of the commit to display full information about the commit. -1. In the top right corner, select **Options**, then select **Revert**. +1. In the upper-right corner, select **Options**, then select **Revert**. 1. In **Revert in branch**, select the branch to revert your changes into. 1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. 1. Select **Revert**. diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index f17015aef4e..dd07f0b4a6e 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -15,21 +15,21 @@ Suggested Reviewers is the first user-facing GitLab machine learning (ML) powere When a Project Maintainer or Owner enables Suggested Reviewers in project settings GitLab kicks off a data extraction job for the project which leverages the Merge Request API to understand pattern of review including recency, domain experience, and frequency to suggest an appropriate reviewer. -This data extraction job can take a few hours to complete (possibly up to a day), which is largely dependent on the size of the project. The process is automated and no action is needed during this process. Once data extraction is complete, you will start getting suggestions in merge requests. +This data extraction job can take a few hours to complete (possibly up to a day), which is largely dependent on the size of the project. The process is automated and no action is needed during this process. Once data extraction is complete, you start getting suggestions in merge requests. ### Generating suggestions -Once Suggested Reviewers is enabled and the data extraction is complete, new merge requests or new commits to existing merge requests will automatically trigger a Suggested Reviewers ML model inference and generate up to 5 suggested reviewers. These suggestions are contextual to the changes in the merge request. Additional commits to merge requests may change the reviewer suggestions which will automatically update in the reviewer dropdown list. +Once Suggested Reviewers is enabled and the data extraction is complete, new merge requests or new commits to existing merge requests automatically trigger a Suggested Reviewers ML model inference and generate up to 5 suggested reviewers. These suggestions are contextual to the changes in the merge request. Additional commits to merge requests may change the reviewer suggestions, which are automatically updated in the reviewer dropdown list. ## Progressive enhancement -This feature is designed as a progressive enhancement to the existing GitLab Reviewers functionality. The GitLab Reviewer UI will only offer suggestions if the ML engine is able to provide a recommendation. In the event of an issue or model inference failure, the feature will gracefully degrade. At no point with the usage of Suggested Reviewers prevent a user from being able to manually set a reviewer. +This feature is designed as a progressive enhancement to the existing GitLab Reviewers functionality. The GitLab Reviewer UI only offers suggestions if the ML engine is able to provide a recommendation. In the event of an issue or model inference failure, the feature gracefully degrades. At no point with the usage of Suggested Reviewers prevent a user from being able to manually set a reviewer. ## 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 every time. +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 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. +Through analysis of beta customer usage, we find that the Suggested Reviewers ML model provides suggestions that are adopted in 60% of cases. We plan to introduce 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 plan to offer an opt-in feature in the future which allows the model to use your project's data for training the underlying model. ## Off by default diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png Binary files differdeleted file mode 100644 index c2aa0689d65..00000000000 --- a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png Binary files differnew file mode 100644 index 00000000000..6839c675625 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png Binary files differdeleted file mode 100644 index 3828868965b..00000000000 --- a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png Binary files differnew file mode 100644 index 00000000000..c7942d1e36d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png Binary files differdeleted file mode 100644 index aae75b0736c..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png Binary files differnew file mode 100644 index 00000000000..70db0d79eaf --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 9a75c038dbc..5291a845437 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -25,21 +25,27 @@ review merge requests in Visual Studio Code. > [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4. -GitLab can recommend reviewers with Suggested Reviewers. Using the changes in a merge request and a project's contribution graph, machine learning powered suggestions appear in the reviewer section of the right merge request sidebar. +GitLab can suggest reviewers. Using the changes in a merge request and a project's contribution graph, machine learning suggestions appear in the reviewer section of the right sidebar. - + This feature is currently in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta) behind a [feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/368356). -Learn more about [how suggested reviewers works and data privacy](data_usage.md). +For more information, see [Data usage in Suggested Reviewers](data_usage.md). ### Enable suggested reviewers -Project Maintainers or Owners can enable suggested reviewers by visiting the [project settings](../../settings/index.md). +Project Maintainers or Owners can enable suggested reviewers by visiting +the [project settings](../../settings/index.md). -Enabling suggested reviewers will trigger GitLab to create an ML model for your project that will be used to generate reviewers. The larger your project, the longer this can take, but usually, the model will be ready to generate suggestions within a few hours. +Enabling suggested reviewers triggers GitLab to create an ML model for your +project that is used to generate reviewers. The larger your project, the longer +this process can take. Usually, the model is ready to generate suggestions +within a few hours. -No action is required once the feature is enabled. Once the model is ready, recommendations will populate the Reviewer dropdown list in the right-hand sidebar of a merge request with new commits. +No action is required after the feature is enabled. After the model is ready, +recommendations populate the **Reviewer** dropdown list in the right-hand sidebar +of a merge request with new commits. ## Review a merge request @@ -51,8 +57,8 @@ to you. When you're ready, you can publish them together in a single action. To start your review: 1. Go to the merge request you want to review, and select the **Changes** tab. - To learn more about navigating the diffs displayed in this tab, read - [Changes tab in merge requests](../changes.md). + For more information about navigating the diffs displayed in this tab, see + [Changes in merge requests](../changes.md). 1. Select the **{comment}** **comment** icon in the gutter to expand the diff lines and display a comment box. In GitLab version 13.2 and later, you can [select multiple lines](#comment-on-multiple-lines). @@ -78,7 +84,7 @@ 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**. +1. In the upper 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 @@ -101,7 +107,7 @@ 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**. +1. In the upper 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 @@ -147,7 +153,7 @@ To resolve or unresolve a thread when replying to a comment: Pending comments display information about the action to be taken when the comment is published: -- **{check-circle-filled}** Thread will be resolved. +- **{check-circle-filled}** Thread is resolved. - **{check-circle}** Thread stays unresolved. ### Add a new comment @@ -170,11 +176,11 @@ below the name of each suggested reviewer. [Code Owners](../../code_owners.md) a This example shows reviewers and approval rules when creating a new merge request: - + This example shows reviewers and approval rules in a merge request sidebar: - + ### Request a new review @@ -194,7 +200,7 @@ them a notification email. ## Comment on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) select-and-drag features in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. When commenting on a diff, you can select which lines of code your comment refers diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 2894b71e7e6..62a2baa049b 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -22,25 +22,23 @@ respond with an associated status. This status is then displayed as a non-blocki widget within the merge request to surface this status to the merge request author or reviewers at the merge request level itself. -The lack of a status check response does not block the merging of a merge request. - You can configure merge request status checks for each individual project. These are not shared between projects. -To learn more about use cases, feature discovery, and development timelines, -see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). +For more information about use cases, feature discovery, and development timelines, +see [epic 3869](https://gitlab.com/groups/gitlab-org/-/epics/3869). ## Block merges of merge requests unless all status checks have passed > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372340) in GitLab 15.8. +> - Enabled on self-managed and feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111492) in GitLab 15.9. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to -[enable the feature flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail: -By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail, enable this feature -using the [project API](../../../api/projects.md#edit-project). You must also [enable the feature flag](../../../administration/feature_flags.md) named -`only_allow_merge_if_all_status_checks_passed` on self-managed GitLab. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Select the **Status checks must succeed** checkbox. +1. Select **Save changes**. ## Lifecycle @@ -63,7 +61,7 @@ Merge requests return a `409 Conflict` error to any responses that do not refer External status checks have the following states: -- `pending` - The default state. No response can been received by the merge request from the external service. +- `pending` - The default state. No response has been received by the merge request from the external service. - `passed` - A response from the external service has been received and approved by it. - `failed` - A response from the external service has been received and denied by it. @@ -146,7 +144,7 @@ The **Remove status check?** modal is then shown. To complete the deletion of the status check you must select the **Remove status check** button. This **permanently** deletes -the status check and it **will not** be recoverable. +the status check and it **is not** recoverable. ## Status checks widget diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index bbe4aadc50d..5f9a2961df5 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -48,8 +48,7 @@ In a group, GitLab displays milestones that belong to the group and all projects If a project has issue tracking [turned off](../settings/index.md#configure-project-visibility-features-and-permissions), -you can get to the milestones page -by going to its URL. +to get to the milestones page, enter its URL. To do so: diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index 0ff354562fd..2b4ce6d2fd0 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -14,6 +14,7 @@ built-in CI/CD to deploy your app. Projects can be available [publicly, internally, or privately](../public_access.md). GitLab does not limit the number of private projects you can create. +- [Create a project](index.md) - [Manage projects](working_with_projects.md) - [Project visibility](../public_access.md) - [Project settings](../project/settings/index.md) @@ -28,6 +29,5 @@ GitLab does not limit the number of private projects you can create. - [Deploy keys](../../user/project/deploy_keys/index.md) - [Deploy tokens](../../user/project/deploy_tokens/index.md) - [File finder](../../user/project/repository/file_finder.md) -- [GitLab Pages](../../user/project/pages/index.md) - [Migrating projects](../../user/project/import/index.md) - [Migrate projects by using file exports](../../user/project/settings/import_export.md) diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 197524f2fc5..e55cf337d16 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 @@ -21,7 +21,7 @@ GitLab Pages with your own (sub)domain, you need to access your domain's registrar control panel to add a DNS record pointing it back to your GitLab Pages site. -Note that **how to** add DNS records depends on which server your domain +How to add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are not an administrator of your domain, and don't have access to your registrar, you must ask the technical support of your hosting service 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 2f814bb0e65..24e9e6e15a4 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 @@ -56,8 +56,11 @@ To add your custom domain to GitLab Pages: 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. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. In the upper-right corner, select **New Domain**. +1. In **Domain**, enter the domain name. 1. Optional. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). You can also add the certificate and key later. 1. Select **Create New Domain**. @@ -102,7 +105,7 @@ server running on your instance).  WARNING: -Note that if you use your root domain for your GitLab Pages website +If you use your root domain for your GitLab Pages website **only**, and if your domain registrar supports this feature, you can add a DNS apex `CNAME` record instead of an `A` record. The main advantage of doing so is that when GitLab Pages IP on GitLab.com @@ -122,7 +125,7 @@ Subdomains (`subdomain.example.com`) require: | `subdomain.example.com` | `ALIAS`/`CNAME` | `namespace.gitlab.io` | | `_gitlab-pages-verification-code.subdomain.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -Note that, whether it's a user or a project website, the DNS record +Whether it's a user or a project website, the DNS record should point to your Pages domain (`namespace.gitlab.io`), without any `/project-name`. @@ -165,10 +168,13 @@ If you're using Cloudflare, check Once you have added all the DNS records: -1. Go back at your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Locate your domain name and select **Details**. -1. Select the **Retry verification** button to activate your new domain. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. In **Verification status**, select **Retry verification** (**{retry}**).  @@ -184,7 +190,7 @@ from the GitLab project. > - Domain verification is **required for GitLab.com users**; for GitLab self-managed instances, your GitLab administrator has the option to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). -> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), +> - [DNS propagation may take some time (up to 24 hours)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification fails, and attempts to visit your domain result in a 404. > - Once your domain has been verified, leave the verification record @@ -287,12 +293,28 @@ meet these requirements. #### Steps -- To add the certificate at the time you add a new domain, go to your - project's **Settings > Pages > New Domain** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)), add the domain name and the - certificate. -- To add the certificate to a domain previously added, go to your - project's **Settings > Pages**, locate your domain name, select **Details** and **Edit** to add the certificate. +- To add the certificate at the time you add a new domain: + + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). + 1. In the upper-right corner, select **New Domain**. + 1. In **Domain**, enter the domain name. + 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). + 1. Select **Create New Domain**. + +- To add the certificate to a domain previously added: + + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). + 1. Next to the domain name, select **Edit**. + 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). + 1. Select **Save changes**. NOTE: The Pages menu entry may also be located at **Deployments > Pages**, [more information](../index.md#menu-position-test) @@ -319,9 +341,13 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. Navigate to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Tick the checkbox **Force HTTPS (requires valid certificates)**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Select the **Force HTTPS (requires valid certificates)** checkbox. +1. Select **Save changes**. If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 770fb4f450a..95ac2e50f29 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -42,11 +42,13 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. Navigate to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Find your domain and select **Details**. -1. Select **Edit** in the top-right corner. -1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**: +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. Turn on the **Automatic certificate management using Let's Encrypt** toggle.  @@ -60,7 +62,7 @@ associated Pages domain. GitLab also renews it automatically. > - Issuing the certificate and updating Pages configuration > **can take up to an hour**. > - If you already have an SSL certificate in domain settings it -> continues to work until replaced by the Let's Encrypt's certificate. +> continues to work until replaced by the Let's Encrypt certificate. ## Troubleshooting @@ -70,31 +72,37 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. Go to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Select **Edit** on your domain. -1. Select **Retry**. -1. If you're still seeing the same error: - 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. - 1. Make sure your domain **doesn't have** an `AAAA` DNS record. - 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). - 1. Go to step 1. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. In **Verification status**, select **Retry verification** (**{retry}**). +1. If you're still getting the same error: + 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. + 1. Make sure your domain **doesn't have** an `AAAA` DNS record. + 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). + 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). + 1. Go to step 1. ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. Go to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Select **Remove** on your domain. -1. [Add the domain again and verify it](index.md#1-add-a-custom-domain). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Remove**. +1. [Add the domain again, and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). -1. If you still see the same message after some time: - 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. - 1. Make sure your domain **doesn't have** an `AAAA` DNS record. - 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Go to step 1. +1. If you're still getting the same error: + 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. + 1. Make sure your domain **doesn't have** an `AAAA` DNS record. + 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). + 1. Go to step 1. <!-- 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 diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index b9d2f8cb9a6..398d8dc6e1e 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -29,7 +29,7 @@ This might be your first question. If our sites are hosted by GitLab Pages, they are static, hence we are not dealing with server-side scripts nor credit card transactions, then why do we need secure connections? -Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" +When HTTPS came out in 1990, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" security measure, necessary just for big companies like banks and shopping sites with financial transactions. @@ -60,7 +60,7 @@ reiterating the importance of HTTPS. GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis.html) format, issued by [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) or as -[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) +[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). [Self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) for public websites for security reasons and to ensure that browsers trust your site's certificate. There are various kinds of certificates, each one 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 e0448621c6a..f596e418b02 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 @@ -27,9 +27,11 @@ these steps, you may have to do additional configuration for the Pages site to g If everything is configured correctly, the site can take approximately 30 minutes to deploy. To view the pipeline, go to **CI/CD > Pipelines**. + When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index e1a245851cb..509609e9b89 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 @@ -19,14 +19,15 @@ To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. 1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#creating-a-fork). -1. In the top right, select **Fork** and then choose a namespace to fork to. +1. In the upper right, select **Fork** and then choose a namespace to fork to. 1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. GitLab CI/CD builds and deploys your site. The site can take approximately 30 minutes to deploy. -When the pipeline is finished, go to **Settings > Pages** to find the link -to your website from your project. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 82e544b0701..a3d6c8f75f9 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -175,10 +175,11 @@ deploy your website: 1. Save and commit the `.gitlab-ci.yml` file. 1. Go to **CI/CD > Pipelines** to watch the pipeline. -1. When the pipeline succeeds, go to **Settings > Pages** - to view the URL where your site is now available. (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +1. When the pipeline is finished, go to **Settings > Pages** to find the link to + your Pages website. + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). When this `pages` job completes successfully, a special `pages:deploy` job appears in the pipeline view. It prepares the content of the website for the GitLab Pages daemon. GitLab runs it in the background and doesn't use a runner. diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index a9988b1fb99..a301d2b64be 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -24,8 +24,9 @@ configured to generate a Pages site. site. When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 984c8e5c619..91c2c532a9a 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -34,8 +34,10 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). A **Get Started with Pages** form appears. If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). 1. For **Step 1**, enter an image name and verify that your files are in a `public` folder. @@ -61,10 +63,10 @@ and on the right side, select **Download artifacts**. ### If the `Get Started with Pages` form is not available -When you go to **Settings > Pages**, the form is not available if you: +The `Get Started with Pages` form is not available if you: - Deployed a GitLab Pages site before. -- Committed a `.gitlab-ci.yml` through the forms at least one time. +- Committed `.gitlab-ci.yml` through the forms at least one time. To fix this issue: diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 89d8fd093b2..691757e3eca 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -31,8 +31,8 @@ like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. You can also publish any website written directly in plain HTML, CSS, and JavaScript. Pages does not support dynamic server-side processing, for instance, as `.php` and `.asp` requires. -Learn more about -[static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). +For more information, see +[Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). ## Menu Position Test @@ -63,7 +63,7 @@ To update a GitLab Pages website: | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | | [Redirects](redirects.md) | Set up HTTP redirects to forward one page to another. | -Learn more and see examples: +For more information, see: | Document | Description | |----------|-------------| diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index a9b8960d629..51c42eeecb8 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -59,8 +59,8 @@ If the case of `404.html`, there are different scenarios. For example: ## Redirects in GitLab Pages -You can configure redirects for your site using a `_redirects` file. To learn more, read -the [redirects documentation](redirects.md). +You can configure redirects for your site using a `_redirects` file. For more information, see +[Create redirects for GitLab Pages](redirects.md). ## Remove your pages @@ -68,6 +68,9 @@ To remove your pages: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](index.md#menu-position-test). 1. Select **Remove pages**. ## Subdomains of subdomains @@ -253,12 +256,12 @@ instead. Here are some examples of what happens given the above Pages site: | `/info/details` | `200 OK`: `public/info/details.html` | | `/info/details.html` | `200 OK`: `public/info/details.html` | -Note that when `public/data/index.html` exists, it takes priority over the `public/data.html` file +When `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. ## Known issues -For a list of known issues, visit the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). +For a list of known issues, see the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). ## Troubleshooting diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index b98772a6702..248a74a8abc 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -34,7 +34,7 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v - **Only project members**: Only project members are able to browse the website. - **Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. -1. Select **Save changes**. Note that your changes may not take effect immediately. GitLab Pages uses +1. Select **Save changes**. Your changes may not take effect immediately. GitLab Pages uses a caching mechanism for efficiency. Your changes may not take effect until that cache is invalidated, which usually takes less than a minute. diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 8c9f1cbec86..751db136e34 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -17,7 +17,7 @@ for the following frameworks. For Eleventy, you should do one of the following: -- Add the `--output=public` flag in Eleventy's build commands, for example: +- Add the `--output=public` flag in the Eleventy build commands, for example: `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index cf0c0dbff82..f5447fd67ca 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -41,13 +41,11 @@ this test suite! To create redirects, create a configuration file named `_redirects` in the `public/` directory of your GitLab Pages site. -Note that: - - All paths must start with a forward slash `/`. - A default status code of `301` is applied if no [status code](#http-status-codes) is provided. - The `_redirects` file has a file size limit and a maximum number of rules per project, configured at the instance level. Only the first matching rules within the configured maximum are processed. - The default file size limit is 64KB, and the default maximum number of rules is 1,000. + The default file size limit is 64 KB, and the default maximum number of rules is 1,000. - If your GitLab Pages site uses the default domain name (such as `namespace.gitlab.io/projectname`) you must prefix every rule with the project name: @@ -74,7 +72,7 @@ is ignored because `hello.html` exists: /projectname/hello.html /projectname/world.html 302 ``` -GitLab doesn't support Netlify's +GitLab does not support Netlify [force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) to change this behavior. @@ -231,7 +229,7 @@ rule 10: valid rule 11: valid ``` -## Differences from Netlify's implementation +## Differences from Netlify implementation Most supported `_redirects` rules behave the same in both GitLab and Netlify. However, there are some minor differences: diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index b0754e74314..da53fe2f5e9 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -10,6 +10,14 @@ In GitLab, [permissions](../permissions.md) are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose further restrictions on certain branches, they can be protected. +A protected branch controls: + +- Which users can merge into the branch. +- Which users can push to the branch. +- If users can force push to the branch. +- If changes to files listed in the CODEOWNERS file can be pushed directly to the branch. +- Which users can unprotect the branch. + The [default branch](repository/branches/default.md) for your repository is protected by default. ## Who can modify a protected branch diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 9e5413b020e..1f85490795f 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.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 --- -# Push Options **(FREE)** +# Push options **(FREE)** GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) to perform various actions at the same time as pushing changes. Additionally, [Push Rules](repository/push_rules.md) offer server-side control and enforcement options. @@ -36,7 +36,7 @@ You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | | `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | +| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. Only passes variables to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index d12a71c9ab3..90da47f7995 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -71,10 +71,10 @@ threads. Some quick actions might not be available to all subscription tiers. | `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | | `/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`. | +| `/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`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. | | `/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. | +| `/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`. For more information, see [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). | @@ -108,7 +108,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | | `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | | `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8041) in GitLab 12.7). | | `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | @@ -129,6 +129,34 @@ threads. Some quick actions might not be available to all subscription tiers. | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | | `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident).| +## Work items + +The following quick actions can be applied through the description field when editing work items. + +| Command | Task | Objective | Key Result | Action | +|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. | +| `/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. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. | +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | + ## Commit messages The following quick actions are applicable for commit messages: diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 7c2d5088f17..dca34af41b4 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -194,7 +194,7 @@ Prerequisites: 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. In the upper-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. On the **Edit Release** page, change the release's details. 1. Select **Save changes**. @@ -216,7 +216,7 @@ 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** +1. In the upper-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**. @@ -236,7 +236,7 @@ the [Releases API](../../../api/releases/index.md#create-a-release). In the user interface, to associate milestones to a release: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). +1. In the upper-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. From the **Milestones** list, select each milestone you want to associate. You can select multiple milestones. 1. Select **Save changes**. @@ -435,7 +435,7 @@ release evidence. If you [schedule release evidence collection](#schedule-release-evidence-collection), some artifacts may already be expired by the time of evidence collection. To avoid this you can use the [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) -keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). +keyword. For more information, see [issue 222351](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). ### Schedule release evidence collection diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index c06e746268f..120bbe32a63 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -34,7 +34,7 @@ Every release has a description. You can add any text you like, but we recommend including a changelog to describe the content of your release. This helps users quickly scan the differences between each release you publish. -[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can +[Tagging messages in Git](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can be included in Release note descriptions by selecting **Include tag message in the release notes**. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 87caeee73e3..b33dc4450a9 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -44,7 +44,7 @@ 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**. For **Initial default branch name**, select a new default branch. +1. Expand **Branch defaults**. For **Default branch**, 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). diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 4e3510c49b7..60504b94502 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -145,6 +145,38 @@ To view the **Branch rules overview** list: ## Troubleshooting +### Multiple branches containing the same commit + +At a deeper technical level, Git branches aren't separate entities, but labels +attached to a set of commit SHAs. When GitLab determines whether or not a branch has been +merged, it checks the target branch for the existence of those commit SHAs. +This behavior can cause unexpected results when two merge requests contain the same +commits. In this example, branches `B` and `C` both start from the same commit (`3`) +on branch `A`: + +```mermaid +gitGraph + commit id:"a" + branch "branch A" + commit id:"b" + commit id:"c" type: HIGHLIGHT + branch "branch B" + commit id:"d" + checkout "branch A" + branch "branch C" + commit id:"e" + checkout main + merge "branch B" id:"merges commits b, c, d" +``` + +If you merge branch `B`, branch `A` also appears as merged (without any action from you) +because all commits from branch `A` now appear in the target branch `main`. Branch `C` +remains unmerged, because commit `5` wasn't part of branch `A` or `B`. + +Merge request `A` remains merged, even if you attempt to push new commits +to its branch. If any changes in merge request `A` remain unmerged (because they +weren't part of merge request `A`), open a new merge request for them. + ### Error: ambiguous `HEAD` branch exists In versions of Git earlier than 2.16.0, you could create a branch named `HEAD`. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index fae6e210a6c..929751b7247 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -13,7 +13,7 @@ if you do not have write access for the repository you want to contribute to, yo can create a fork. A fork is a personal copy of the repository and all its branches, which you create -in a namespace of your choice. This way you can make changes in your own fork and +in a namespace of your choice. Make changes in your own fork and submit them through a merge request to the repository you don't have access to. ## Creating a fork @@ -23,7 +23,7 @@ submit them through a merge request to the repository you don't have access to. To fork an existing project in GitLab: -1. On the project's home page, in the top right, select **{fork}** **Fork**: +1. On the project's home page, in the upper right, select **{fork}** **Fork**:  1. Optional. Edit the **Project name**. 1. For **Project URL**, select the [namespace](../../namespace/index.md) @@ -37,19 +37,82 @@ To fork an existing project in GitLab: GitLab creates your fork, and redirects you to the new fork's page. -## Repository mirroring +## Update your fork -You can use [repository mirroring](mirror/index.md) to keep your fork synced with the original repository. You can also use `git remote add upstream` to achieve the same result. +To copy the latest changes from the upstream repository into your fork, update it +[from the command line](#from-the-command-line). GitLab Premium and higher tiers can also +[configure forks as pull mirrors](#with-repository-mirroring) +of the upstream repository. -The main difference is that with repository mirroring, your remote fork is automatically kept up-to-date. +### From the command line -Without mirroring, to work locally you must use `git pull` to update your local repository -with the upstream project, then push the changes back to your fork to update it. +To update your fork from the command line, first ensure that you have configured +an `upstream` remote repository for your fork: -WARNING: -With mirroring, before approving a merge request, you are asked to sync. We recommend you automate it. +1. Clone your fork locally, if you have not already done so. For more information, see + [Clone a repository](../../../gitlab-basics/start-using-git.md#clone-a-repository). +1. View the remotes configured for your fork: + + ```shell + git remote -v + ``` + +1. If your fork does not have a remote pointing to the original repository, + use one of these examples to configure a remote called `upstream`: + + ```shell + # Use this line to set any repository as your upstream after editing <upstream_url> + git remote add upstream <upstream_url> + + # Use this line to set the main GitLab repository as your upstream + git remote add upstream https://gitlab.com/gitlab-org/gitlab.git + ``` + + After ensuring your local copy has the extra remote configured, you are ready to update your fork. + +1. In your local copy, ensure you have checked out the [default branch](branches/default.md), + replacing `main` with the name of your default branch: + + ```shell + git checkout main + ``` + + If Git identifies unstaged changes, commit or stash them before continuing. + +1. Fetch the changes to the upstream repository: + + ```shell + git fetch upstream + ``` -Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). +1. Pull the changes into your fork, replacing `main` with the name of the branch + you are updating: + + ```shell + git pull upstream main + ``` + +1. Push the changes to your fork repository on the server (GitLab.com or self-managed): + + ```shell + git push origin main + ``` + +### With repository mirroring **(PREMIUM)** + +A fork can be configured as a mirror of the upstream if all these conditions are met: + +1. Your subscription is **(PREMIUM)** or a higher tier. +1. You create all changes in branches (not `main`). +1. You do not work on [merge requests for confidential issues](../merge_requests/confidential.md), + which requires changes to `main`. + +[Repository mirroring](mirror/index.md) keeps your fork synced with the original repository. +This method updates your fork once per hour, with no manual `git pull` required. +For instructions, read [Configure pull mirroring](mirror/pull.md#configure-pull-mirroring). + +WARNING: +With mirroring, before approving a merge request, you are asked to sync. You should automate it. ## Merging upstream @@ -60,7 +123,7 @@ choose your forked project's branch. For **Target branch**, choose the original NOTE: When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch defaults to the forked project's default branch. This prevents potentially exposing the private code of the forked project. - + Then you can add labels, a milestone, and assign the merge request to someone who can review your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your @@ -69,3 +132,8 @@ changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#remove-a-fork-relationship). + +## Related topics + +- GitLab blog post: [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). +- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/). diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 6b67ffd0e59..64f19d1a92c 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -43,7 +43,7 @@ To view a user's public GPG key, you can either: - Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, if the user has configured one, or a blank page for users without a configured GPG key. -- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the top right +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper right of the user's profile, select **View public GPG keys** (**{key}**). ## Configure commit signing @@ -119,7 +119,7 @@ If you don't already have a GPG key, create one: To add a GPG key to your user settings: 1. Sign in to GitLab. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. In **Key**, paste your _public_ key. @@ -180,6 +180,47 @@ you can sign individual commits manually, or configure Git to default to signed git config --global commit.gpgsign true ``` +#### Set signing key conditionally + +If you maintain signing keys for separate purposes, such as work and personal +use, use an `IncludeIf` statement in your `.gitconfig` file to set which key +you sign commits with. + +Prerequisites: + +- Requires Git version 2.13 or later. + +1. In the same directory as your main `~/.gitconfig` file, create a second file, + such as `.gitconfig-gitlab`. +1. In your main `~/.gitconfig` file, add your Git settings for work in non-GitLab projects. +1. Append this information to the end of your main `~/.gitconfig` file: + + ```ini + # The contents of this file are included only for GitLab.com URLs + [includeIf "hasconfig:remote.*.url:https://gitlab.com/**"] + + # Edit this line to point to your alternate configuration file + path = ~/.gitconfig-gitlab + ``` + +1. In your alternate `.gitconfig-gitlab` file, add the configuration overrides to + use when you're committing to a GitLab repository. All settings from your + main `~/.gitconfig` file are retained unless you explicitly override them. + In this example, + + ```ini + # Alternate ~/.gitconfig-gitlab file + # These values are used for repositories matching the string 'gitlab.com', + # and override their corresponding values in ~/.gitconfig + + [user] + email = you@example.com + signingkey = <KEY ID> + + [commit] + gpgsign = true + ``` + ## Verify commits You can review commits for a merge request, or for an entire project: @@ -212,7 +253,7 @@ If a GPG key becomes compromised, revoke it. Revoking a key changes both future To revoke a GPG key: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. @@ -227,7 +268,7 @@ When you remove a GPG key from your GitLab account: To remove a GPG key from your account: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. diff --git a/doc/user/project/repository/img/forking_workflow_branch_select.png b/doc/user/project/repository/img/forking_workflow_branch_select.png Binary files differdeleted file mode 100644 index 0ea5410f832..00000000000 --- a/doc/user/project/repository/img/forking_workflow_branch_select.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png b/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png Binary files differnew file mode 100644 index 00000000000..6b15abd8460 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 3c33467df3f..5b4e1b14489 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -86,13 +86,28 @@ Visual Studio Code: - From the GitLab interface: 1. Go to the project's overview page. 1. Select **Clone**. - 1. Under either the **HTTPS** or **SSH** method, select **Clone with Visual Studio Code**. + 1. Under **Open in your IDE**, select **Visual Studio Code (SSH)** or **Visual Studio Code (HTTPS)**. 1. Select a folder to clone the project into. After Visual Studio Code clones your project, it opens the folder. - From Visual Studio Code, with the [extension](vscode.md) installed, use the extension's [`Git: Clone` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#clone-gitlab-projects). +### Clone and open in IntelliJ IDEA + +All projects can be cloned into [IntelliJ IDEA](https://www.jetbrains.com/idea/) +from the GitLab user interface. + +Prerequisites: + +- The [Jetbrains Toolbox App](https://www.jetbrains.com/toolbox-app/) must be also be installed. + +To do this: + +1. Go to the project's overview page. +1. Select **Clone**. +1. Under **Open in your IDE**, select **IntelliJ IDEA (SSH)** or **IntelliJ IDEA (HTTPS)**. + ## Download the code in a repository > Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. @@ -111,6 +126,9 @@ You can download the source code that's stored in a repository. - **Artifacts:** Download the artifacts from the latest CI job. +The checksums of generated archives can change even if the repository itself doesn't +change. This can occur, for example, if Git or a third-party library that GitLab uses changes. + ## Repository languages For the default branch of each repository, GitLab determines which programming languages diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index bc0073e6ec8..7a50c294dfc 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -55,7 +55,7 @@ Prerequisite: When mirroring the repository, GitLab confirms at least one of the stored host keys matches before connecting. This check can protect your mirror from malicious code injections, or your password from being stolen. -1. Select an **Authentication method**. To learn more, read +1. Select an **Authentication method**. For more information, see [Authentication methods for mirrors](#authentication-methods-for-mirrors). 1. If you authenticate with SSH host keys, [verify the host key](#verify-a-host-key) to ensure it is correct. @@ -65,7 +65,7 @@ Prerequisite: If you select `SSH public key` as your authentication method, GitLab generates a public key for your GitLab repository. You must provide this key to the non-GitLab server. -To learn more, read [Get your SSH public key](#get-your-ssh-public-key). +For more information, see [Get your SSH public key](#get-your-ssh-public-key). ## Update a mirror diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 1923d8e2ae7..0eb51f40208 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -65,9 +65,14 @@ Prerequisite: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter the **Git repository URL**. Include the username - in the URL, if required: `https://MYUSERNAME@github.com/GROUPNAME/PROJECTNAME.git` + in the URL, if required: `https://MYUSERNAME@gitlab.com/GROUPNAME/PROJECTNAME.git` + + NOTE: + To mirror the `gitlab` repository, use `git@gitlab.com:gitlab-org/gitlab.git` + or `https://gitlab.com/gitlab-org/gitlab.git`. + 1. In **Mirror direction**, select **Pull**. -1. In **Authentication method**, select your authentication method. To learn more, read +1. In **Authentication method**, select your authentication method. For more information, see [Authentication methods for mirrors](index.md#authentication-methods-for-mirrors). 1. Select any of the options you need: - [**Overwrite diverged branches**](#overwrite-diverged-branches) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 11d53b0c1d1..f06dd747897 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -38,7 +38,7 @@ To set up push mirroring for an existing project: 1. Expand **Mirroring repositories**. 1. Enter a repository URL. 1. In the **Mirror direction** dropdown list, select **Push**. -1. Select an **Authentication method**. To learn more, read +1. Select an **Authentication method**. For more information, see [Authentication methods for mirrors](index.md#authentication-methods-for-mirrors). 1. Select **Only mirror protected branches**, if necessary. 1. Select **Keep divergent refs**, if desired. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index a8a79591e9e..cf7d4f44aad 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -110,7 +110,7 @@ To purge files from a GitLab repository: for more examples and the complete documentation. 1. Because you are trying to remove internal refs, - you'll later rely on `commit-map` files produced by each run + you need the `commit-map` files produced by each run to tell you which internal refs to remove. Every `git filter-repo` run creates a new `commit-map`, and overwrites the `commit-map` from the previous run. @@ -174,7 +174,7 @@ To clean up a repository: 1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the `filter-repo` directory. - If your `commit-map` file is larger than about 250KB or 3000 lines, the file can be split and uploaded piece by piece: + If your `commit-map` file is larger than about 250 KB or 3000 lines, the file can be split and uploaded piece by piece: ```shell split -l 3000 filter-repo/commit-map filter-repo/commit-map- diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index 85d2ce1d480..f2ce80263c8 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -19,8 +19,8 @@ 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). +For more information about managing the SSH keys associated with your GitLab account, see +[Use SSH keys to communicate with GitLab](../../../ssh.md). ## Configure Git to sign commits with your SSH key @@ -160,8 +160,19 @@ for Git to associate SSH public keys with users: ## 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). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9. + +If an SSH key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. + +To revoke an SSH key: + +1. In the upper-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select (**{key}**) **SSH Keys**. +1. Select **Revoke** next to the SSH key you want to delete. ## Related topics diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index 4afdb3be0bd..9260d59bc3a 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.md @@ -1,6 +1,6 @@ --- stage: Create -group: Code Review +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 --- @@ -15,8 +15,9 @@ do more day-to-day tasks in Visual Studio Code, such as: from the Visual Studio Code [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). - Create and [review](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#merge-request-reviews) merge requests directly from Visual Studio Code. -- [Validate your GitLab CI configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration). +- [Validate your GitLab CI/CD configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-cicd-configuration). - [View the status of your pipeline](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). +- [View the output of CI/CD jobs](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#view-the-job-output). - [Create](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet) and paste snippets to, and from, your editor. - [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b5b2b8aaae9..80b0ada6f7b 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -6,10 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Web Editor **(FREE)** -You can use the Web Editor to make changes directly from the GitLab UI instead of -cloning a project and using the command line. +You can use the Web Editor to make changes to a single file directly from the +GitLab UI. To make changes to multiple files, see [Web IDE](../web_ide/index.md). -From the project dashboard or repository, you can: +In the Web Editor, you can: - [Create a file](#create-a-file). - [Edit a file](#edit-a-file). @@ -18,8 +18,8 @@ From the project dashboard or repository, you can: - [Create a branch](#create-a-branch). - [Create a tag](#create-a-tag). -Your [primary email address](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) -is used by default for any change you commit through the Web Editor. +Your [primary email address is used by default](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) +for any change you commit through the Web Editor. ## Create a file @@ -28,18 +28,22 @@ To create a text file in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. -1. Complete the fields. - - From the **Select a template type** dropdown list, you can apply a template to the new file. - - To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. +1. Complete the fields. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. 1. Select **Commit changes**. ## Edit a file -To edit a file in the Web Editor: +To edit a text file in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. 1. Go to your file. -1. Next to the display buttons, select **Edit**. +1. In the upper-right corner of the file, select **Edit**. + + If **Edit** is not visible: + + 1. Next to **Open in Web IDE** or **Open in Gitpod**, select the down arrow (**{chevron-lg-down}**). + 1. From the dropdown list, select **Edit** as your default setting. + 1. Select **Edit**. ### Keyboard shortcuts diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 922accf9d28..b04905e6b34 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -236,7 +236,7 @@ To import requirements: 1. In a project, go to **Issues > Requirements**. - If the project already has existing requirements, select the import icon (**{import}**) in the - top right. + upper right. - For a project without any requirements, select **Import CSV** in the middle of the page. 1. Select the file and select **Import requirements**. @@ -296,7 +296,7 @@ Prerequisite: To export requirements: 1. In a project, go to **Issues > Requirements**. -1. In the top right, select the **Export as CSV** icon (**{export}**). +1. In the upper right, select the **Export as CSV** icon (**{export}**). A confirmation modal appears. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index cc195c3c959..22297149561 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -67,7 +67,7 @@ one from the selector menu to append it to all Service Desk issues. To enable Service Desk in your project: 1. (GitLab self-managed only) [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. - We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), + You should use [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). 1. In a project, in the left sidebar, go to **Settings > General** and expand the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues @@ -80,7 +80,7 @@ WARNING: Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless of their access level** to your GitLab instance. -To improve your project's security, we recommend the following: +To improve your project's security, you should: - Put the Service Desk email address behind an alias on your email system so you can change it later. - [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. @@ -95,6 +95,7 @@ displayed in the information note. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab 12.7. > - Moved from GitLab Premium to GitLab Free in 13.2. +> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. An email is sent to the author when: @@ -128,6 +129,10 @@ You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID +- `%{UNSUBSCRIBE_URL}`: unsubscribe URL +- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), the response email does not contain the issue link. @@ -142,6 +147,10 @@ You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID - `%{NOTE_TEXT}`: note text +- `%{UNSUBSCRIBE_URL}`: unsubscribe URL +- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) #### New Service Desk issues @@ -154,7 +163,7 @@ You can set description templates at various levels: - A specific [group or subgroup](description_templates.md#set-group-level-description-templates). - A specific [project](description_templates.md#set-a-default-template-for-merge-requests-and-issues). -The templates are inherited. For example, in a project, you can also access templates set for the instance or the project's parent groups. +The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. To use a custom description template with Service Desk: @@ -217,9 +226,9 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip 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). +For more information, see [merge request 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). +For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). ```ruby gitlab_rails['service_desk_email_enabled'] = true @@ -260,13 +269,141 @@ service_desk_email: The configuration options are the same as for configuring [incoming email](../../administration/incoming_email.md#set-it-up). +##### Use encrypted credentials + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally +use an encrypted file for the Incoming email credentials. + +Prerequisites: + +- To use encrypted credentials, you must first enable the + [encrypted configuration](../../administration/encrypted_configuration.md). + +The supported configuration items for the encrypted file are: + +- `user` +- `password` + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: + + ```ruby + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Edit the encrypted secret: + + ```shell + sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim + ``` + +1. Enter the unencrypted contents of the Service Desk email secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +1. If initially your Service Desk configuration in `docker-compose.yml` looked like: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Get inside the container, and edit the encrypted secret: + + ```shell + sudo docker exec -t <container_name> bash + gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: + + ```yaml + production: + service_desk_email: + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit the encrypted secret: + + ```shell + bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. +1. Save the file and restart GitLab and Mailroom + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + ##### Microsoft Graph > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. > - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). +Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth 2.0 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). - Example for Omnibus GitLab installations: @@ -358,12 +495,10 @@ issues created through customer support requests, and filter or interact with th Messages from the end user are shown as coming from the special [Support Bot user](../../subscriptions/self_managed/index.md#billable-users). -You can read and write comments as you normally do in GitLab: +You can read and write comments as you usually do in GitLab:  -Note that: - - The project's visibility (private, internal, public) does not affect Service Desk. - The path to the project, including its group or namespace, is shown in emails. @@ -378,12 +513,34 @@ On GitLab.com, this feature is not available. If a comment contains any attachments and their total size is less than or equal to 10 MB, these attachments are sent as part of the email. In other cases, the email contains links to the attachments. +#### Special HTML formatting in HTML emails + +<!-- When the feature flag is removed, delete this topic and add as a line in version history under one of the topics above this one.--> + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372301) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. +On GitLab.com, this feature is not available. + +When this feature is enabled, HTML emails correctly show additional HTML formatting, such as: + +- Tables +- Blockquotes +- Images +- Collapsible sections + #### Privacy considerations +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. + Service Desk issues are confidential, but the project owner can [make an issue public](issues/confidential_issues.md#modify-issue-confidentiality). -When a Service Desk issue becomes public, the issue creator's email address is disclosed -to everyone who can view the project. +When a Service Desk issue becomes public, the issue creator's and participants' email addresses are +visible to signed-in users with at least the Reporter role for the project. + +In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email +address is disclosed to everyone who can view the project. ### Support Bot user diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index b85f52d43bb..3715eef08e0 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -14,7 +14,7 @@ then imported into a new GitLab instance. You can also: 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 +Consequently, 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 @@ -27,6 +27,30 @@ To preserve contribution history, [migrate using direct transfer](../../group/im If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. +## Compatibility + +FLAG: +On self-managed GitLab by default project, file exports are in NDJSON format. To make GitLab produce project file +exports in JSON format, ask an administrator to [disable the feature flags](../../../administration/feature_flags.md) +named `project_export_as_ndjson`. To allow GitLab to import project file exports in JSON format, ask an administrator to +[disable the feature flags](../../../administration/feature_flags.md) named `project_import_ndjson`. On GitLab.com, +project file exports are in NDJSON format only. + +Project file exports are in NDJSON format. Before version 14.0, GitLab produced project file exports in JSON format. +To support transitions, you can still import JSON-formatted project file exports if you configure the relevant feature +flags. + +From GitLab 13.0, GitLab can import project file exports that were exported from a version of GitLab up to two +[minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for +[security releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Destination version | Compatible source versions | +|:--------------------|:---------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + ## Configure file exports as an import source **(FREE SELF)** Before you can migrate projects on a self-managed GitLab instance using file exports, GitLab administrators must: @@ -47,7 +71,7 @@ To enable file exports as an import source for the destination instance: ## 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, assuming [compatibility](#compatibility) is 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 @@ -127,10 +151,11 @@ Items that are **not** exported include: - Pipeline triggers - Webhooks - Any encrypted tokens -- [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) +- [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221087) - Repository size limits - Deploy keys allowed to push to protected branches - Secure Files +- [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700). For example, pushing and creating tags ## Import a project and its data @@ -145,7 +170,7 @@ Prerequisites: - You must have [exported the project and its data](#export-a-project-and-its-data). - Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later than the GitLab version you exported to. -- Review the [Version history](#version-history) for compatibility issues. +- Review [compatibility](#compatibility) for any issues. - At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. @@ -220,32 +245,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 | -## Version history - -### 15.8+ - -Starting with GitLab 15.8, importing groups from a JSON export is no longer supported. Groups must be imported -in NDJSON format. - -### 14.0+ - -In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a -transitional period, you can still import any JSON exports. The new format for imports and exports -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). - -For example: - -| Current version | Can import bundles exported from | -|-----------------|----------------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | - ## Related topics - [Project import and export API](../../../api/project_import_export.md) diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index 81ceba7139b..00edeef5cfa 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -153,7 +153,8 @@ Rather than attempting to push all changes at once, this workaround: You usually export a project through [the web interface](import_export.md#export-a-project-and-its-data) or through [the API](../../../api/project_import_export.md). Exporting using these methods can sometimes fail without giving enough information to troubleshoot. In these cases, -[open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +[open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and loop through +[all the defined exporters](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/projects/import_export/export_service.rb). Execute each line individually, rather than pasting the entire block at once, so you can see any errors each command returns. @@ -197,7 +198,7 @@ Read through the current performance problems using the Import/Export below. ### OOM errors -Out of memory (OOM) errors are normally caused by the [Sidekiq Memory Killer](../../../administration/sidekiq/sidekiq_memory_killer.md): +Out of memory (OOM) errors are usually caused by the [Sidekiq Memory Killer](../../../administration/sidekiq/sidekiq_memory_killer.md): ```shell SIDEKIQ_MEMORY_KILLER_MAX_RSS = 2000000 diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 3798643549d..ed4eea56514 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -158,7 +158,7 @@ Configure your project's merge request settings: - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). -- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). +- Enable [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. @@ -230,6 +230,18 @@ To rename a repository: 1. In the **Change path** text box, edit the path. 1. Select **Change path**. +## Delete the source branch on merge by default + +In merge requests, you can change the default behavior so that the +**Delete the source branch** checkbox is always selected. + +To set this default: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Select **Enable "Delete source branch" option by default**. +1. Select **Save changes**. + ## Transfer a project to another namespace When you transfer a project to another namespace, you move the project to a different group. @@ -241,6 +253,7 @@ Prerequisites: - The group must allow creation of new projects. - The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). - Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. +- If a security policy is assigned to the project, it is automatically unassigned during the transfer. To transfer a project: diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index cb7ba2a7df2..f9218a228ca 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -17,7 +17,7 @@ select a limited role, and provide an expiry date. Use a project access token to authenticate: -- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- With the [GitLab API](../../../api/rest/index.md#personalprojectgroup-access-tokens). - With Git, when using HTTP Basic Authentication, use: - Any non-blank value as a username. - The project access token as the password. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 186ca0ba9f0..d5f0b7e6180 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -42,7 +42,8 @@ You can see the estimated time remaining when you hover over the time tracking i Prerequisites: -- You must have at least the Reporter role for the project. +- In issues, you must have at least the Reporter role for the project. +- In merge requests, you must have at least the Developer role for the project. To enter an estimate, use the `/estimate` [quick action](quick_actions.md), followed by the time. @@ -57,7 +58,8 @@ Every time you enter a new time estimate, it overwrites the previous value. Prerequisites: -- You must have at least the Reporter role for the project. +- In issues, you must have at least the Reporter role for the project. +- In merge requests, you must have at least the Developer role for the project. To remove an estimate entirely, use the `/remove_estimate` [quick action](quick_actions.md). @@ -171,10 +173,10 @@ The following time units are available: | Time unit | What to type | Conversion rate | | --------- | --------------------------- | --------------- | -| Month | `mo`, `month`, or `months` | 4w (160h) | -| Week | `w`, `week`, or `weeks` | 5d (40h) | -| Day | `d`, `day`, or `days` | 8h | -| Hour | `h`, `hour`, or `hours` | 60m | +| Month | `mo`, `month`, or `months` | 4 w (160 h) | +| Week | `w`, `week`, or `weeks` | 5 d (40 h) | +| Day | `d`, `day`, or `days` | 8 h | +| Hour | `h`, `hour`, or `hours` | 60 m | | Minute | `m`, `minute`, or `minutes` | | ### Limit displayed units to hours **(FREE SELF)** diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 4648df7dbd7..5e9f648daba 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Web IDE **(FREE)** -The Web Integrated Development Environment (IDE) editor streamlines the process -to contribute changes to your projects, by providing an advanced editor with -commit staging. +The Web IDE is an advanced editor with commit staging. +You can use the Web IDE to make changes to multiple files directly from the +GitLab UI. For a more basic implementation, see [Web Editor](../repository/web_editor.md). NOTE: The Web IDE is being updated to use VS Code. For details, @@ -175,8 +175,8 @@ access to the selected branch, you see a warning, but can still create a new branch and start a merge request. To discard a change in a particular file, select **Discard changes** on that -file in the changes tab. To discard all the changes, select the trash icon on the -top-right corner of the changes sidebar. +file in the changes tab. To discard all the changes, select the trash icon in the +upper-right corner of the changes sidebar.  @@ -238,7 +238,13 @@ There are two ways to preview Markdown content in the Web IDE: 1. Right-click or use the keyboard shortcut `Command/Control + Shift + P` and select **Preview Markdown** to toggle a live Markdown preview panel. -## Live Preview +<!--- start_remove The following content will be removed on remove_date: '2023-02-01' --> + +## Live Preview (removed) + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108627) in GitLab 15.8 +and is planned for removal in 15.9. This change is a breaking change. > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. @@ -283,6 +289,8 @@ An example `package.json`: } ``` +<!--- end_remove --> + ## Interactive Web Terminals for the Web IDE > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) from GitLab Ultimate to GitLab Free in 13.1. diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md index 4f84110a038..fe110baf578 100644 --- a/doc/user/project/web_ide_beta/index.md +++ b/doc/user/project/web_ide_beta/index.md @@ -40,7 +40,7 @@ or a merge request. 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**. +- In the upper right of the page, select **Open in Web IDE**. If **Open in Web IDE** is not visible: @@ -88,7 +88,7 @@ For details, see the [VS Code documentation](https://code.visualstudio.com/docs/ 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. On the top bar, in the upper-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**. @@ -96,7 +96,7 @@ If you do not want to use the Web IDE Beta, you can change your personal prefere ## 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. +and [Live Preview](../web_ide/index.md#live-preview-removed) are not available in the Web IDE Beta. These features might become available at a later date. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 04a6f9bee80..f01331ac784 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -252,7 +252,7 @@ replaces the default sidebar navigation: - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. -1. In the top right corner of the page, select **Edit sidebar**. +1. In the upper-right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. A `_sidebar` example, formatted with Markdown: @@ -269,8 +269,6 @@ A `_sidebar` example, formatted with Markdown: - [Sidebar](_sidebar) ``` -Support for displaying a generated table of contents with a custom side navigation is being considered. - ## Enable or disable a project wiki Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 92db90d66dc..a0e6a78dfe2 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -87,7 +87,7 @@ called `my-project` under your username, the project is created at `https://gitl To view your personal projects: 1. On the top bar, select **Main menu > Projects > View all projects**. -1. In the **Your projects** tab, select **Personal**. +1. In the **Yours** tab, select **Personal**. ## Delete a project @@ -157,6 +157,18 @@ You can sort projects by: You can also choose to hide or show archived projects. +### Filter projects by language + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385465) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `project_language_search`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110956) in GitLab 15.9. Feature flag `project_language_search` removed. + +You can filter projects by the programming language they use. To do this: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. From the **Language** dropdown list, select the language you want to filter projects by. + +A list of projects that use the selected language is displayed. + ## Change the visibility of individual features in a project You can change the visibility of individual features in a project. |
