diff options
Diffstat (limited to 'doc/user/project/settings')
| -rw-r--r-- | doc/user/project/settings/import_export.md | 21 | ||||
| -rw-r--r-- | doc/user/project/settings/index.md | 228 | ||||
| -rw-r--r-- | doc/user/project/settings/project_access_tokens.md | 13 |
3 files changed, 67 insertions, 195 deletions
diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 375e4a62b86..a47873f5179 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Migrating projects using file exports **(FREE)** @@ -58,7 +58,7 @@ moved to your configured `uploads_directory`. Every 24 hours, a worker deletes t ### Items that are exported The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) -file lists the items exported and imported when migrating projects using file exports. View this file in the branch +file for projects lists many of the items exported and imported when migrating projects using file exports. View this file in the branch for your version of GitLab to see the list of items relevant to you. For example, [`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). @@ -72,8 +72,10 @@ Items that are exported include: - Project configuration, excluding integrations - Issues - Issue comments + - Issue iteration ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96184) in 15.4) - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource iteration events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Merge requests - Merge request diffs - Merge request comments @@ -135,16 +137,15 @@ To import a project: To get the status of an import, you can query it through the [Project import/export API](../../../api/project_import_export.md#import-status). As described in the API documentation, the query may return an import error or exceptions. -### Items that are imported +### Changes to imported items -The following items are imported but changed slightly: +Exported items are imported with the following changes: -- Project members with the Owner role are imported as Maintainers. -- If an imported project contains merge requests originating from forks, then new branches - associated with such merge requests are created in a project during the import/export. Thus, the - number of branches in the exported project might be bigger than in the original project. -- If use of the `Internal` visibility level - [is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), +- Project members with the Owner role are imported with the Maintainer role. +- If an imported project contains merge requests originating from forks, new branches associated with these merge + requests are created in the project. Therefore, the number of branches in the new project can be more than in the + source project. +- If the `Internal` visibility level [is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), all imported projects are given `Private` visibility. Deploy keys aren't imported. To use deploy keys, you must enable them in your imported project and update protected branches. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 5c2118e02cf..4407986f354 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: reference, index, howto --- @@ -40,187 +40,24 @@ To assign topics to a project: 1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. -## Compliance frameworks **(PREMIUM)** +If you're an instance administrator, you can administer all project topics from the +[Admin Area's Topics page](../../admin_area/index.md#administering-topics). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. +## Add a compliance framework to a project **(PREMIUM)** -You can create a compliance framework label to identify that your project has certain compliance -requirements or needs additional oversight. The label can optionally apply -[compliance pipeline configuration](#compliance-pipeline-configuration). +[Compliance frameworks](../../group/manage.md#compliance-frameworks) can be assigned to projects within group that has a +compliance framework using either: -Group owners can create, edit, and delete compliance frameworks: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings** > **General**. -1. Expand the **Compliance frameworks** section. - -Compliance frameworks created can then be assigned to projects within the group using: - -- The GitLab UI, using the project settings page. +- The GitLab UI: + 1. On the top bar, select **Main menu > Projects > View all projects** and find your project. + 1. On the left sidebar, select **Settings** > **General**. + 1. Expand the **Compliance frameworks** section. + 1. Select a compliance framework. + 1. Select **Save changes**. - In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) and later, using the - [GraphQL API](../../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework). - -NOTE: -Creating compliance frameworks on subgroups with GraphQL causes the framework to be -created on the root ancestor if the user has the correct permissions. The GitLab UI presents a -read-only view to discourage this behavior. - -### Compliance pipeline configuration **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../../administration/feature_flags.md). -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. - -Compliance framework pipelines allow group owners to define -a compliance pipeline in a separate repository that gets -executed in place of the local project's `.gitlab-ci.yml` file. As part of this pipeline, an -`include` statement can reference the local project's `.gitlab-ci.yml` file. This way, the compliance -pipeline jobs can run alongside the project-specific jobs any time the pipeline runs. -Jobs and variables defined in the compliance -pipeline can't be changed by variables in the local project's `.gitlab-ci.yml` file. - -When you set up the compliance framework, use the **Compliance pipeline configuration** box to link -the compliance framework to specific CI/CD configuration. Use the -`path/file.y[a]ml@group-name/project-name` format. For example: - -- `.compliance-ci.yml@gitlab-org/gitlab`. -- `.compliance-ci.yaml@gitlab-org/gitlab`. - -This configuration is inherited by projects where the compliance framework label is applied. The -result forces projects with the label to run the compliance CI/CD configuration in addition to -the project's own CI/CD configuration. When a project with a compliance framework label executes a -pipeline, it evaluates configuration in the following order: - -1. Compliance pipeline configuration. -1. Project-specific pipeline configuration. - -The user running the pipeline in the project must at least have the Reporter role on the compliance -project. - -Example `.compliance-gitlab-ci.yml`: - -```yaml -# Allows compliance team to control the ordering and interweaving of stages/jobs. -# Stages without jobs defined will remain hidden. -stages: - - pre-compliance - - build - - test - - pre-deploy-compliance - - deploy - - post-compliance - -variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml - FOO: sast - -sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml - variables: - FOO: sast - image: ruby:2.6 - stage: pre-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -sanity check: - image: ruby:2.6 - stage: pre-deploy-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -audit trail: - image: ruby:2.6 - stage: post-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) - project: '$CI_PROJECT_PATH' - file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch -``` - -When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/scan-execution-policies.md), -as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). -For details on the similarities and differences between these features, see -[Enforce scan execution](../../application_security/index.md#enforce-scan-execution). - -### Ensure compliance jobs are always run - -Compliance pipelines use GitLab CI/CD to give you an incredible amount of flexibility -for defining any sort of compliance jobs you like. Depending on your goals, these jobs -can be configured to be: - -- Modified by users. -- Non-modifiable. - -At a high-level, if a value in a compliance job: - -- Is set, it cannot be changed or overridden by project-level configurations. -- Is not set, a project-level configuration may set. - -Either might be wanted or not depending on your use case. - -There are a few best practices for ensuring that these jobs are always run exactly -as you define them and that downstream, project-level pipeline configurations -cannot change them: - -- Add a `rules:when:always` block to each of your compliance jobs. This ensures they are - non-modifiable and are always run. -- Explicitly set any variables the job references. This: - - Ensures that project-level pipeline configurations do not set them and alter their - behavior. - - Includes any jobs that drive the logic of your job. -- Explicitly set the container image file to run the job in. This ensures that your script - steps execute in the correct environment. -- Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/index.md#job-keywords). - This ensures that your job uses the settings you intend and that they are not overridden by - project-level pipelines. - -### Avoid parent and child pipelines in GitLab 14.7 and earlier - -NOTE: -This advice does not apply to GitLab 14.8 and later because [a fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78878) added -compatibility for combining compliance pipelines, and parent and child pipelines. - -Compliance pipelines start on the run of _every_ pipeline in a relevant project. This means that if a pipeline in the relevant project -triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. - -Therefore, in projects with compliance frameworks, we recommend replacing -[parent-child pipelines](../../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) with the following: - -- Direct [`include`](../../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. -- Child pipelines placed in another project that are run using the [trigger API](../../../ci/triggers/index.md) rather than the parent-child - pipeline feature. - -This alternative ensures the compliance pipeline does not re-start the parent pipeline. + [GraphQL API](../../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework). If you create + compliance frameworks on subgroups with GraphQL, the framework is created on the root ancestor if the user has the + correct permissions. The GitLab UI presents a read-only view to discourage this behavior. ## Configure project visibility, features, and permissions @@ -255,7 +92,8 @@ Use the toggles to enable or disable features in the project. | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | | **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | | **Operations** | ✓ | Control access to Operations-related features, including [Operations Dashboard](../../../operations/index.md), [Environments and Deployments](../../../ci/environments/index.md), [Feature Flags](../../../operations/feature_flags.md). | -| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | +| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | +| **Releases** | ✓ | Control access to [Releases](../releases/index.md). | When you disable a feature, the following additional features are also disabled: @@ -372,7 +210,7 @@ where GitLab is installed. Prerequisites: -You must be a project maintainer or administrator to rename a repository. +You must be a project maintainer, owner, or administrator to rename a repository. NOTE: When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see @@ -538,3 +376,33 @@ Configure Error Tracking to discover and view [Sentry errors within GitLab](../. [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). + +## Troubleshooting + +When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks. + +### Remove a fork relationship through console + +If removing the fork through the UI or API is not working, you can attempt the fork relationship removal in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +```ruby +p = Project.find_by_full_path('<project_path>') +u = User.find_by_username('<username>') +Projects::UnlinkForkService.new(p, u).execute +``` + +### Transfer a project through console + +If transferring a project through the UI or API is not working, you can attempt the transfer in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +```ruby +p = Project.find_by_full_path('<project_path>') + +# To set the owner of the project +current_user = p.creator + +# Namespace where you want this to be moved +namespace = Namespace.find_by_full_path("<new_namespace>") + +Projects::TransferService.new(p, current_user).execute(namespace) +``` diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index c9c5efce9b1..f27672a1b07 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +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, howto --- @@ -48,6 +48,9 @@ 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. @@ -82,10 +85,10 @@ The scope determines the actions you can perform when you authenticate with a pr |:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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. | +| `read_registry` | Grants read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | Grants write access (push) to the [Container Registry](../../packages/container_registry/index.md). | +| `read_repository` | Grants read access (pull) to the repository. | +| `write_repository` | Grants read and write access (pull and push) to the repository. | ## Enable or disable project access token creation |