diff options
Diffstat (limited to 'doc/user/project/settings')
| -rw-r--r-- | doc/user/project/settings/import_export.md | 5 | ||||
| -rw-r--r-- | doc/user/project/settings/index.md | 37 | ||||
| -rw-r--r-- | doc/user/project/settings/project_access_tokens.md | 220 |
3 files changed, 147 insertions, 115 deletions
diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 74879dae2d6..da0336d01ff 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -44,8 +44,9 @@ Note the following: a maintainer or administrator role in the group where the exported project lives. - Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. - Additionally, the user must be an existing member of the namespace, or the user can be added as a -member of the project for contributions to be mapped. + The public email is not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) + for mapping to work correctly. Additionally, the user must be an existing member of the namespace, + or the user can be added as a member of the project for contributions to be mapped. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues are owned by the importer. - For project migration imports performed over GitLab.com Groups, preserving author information is diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 5c4d4649240..c6cbd45a6ab 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -7,18 +7,18 @@ type: reference, index, howto # Project settings **(FREE)** -NOTE: -Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) -to access project settings. - The **Settings** page in GitLab provides a centralized home for your [project](../index.md) configuration options. To access it, go to your project's homepage -and, in the left navigation menu, clicking **Settings**. To reduce complexity, settings are -grouped by topic into sections. To display all settings in a section, click **Expand**. +and, in the left navigation menu, select **Settings**. To reduce complexity, settings are +grouped by topic into sections. To display all settings in a section, select **Expand**. In GitLab versions [13.10 and later](https://gitlab.com/groups/gitlab-org/-/epics/4842), GitLab displays a search box to help you find the settings you want to view. +NOTE: +Only users who have the [Maintainer role](../../permissions.md) for the project and administrators can +access project settings. + ## General settings Under a project's general settings, you can find everything concerning the @@ -315,7 +315,7 @@ Set up your project's merge request settings: - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). -- Configure [merge commit message template](../merge_requests/commit_templates.md). +- Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. ### Service Desk @@ -449,17 +449,22 @@ To delete a project: This action deletes a project including all associated resources (issues, merge requests, and so on). -In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) and later, on Premium or higher tiers, -group Owners can [configure](../../group/index.md#enable-delayed-project-removal) projects in a group -to be deleted after a delayed period. -When enabled, actual deletion happens after number of days -specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). - WARNING: -The default behavior of [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to -[Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +The default deletion behavior for projects was changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) +in GitLab 12.6, and then to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. + +#### Delayed project deletion **(PREMIUM)** + +Projects in a group (not a personal namespace) can be deleted after a delay period. Multiple settings can affect whether +delayed project deletion is enabled for a particular project: + +- Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion). + You can enable delayed project deletion as the default setting for new groups, and configure the number of days for the + delay. For GitLab.com, see the [GitLab.com settings](../../gitlab_com/index.md#delayed-project-deletion). +- Group [settings](../../group/index.md#enable-delayed-project-deletion) to enabled delayed project deletion for all + projects in the group. -#### Delete a project immediately **(PREMIUM)** +##### Delete a project immediately > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 85e412e7a41..44ece6cb172 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -12,111 +12,91 @@ type: reference, howto > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added. -Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md) -except they are attached to a project rather than a user. They can be used to: +You can use a project access token to authenticate: -- Authenticate with the [GitLab API](../../../api/index.md#personalproject-access-tokens). -- Authenticate with Git using HTTP Basic Authentication. If you are asked for a username when - authenticating, you can use any non-empty value because only the token is needed. +- With the [GitLab API](../../../api/index.md#personalproject-access-tokens). +- With Git, when using HTTP Basic Authentication. -Project access tokens: +After you configure a project access token, you don't need a password when you authenticate. +Instead, you can enter any non-blank value. -- Expire on the date you define, at midnight UTC. -- Are supported for self-managed instances on Free tier and above. Free self-managed instances - should: - - Review their security and compliance policies with regards to +Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md), +except they are associated with a project rather than a user. + +You can use project access tokens: + +- On GitLab SaaS if you have the Premium license tier or higher. Personal access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). +- On self-managed instances of GitLab, with any license tier. If you have the Free tier: + - Review your security and compliance policies around [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. -- Are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/).) -For examples of how you can use a project access token to authenticate with the API, see the -[relevant section from our API Docs](../../../api/index.md#personalproject-access-tokens). +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: -For GitLab.com and self-managed instances, the default prefix is `glpat-`. +## Create a project access token -## Creating a project access token +To create a project access token: -1. Log in to GitLab. -1. Navigate to the project you would like to create an access token for. -1. In the **Settings** menu choose **Access Tokens**. -1. Choose a name and optional expiry date for the token. -1. Choose a role for the token. -1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token). -1. Click the **Create project access token** button. -1. Save the project access token somewhere safe. Once you leave or refresh - the page, you don't have access to it again. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Enter a name. +1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. +1. Select a role for the token. +1. Select the [desired scopes](#scopes-for-a-project-access-token). +1. Select **Create project access token**. -## Project bot users +A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you can't view it again. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. -> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. +## Revoke a project access token -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. +To revoke a project access token: -For each project access token created, a bot user is created and added to the project with -the [specified level permissions](../../permissions.md#project-members-permissions). - -For the bot: - -- The name is set to the name of the token. -- The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. -- The email is set to `project{project_id}_bot@example.com`, for example `project123_bot@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 acess tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`, for example `project123_bot1@example.com` - -API calls made with a project access token are associated with the corresponding bot user. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Next to the project access token to revoke, select **Revoke**. -These bot users are included in a project's **Project information > Members** list but cannot be modified. Also, a bot -user cannot be added to any other project. +## Scopes for a project access token -When the project access token is [revoked](#revoking-a-project-access-token), the bot user is deleted -and all records are moved to a system-wide user with the username "Ghost User". For more -information, see [Associated Records](../../profile/account/delete_account.md#associated-records). +The scope determines the actions you can perform when you authenticate with a project access token. -## Revoking a project access token - -At any time, you can revoke any project access token by clicking the -respective **Revoke** button in **Settings > Access Tokens**. - -## Limiting scopes of a project access token - -Project access tokens can be created with one or more scopes that allow various -actions that a given token can perform. The available scopes are depicted in -the following table. - -| Scope | Description | -| ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | -| `read_repository` | Allows read-only access (pull) to the repository. | -| `write_repository` | Allows read-write access (pull, push) to the repository. | +| Scope | Description | +|:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_registry` | Allows read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). | +| `read_repository` | Allows read access (pull) to the repository. | +| `write_repository` | Allows read and write access (pull and push) to the repository. | ## Enable or disable project access token creation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287707) in GitLab 13.11. -You may enable or disable project access token creation for all projects in a group in **Group > Settings > General > Permissions, LFS, 2FA > Allow project access token creation**. -Even when creation is disabled, you can still use and revoke existing project access tokens. -This setting is available only on top-level groups. +To enable or disable project access token creation for all projects in a top-level group: -## Group access token workaround **(FREE SELF)** +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions, LFS, 2FA**. +1. Under **Permissions**, turn on or off **Allow project access token creation**. -NOTE: -This section describes a workaround and is subject to change. +Even when creation is disabled, you can still use and revoke existing project access tokens. + +## Group access tokens **(FREE SELF)** -Group access tokens let you use a single token to: +With group access tokens, you can use a single token to: -- Perform actions at the group level. +- Perform actions for groups. - Manage the projects within the group. -- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate - with Git over HTTPS. +- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. + +NOTE: +You cannot use the UI to create a group access token. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) +to add this functionality. This section describes a workaround. -We don't support group access tokens in the GitLab UI, though GitLab self-managed -administrators can create them using the [Rails console](../../../administration/operations/rails_console.md). +If you are an administrator of a self-managed GitLab instance, you can create a group access token in the +[Rails console](../../../administration/operations/rails_console.md). <div class="video-fallback"> For a demo of the group access token workaround, see <a href="https://www.youtube.com/watch?v=W2fg1P1xmU0">Demo: Group Level Access Tokens</a>. @@ -127,37 +107,83 @@ administrators can create them using the [Rails console](../../../administration ### Create a group access token -To create a group access token, run the following in a Rails console: +To create a group access token: -```ruby -admin = User.find(1) # group admin -group = Group.find(109) # the group you want to create a token for -bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute # create the group bot user -# for further group access tokens, the username should be group_#{group.id}_bot#{bot_count}, e.g. group_109_bot2, and their email should be group_109_bot2@example.com -bot.confirm # confirm the bot -group.add_user(bot, :maintainer) # add the bot to the group at the desired access level -token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') # give it a PAT -gtoken = token.token # get the token value -``` +1. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md): + + ```ruby + # Set the GitLab administration user to use. If user ID 1 is not available or is not an adinistrator, use 'admin = User.admins.first' instead to select an admininistrator. + admin = User.find(1) + + # Set the group group you want to create a token for. For example, group with ID 109. + group = Group.find(109) + + # Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com. + bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute + + # Confirm the group bot. + bot.confirm + + # Add the bot to the group with the required role. + group.add_user(bot, :maintainer) -Test if the generated group access token works: + # Give the bot a personal access token. + token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') -1. Pass the group access token in the `PRIVATE-TOKEN` header to GitLab REST APIs. For example: + # Get the token value. + gtoken = token.token + ``` - - [Create an epic](../../../api/epics.md#new-epic) on the group. - - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) - in one of the group's projects. - - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. +1. Test if the generated group access token works: -1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) - using HTTPS. + 1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example: + + - [Create an epic](../../../api/epics.md#new-epic) in the group. + - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects. + - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. + + 1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) + using HTTPS. ### Revoke a group access token -To revoke a group access token, run the following in a Rails console: +To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md): ```ruby bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke token = bot.personal_access_tokens.last # the token you want to revoke token.revoke! ``` + +## Project bot users + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. +> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. + +Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). +Each time you create a project access token, a bot user is created and added to the project. +These bot users do not count as licensed seats. + +The bot users have [permissions](../../permissions.md#project-members-permissions) that correspond with the +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@example.com`. For example, `project123_bot@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}@example.com`. + For example, `project123_bot1@example.com`. + +API calls made with a project access token are associated with the corresponding bot user. + +Bot users: + +- Are included in a project's member list but cannot be modified. +- Cannot be added to any other project. + +When the project access token is [revoked](#revoke-a-project-access-token): + +- The bot user is deleted. +- All records are moved to a system-wide user with the username `Ghost User`. For more information, see + [associated records](../../profile/account/delete_account.md#associated-records). |