diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-03-20 15:19:03 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-03-20 15:19:03 +0000 |
| commit | 14bd84b61276ef29b97d23642d698de769bacfd2 (patch) | |
| tree | f9eba90140c1bd874211dea17750a0d422c04080 /doc/user/project | |
| parent | 891c388697b2db0d8ee0c8358a9bdbf6dc56d581 (diff) | |
| download | gitlab-ce-14bd84b61276ef29b97d23642d698de769bacfd2.tar.gz | |
Add latest changes from gitlab-org/gitlab@15-10-stable-eev15.10.0-rc42
Diffstat (limited to 'doc/user/project')
126 files changed, 1092 insertions, 583 deletions
diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 0ea1a80bc54..2d36a378b82 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -117,6 +117,10 @@ time with the `?order_by` query parameter. https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at ``` +You can change the width of the release name field by using the `value_width` parameter ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113615) in GitLab 15.10). +The value must be between 1 and 200, and the default value is 54. +If you set an out of range value, GitLab automatically adjusts it to the default value. + ## Project badges Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 52288af101a..3ed8a4a67cf 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Connect EKS clusters through cluster certificates (DEPRECATED) **(FREE)** +# Connect EKS clusters through cluster certificates (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. @@ -25,7 +25,7 @@ use the [GitLab agent](../../clusters/agent/index.md). To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md). -### How to create a new cluster on EKS through cluster certificates (DEPRECATED) +### How to create a new cluster on EKS through cluster certificates (deprecated) > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 0b0555806ce..a7fac2a1cea 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Connect existing clusters through cluster certificates (DEPRECATED) **(FREE)** +# Connect existing clusters through cluster certificates (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index b1c5bbfc4f7..e00c4370da9 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Connect GKE clusters through cluster certificates (DEPRECATED) **(FREE)** +# Connect GKE clusters through cluster certificates (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index d3048158958..bf2f6e28d9a 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Add a cluster using cluster certificates (DEPRECATED) **(FREE)** +# Add a cluster using cluster certificates (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 529e7a6da12..0eea3ebb8cd 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Access controls with cluster certificates (RBAC or ABAC) (DEPRECATED) **(FREE)** +# Access controls with cluster certificates (RBAC or ABAC) (deprecated) **(FREE)** > - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 173f1f39a66..e2d0a010293 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Deploy to a Kubernetes cluster with cluster certificates (DEPRECATED) **(FREE)** +# Deploy to a Kubernetes cluster with cluster certificates (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index b2a4bd85de4..46e74eb8460 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab-managed clusters (DEPRECATED) **(FREE)** +# GitLab-managed clusters (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 94513fc7124..490188b27b0 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Project-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE)** +# Project-level Kubernetes clusters (certificate-based) (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index c79f250da7a..9167e6197d6 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Multiple clusters per project with cluster certificates (DEPRECATED) **(FREE)** +# Multiple clusters per project with cluster certificates (deprecated) **(FREE)** > - Introduced in GitLab 10.3 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) from GitLab Premium to GitLab Free in 13.2. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index df0ffff8561..b1f2a9dbb79 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -107,7 +107,7 @@ the components outlined above and the pre-loaded demo runbook. ''' We set user's id, login and access token on single user image to enable repository integration for JupyterHub. - See: https://gitlab.com/gitlab-org/gitlab-foss/issues/47138#note_154294790 + See: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47138#note_154294790 ''' auth_state = await spawner.user.get_auth_state() diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 9de9d445965..0994bff4aa2 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -8,12 +8,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Moved to GitLab Premium in 13.9. -Code Owners define who develops and maintains a feature, and own the resulting -files or directories in a repository. +Use the Code Owners feature to define who has expertise for specific parts of your project's codebase. +Define the owners of files and directories in a repository to: -- The users you define as Code Owners are displayed in the UI when you browse directories. -- 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. +- **Require owners to approve changes.** Combine protected branches with Code Owners to require + experts to approve merge requests before they merge into a protected branch. +- **Identify owners.** Code Owner names are displayed on the files and directories they own: +  + +Use Code Owners in combination with merge request +[approval rules](merge_requests/approvals/rules.md) (either optional or required) +to build a flexible approval workflow: + +- Use **Code Owners** to ensure quality. Define the users who have domain expertise + for specific paths in your repository. +- Use **Approval rules** to define areas of expertise that don't correspond to specific + file paths in your repository. Approval rules help guide merge request creators to + the correct set of reviewers, such as frontend developers or a security team. + +For example: + +| Type | Name | Scope | Comment | +|------|------|--------|------------| +| Approval rule | UX | All files | A user experience (UX) team member reviews the user experience of all changes made in your project. +| Approval rule | Security | All files | A security team member reviews all changes for vulnerabilities. +| 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. <div class="video-fallback"> Video introduction: <a href="https://www.youtube.com/watch?v=RoyBySTUSB0">Code Owners</a>. @@ -24,45 +44,20 @@ files or directories in a repository. <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: - -- Use **Code Owners** to define the users who have domain expertise for specific paths in your repository. -- Use **Approvers** and **Approval rules** to define domains of expertise (such as a security team) - that are not scoped to specific file paths in your repository. - - **Approvers** define the users. - - **Approval rules** define when these users can approve work, and whether or not their approval is required. - -For example: - -| Type | Name | Scope | Comment | -|------|------|--------|------------| -| Approval rule | UX | All files | A user experience (UX) team member reviews the user experience of all changes made in your project. | -| Approval rule | Security | All files | A security team member reviews all changes for vulnerabilities. | -| 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. | - -## Code Owners file +## View a file's Code Owner -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, and it must be found one of these three locations: +To view the Code Owners for a file: -- In the root directory of the repository. -- In the `.gitlab/` directory. -- In the `docs/` directory. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. Go to the file or directory you want to see the Code Owners for. +1. Optional. Select your desired branch. -A CODEOWNERS file in any other location is ignored. +GitLab shows the Code Owners at the top of the page. ## Set up Code Owners -1. Create a file named `CODEOWNERS` (with no extension) in one of these locations: - -- In the root directory of the repository -- In the `.gitlab/` directory -- In the `docs/` directory - +1. Create a `CODEOWNERS` file in your [preferred location](#code-owners-file). 1. In the file, enter text that follows one of these patterns: ```plaintext @@ -79,17 +74,28 @@ A CODEOWNERS file in any other location is ignored. directoryname/ @groupname ``` -The Code Owners are now displayed in the UI. They apply to the current branch only. +### Code Owners file + +A `CODEOWNERS` file (with no extension) specifies the users or +[shared groups](members/share_project_with_groups.md) responsible for +specific files and directories in a repository. + +Each repository uses a single `CODEOWNERS` file. GitLab checks these locations +in your repository in this order. The first `CODEOWNERS` file found is used, and +all others are ignored: -Next steps: +1. In the root directory: `./CODEOWNERS`. +1. In the `docs` directory: `./docs/CODEOWNERS`. +1. In the `.gitlab` directory: `./.gitlab/CODEOWNERS`. + +### Make Code Owners eligible approvers or require their approval of MRs - [Add Code Owners as merge request approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers). - Set up [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch). -## Groups as Code Owners +### Groups as Code Owners -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. -> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. +> Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. You can use members of groups and subgroups as Code Owners for projects: @@ -137,7 +143,7 @@ For approval to be required, groups as Code Owners must have a direct membership that inherit membership. Members in the Code Owners group also must be direct members, and not inherit membership from any parent groups. -### Add a group as a Code Owner +#### Add a group as a Code Owner To set a group as a Code Owner: @@ -154,23 +160,26 @@ file.md @group-x/subgroup-y file.md @group-x @group-x/subgroup-y ``` -## When a file matches multiple `CODEOWNERS` entries +### Define more specific owners for more specifically defined files or directories -When a file matches multiple entries in the `CODEOWNERS` file, -the users from last pattern matching the file are used. +When a file or directory matches multiple entries in the `CODEOWNERS` file, +the users from last pattern matching the file or directory are used. This enables you +to define more specific owners for more specifically defined files or directories, when +you order the entries in a sensible way. For example, in the following `CODEOWNERS` file: ```plaintext -README.md @user1 +# This line would match the file terms.md +*.md @doc-team -# This line would also match the file README.md -*.md @user2 +# This line would also match the file terms.md +terms.md @legal-team ``` -The Code Owner for `README.md` would be `@user2`. +The Code Owner for `terms.md` would be `@legal-team`. -If you use sections, the last pattern matching the file for each section is used. +If you use sections, the last pattern matching the file or directory for each section is used. For example, in a `CODEOWNERS` file using sections: ```plaintext @@ -183,9 +192,9 @@ 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`. +and `@user3`. The Code Owners for `internal/README.md` are `@user4` and `@user3`. -Only one CODEOWNERS pattern can match per file path. +Only one CODEOWNERS pattern per section is matched to a file path. ### Organize Code Owners by putting them into sections @@ -211,7 +220,56 @@ The following image shows a **Groups** and **Documentation** section:  -### Sections with duplicate names +#### Set default owner for a section **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371711) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `codeowners_default_owners`. 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 `codeowners_default_owners`. +The feature is not ready for production use. + +WARNING: +To disable this feature flag after setting default owners per section, edit your +CODEOWNERS file to [list Code Owners per line](#set-up-code-owners). + +If multiple file paths inside a section share the same ownership, define a default +Code Owner for the section. All paths in that section inherit this default, unless +you override the section default on a specific line. + +Default owners are applied when specific owners are not specified for file paths. +Specific owners defined beside the file path override default owners: + +```plaintext +[Documentation] @docs-team +docs/ +README.md + +[Database] @database-team +model/db/ +config/db/database-setup.md @docs-team +``` + +In this example: + +- `@docs-team` owns all items in the `Documentation` section. +- `@database-team` owns all items in the `Database` section except + `config/db/database-setup.md`, which has an override assigning it to `@docs-team`. + +To combine the syntax for default owners with [optional sections](#make-a-code-owners-section-optional) +and required approvals, place default owners at the end: + +```plaintext +[Documentation][2] @docs-team +docs/ +README.md + +^[Database] @database-team +model/db/ +config/db/database-setup.md @docs-team +``` + +#### Sections with duplicate names If multiple sections have the same name, they are combined. Also, section headings are not case-sensitive. For example: @@ -233,7 +291,7 @@ This code results in three entries under the **Documentation** section header, a entries under **Database**. The entries defined under the sections **Documentation** and **DOCUMENTATION** are combined, using the case of the first section. -### Make a Code Owners section optional +#### Make a Code Owners section optional > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. @@ -268,6 +326,35 @@ when changes are submitted by using merge requests. If a change is submitted dir to the protected branch, approval from Code Owners is still required, even if the section is marked as optional. +### Require multiple approvals from Code Owners + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335451) in GitLab 15.9. + +You can require multiple approvals for the Code Owners sections under the Approval Rules area in merge requests. +Append the section name with a number `n` in brackets. This requires `n` approvals from the Code Owners in this section. +Please note valid entries for `n` are integers `≥ 1`. `[1]` is optional as it is the default. Invalid values for `n` are treated as `1`. + +WARNING: +[Issue #384881](https://gitlab.com/gitlab-org/gitlab/-/issues/385881) proposes changes +to the behavior of this setting. Do not intentionally set invalid values. They may +become valid in the future, and cause unexpected behavior. + +Please confirm you enabled `Require approval from code owners` in `Settings > Repository > Protected branches`, otherwise the Code Owner approvals will be optional. + +In this example, the `[Documentation]` section requires 2 approvals: + +```plaintext +[Documentation][2] +*.md @tech-writer-team + +[Ruby] +*.rb @dev-team +``` + +The `Documentation` Code Owners section under the **Approval Rules** area displays 2 approvals are required: + + + ### Allowed to Push The Code Owner approval and protected branch features do not apply to users who @@ -338,15 +425,22 @@ path\ with\ spaces/ @space-owner ee/docs @docs docs @docs -[Database] -README.md @database -model/db @database +# Use of default owners for a section. In this case, all files (*) are owned by +the dev team except the README.md and data-models which are owned by other teams. +[Development] @dev-team +* +README.md @docs-team +data-models/ @data-science-team # This section is combined with the previously defined [Documentation] section: [DOCUMENTATION] README.md @docs ``` +## Technical Resources + +[Code Owners development guidelines](../../../ee/development/code_owners/index.md) + ## Troubleshooting ### Approvals shown as optional @@ -371,3 +465,9 @@ if any of these conditions are true: Check the project [merge request approval](merge_requests/approvals/settings.md#edit-merge-request-approval-settings) settings. - A Code Owner group has a visibility of **private**, and the current user is not a member of the Code Owner group. +- Current user is an external user who does not have permission to the internal Code Owner group. + +### Approval rule is invalid. GitLab has approved this rule automatically to unblock the merge request + +This message may appear if an approval rule uses a Code Owner that is not a direct member of the project. +Check that the group or user has been invited to the project. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index a68f9550ebf..5adc678e942 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,11 +1,11 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: howto, reference --- -# Deploy boards (DEPRECATED) **(FREE)** +# Deploy boards (deprecated) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in GitLab 9.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index fc88535dc77..362d5826124 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -15,8 +15,7 @@ Depending on your needs, you might want to use a [deploy token](../deploy_tokens |------------------|-------------|--------------| | Sharing | Shareable between multiple projects, even those in different groups. | Belong to a project or group. | | Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. | -| Validity | Valid as long as it's registered and enabled, and the user that created it exists. | Can be given an expiration date. | -| Registry access | Cannot access a package registry. | Can read from and write to a package registry. | +| Accessible resources | Git repository over SSH | Git repository over HTTP, package registry, and container registry. | Deploy keys can't be used for Git operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. @@ -41,10 +40,8 @@ A deploy key is given a permission level when it is created: You can change a deploy key's permission level after creating it. Changing a project deploy key's permissions only applies for the current project. -When a read-write deploy key is used to push a commit, GitLab checks if the creator of the -deploy key has permission to access the resource. - -For example: +Although a deploy key is a secret that isn't associated with a specific user, +GitLab authorizes the creator of the deploy key if the Git-command triggers additional processes. For example: - When a deploy key is used to push a commit to a [protected branch](../protected_branches.md), the _creator_ of the deploy key must have access to the branch. @@ -52,6 +49,15 @@ For example: deploy key must have access to the CI/CD resources, including protected environments and secret variables. +## Security implications + +The intended use case for deploy keys is for non-human interaction with GitLab, for example: an automated script running on a server in your organization. +As with all sensitive information, you should ensure only those who need access to the secret can read it. +For human interactions, use credentials tied to users such as Personal Access Tokens. + +To help detect a potential secret leak, you can use the +[Audit Event](../../../administration/audit_event_streaming.md#example-payloads-for-ssh-events-with-deploy-key) feature. + ## View deploy keys To view the deploy keys available to a project: @@ -88,9 +94,9 @@ name and permissions. Prerequisites: -- You must have administrator access. -- [Generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). Put the private SSH - key on the host that requires access to the repository. +- You must have administrator access to the instance. +- You must [generate an SSH key pair](../../ssh.md#generate-an-ssh-key-pair). +- You must put the private SSH key on the host that requires access to the repository. To create a public deploy key: diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index cfb382d73e2..23cfa7cc500 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index ffbe7447aa8..eeaf5d799d2 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -87,6 +87,10 @@ For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_templat > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89810) in GitLab 15.7. +NOTE: +This feature is available only for +[the default template](#set-a-default-template-for-merge-requests-and-issues). + When you save a merge request for the first time, GitLab replaces these variables in your merge request template with their values: diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 8d3446994e8..b83feda0c96 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -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. In the upper right, above the file, select **Lock**. +1. In the upper-right corner, 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. @@ -221,7 +221,7 @@ To view the user who locked the file (if it was not you), hover over the button. To view and remove file locks: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Locked Files**. +1. On the left sidebar, select **Repository > Locked files**. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/img/codeowners_in_UI_v15_10.png b/doc/user/project/img/codeowners_in_UI_v15_10.png Binary files differnew file mode 100644 index 00000000000..c643d333791 --- /dev/null +++ b/doc/user/project/img/codeowners_in_UI_v15_10.png diff --git a/doc/user/project/img/multi_approvals_code_owners_sections_v15_9.png b/doc/user/project/img/multi_approvals_code_owners_sections_v15_9.png Binary files differnew file mode 100644 index 00000000000..a7fea76d5b1 --- /dev/null +++ b/doc/user/project/img/multi_approvals_code_owners_sections_v15_9.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 7114974d8db..a5d5f93f9ad 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -35,6 +35,8 @@ When importing: - [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. +- [Bitbucket Cloud import source](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your + GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. 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. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index e6d2e3e00b6..9937ea956c4 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -120,6 +120,16 @@ If the project import completes but LFS objects can't be downloaded or cloned, y password or personal access token containing special characters. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337769). +### Pull requests are missing + +Importing large projects spawns a process that can consume a lot of memory. Sometimes you can see messages such as `Sidekiq worker RSS out of range` in the +[Sidekiq logs](../../../administration/logs/index.md#sidekiq-logs). This can mean that MemoryKiller is interrupting the `RepositoryImportWorker` because it's using +too much memory. + +To resolve this problem, temporarily increase the `SIDEKIQ_MEMORY_KILLER_MAX_RSS` environment variable using +[custom environment variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html) from the default `2000000` value to a larger value like `3000000`. +Consider memory constraints on the system before deciding to increase `SIDEKIQ_MEMORY_KILLER_MAX_RSS`. + ## Related topics For information on automating user, group, and project import API calls, see diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 404bb4c8600..29fe9db8887 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -75,10 +75,9 @@ From there, you can view the import statuses of your Gitea repositories: You also can: -- Import all of your Gitea projects in one go by selecting **Import all projects** - in the upper left corner. -- Filter projects by name. If filter is applied, selecting **Import all projects** - imports only matched projects. +- In the upper-left corner, select **Import all projects** to import all of your Gitea projects at once. +- Filter projects by name. If a filter is applied, **Import all projects** + imports only selected projects.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index eeebb5a166c..a1d94d81e69 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -30,10 +30,8 @@ When importing projects: imported with a naming scheme similar to `GH-SHA-username/pull-request-number/fork-name/branch`. This may lead to a discrepancy in branches compared to those of the GitHub repository. -For additional technical details, refer to the [GitHub Importer](../../../development/github_importer.md) -developer documentation. - -For an overview of the import process, see the video [Migrating from GitHub to GitLab](https://youtu.be/VYOXuOg9tQI). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview of the import process, see [Migrating from GitHub to GitLab](https://youtu.be/VYOXuOg9tQI). ## Prerequisites @@ -62,7 +60,7 @@ prerequisites for those imports. If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable the [GitHub integration](../../../integration/github.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) +- If GitLab is behind an HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#allow-outbound-requests-to-certain-ip-addresses-and-domains) 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). @@ -209,17 +207,18 @@ The following items of a project are imported: - Repository description. - Git repository data. - Branch protection rules. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22650) in GitLab 15.4. +- Collaborators (members). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10. - Issues. - Pull requests. - Wiki pages. - Milestones. - Labels. -- Release note descriptions. +- Release notes content. - Attachments for: - Release notes. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15620) in GitLab 15.4. - - Comments and notes. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. + - Comments. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. - Issue description. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. - - Merge Request description. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. + - Pull Request description. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. All attachment imports are disabled by default behind `github_importer_attachments_import` [feature flag](../../../administration/feature_flags.md). From GitLab 15.5, can @@ -232,7 +231,7 @@ The following items of a project are imported: - Pull request "merged by" information. - Pull request comments replies in discussions. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336596) in GitLab 14.5. -- Diff Notes suggestions. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340624) in GitLab 14.7. +- Pull request review comments suggestions. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340624) in GitLab 14.7. - Issue events and pull requests events. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7673) in GitLab 15.4 with `github_importer_issue_events_import` [feature flag](../../../administration/feature_flags.md) disabled by default. From GitLab 15.5, can be imported [as an additional item](#select-additional-items-to-import). The feature flag was @@ -267,39 +266,25 @@ Mapping GitHub rule **Require status checks to pass before merging** to into GitLab due to technical difficulties. You can still create [external status checks](../merge_requests/status_checks.md) manually. -## Alternative way to import notes and diff notes - -When GitHub Importer runs on extremely large projects not all notes & diff notes can be imported due to GitHub API `issues_comments` & `pull_requests_comments` endpoints limitation. -Not all pages can be fetched due to the following error coming from GitHub API: `In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse.`. - -An [alternative approach](#select-additional-items-to-import) for importing comments is available. - -Instead of using `issues_comments` and `pull_requests_comments`, use individual resources `issue_comments` and `pull_request_comments` instead to pull notes from one object at a time. -This allows us to carry over any missing comments, however it increases the number of network requests required to perform the import, which means its execution takes a longer time. +### Collaborators (members) -## Reduce GitHub API request objects per page +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388716) in GitLab 15.10. -Some GitHub API endpoints may return a 500 or 502 error for project imports from large repositories. -To reduce the chance of such errors, you can enable the feature flag -`github_importer_lower_per_page_limit` in the group project importing the data. This reduces the -page size from 100 to 50. +These GitHub collaborator roles are mapped to these GitLab [member roles](../../permissions.md#roles): -To enable this feature flag, start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) -and run the following `enable` command: +| GitHub role | Mapped GitLab role | +|:------------|:-------------------| +| Read | Guest | +| Triage | Reporter | +| Write | Developer | +| Maintain | Maintainer | +| Admin | Owner | -```ruby -group = Group.find_by_full_path('my/group/fullpath') - -# Enable -Feature.enable(:github_importer_lower_per_page_limit, group) -``` +GitHub Enterprise Cloud has +[custom repository roles](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles). +These roles aren't supported and cause partial imports. -To disable the feature, run this command: - -```ruby -# Disable -Feature.disable(:github_importer_lower_per_page_limit, group) -``` +To import GitHub collaborators, you must have at least the Write role on the GitHub project. Otherwise collaborators import is skipped. ## Import from GitHub Enterprise on an internal network @@ -443,3 +428,47 @@ repository to be imported manually. Administrators can manually import the repos # Trigger import from second step Gitlab::GithubImport::Stage::ImportRepositoryWorker.perform_async(project.id) ``` + +### Errors when importing large projects + +The GitHub importer might encounter some errors when importing large projects. + +#### Alternative way to import notes and diff notes + +When the GitHub importer runs on extremely large projects, not all notes and diff notes can be imported due to the GitHub API `issues_comments` and `pull_requests_comments` endpoint limitations. + +If it's not possible to fetch all pages, the GitHub API might return the following error: + +```plaintext +In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse. +``` + +An [alternative approach](#select-additional-items-to-import) for importing comments is available. + +Instead of using `issues_comments` and `pull_requests_comments`, use individual resources to pull notes from one object at a time. This way, you can carry over any missing comments. However, execution takes longer because this method increases the number of network requests required to perform the import. + +#### Reduce GitHub API request objects per page + +Some GitHub API endpoints might return a `500` or `502` error for project imports from large repositories. +To reduce the chance of these errors, in the group project importing the data, enable the +`github_importer_lower_per_page_limit` feature flag. When enabled, the flag reduces the +page size from `100` to `50`. + +To enable this feature flag: + +1. Start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Run the following `enable` command: + + ```ruby + group = Group.find_by_full_path('my/group/fullpath') + + # Enable + Feature.enable(:github_importer_lower_per_page_limit, group) + ``` + +To disable the feature flag, run this command: + +```ruby +# Disable +Feature.disable(:github_importer_lower_per_page_limit, group) +``` diff --git a/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png b/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png Binary files differdeleted file mode 100644 index bbc72a0b4b7..00000000000 --- a/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png +++ /dev/null diff --git a/doc/user/project/import/img/fogbugz_import_finished.png b/doc/user/project/import/img/fogbugz_import_finished.png Binary files differdeleted file mode 100644 index 62c5c86c9b3..00000000000 --- a/doc/user/project/import/img/fogbugz_import_finished.png +++ /dev/null diff --git a/doc/user/project/import/img/manifest_status_v13_3.png b/doc/user/project/import/img/manifest_status_v13_3.png Binary files differdeleted file mode 100644 index c1a55ba1f50..00000000000 --- a/doc/user/project/import/img/manifest_status_v13_3.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 24748b2e89c..8c95e68e1f2 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -109,7 +109,7 @@ To view project import history: 1. On the top bar, select **Create new...** (**{plus-square}**). 1. Select **New project/repository**. 1. Select **Import project**. -1. Select **History** in the upper right corner. +1. In the upper-right corner, select **History**. 1. If there are any errors for a particular import, you can see them by selecting **Details**. The history also includes projects created from [built-in](../index.md#create-a-project-from-a-built-in-template) diff --git a/doc/user/project/index.md b/doc/user/project/index.md index decf3b071e7..da0546b85e6 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- @@ -139,9 +139,8 @@ Prerequisites: - You must have permission to add new projects to a namespace. To check if you have permission: 1. On the top bar, select **Main menu > Groups** and find your group. - 1. Confirm that **New project** is visible in the upper right - corner. Contact your GitLab - administrator if you require permission. + 1. In the upper-right corner, confirm that **New project** is visible. + Contact your GitLab administrator if you require permission. To push your repository and create a project: diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 1b41dd0b669..e326e7a222b 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -6,12 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # 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. +> - [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. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385335) in GitLab 15.10. Feature flag `apple_app_store_integration` removed. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. On GitLab.com, this feature is not available. - -The Apple App Store integration makes it easy to configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. +With the Apple App Store integration, you can configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. The integration is designed to be able to work out of the box with [fastlane](http://fastlane.tools/), but can be used with other build tools as well. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 8bc1a984e3d..fac09e7f071 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Asana **(FREE)** -This integration adds commit messages as comments to Asana tasks. +The Asana integration adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with `#` (for example, `#987654`). Every task ID found gets the commit comment added to it. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index c2371d32853..42f0ec6b0de 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Engineering Workflow Management (EWM) **(FREE)** -This integration allows you to go from GitLab to EWM work items mentioned in merge request +The EWM 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. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 990d0839581..3b5e55b48a1 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub **(PREMIUM)** You can update GitHub with pipeline status updates from GitLab. -This integration can help you if you use GitLab for CI/CD. +The GitHub integration can help you if you use GitLab for CI/CD.  diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md new file mode 100644 index 00000000000..553e82be382 --- /dev/null +++ b/doc/user/project/integrations/google_play.md @@ -0,0 +1,49 @@ +--- +stage: Manage +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Google Play **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111621) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `google_play_integration`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `google_play_integration`. On GitLab.com, this feature is not available. + +With the Google Play integration, you can configure your CI/CD pipelines to connect to the [Google Play Console](https://play.google.com/console) to build and release apps for Android devices. + +The Google Play integration works out of the box with [fastlane](https://fastlane.tools/). You can also use this integration with other build tools. + +## Enable the integration in GitLab + +Prerequisites: + +- You must have a [Google Play Console](https://play.google.com/console/signup) developer account. +- You must [generate a new service account key for your project](https://developers.google.com/android-publisher/getting_started) from the Google Cloud console. + +To enable the Google Play integration in GitLab: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Google Play**. +1. In **Enable Integration**, select the **Active** checkbox. +1. In **Service account key (.JSON)**, drag or upload your key file. +1. Select **Save changes**. + +After you enable the integration, the global variable `$SUPPLY_JSON_KEY_DATA` is created for CI/CD use. + +### CI/CD variable security + +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables, including `$SUPPLY_JSON_KEY_DATA`, and send them to a third-party server. For more information, see [CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). + +## Enable the integration in fastlane + +To enable the integration in fastlane and upload the build to the given track in Google Play, you can add the following code to your app's `fastlane/Fastfile`: + +```ruby +upload_to_play_store( + track: 'internal', + aab: '../build/app/outputs/bundle/release/app-release.aab' +) +``` diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 3537033902d..c9ba5b1b3aa 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # 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 +You can configure your project to send notifications from GitLab to a +room of your choice in [Google Chat](https://chat.google.com/) (formerly Google Hangouts). ## Integration workflow @@ -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 in the upper left and select **Manage webhooks**. +1. In the upper-left corner, from the room dropdown list, 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 596821ba12b..e316f6fbd9e 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -8,11 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. -Use Harbor as the container registry for your GitLab project. +You can use Harbor as the container registry for your GitLab project. -[Harbor](https://goharbor.io/) is an open source registry that can help you manage artifacts across cloud-native compute platforms, like Kubernetes and Docker. +[Harbor](https://goharbor.io/) is an open-source registry that can help you manage artifacts across cloud-native compute platforms like Kubernetes and Docker. -This integration can help you if you need GitLab CI/CD and a container image repository. +The Harbor integration can help you if you need GitLab CI/CD and a container image repository. ## Prerequisites diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 57947e21736..9ff6ad2a237 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -72,13 +72,14 @@ You can configure the following integrations. | [Pipelines emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | | [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | | [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | -| [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | +| [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | | [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | -| [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | +| [Shimo Workspace](shimo.md) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | | [GitLab for Slack app](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | | [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | | [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | +| [Squash TM](squash_tm.md) | Update Squash TM requirements when GitLab issues are modified. | **{check-circle}** Yes | | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 23525c33e84..757d15e71b3 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # irker (IRC gateway) **(FREE)** -GitLab provides a way to push update messages to an irker server. When -configured, pushes to a project trigger the integration to send data directly +GitLab provides a way to push update messages to an irker server. After you configure +the integration, each push to a project triggers 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/mock_ci.md b/doc/user/project/integrations/mock_ci.md index ae1737f8d3f..cbe073485e0 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -9,12 +9,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: 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 +To set up the mock CI service server, respond to the following endpoints: - `commit_status`: `#{project.namespace.path}/#{project.path}/status/#{sha}.json` - - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }` - - If the service returns a 404, it is interpreted as `pending` + - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }`. + - If the service returns a 404, the service is interpreted as `pending`. - `build_page`: `#{project.namespace.path}/#{project.path}/status/#{sha}` - - Just where the build is linked to, doesn't matter if implemented + - Where the build is linked to (whether or not it's implemented). -For an example of a mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service) +For an example of a mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service). diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 034be8ab3d8..c794001672b 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Pivotal Tracker **(FREE)** -This integration adds commit messages as comments to Pivotal Tracker stories. +The Pivotal Tracker 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 cd92e49cada..80c6337f934 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -23,7 +23,7 @@ Once enabled, GitLab detects metrics from known services in the [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create [custom dashboards](../../../operations/metrics/dashboards/index.md). -## Enabling Prometheus Integration +## Enabling the Prometheus integration ### Prometheus cluster integration diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 1e9319fa7c7..4f841b7ccb3 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.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 --- -# Monitoring AWS resources (DEPRECATED) **(FREE)** +# Monitoring AWS resources (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index b4533d83acd..8fec7f68ab1 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.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 --- -# Monitoring HAProxy (DEPRECATED) **(FREE)** +# Monitoring HAProxy (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index afefe80271e..fe9ce323b23 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.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 Metrics library (DEPRECATED) **(FREE)** +# Prometheus Metrics library (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 34a6823f007..dc6aa41d691 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.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 --- -# Monitoring Kubernetes (DEPRECATED) **(FREE)** +# Monitoring Kubernetes (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index f0a3b25f11a..90fe3ab8f8e 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.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 --- -# Monitoring NGINX (DEPRECATED) **(FREE)** +# Monitoring NGINX (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 947210541f4..ba3f41e8201 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.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 --- -# Monitoring NGINX Ingress Controller (DEPRECATED) **(FREE)** +# Monitoring NGINX Ingress Controller (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. 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 f8057866592..89b8388b70c 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.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 --- -# Monitoring NGINX Ingress Controller with VTS metrics (DEPRECATED) **(FREE)** +# Monitoring NGINX Ingress Controller with VTS metrics (deprecated) **(FREE)** > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 0a399d3481f..97c3e14dd9d 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Redmine **(FREE)** -Use [Redmine](https://www.redmine.org/) as the issue tracker. - +You can use [Redmine](https://www.redmine.org/) as an external issue tracker. To enable the Redmine integration in a project: 1. On the top bar, select **Main menu > Projects** and find your project. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index a34655c8e35..149c9172896 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -9,6 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. +To simplify your stack and streamline your processes, you should use GitLab [deployment approvals](../../../ci/environments/deployment_approvals.md) whenever possible. + ## GitLab spoke With the GitLab spoke in ServiceNow, you can automate actions for GitLab diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 2563cec2b05..f9b95a0dd0c 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -15,7 +15,7 @@ working in Slack, you can use Slack slash commands. 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. +The [Slack notifications integration](slack.md) is configured separately. ## Configure GitLab and Slack diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md new file mode 100644 index 00000000000..0f63b4a48db --- /dev/null +++ b/doc/user/project/integrations/squash_tm.md @@ -0,0 +1,37 @@ +--- +stage: Ecosystem +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 +--- + +# Squash TM integration **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337855) in GitLab 15.10. + +When [Squash TM](https://www.squashtest.com/squash-gitlab-integration?lang=en) (Test Management) +integration is enabled and configured in GitLab, issues (typically user stories) created in GitLab +are synchronized as requirements in Squash TM and test progress is reported in GitLab issues. + +## Configure Squash TM + +1. Optional. Ask your system administrator to [configure a token in the properties file](https://tm-en.doc.squashtest.com/latest/redirect/gitlab-integration-token.html). +1. Follow the [Squash TM documentation](https://tm-en.doc.squashtest.com/latest/redirect/gitlab-integration-configuration.html) to: + 1. Create a GitLab server. + 1. Enable the `Xsquash4GitLab` plugin + 1. Configure a synchronization. + 1. From the **Real-time synchronization** panel, copy the following fields to use later in GitLab: + + - **Webhook URL**. + - **Secret token** if your Squash TM system administrator configured one at step 1. + +## Configure GitLab + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Squash TM**. +1. Ensure that the **Active** toggle is enabled. +1. In the **Trigger** section, indicate which type of issue is concerned by the real-time synchronization. +1. Complete the fields: + + - Enter the **Squash TM webhook URL**, + - Enter the **secret token** if your Squash TM system administrator configured it earlier. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index d465b4e50f0..9c38cec0a01 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Unify Circuit integration sends notifications from GitLab to a Circuit conversation. -## Set up Unify Circuit service +## Set up Unify Circuit In Unify Circuit, [add a webhook](https://www.circuit.com/unifyportalfaqdetail?articleId=164448) and copy its URL. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 3d971af5c2a..1511e37e31e 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -118,11 +118,16 @@ Endpoints should follow these best practices: - Never return `500` server error status responses if the event has been handled as this can cause the webhook to be [temporarily disabled](#failing-webhooks). - Invalid HTTP responses are treated as failed requests. -### Failing webhooks +## Failing webhooks -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60837) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 15.7. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 15.7. Feature flag `web_hooks_disable_failed` removed. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60837) for project webhooks in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) for project webhooks in GitLab 15.7. Feature flag `web_hooks_disable_failed` removed. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385902) for group webhooks in GitLab 15.10. +> - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/390157) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`. +On GitLab.com, this feature is available. If a webhook fails repeatedly, it may be disabled automatically. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 234faa893eb..98017fb5542 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -74,7 +74,7 @@ Prerequisites: To create a new issue board: -1. Select the dropdown list with the current board name in the upper left corner of the issue boards page. +1. In the upper-left corner of the issue board page, select the dropdown list with the current board name. 1. Select **Create new board**. 1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. @@ -86,7 +86,7 @@ Prerequisites: To delete the currently active issue board: -1. Select the dropdown list with the current board name in the upper left corner of the issue boards page. +1. In the upper-left corner of the issue board page, select the dropdown list with the current board name. 1. Select **Delete board**. 1. Select **Delete** to confirm. @@ -394,11 +394,11 @@ You can also [drag issues](#move-issues-and-lists) to change their position and  -## Work In Progress limits **(PREMIUM)** +## Work in progress limits **(PREMIUM)** > Moved to GitLab Premium in 13.9. -You can set a Work In Progress (WIP) limit for each issue list on an issue board. When a limit is +You can set a work in progress (WIP) limit for each issue list on an issue board. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. You cannot set a WIP limit on the default lists (**Open** and **Closed**). @@ -413,11 +413,11 @@ Prerequisites: - You must have at least the Reporter role for the project. -To set a WIP limit for a list: +To set a WIP limit for a list, in an issue board: -1. Navigate to a Project or Group board of which you're a member. -1. Select the settings icon in a list's header. -1. Next to **Work In Progress Limit**, select **Edit**. +1. On the top of the list you want to edit, select **List actions** (**{ellipsis_v}**) **> Edit list settings**. + The list settings sidebar opens on the right. +1. Next to **Work in progress limit**, select **Edit**. 1. Enter the maximum number of issues. 1. Press <kbd>Enter</kbd> to save. @@ -475,7 +475,7 @@ Additionally, you can also see the time tracking value. ### Create a new list -Create a new list by selecting the **Create** button in the upper right corner of the issue board. +To create a new list, in the upper-right corner of the issue board, select **Create**.  @@ -493,10 +493,10 @@ Prerequisites: To remove a list from an issue board: -1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). +1. On the top of the list you want to remove, select **List actions** (**{ellipsis_v}**). The list settings sidebar opens on the right. 1. Select **Remove list**. A confirmation dialog appears. -1. Select **OK**. +1. Select **Remove list** again. ### Add issues to a list diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 5ebb2fc2e1c..b6931149ede 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -100,7 +100,7 @@ To create an issue from a project issue board: 1. On the top bar, select **Main menu > Projects** and find your project. 1. Select **Issues > Boards**. -1. At the top of a board list, select **New issue** (**{plus-square}**). +1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. 1. Enter the issue's title. 1. Select **Create issue**. @@ -108,7 +108,7 @@ To create an issue from a group issue board: 1. On the top bar, select **Main menu > Groups** and find your group. 1. Select **Issues > Boards**. -1. At the top of a board list, select **New issue** (**{plus-square}**). +1. At the top of a board list, select **List actions** (**{ellipsis_v}**) **> Create new issue**. 1. Enter the issue's title. 1. Under **Projects**, select the project in the group that the issue should belong to. 1. Select **Create issue**. @@ -118,9 +118,6 @@ example, if the list is scoped to a label `Frontend`, the new issue also has thi ## By sending an email -> - Generated email address format changed in GitLab 11.7. -> - The older format is still supported, so existing aliases and contacts still work. - You can send an email to create an issue in a project on the project's **Issues List** page. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 52da1acd32a..f1f41de7cb4 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -39,10 +39,10 @@ git commit -m "this is my commit message. Ref projectname#xxx" ``` If they are not in the same group, you can add the full URL to the issue -(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). +(`https://gitlab.com/<username>/<projectname>/-/issues/<xxx>`). ```shell -git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>" +git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/-/issues/<xxx>" ``` Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 8a6683a55b5..ac7d8c99fa8 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -36,8 +36,8 @@ 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 in the upper right, next to **Edit issues**. - - Project has no issues: Select **Import CSV** in the middle of the page. + - The project has existing issues: in the upper-right corner, next to **Edit issues**, select the import icon (**{import}**). + - The project has no issues: in the middle of the page, select **Import CSV**. 1. Select the file you want to import, and then select **Import issues**. The file is processed in the background, and a notification email is sent diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index f43f87119a6..10b29feb072 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -227,6 +227,19 @@ New discussion threads get different pin numbers, which you can use to refer to In GitLab 12.5 and later, new discussions are output to the issue activity, so that everyone involved can participate in the discussion. +## Delete a comment from a design + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385100) in GitLab 15.9. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To delete a comment from a design: + +1. On the comment you want to delete, select **More actions** **{ellipsis_v}** **> Delete comment**. +1. On the confirmation dialog box, select **Delete comment**. + ## Resolve a discussion thread on a design > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13049) in GitLab 13.1. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index c16074ea1d8..e0966909b1e 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -400,7 +400,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, in the upper right, select **{issues}** **Issues**. +- On the top bar, in the upper-right corner, select **Issues** (**{issues}**). ## Filter the list of issues diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index c7d45b0bd15..6e20492db05 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 4dda68a6d08..356e4e1b194 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -70,17 +70,21 @@ are given access to the project. In addition: ## Maximum role +When you invite a group to a project, the maximum role is the highest level of access the invited group members are allowed to have in the project. + 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**. +given the highest access level of the two for the project. 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. +NOTE: +The Max role does not elevate the privileges of users. +For example, if a group member has the role of Developer, and the group is invited to a project with a Max role of Maintainer, the member's role is not elevated to Maintainer. + ### View the member's Max role To view the maximum role assigned to a member: diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 0729e024df4..4a22cc71349 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -61,7 +61,7 @@ In the following example: To change or add a commit to the contributor's merge request: 1. Go to the merge request. -1. In the upper right corner, select **Code**, then select **Check out branch**. +1. In the upper-right corner, select **Code**, then select **Check out branch**. 1. In the modal window, select **Copy** (**{copy-to-clipboard}**). 1. In your terminal, go to your cloned version of the repository, and paste the commands. For example: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 9fac872ac4b..d2676b1bdf0 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 upper right, select **Cherry-pick**: +1. In the upper-right corner, select **Cherry-pick**:  1. In the modal window, select the project and branch to cherry-pick into. @@ -72,7 +72,8 @@ To cherry-pick a commit from the list of all commits for a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Repository > Commits**. -1. Select the title of the commit you want to cherry-pick. +1. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. +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**. @@ -86,7 +87,7 @@ list of commits included in a 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. 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. Select the [title](https://git-scm.com/docs/git-commit#_discussion) of the commit you want to cherry-pick. 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**. @@ -100,7 +101,8 @@ when you view that file in your project's Git repository: 1. On the top bar, select **Main menu > Projects** and find your project. 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. Select **History**, then select the [title](https://git-scm.com/docs/git-commit#_discussion) + of the commit you want to cherry-pick. 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**. diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md deleted file mode 100644 index a9f67c39ae8..00000000000 --- a/doc/user/project/merge_requests/commits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../merge_requests/index.md' -remove_date: '2023-03-12' ---- - -This document was removed. - -<!-- This redirect file can be deleted after <2023-03-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 875312bbb7c..4ea549e5986 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -11,7 +11,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.h There are many different ways to create a merge request. NOTE: -Use [branch naming patterns](../repository/branches/index.md#naming) to streamline merge request creation. +Use [branch naming patterns](../repository/branches/index.md#prefix-branch-names-with-issue-numbers) to streamline merge request creation. ## From the merge request list @@ -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 upper right, select **New merge request**. +1. In the upper-right corner, 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**. @@ -171,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 upper right, select **Email a new merge request to this project**. +1. In the upper-right corner, 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/img/remove_source_branch_status.png b/doc/user/project/merge_requests/img/remove_source_branch_status.png Binary files differdeleted file mode 100644 index afd93207e02..00000000000 --- a/doc/user/project/merge_requests/img/remove_source_branch_status.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index a633366cc62..f760b1b730a 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -65,7 +65,7 @@ or: or: -1. On the top bar, in the upper right, select **{merge-request-open}** **Merge requests**. +1. On the top bar, in the upper-right corner, select **Merge requests** (**{merge-request-open}**). 1. From the dropdown list, select **Assigned to you**. ## Filter the list of merge requests @@ -257,8 +257,8 @@ FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `moved_mr_sidebar`. On GitLab.com, this feature is enabled in the following projects: `gitlab-org/gitlab`, `gitlab-com/www-gitlab-com`, and `gitlab-org/customers-gitlab-com`. -When this feature flag is enabled, you can find the following actions in -**Merge request actions** (**{ellipsis_v}**) in the upper right: +When this feature flag is enabled, in the upper-right corner, +**Merge request actions** (**{ellipsis_v}**) contains the following actions: - 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) @@ -304,7 +304,6 @@ For a web developer writing a webpage for your company's website: - [GitLab keyboard shortcuts](../../shortcuts.md) - [Comments and threads](../../discussions/index.md) - [Suggest code changes](reviews/suggestions.md) -- [Commits](commits.md) - [CI/CD pipelines](../../../ci/index.md) - [Push options](../push_options.md) for merge requests diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 1f7e15ee982..02bd4ed0502 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -228,5 +228,4 @@ workflow that requires frequent rebases. ## Related topics -- [Commits history](../commits.md) - [Squash and merge](../squash_and_merge.md) diff --git a/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png Binary files differdeleted file mode 100644 index e27fa629672..00000000000 --- a/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png Binary files differdeleted file mode 100644 index 92d5ba5ddda..00000000000 --- a/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png Binary files differdeleted file mode 100644 index 58e0508d8cf..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png Binary files differdeleted file mode 100644 index 2805ef19f2d..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 5291a845437..4bd77c7ebdd 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Review a merge request **(FREE)** +# Merge request reviews **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. @@ -84,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. In the upper right, select **Code > Plain diff**. +1. In the upper-right corner, 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 @@ -107,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. In the upper right, select **Code > Email patches**. +1. In the upper-right corner, 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 diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 668dece9fda..6976d4052e1 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -8,44 +8,40 @@ type: index, reference # Suggest changes **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. - -As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request -diff threads. Then, the merge request author (or other users with appropriate -[permission](../../../permissions.md)) can apply these suggestions. -This action generates a commit in the merge request, authored by the user that suggested the changes. - -1. Choose a line of code to be changed, add a new comment, then select - the **Insert suggestion** icon in the toolbar: - -  - -1. In the comment, add your suggestion to the pre-populated code block: - -  - +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. Feature flag `suggestions_custom_commit` removed. + +Reviewers can suggest code changes with a Markdown syntax in merge request diff threads. +The merge request author (or other users with the appropriate role) can apply any or +all of the suggestions from the GitLab UI. Applying suggestions adds a commit to the +merge request, authored by the user who suggested the changes. + +## Create suggestions + +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. On the secondary menu, select **Changes**. +1. Find the lines of code you want to change. + - To select a single line: + - Hover over the line number, and + select **Add a comment to this line** (**{comment}**). + - To select multiple lines: + 1. Hover over the line number, and select **Add a comment to this line** (**{comment}**). + 1. Select and drag your selection until all desired lines are included. To + learn more, see [Multi-line suggestions](#multi-line-suggestions). +1. In the comment toolbar, select **Insert suggestion** (**{doc-code}**). GitLab + inserts a pre-populated code block into your comment, like this: + + ````markdown + ```suggestion:-0+0 + The content of the line you selected is shown here. + ``` + ```` + +1. Edit the pre-populated code block to add your suggestion. 1. Select either **Start a review** or **Add to review** to add your comment to a [review](index.md), or **Add comment now** to add the comment to the thread immediately. - The suggestion in the comment can be applied by the merge request author - directly from the merge request: - -  - -1. Optionally specify a custom commit message for individual suggestions (GitLab 13.9 and later) to - describe your change. If you don't specify it, the default commit message is used. - -  - -After the author applies a suggestion: - -1. The suggestion is marked as **Applied**. -1. The thread is resolved. -1. GitLab creates a new commit with the changes. -1. If the user has the Developer role, GitLab pushes - the suggested change directly into the codebase in the merge request's branch. - -## Multi-line suggestions +### Multi-line suggestions > [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/232339) in GitLab 13.11: suggestions in multi-line comments also become multi-line. @@ -68,65 +64,83 @@ Suggestions for multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line. This allows for up to 200 changed lines per suggestion. -## Code block nested in suggestions +## Apply suggestions + +The merge request author can apply suggested changes directly from 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. Find the comment containing the suggestion you want to apply. + - To apply suggestions individually, select **Apply suggestion**. + - To apply multiple suggestions in a single commit, select **Add suggestion to batch**. +1. Optional. Provide a custom commit message to describe your change. If you don't provide a custom message, the default commit message is used. +1. Select **Apply**. + +After a suggestion is applied: + +- The suggestion is marked as **Applied**. +- The comment thread is resolved. +- GitLab creates a new commit with the changes. +- If the user has the Developer role, GitLab pushes + the suggested change directly into the codebase in the merge request's branch. + +## Nest code blocks in suggestions To add a suggestion that includes a [fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks instead of three: -~~~markdown +`````markdown ````suggestion:-0+2 ```shell git config --global receive.advertisepushoptions true ``` ```` -~~~ +`````  ## Configure the commit message for applied suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. +GitLab uses a default commit message when applying suggestions. This message +supports placeholders, and can be changed. For example, the default message +`Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` renders +like this if you apply three suggestions to two different files: -GitLab uses a default commit message -when applying suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` - -<!-- vale gitlab.BadPlurals = NO --> +```plaintext +Apply 3 suggestion(s) to 2 file(s) +``` -For example, consider that a user applied 3 suggestions to 2 different files, the -default commit message is: **Apply 3 suggestion(s) to 2 file(s)** +Merge requests created from forks use the template defined in the target project. -<!-- vale gitlab.BadPlurals = YES --> +To meet your project's needs, you can customize these messages and include other +placeholder variables: -These commit messages can be customized to follow any guidelines you might have. -To do so, expand the **Merge requests** tab within your project's **General** -settings and change the **Merge suggestions** text: +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Scroll to **Merge suggestions**, and alter the text to meet your needs. + See [Supported variables](#supported-variables) for a list of placeholders + you can use in this message. - +### Supported variables -You can also use following variables besides static text: +The template for commit messages for applied suggestions supports these variables: | Variable | Description | Output example | |------------------------|-------------|----------------| | `%{branch_name}` | The name of the branch to which suggestions were applied. | `my-feature-branch` | -| `%{files_count}` | The number of files to which suggestions were applied.| **2** | +| `%{files_count}` | The number of files to which suggestions were applied.| `2` | | `%{file_paths}` | The paths of the file to which suggestions were applied. Paths are separated by commas.| `docs/index.md, docs/about.md` | | `%{project_path}` | The project path. | `my-group/my-project` | -| `%{project_name}` | The human-readable name of the project. | **My Project** | -| `%{suggestions_count}` | The number of suggestions applied.| **3** | +| `%{project_name}` | The human-readable name of the project. | `My Project` | +| `%{suggestions_count}` | The number of suggestions applied.| `3` | | `%{username}` | The username of the user applying suggestions. | `user_1` | -| `%{user_full_name}` | The full name of the user applying suggestions. | **User 1** | +| `%{user_full_name}` | The full name of the user applying suggestions. | `User 1` | For example, to customize the commit message to output -**Addresses user_1's review**, set the custom text to +`Addresses user_1's review`, set the custom text to `Addresses %{username}'s review`. -For merge requests created from forks, GitLab uses the template defined in target project. - -NOTE: -Custom commit messages for each applied suggestion is -introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). - ## Batch suggestions > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](../../../../policy/alpha-beta-support.md#alpha-features) with a flag named `batch_suggestions`, disabled by default. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 62a2baa049b..6a791a17057 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -151,12 +151,15 @@ the status check and it **is not** recoverable. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1. > - UI [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91504) in GitLab 15.2. > - Ability to retry failed external status checks [added](https://gitlab.com/gitlab-org/gitlab/-/issues/383200) in GitLab 15.8. +> - Widget [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111763) to poll for updates when there are pending status checks in GitLab 15.11. The status checks widget displays in merge requests and displays the following statuses: - **pending** (**{status-neutral}**), while GitLab waits for a response from an external status check. - **success** (**{status-success}**) or **failed** (**{status-failed}**), when GitLab receives a response from an external status check. +When there are pending status checks, the widget polls for updates every few seconds until it receives a **success** or **failed** response. + To retry a failed status check: 1. Expand the merge request widget to show the list of external status checks. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 81b334c0a02..c7ed6069cb6 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -137,14 +137,16 @@ To switch between the two settings, select either **Issues** or **Issue weight** When sorting by weight, make sure all your issues have weight assigned, because issues with no weight don't show on the chart. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Burndown and burnup charts do not show the correct issue status -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +A limitation of these charts is that [the days are in the UTC time zone](https://gitlab.com/gitlab-org/gitlab/-/issues/267967). + +This can cause the graphs to be inaccurate in other timezones. For example: + +- All the issues in a milestone are recorded as being closed on or before the last day. +- One issue was closed on the last day at 6 PM PST (Pacific time), which is UTC-7. +- The issue activity log displays the closure time at 6 PM on the last day of the milestone. +- The charts plot the time in UTC, so for this issue, the close time is 1 AM the following day. +- The charts show the milestone as incomplete and missing one closed issue. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 5f9a2961df5..e9de780655a 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -65,7 +65,10 @@ Improving this experience is tracked in issue [339009](https://gitlab.com/gitlab You can view all the milestones you have access to in the entire GitLab namespace. You might not see some milestones because they're in projects or groups you're not a member of. -To do so, on the top bar select **Main menu > Milestones**. +To do so: + +1. On the top bar select **Main menu > Your work**. +1. On the left sidebar, select **Milestones**. ### View milestone details diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index 2b4ce6d2fd0..85a1dfda679 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- 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 e55cf337d16..a92f65b064e 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 @@ -5,10 +5,7 @@ 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 --- -# DNS records overview **(FREE)** - -_Read this document for a brief overview of DNS records in the scope -of GitLab Pages, for beginners in web development._ +# GitLab Pages DNS records **(FREE)** A Domain Name System (DNS) web service routes visitors to websites by translating domain names (such as `www.example.com`) into the @@ -74,7 +71,7 @@ Example: This way, visitors visiting `www.example.com` are redirected to `example.com`. -## MX record +## `MX` record MX records are used to define the mail exchanges that are used for the domain. This helps email messages arrive at your mail server correctly. 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 24e9e6e15a4..3bb62921979 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 @@ -5,7 +5,7 @@ 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 --- -# Custom domains and SSL/TLS certificates **(FREE)** +# GitLab Pages custom domains **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238461) in GitLab 15.4, you can use verified domains to [bypass user email confirmation for SAML- or SCIM-provisioned users](../../../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). 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 95ac2e50f29..34a2f221327 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 @@ -6,7 +6,7 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Pages integration with Let's Encrypt **(FREE)** +# GitLab Pages Let's Encrypt certificates **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. 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 398d8dc6e1e..0ba00177659 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 @@ -5,10 +5,7 @@ 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 --- -# SSL/TLS certificates **(FREE)** - -_Read this document for a brief overview of SSL/TLS certificates in -the scope of GitLab Pages, for beginners in web development._ +# GitLab Pages SSL/TLS certificates **(FREE)** Every GitLab Pages project on GitLab.com is available under HTTPS for the default Pages domain (`*.gitlab.io`). Once you set 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 f596e418b02..37f74d18d4c 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 @@ -5,7 +5,7 @@ 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 --- -# Create a Pages website by using a CI/CD template **(FREE)** +# Create a GitLab Pages website from a CI/CD template **(FREE)** GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). You can create your own `.gitlab-ci.yml` file from one of these templates, and run 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 509609e9b89..a864c114b3e 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 @@ -5,7 +5,7 @@ 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 --- -# Create a Pages website from a forked sample **(FREE)** +# Create a GitLab Pages website from a forked sample project **(FREE)** GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. @@ -19,7 +19,7 @@ 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 upper right, select **Fork** and then choose a namespace to fork to. +1. In the upper-right corner, select **Fork**, then choose a namespace to fork to. 1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. GitLab CI/CD builds and deploys your site. 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 a301d2b64be..7b6efaa7af4 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 @@ -4,7 +4,7 @@ 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 --- -# Create a Pages website from a template **(FREE)** +# Create a GitLab Pages website from a project template **(FREE)** GitLab provides templates for the most popular Static Site Generators (SSGs). You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 91c2c532a9a..00635fe6db2 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -4,7 +4,7 @@ group: Incubation info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Create a Pages deployment for your static site **(FREE)** +# Create a GitLab Pages deployment for a static site **(FREE)** If you already have a GitLab project that contains your static site or framework, you can generate a GitLab Pages website from it. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index a0c8073d6eb..b286c59916a 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -4,7 +4,7 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Pages domain names, URLs, and base URLs **(FREE)** +# GitLab Pages default domain names and URLs **(FREE)** On this document, learn how to name your project for GitLab Pages according to your intended website's URL. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 51c42eeecb8..0a8348f468e 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -4,7 +4,7 @@ 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 --- -# Exploring GitLab Pages **(FREE)** +# GitLab Pages settings **(FREE)** This document is a user guide to explore the options and settings GitLab Pages offers. diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 751db136e34..3007d1a10d1 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -6,7 +6,7 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Configure the public files folder **(FREE)** +# GitLab Pages public folder **(FREE)** All the files that should be accessible by the browser must be in a root-level folder called `public`. @@ -98,7 +98,7 @@ example: next export -o public ``` -### Nuxt.js +## Nuxt.js NOTE: GitLab Pages supports only static sites. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index f5447fd67ca..75cb1474dc2 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -4,7 +4,7 @@ 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 --- -# Create redirects for GitLab Pages **(FREE)** +# GitLab Pages redirects **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index da53fe2f5e9..725818a7d25 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -36,6 +36,40 @@ When a branch is protected, the default behavior enforces these restrictions on 1. No one can delete a protected branch using Git commands, however, users with at least Maintainer role can [delete a protected branch from the UI or API](#delete-a-protected-branch). +### When a branch matches multiple rules + +When a branch matches multiple rules, the **most permissive rule** determines the +level of protection for the branch. For example, consider these rules, which include +[wildcards](#configure-multiple-protected-branches-by-using-a-wildcard): + +| Branch name pattern | Allowed to merge | Allowed to push | +|---------------------|------------------------|-----------------| +| `v1.x` | Maintainer | Maintainer | +| `v1.*` | Maintainer + Developer | Maintainer | +| `v*` | No one | No one | + +A branch named `v1.x` matches all three branch name patterns: `v1.x`, `v1.*`, and `v*`. +As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are: + +- **Allowed to merge:** Of the three settings, `Maintainer + Developer` is most permissive, + and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*` + (which each have stricter permissions), users with the Developer role can merge into the branch. +- **Allowed to push:** Of the three settings, `Maintainer` is the most permissive, and controls + branch behavior as a result. Even though branches matching `v*` are set to `No one`, branches + that _also_ match `v1.x` or `v1.*` receive the more permissive `Maintainer` permission. + +To be certain that a rule controls the behavior of a branch, +_all_ other patterns that match must apply less or equally permissive rules. + +If you want to ensure that `No one` is allowed to push to branch `v1.x`, every pattern +that matches `v1.x` must set `Allowed to push` to `No one`, like this: + +| Branch name pattern | Allowed to merge | Allowed to push | +|---------------------|------------------------|-----------------| +| `v1.x` | Maintainer | No one | +| `v1.*` | Maintainer + Developer | No one | +| `v*` | No one | No one | + ### Set the default branch protection level Administrators can set a default branch protection level in the @@ -43,6 +77,37 @@ Administrators can set a default branch protection level in the ## Configure a protected branch +Configure protected branches for all projects in a group, or just for a project. + +### For all projects in a group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 behind a feature flag, disabled by default. + +Group owners can create protected branches for a group. These settings are inherited by all projects in the group and can't be overridden by project settings. + +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 `group_protected_branches`. On GitLab.com, this feature is not available. + +Prerequisite: + +- You must have the Owner role in the group. + +To protect a branch for all the projects in a group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Protected branches**. +1. In the **Branch** text box, type the branch name or a wildcard. +1. From the **Allowed to merge** list, select a role, group, or user that can merge into this branch. +1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. +1. Select **Protect**. + +The protected branch is added to the list of protected branches. + +### For a project + Prerequisite: - You must have at least the Maintainer role. @@ -203,8 +268,7 @@ Members who can push to this branch can now also force push. ## Require Code Owner approval on a protected branch **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab 12.4. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. For a protected branch, you can require at least one approval by a [Code Owner](code_owners.md). diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 152a55d24b7..1256599c521 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Protected tags **(FREE)** -Protected tags: +Protected [tags](repository/tags/index.md): - Allow control over who has permission to create tags. - Prevent accidental update or deletion once created. @@ -86,6 +86,32 @@ To prevent this problem: Users can still create branches, but not tags, with the protected names. +## Allow deploy keys to create protected tags + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325415) in GitLab 15.11. + +You can permit the owner of a [deploy key](deploy_keys/index.md) to create protected tags. +The deploy key works, even if the user isn't a member of the related project. However, the owner of the deploy +key must have at least read access to the project. + +Prerequisites: + +- The deploy key must be enabled for your project. A project deploy key is enabled by default when + it is created. However, a public deploy key must be + [granted](deploy_keys/index.md#grant-project-access-to-a-public-deploy-key) access to the + project. +- The deploy key must have [write access](deploy_keys/index.md#permissions) to your project + repository. + +To allow a deploy key to create a protected tag: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Protected tags**. +1. From the **Tag** dropdown list, select the tag you want to protect. +1. From the **Allowed to create** list, select the deploy key. +1. Select **Protect**. + ## Delete a protected tag You can manually delete protected tags with the GitLab API, or the @@ -106,6 +132,11 @@ Protected tags can only be deleted by using GitLab either from the UI or API. These protections prevent you from accidentally deleting a tag through local Git commands or third-party Git clients. +## Related topics + +- [Protected Tags API](../../api/protected_tags.md) +- [Tags API](../../api/tags.md) + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 90da47f7995..3a00260770e 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -69,7 +69,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | | `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | | `/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. | +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to-do item 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`. 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>`. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index dca34af41b4..be2c923adcc 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -88,7 +88,7 @@ To create a release in the Releases page: - [Title](release_fields.md#title). - [Milestones](#associate-milestones-with-a-release). - [Release notes](release_fields.md#release-notes-description). - - Whether or not to include the [Tag message](../../../topics/git/tags.md). + - Whether or not to include the [Tag message](../repository/tags/index.md). - [Asset links](release_fields.md#links). 1. Select **Create release**. diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index 1ec82d6702e..36e36412cf1 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index 5af19c7cced..953e1d4b082 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index 120bbe32a63..93822be89b6 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Configure +group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 1abcca547db..58d43f64812 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -97,7 +97,7 @@ docker run -d \ -v "${CERTS_DIR}/fullchain.pem:/gitlab-rd-web-ide/certs/fullchain.pem" \ -v "${CERTS_DIR}/privkey.pem:/gitlab-rd-web-ide/certs/privkey.pem" \ -v "${PROJECTS_DIR}:/projects" \ - registry.gitlab.com/gitlab-com/create-stage/editor-poc/remote-development/gitlab-rd-web-ide-docker:0.1-alpha \ + registry.gitlab.com/gitlab-org/remote-development/gitlab-rd-web-ide-docker:0.2-alpha \ --log-level warn --domain "${DOMAIN}" --ignore-version-mismatch ``` diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png Binary files differdeleted file mode 100644 index a1cf9f10122..00000000000 --- a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_12.png b/doc/user/project/repository/branches/img/compare_branches_v13_12.png Binary files differdeleted file mode 100644 index 29627406729..00000000000 --- a/doc/user/project/repository/branches/img/compare_branches_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png Binary files differdeleted file mode 100644 index 230abf0d875..00000000000 --- a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png Binary files differdeleted file mode 100644 index 7eb10d10938..00000000000 --- a/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png Binary files differdeleted file mode 100644 index f92c4279871..00000000000 --- a/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png b/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png Binary files differnew file mode 100644 index 00000000000..09b30af91d0 --- /dev/null +++ b/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 60504b94502..ef625739956 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -6,142 +6,148 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Branches **(FREE)** -A branch is a version of a project's working tree. You create a branch for each -set of related changes you make. This keeps each set of changes separate from -each other, allowing changes to be made in parallel, without affecting each -other. +Branches are versions of a project's working tree. When you create a new +[project](../../index.md), GitLab creates a [default branch](default.md) (which +cannot be deleted) for your repository. Default branch settings can be configured +at the project, subgroup, group, or instance level. -After pushing your changes to a new branch, you can: +As your project grows, your team [creates](../web_editor.md#create-a-branch) more +branches, preferably by following [branch naming patterns](#prefix-branch-names-with-issue-numbers). +Each branch represents a set of changes, which allows development work to be done +in parallel. Development work in one branch does not affect another branch. -- Create a [merge request](../../merge_requests/index.md). You can streamline this process - by following [branch naming patterns](#naming). -- Perform inline code review. -- [Discuss](../../../discussions/index.md) your implementation with your team. -- Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). +Branches are the foundation of development in a project: -You can also request [approval](../../merge_requests/approvals/index.md) -from your managers. +1. To get started, create a branch and add commits to it. +1. When the work is ready for review, create a [merge request](../../merge_requests/index.md) to propose + merging the changes in your branch. To streamline this process, you should follow + [branch naming patterns](#prefix-branch-names-with-issue-numbers). +1. Preview changes in a branch with a [review app](../../../../ci/review_apps/index.md). +1. After the contents of your branch are merged, [delete the merged branch](#delete-merged-branches). -For more information on managing branches using the GitLab UI, see: +## Manage and protect branches -- [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a - default branch for the repository. You can change this setting at the project, - subgroup, group, or instance level. -- [Create a branch](../web_editor.md#create-a-branch) -- [Protected branches](../../protected_branches.md#protected-branches) -- [Delete merged branches](#delete-merged-branches) -- [Branch filter search box](#branch-filter-search-box) +GitLab provides you multiple methods to protect individual branches. These methods +ensure your branches receive oversight and quality checks from their creation to their deletion: -You can also manage branches using the -[command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +- The [default branch](default.md) in your project receives extra protection. +- Configure [protected branches](../../protected_branches.md#protected-branches) + to restrict who can commit to a branch, merge other branches into it, or merge + the branch itself into another branch. +- Configure [approval rules](../../merge_requests/approvals/rules.md) to set review + requirements, including [security-related approvals](../../merge_requests/approvals/rules.md#security-approvals), before a branch can merge. +- Integrate with third-party [status checks](../../merge_requests/status_checks.md) + to ensure your branch contents meet your standards of quality. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Watch the video [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE). +You can manage your branches: -See also: +- With the GitLab user interface. +- With the [command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +- With the [Branches API](../../../../api/branches.md). -- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. -- [GitLab Flow](../../../../topics/gitlab_flow.md) documentation. -- [Getting started with Git](../../../../topics/git/index.md) and GitLab. - -## Naming - -Prefix a branch name with an issue number to streamline merge request creation. -When you create a merge request for a branch with a name beginning with an issue -number, GitLab: - -- Marks the issue as related. If your project is configured with a - [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), - merging this merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) - the related issue. -- Copies label and milestone metadata from the issue. - -## Compare - -To compare branches in a repository: - -1. Navigate to your project's repository. -1. Select **Repository > Compare** in the sidebar. -1. Select the target repository to compare with the [repository filter search box](#repository-filter-search-box). -1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). -1. Select **Compare** to view the changes inline: - -  - -## Delete merged branches - - +### View all branches -This feature allows merged branches to be deleted in bulk. Only branches that -have been merged into the project's default branch and -[are not protected](../../protected_branches.md) are deleted as part of -this operation. +To view and manage your branches in the GitLab user interface: -It's particularly useful to clean up old branches that were not deleted -automatically when a merge request was merged. - -## Repository filter search box +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. +On this page, you can: -This feature allows you to search and select a repository quickly when [comparing branches](#compare). +- See all branches, active branches, or stale branches. +- Create new branches. +- [Compare branches](#compare-branches). +- Delete merged branches. - +### View branches with configured protections -Search results appear in the following order: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.10. -- Repositories with names exactly matching the search terms. -- Other repositories with names that include search terms, sorted alphabetically. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../feature_flags.md) named `branch_rules`. +On GitLab.com, this feature is available. -## Branch filter search box +Branches in your repository can be [protected](../../protected_branches.md) in multiple ways. You can: - +- Limit who can push to the branch. +- Limit who can merge the branch. +- Require approval of all changes. +- Require external tests to pass. -This feature allows you to search and select branches quickly. Search results appear in the following order: +The **Branch rules overview** page shows all branches with any configured protections, +and their protection methods: -- Branches with names that matched search terms exactly. -- Other branches with names that include search terms, sorted alphabetically. + -Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following operators: +Prerequisites: -- `^` matches beginning of branch name, for example `^feat` would match `feat/user-authentication` -- `$` matches end of branch name, for example `widget$` would match `feat/search-box-widget` -- `*` wildcard matcher, for example `branch*cache*` would match `fix/branch-search-cache-expiration` +- You must have at least the Developer role in the project. -These operators can be mixed, for example `^chore/*migration$` would match `chore/user-data-migration` +To view the **Branch rules overview** list: -## Swap revisions +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Branch Rules** to view all branches with protections. + - To add protections to a new branch: + 1. Select **Add branch rule**. + 1. Select **Create protected branch**. + - To view more information about protections on an existing branch: + 1. Identify the branch you want more information about. + 1. Select **Details** to see information about its: + - [Branch protections](../../protected_branches.md). + - [Approval rules](../../merge_requests/approvals/rules.md). + - [Status checks](../../merge_requests/status_checks.md). + +## Prefix branch names with issue numbers + +To streamline the creation of merge requests, start your branch name with an +issue number. GitLab uses the issue number to import data into the merge request: + +- The issue is marked as related. The issue and merge request display links to each other. +- If your project is configured with a + [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), + merging the merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) + the related issue. +- The issue milestone and labels are copied to the merge request. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. +## Compare branches - +> - Repository filter search box [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. +> - Revision swapping [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. -The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is selected, the selected revisions for Source and Target is swapped. +To compare branches in a repository: - +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Compare revisions**. +1. Select the **Source** branch to search for your desired branch. Exact matches are + shown first. You can refine your search with operators: + - `^` matches the beginning of the branch name: `^feat` matches `feat/user-authentication`. + - `$` matches the end of the branch name: `widget$` matches `feat/search-box-widget`. + - `*` matches using a wildcard: `branch*cache*` matches `fix/branch-search-cache-expiration`. + - You can combine operators: `^chore/*migration$` matches `chore/user-data-migration`. +1. Select the **Target** repository and branch. Exact matches are shown first. +1. Select **Compare** to show the list of commits, and changed files. To reverse + the **Source** and **Target**, select **Swap revisions**. -## View branches with configured protections **(FREE SELF)** +## Delete merged branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. + -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../feature_flags.md) named `branch_rules`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +This feature allows merged branches to be deleted in bulk. Only branches that +have been merged into the project's default branch and +[are not protected](../../protected_branches.md) are deleted as part of +this operation. -Branches in your repository can be [protected](../../protected_branches.md) by limiting -who can push to a branch, require approval for those pushed changes, or merge those changes. -To help you track the protections for all branches, the **Branch rules overview** -page shows your branches with their configured rules. +It's particularly useful to clean up old branches that were not deleted +automatically when a merge request was merged. -To view the **Branch rules overview** list: +## Related topics -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Branch Rules** to view all branches with protections. -1. Select **Details** next to your desired branch to show information about its: - - [Branch protections](../../protected_branches.md). - - [Approval rules](../../merge_requests/approvals/rules.md). - - [Status checks](../../merge_requests/status_checks.md). +- [Protected branches](../../protected_branches.md) user documentation. +- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. +- [Protected Branches API](../../../../api/protected_branches.md). +- [Getting started with Git](../../../../topics/git/index.md) and GitLab. ## Troubleshooting diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index f9a5d4e3aa7..3fcc19db344 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -11,7 +11,7 @@ The file finder feature allows you to search for a file in a repository using th GitLab UI. To use it: 1. Go to your project's **Repository > Files**. -1. In the upper right corner, select **Find File**. +1. In the upper-right corner, select **Find File**. If you prefer to keep your fingers on the keyboard, use the [shortcut button](../../shortcuts.md), which you can invoke from anywhere diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 929751b7247..8c7c94613a7 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -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 upper right, select **{fork}** **Fork**: +1. On the project's homepage, in the upper-right corner, select **Fork** (**{fork}**):  1. Optional. Edit the **Project name**. 1. For **Project URL**, select the [namespace](../../namespace/index.md) @@ -137,3 +137,11 @@ You can unlink your fork from its upstream project in the [advanced settings](.. - 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/). + +## Troubleshooting + +### An error occurred while forking the project. Please try again + +This error can be due to a mismatch in shared runner settings between the forked project +and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#forks) +in the Runner documentation for more information. diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 78fcdec2a0b..fbf29bddd46 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -14,7 +14,7 @@ commit hash. To view it for a file: 1. Go to your project's **Repository > Files**. 1. Select the file you want to review. -1. In the upper right corner, select **Blame**. +1. In the upper-right corner, select **Blame**. When you select **Blame**, this information is displayed: diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 321b9a5eb53..a9228b8cabd 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -12,7 +12,7 @@ Git file History provides information about the commit history associated with a file. To use it: 1. Go to your project's **Repository > Files**. -1. In the upper right corner, select **History**. +1. In the upper-right corner, select **History**. When you select **History**, this information is displayed: diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 64f19d1a92c..a2dd2488961 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 upper right +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper-right corner of the user's profile, select **View public GPG keys** (**{key}**). ## Configure commit signing diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 5b4e1b14489..1c64a47985b 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -25,7 +25,7 @@ You can add files to a repository: - When you create a project. - After you create a project: - By using [the web editor](web_editor.md). - - [From the command line](../../../gitlab-basics/command-line-commands.md). + - From the command line. ## Commit changes to a repository @@ -235,9 +235,9 @@ The size can differ slightly from one instance to another due to compression, ho Administrators can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md). [GitLab sets the size limits for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). -## Repository contributor graph +## Repository contributor statistics -All code contributors are displayed under your project's **Repository > Contributors**. +All code contributors are displayed under your project's **Repository > Contributor statistics**. The graph shows the contributor with the most commits to the fewest. diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index f06dd747897..ea58c472f4a 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -26,8 +26,10 @@ When you push a change to the upstream repository, the push mirror receives it: - Within five minutes. - Within one minute, if you enabled **Only mirror protected branches**. -In the case of a diverged branch, an error displays in the **Mirroring repositories** -section. +When a branch is merged into the default branch and deleted in the source project, +it is deleted from the remote mirror on the next push. Branches with unmerged +changes are kept. If a branch diverges, the **Mirroring repositories** section +displays an error. ## Configure push mirroring diff --git a/doc/user/project/repository/tags/img/tag-display_v15_9.png b/doc/user/project/repository/tags/img/tag-display_v15_9.png Binary files differnew file mode 100644 index 00000000000..015df07d025 --- /dev/null +++ b/doc/user/project/repository/tags/img/tag-display_v15_9.png diff --git a/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png b/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png Binary files differnew file mode 100644 index 00000000000..247d2f368d5 --- /dev/null +++ b/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md new file mode 100644 index 00000000000..706b50a916d --- /dev/null +++ b/doc/user/project/repository/tags/index.md @@ -0,0 +1,108 @@ +--- +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 +--- + +# Tags **(FREE)** + +In Git, a tag marks an important point in a repository's history. +Git supports two types of tags: + +- **Lightweight tags** point to specific commits, and contain no other information. + Also known as soft tags. Create or remove them as needed. +- **Annotated tags** contain metadata, can be signed for verification purposes, + and can't be changed. + +The creation or deletion of a tag can be used as a trigger for automation, including: + +- Using a [webhook](../../integrations/webhook_events.md#tag-events) to automate actions + like Slack notifications. +- Signaling a [repository mirror](../mirror/index.md) to update. +- Running a CI/CD pipeline with [`if: $CI_COMMIT_TAG`](../../../../ci/jobs/job_control.md#common-if-clauses-for-rules). + +When you [create a release](../../releases/index.md), +GitLab also creates a tag to mark the release point. +Many projects combine an annotated release tag with a stable branch. Consider +setting deployment or release tags automatically. + +In the GitLab UI, each tag displays: + + + +- The tag name. (**{tag}**) +- Optional. If the tag is [protected](../../protected_tags.md), a **protected** badge. +- The commit SHA (**{commit}**), linked to the commit's contents. +- The commit's title and creation date. +- Optional. A link to the release (**{rocket}**). +- Optional. If a pipeline has been run, the current pipeline status. +- Download links to the source code and artifacts linked to the tag. +- A [**Create release**](../../releases/index.md#create-a-release) (**{pencil}**) link. +- A link to delete the tag. + +## View tags for a project + +To view all existing tags for a project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. + +## View tagged commits in the commits list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Commits**. +1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag. + This example shows a commit tagged `v1.26.0`: + +  + +To view the list of commits in this tag, select the tag name. + +## Create a tag + +Tags can be created from the command line, or the GitLab UI. + +### From the command line + +To create either a lightweight or annotated tag from the command line, and push it upstream: + +1. To create a lightweight tag, run the command `git tag TAG_NAME`, changing + `TAG_NAME` to your desired tag name. +1. To create an annotated tag, run one of the versions of `git tag` from the command line: + + ```shell + # In this short version, the annotated tag's name is "v1.0", + # and the message is "Version 1.0". + git tag -a v1.0 -m "Version 1.0" + + # Use this version to write a longer tag message + # for annotated tag "v1.0" in your text editor. + git tag -a v1.0 + ``` + +1. Push your tags upstream with `git push origin --tags`. + +### From the UI + +To create a tag from the GitLab UI: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. +1. Select **New tag**. +1. Provide a **Tag name**. +1. For **Create from**, select an existing branch name, tag, or commit SHA. +1. Optional. Add a **Message** to create an annotated tag, or leave blank to + create a lightweight tag. +1. Select **Create tag**. + +## Prevent tag deletion **(PREMIUM)** + +To prevent users from removing a tag with `git push`, create a [push rule](../push_rules.md). + +## Related topics + +- [Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) Git reference page. +- [Protected tags](../../protected_tags.md). +- [Tags API](../../../../api/tags.md). diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 80b0ada6f7b..ace7e119469 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -26,11 +26,32 @@ for any change you commit through the Web Editor. 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 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. 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. +1. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected, if you had chosen a **Target branch** other than the [default branch (such as `main`)](../../../user/project/repository/branches/default.md). 1. Select **Commit changes**. +### Create a file from a template + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. Next to the project name, select the plus icon (**{plus}**) to display a + dropdown list, then select **New file** from the list. +1. For **Filename**, provide one of the filenames that GitLab provides a template for: + - `.gitignore` + - `.gitlab-ci.yml` + - `LICENSE` + - `Dockerfile` +1. Select **Apply a template**, then select the template you want to apply. +1. Make your changes to the file. +1. Provide a **Commit message**. +1. Enter a **Target branch** to merge into. To create a new merge request with + your changes, enter a branch name that is not your repository's + [default branch](../../../user/project/repository/branches/default.md), +1. Select **Commit changes** to add the commit to your branch. + ## Edit a file To edit a text file in the Web Editor: @@ -87,6 +108,9 @@ To link to a single line, you can also: To upload a binary file in the Web Editor: +<!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> +<!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> + 1. On the top bar, select **Main menu > Projects** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **Upload file**. @@ -115,7 +139,7 @@ To create a [branch](branches/index.md) in the Web Editor: ## Create a tag -You can create [tags](../../../topics/git/tags.md) to mark milestones such as +You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index b04905e6b34..d385daa4fa1 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Plan -group: Certify +group: Product Planning 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 --- @@ -235,9 +235,9 @@ Before you import your file: 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 - upper right. - - For a project without any requirements, select **Import CSV** in the middle of the page. + - For a project with requirements, in the + upper-right corner, select the import icon (**{import}**). + - For a project without requirements, in the middle of the page, select **Import CSV**. 1. Select the file and select **Import requirements**. The file is processed in the background and a notification email is sent @@ -296,7 +296,7 @@ Prerequisite: To export requirements: 1. In a project, go to **Issues > Requirements**. -1. In the upper right, select the **Export as CSV** icon (**{export}**). +1. In the upper-right corner, select **Export as CSV** (**{export}**). A confirmation modal appears. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 22297149561..c4fcdc5733e 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -8,29 +8,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Moved to GitLab Free in 13.2. -Service Desk is a module that allows your team to connect -with any external party through email, without any external tools. -An ongoing conversation in the same place as where your software -is built ensures user feedback ends up where it's needed. +With Service Desk, your customers +can email you bug reports, feature requests, or general feedback. +Service Desk provides a unique email address, so they don't need their own GitLab accounts. -With Service Desk, you can provide efficient email support to your customers. They can -email you bug reports, feature requests, or general feedback. They all end up in your -GitLab project as new issues. In turn, your team can respond directly from the project. +Service Desk emails are created in your GitLab project as new issues. +Your team can respond directly from the project, while customers interact with the thread only +through email. -As Service Desk is built right into GitLab itself, the complexity and inefficiencies -of multiple tools and external integrations are eliminated. This significantly shortens -the cycle time from feedback to software update. - -For an overview, check the video demonstration on [GitLab Service Desk](https://about.gitlab.com/blog/2017/05/09/demo-service-desk/). - -## How it works - -GitLab Service Desk enables people to create issues in your -GitLab instance without needing their own user account. - -It provides a unique email address for end users to create issues in a project. -Follow-up notes can be sent either through the GitLab interface or by email. End -users only see the thread through email. +## Service Desk workflow For example, let's assume you develop a game for iOS or Android. The codebase is hosted in your GitLab instance, built and deployed @@ -43,23 +29,24 @@ Here's how Service Desk works for you: 1. Each email they send creates an issue in the appropriate project. 1. Your team members go to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues. -1. Your team communicates back and forth with the customer to understand the request. +1. Your team communicates with the customer to understand the request. 1. Your team starts working on implementing code to solve your customer's problem. -1. When your team finishes the implementation, whereupon the merge request is merged and the issue +1. When your team finishes the implementation, the merge request is merged and the issue is closed automatically. -1. The customer's requests are handled through email, without ever having access to your - GitLab instance. -1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with - your customer. + +Meanwhile: + +- The customer interacts with your team entirely through email, without needing access to your + GitLab instance. +- Your team saves time by not having to leave GitLab (or set up integrations) to follow up with + your customer. ## Configuring Service Desk Users with Maintainer and higher access in a project can configure Service Desk. Service Desk issues are [confidential](issues/confidential_issues.md), so they are -only visible to project members. In GitLab 11.7 we updated the generated email -address format. The older format is still supported, so existing aliases or -contacts still work. +only visible to project members. If you have [templates](description_templates.md) in your repository, you can optionally select one from the selector menu to append it to all Service Desk issues. @@ -93,7 +80,6 @@ displayed in the information note. ### Using customized email templates -> - [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. @@ -174,8 +160,6 @@ To use a custom description template with Service Desk: ### Using a custom email display name -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. - You can customize the email display name. Emails sent from Service Desk have this name in the `From` header. The default display name is `GitLab Support Bot`. @@ -207,15 +191,12 @@ you can customize the mailbox used by Service Desk. This allows you to have a separate email address for Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) in project settings. -The `address` must include the `+%{key}` placeholder in the 'user' -portion of the address, before the `@`. The placeholder is used to identify the project -where the issue should be created. +Prerequisites: -NOTE: -When configuring a custom mailbox, the `service_desk_email` and `incoming_email` -configurations must always use separate mailboxes. It's important, because -emails picked from `service_desk_email` mailbox are processed by a different -worker and it would not recognize `incoming_email` emails. +- The `address` must include the `+%{key}` placeholder in the `user` portion of the address, + before the `@`. The placeholder is used to identify the project where the issue should be created. +- The `service_desk_email` and `incoming_email` configurations must always use separate mailboxes + to make sure Service Desk emails are processed correctly. To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: @@ -504,15 +485,18 @@ You can read and write comments as you usually do in GitLab: #### Receiving files attached to comments as email attachments -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11733) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/386860) in GitLab 15.10. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. -On GitLab.com, this feature is not available. +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `service_desk_new_note_email_native_attachments`. +On GitLab.com, this feature is available. If a comment contains any attachments and their total size is less than or equal to 10 MB, these attachments are sent as part of the email. In other cases, the email contains links to the attachments. +In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. + #### 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.--> @@ -567,8 +551,3 @@ in both issues. They continue to receive any notifications in the old issue and Your emails might be ignored because they contain one of the [email headers that GitLab ignores](../../administration/incoming_email.md#rejected-headers). - -### Responses to a Service Desk issue do not generate emails - -Your issue might have been moved to a different project. -Moved Service Desk issues do not retain email participants. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 3715eef08e0..230795222a0 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -9,8 +9,8 @@ info: "To determine the technical writer assigned to the Stage/Group associated Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and then imported into a new GitLab instance. You can also: -- [Migrate groups](../../group/import/index.md) using the preferred method. -- [Migrate groups using file exports](../../group/settings/import_export.md). +- Migrate projects when you [migrate groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). +- [Migrate groups by using file exports](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated). GitLab maps user contributions correctly when an admin access token is used to perform the import. @@ -155,7 +155,8 @@ Items that are **not** exported include: - 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 +- [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700) (for example, pushing and creating tags) +- Security policies associated with your project ## Import a project and its data @@ -200,7 +201,7 @@ Deploy keys aren't imported. To use deploy keys, you must enable them in your im ### Import large projects **(FREE SELF)** -If you have a larger project, consider using a Rake task as described in the [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). +If you have a larger project, consider [using a Rake task](../../../administration/raketasks/project_import_export.md#import-large-projects). ## Automate group and project import **(PREMIUM)** diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index 00edeef5cfa..82412a1dcbf 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -48,41 +48,41 @@ reduce the repository size for another import attempt: 1. Create a temporary working directory from the export: - ```shell - EXPORT=<filename-without-extension> + ```shell + EXPORT=<filename-without-extension> - mkdir "$EXPORT" - tar -xf "$EXPORT".tar.gz --directory="$EXPORT"/ - cd "$EXPORT"/ - git clone project.bundle + mkdir "$EXPORT" + tar -xf "$EXPORT".tar.gz --directory="$EXPORT"/ + cd "$EXPORT"/ + git clone project.bundle - # Prevent interference with recreating an importable file later - mv project.bundle ../"$EXPORT"-original.bundle - mv ../"$EXPORT".tar.gz ../"$EXPORT"-original.tar.gz + # Prevent interference with recreating an importable file later + mv project.bundle ../"$EXPORT"-original.bundle + mv ../"$EXPORT".tar.gz ../"$EXPORT"-original.tar.gz - git switch --create smaller-tmp-main - ``` + git switch --create smaller-tmp-main + ``` 1. To reduce the repository size, work on this `smaller-tmp-main` branch: [identify and remove large files](../repository/reducing_the_repo_size_using_git.md) or [interactively rebase and fixup](../../../topics/git/git_rebase.md#interactive-rebase) to reduce the number of commits. - ```shell - # Reduce the .git/objects/pack/ file size - cd project - git reflog expire --expire=now --all - git gc --prune=now --aggressive - - # Prepare recreating an importable file - git bundle create ../project.bundle <default-branch-name> - cd .. - mv project/ ../"$EXPORT"-project - cd .. - - # Recreate an importable file - tar -czf "$EXPORT"-smaller.tar.gz --directory="$EXPORT"/ . - ``` + ```shell + # Reduce the .git/objects/pack/ file size + cd project + git reflog expire --expire=now --all + git gc --prune=now --aggressive + + # Prepare recreating an importable file + git bundle create ../project.bundle <default-branch-name> + cd .. + mv project/ ../"$EXPORT"-project + cd .. + + # Recreate an importable file + tar -czf "$EXPORT"-smaller.tar.gz --directory="$EXPORT"/ . + ``` 1. Import this new, smaller file into GitLab. 1. In a full clone of the original repository, @@ -265,12 +265,12 @@ Marked stuck import jobs as failed. JIDs: xyz | Problem | Possible solutions | | -------- | -------- | | [Slow JSON](https://gitlab.com/gitlab-org/gitlab/-/issues/25251) loading/dumping models from the database | [split the worker](https://gitlab.com/gitlab-org/gitlab/-/issues/25252) | -| | Batch export -| | Optimize SQL -| | Move away from `ActiveRecord` callbacks (difficult) -| High memory usage (see also some [analysis](https://gitlab.com/gitlab-org/gitlab/-/issues/18857) | DB Commit sweet spot that uses less memory | +| | Batch export | +| | Optimize SQL | +| | Move away from `ActiveRecord` callbacks (difficult) | +| High memory usage (see also some [analysis](https://gitlab.com/gitlab-org/gitlab/-/issues/18857)) | DB Commit sweet spot that uses less memory | | | [Netflix Fast JSON API](https://github.com/Netflix/fast_jsonapi) may help | -| | Batch reading/writing to disk and any SQL +| | Batch reading/writing to disk and any SQL | ### Temporary solutions diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index ed4eea56514..7250406144f 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments' type: reference, index, howto --- @@ -87,7 +87,7 @@ Use the toggles to enable or disable features in the project. | **Container Registry** | | Activates a [registry](../../packages/container_registry/index.md) for your Docker images. | | **Analytics** | ✓ | Enables [analytics](../../analytics/index.md). | | **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | -| **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | +| **Security and Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/index.md). | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | | **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index f9218a228ca..b4d48e52e46 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -48,9 +48,6 @@ You cannot use project access tokens to create other group, project, or personal Project access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. -NOTE: -Project access tokens are not FIPS compliant and creation and use are disabled when [FIPS mode](../../../development/fips_compliance.md) is enabled. - ## Create a project access token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens. @@ -121,12 +118,8 @@ The bot users for projects have [permissions](../../permissions.md#project-membe selected role and [scope](#scopes-for-a-project-access-token) of the project access token. - The name is set to the name of the token. -- The username is set to `project_{project_id}_bot` for the first access token. For example, `project_123_bot`. -- The email is set to `project{project_id}_bot@noreply.{Gitlab.config.gitlab.host}`. For example, `project123_bot@noreply.example.com`. -- For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`. For - example, `project_123_bot1`. -- For additional access tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@noreply.{Gitlab.config.gitlab.host}`. - For example, `project123_bot1@noreply.example.com`. +- The username is set to `project_{project_id}_bot_{random_string}`. For example, `project_123_bot_4ffca233d8298ea1`. +- The email is set to `project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}`. For example, `project_123_bot_4ffca233d8298ea1@noreply.example.com`. API calls made with a project access token are associated with the corresponding bot user. @@ -143,3 +136,7 @@ When the project access token is [revoked](#revoke-a-project-access-token): - All records are moved to a system-wide user with the username [Ghost User](../../profile/account/delete_account.md#associated-records). See also [Bot users for groups](../../group/settings/group_access_tokens.md#bot-users-for-groups). + +## Token availability + +Project access tokens are only available in paid subscriptions, and not available in trial subscriptions. For more information, see the ["What is included" section of the GitLab Trial FAQ](https://about.gitlab.com/free-trial/#what-is-included-in-my-free-trial-what-is-excluded). diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 5e9f648daba..e2a74f02008 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -22,7 +22,7 @@ and from merge requests: ### When viewing a file or the repository file list - 1. In the upper right corner of the page, select **Open in Web IDE** if it is visible. + 1. In the upper-right corner of the page, select **Open in Web IDE** if it is visible. 1. If **Open in Web IDE** is not visible: 1. Select the (**{chevron-lg-down}**) next to **Edit** or **Gitpod**, depending on your configuration. 1. Select **Open in Web IDE** from the list to display it as the editing option. @@ -31,7 +31,7 @@ and from merge requests: ### When viewing a merge request 1. Go to your merge request. - 1. In the upper right corner, select **Code > Open in Web IDE**. + 1. In the upper-right corner, select **Code > Open in Web IDE**. ## File finder diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md index fe110baf578..635b5e12575 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: -- In the upper right of the page, select **Open in Web IDE**. +- In the upper-right corner of the page, select **Open in Web IDE**. If **Open in Web IDE** is not visible: @@ -53,7 +53,7 @@ If **Open in Web IDE** is not visible: To open the Web IDE Beta from a merge request: 1. Go to your merge request. -1. In the upper right corner, select **Code > Open in Web IDE**. +1. In the upper-right corner, select **Code > Open in Web IDE**. ## Open a file in the Web IDE Beta @@ -64,6 +64,26 @@ To open any file by its name:  +## Switch branches + +The Web IDE Beta uses the currently selected branch by default. +To switch branches in the Web IDE Beta: + +1. On the status bar, in the lower-left corner, select the current branch name. +1. In the search box, start typing the branch name. +1. From the dropdown list, select the branch. + +## Create a branch + +To create a branch from the current branch in the Web IDE Beta: + +1. On the status bar, in the lower-left corner, select the current branch name. +1. From the dropdown list, select **Create new branch...**. +1. Enter the branch name. +1. Press <kbd>Enter</kbd>. + +If you don't have write access to the repository, **Create new branch...** is not visible. + ## Search across files You can use VS Code to quickly search all files in the opened folder. @@ -84,6 +104,15 @@ Your `CHANGES`, `STAGED CHANGES`, and `MERGE CHANGES` are displayed. For details, see the [VS Code documentation](https://code.visualstudio.com/docs/sourcecontrol/overview#_commit). +## Open the command palette + +In the Web IDE Beta, you can access many commands through the command palette. +To open the command palette and run a command in the Web IDE Beta: + +1. Press <kbd>F1</kbd> or <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd>. +1. In the search box, start typing the command name. +1. From the dropdown list, select the command. + ## Stop using the Web IDE Beta If you do not want to use the Web IDE Beta, you can change your personal preferences. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 53aaa41319b..1513ea18ed2 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -38,8 +38,8 @@ To access a group wiki: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9. Users with the Owner role in a group can -[import and export group wikis](../../group/settings/import_export.md) when importing -or exporting a group. +[import or export a group wiki](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated) when they +import or export a group. Content created in a group wiki is not deleted when an account is downgraded or a GitLab trial ends. The group wiki data is exported whenever the group owner of @@ -48,8 +48,8 @@ the wiki is exported. To access the group wiki data from the export file if the feature is no longer available, you have to: -1. Extract the [export file tarball](../../group/settings/import_export.md) with - this command, replacing `FILENAME` with your file's name: +1. Extract the [export file tarball](../../group/import/index.md#migrate-groups-by-uploading-an-export-file-deprecated) + with this command, replacing `FILENAME` with your file's name: `tar -xvzf FILENAME.tar.gz` 1. Browse to the `repositories` directory. This directory contains a [Git bundle](https://git-scm.com/docs/git-bundle) with the extension `.wiki.bundle`. diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index a0e6a78dfe2..24ca86fc93b 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -1,6 +1,6 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- @@ -11,12 +11,9 @@ code are saved in projects, and most features are in the scope of projects. ## View projects -To view projects, on the top bar, select **Main menu > Projects > View all projects**. +To view all your projects, on the top bar, select **Main menu > Projects > View all projects**. -NOTE: -The **Explore projects** tab is visible to unauthenticated users unless the -[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted. Then the tab is visible only to authenticated users. +To browse all public projects, select **Main menu > Explore > Projects**. ### Who can view the Projects page @@ -63,7 +60,7 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: 1. On the top bar, select **Main menu > Projects** and find your project. -1. In the upper right corner of the page, select **Star**. +1. In the upper-right corner of the page, select **Star**. ## View starred projects @@ -241,15 +238,15 @@ Configure Git to either: - Embed credentials in the request URL: - ```shell - git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" - ``` + ```shell + git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + ``` - Use SSH instead of HTTPS: - ```shell - git config --global url."git@gitlab.example.com:".insteadOf "https://gitlab.example.com/" - ``` + ```shell + git config --global url."git@gitlab.example.com:".insteadOf "https://gitlab.example.com/" + ``` ### Disable Go module fetching for private projects @@ -263,8 +260,8 @@ the [environment variables](../../development/go_guide/dependencies.md#proxies): To disable fetching: 1. Disable `GOPRIVATE`: - - To disable queries for one project, disable `GOPRIVATE=gitlab.example.com/my/private/project`. - - To disable queries for all projects on GitLab.com, disable `GOPRIVATE=gitlab.example.com`. + - To disable queries for one project, disable `GOPRIVATE=gitlab.example.com/my/private/project`. + - To disable queries for all projects on GitLab.com, disable `GOPRIVATE=gitlab.example.com`. 1. Disable proxy queries in `GONOPROXY`. 1. Disable checksum queries in `GONOSUMDB`. @@ -291,8 +288,8 @@ To access the Geo secondary server with SSH: git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" ``` - - For `gitlab.example.com`, use the primary site domain name. - - For `gitlab-secondary.example.com`, use the secondary site domain name. + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. 1. Ensure the client is set up for SSH access to GitLab repositories. You can test this on the primary, and GitLab replicates the public key to the secondary. |
