1--- 2stage: Manage 3group: Workspace 4info: "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" 5type: reference, index, howto 6--- 7 8# Project settings **(FREE)** 9 10The **Settings** page in GitLab provides a centralized home for your 11[project](../index.md) configuration options. To access it, go to your project's homepage 12and, in the left navigation menu, select **Settings**. To reduce complexity, settings are 13grouped by topic into sections. To display all settings in a section, select **Expand**. 14 15In GitLab versions [13.10 and later](https://gitlab.com/groups/gitlab-org/-/epics/4842), 16GitLab displays a search box to help you find the settings you want to view. 17 18NOTE: 19Only users who have the [Maintainer role](../../permissions.md) for the project and administrators can 20access project settings. 21 22## General settings 23 24Under a project's general settings, you can find everything concerning the 25functionality of a project. 26 27### General project settings 28 29Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics: 30 31The project description also partially supports [standard Markdown](../../markdown.md#features-extended-from-standard-markdown). 32You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and 33[line-breaks](../../markdown.md#line-breaks) to add more context to the project description. 34 35#### Topics 36 37Use topics to categorize projects and find similar new projects. 38 39To assign topics to a project: 40 411. On the top bar, select **Menu > Projects** and find your project. 421. On the left sidebar, select **Settings** > **General**. 431. Under **Topics**, enter the project topics. Existing popular topics are suggested as you type. 441. Select **Save changes**. 45 46For GitLab.com, explore popular topics on the [Explore topics page](../working_with_projects.md#explore-topics). 47When you select a topic, you can see relevant projects. 48 49NOTE: 50The assigned topics are visible only to everyone with access to the project, 51but everyone can see which topics exist at all on the GitLab instance. 52Do not include sensitive information in the name of a topic. 53 54If you're an instance administrator, see also 55[Administering topics](../../admin_area/index.md#administering-topics). 56 57#### Compliance frameworks **(PREMIUM)** 58 59> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. 60> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. 61 62You can create a compliance framework label to identify that your project has certain compliance 63requirements or needs additional oversight. The label can optionally apply 64[compliance pipeline configuration](#compliance-pipeline-configuration). 65 66Group owners can create, edit, and delete compliance frameworks: 67 681. On the top bar, select **Menu > Groups** and find your group. 691. On the left sidebar, select **Settings** > **General**. 701. Expand the **Compliance frameworks** section. 71 72Compliance frameworks created can then be assigned to projects within the group using: 73 74- The GitLab UI, using the project settings page. 75- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) and later, using the 76 [GraphQL API](../../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework). 77 78NOTE: 79Creating compliance frameworks on subgroups with GraphQL causes the framework to be 80created on the root ancestor if the user has the correct permissions. The GitLab UI presents a 81read-only view to discourage this behavior. 82 83#### Compliance pipeline configuration **(ULTIMATE)** 84 85> - [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). 86> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. 87> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. 88 89Group owners can use compliance pipeline configuration to add additional pipeline configuration to 90projects to define compliance requirements such as scans or tests. 91 92[Compliance frameworks](#compliance-frameworks) allow group owners to specify the location of 93compliance pipeline configuration stored and managed in dedicated projects, separate from regular 94projects. 95 96When you set up the compliance framework, use the **Compliance pipeline configuration** box to link 97the compliance framework to specific CI/CD configuration. Use the 98`path/file.y[a]ml@group-name/project-name` format. For example: 99 100- `.compliance-ci.yml@gitlab-org/gitlab`. 101- `.compliance-ci.yaml@gitlab-org/gitlab`. 102 103This configuration is inherited by projects where the compliance framework label is applied. The 104result forces projects with the label to run the compliance CI/CD configuration in addition to 105the project's own CI/CD configuration. When a project with a compliance framework label executes a 106pipeline, it evaluates configuration in the following order: 107 1081. Compliance pipeline configuration. 1091. Project-specific pipeline configuration. 110 111The user running the pipeline in the project must at least have the Reporter role on the compliance 112project. 113 114Example `.compliance-gitlab-ci.yml`: 115 116```yaml 117# Allows compliance team to control the ordering and interweaving of stages/jobs. 118# Stages without jobs defined will remain hidden. 119stages: 120 - pre-compliance 121 - build 122 - test 123 - pre-deploy-compliance 124 - deploy 125 - post-compliance 126 127variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml 128 FOO: sast 129 130sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml 131 variables: 132 FOO: sast 133 image: ruby:2.6 134 stage: pre-compliance 135 rules: 136 - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" 137 when: never 138 - when: always # or when: on_success 139 allow_failure: false 140 before_script: 141 - "# No before scripts." 142 script: 143 - echo "running $FOO" 144 after_script: 145 - "# No after scripts." 146 147sanity check: 148 image: ruby:2.6 149 stage: pre-deploy-compliance 150 rules: 151 - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" 152 when: never 153 - when: always # or when: on_success 154 allow_failure: false 155 before_script: 156 - "# No before scripts." 157 script: 158 - echo "running $FOO" 159 after_script: 160 - "# No after scripts." 161 162audit trail: 163 image: ruby:2.6 164 stage: post-compliance 165 rules: 166 - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" 167 when: never 168 - when: always # or when: on_success 169 allow_failure: false 170 before_script: 171 - "# No before scripts." 172 script: 173 - echo "running $FOO" 174 after_script: 175 - "# No after scripts." 176 177include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) 178 project: '$CI_PROJECT_PATH' 179 file: '$CI_CONFIG_PATH' 180 ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch 181 rules: 182 - exists: '$CI_CONFIG_PATH' 183``` 184 185##### Ensure compliance jobs are always run 186 187Compliance pipelines use GitLab CI/CD to give you an incredible amount of flexibility 188for defining any sort of compliance jobs you like. Depending on your goals, these jobs 189can be configured to be: 190 191- Modified by users. 192- Non-modifiable. 193 194At a high-level, if a value in a compliance job: 195 196- Is set, it cannot be changed or overridden by project-level configurations. 197- Is not set, a project-level configuration may set. 198 199Either might be wanted or not depending on your use case. 200 201There are a few best practices for ensuring that these jobs are always run exactly 202as you define them and that downstream, project-level pipeline configurations 203cannot change them: 204 205- Add a `rules:when:always` block to each of your compliance jobs. This ensures they are 206 non-modifiable and are always run. 207- Explicitly set any variables the job references. This: 208 - Ensures that project-level pipeline configurations do not set them and alter their 209 behavior. 210 - Includes any jobs that drive the logic of your job. 211- Explicitly set the container image file to run the job in. This ensures that your script 212 steps execute in the correct environment. 213- Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/index.md#job-keywords). 214 This ensures that your job uses the settings you intend and that they are not overridden by 215 project-level pipelines. 216 217##### Avoid parent and child pipelines 218 219Compliance pipelines start on the run of _every_ pipeline in a relevant project. This means that if a pipeline in the relevant project 220triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. 221 222Therefore, in projects with compliance frameworks, we recommend replacing 223[parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md) with the following: 224 225- Direct [`include`](../../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. 226- Child pipelines placed in another project that are run using the [trigger API](../../../ci/triggers/) rather than the parent-child 227 pipeline feature. 228 229This alternative ensures the compliance pipeline does not re-start the parent pipeline. 230 231### Sharing and permissions 232 233For your repository, you can set up features such as public access, repository features, 234documentation, access permissions, and more. To do so from your project, 235go to **Settings** > **General**, and expand the **Visibility, project features, permissions** 236section. 237 238You can now change the [Project visibility](../../../public_access/public_access.md). 239If you set **Project Visibility** to public, you can limit access to some features 240to **Only Project Members**. In addition, you can select the option to 241[Allow users to request access](../members/index.md#request-access-to-a-project). 242 243Use the switches to enable or disable the following features: 244 245| Option | More access limit options | Description | 246|:---------------------------------|:--------------------------|:--------------| 247| **Issues** | ✓ | Activates the GitLab issues tracker. | 248| **Repository** | ✓ | Enables [repository](../repository/) functionality | 249| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | 250| **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | 251| **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | 252| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | 253| **CI/CD** | ✓ | Enables [CI/CD](../../../ci/index.md) functionality. | 254| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images. | 255| **Analytics** | ✓ | Enables [analytics](../../analytics/). | 256| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md). | 257| **Security & Compliance** | ✓ | Control access to [security features](../../application_security/index.md). | 258| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/). | 259| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | 260| **Pages** | ✓ | Allows you to [publish static websites](../pages/). | 261| **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). | 262| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | 263 264Some features depend on others: 265 266- If you disable the **Issues** option, GitLab also removes the following 267 features: 268 - **issue boards** 269 - [**Service Desk**](#service-desk) 270 271 NOTE: 272 When the **Issues** option is disabled, you can still access **Milestones** 273 from merge requests. 274 275- Additionally, if you disable both **Issues** and **Merge Requests**, you cannot access: 276 - **Labels** 277 - **Milestones** 278 279- If you disable **Repository** functionality, GitLab also disables the following 280 features for your project: 281 - **Merge Requests** 282 - **CI/CD** 283 - **Container Registry** 284 - **Git Large File Storage** 285 - **Packages** 286 287- Metrics dashboard access requires reading both project environments and deployments. 288 Users with access to the metrics dashboard can also access environments and deployments. 289 290#### Disabling the CVE ID request button **(FREE SAAS)** 291 292> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. 293 294In applicable environments, a [**Create CVE ID Request** button](../../application_security/cve_id_request.md) 295is present in the issue sidebar. The button may be disabled on a per-project basis by toggling the 296setting **Enable CVE ID requests in the issue sidebar**. 297 298 299 300#### Disabling email notifications 301 302Project owners can disable all [email notifications](../../profile/notifications.md) 303related to the project by selecting the **Disable email notifications** checkbox. 304 305### Merge request settings 306 307Set up your project's merge request settings: 308 309- Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.md)). 310- Add merge request [description templates](../description_templates.md#description-templates). 311- Enable [merge request approvals](../merge_requests/approvals/index.md). 312- Enable [status checks](../merge_requests/status_checks.md). 313- Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). 314- Enable [merge only when all threads are resolved](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). 315- Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). 316- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). 317- Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). 318- Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). 319- Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. 320 321### Service Desk 322 323Enable [Service Desk](../service_desk.md) for your project to offer customer support. 324 325### Export project 326 327Learn how to [export a project](import_export.md#import-the-project) in GitLab. 328 329### Advanced settings 330 331Here you can run housekeeping, archive, rename, transfer, 332[remove a fork relationship](#removing-a-fork-relationship), or delete a project. 333 334#### Archiving a project 335 336Archiving a project makes it read-only for all users and indicates that it's 337no longer actively maintained. Projects that have been archived can also be 338unarchived. Only project owners and administrators have the 339[permissions](../../permissions.md#project-members-permissions) to archive a project. 340 341When a project is archived, the repository, packages, issues, merge requests, and all 342other features are read-only. Archived projects are also hidden 343in project listings. 344 345To archive a project: 346 3471. Navigate to your project's **Settings > General**. 3481. Under **Advanced**, click **Expand**. 3491. In the **Archive project** section, click the **Archive project** button. 3501. Confirm the action when asked to. 351 352#### Unarchiving a project 353 354Unarchiving a project removes the read-only restriction on a project, and makes it 355available in project listings. Only project owners and administrators have the 356[permissions](../../permissions.md#project-members-permissions) to unarchive a project. 357 358To find an archived project: 359 3601. Sign in to GitLab as the project owner or a user with the Administrator role. 3611. If you: 362 - Have the project's URL, open the project's page in your browser. 363 - Don't have the project's URL: 364 1. On the top bar, select **Menu > Project**. 365 1. Select **Explore projects**. 366 1. In the **Sort projects** dropdown box, select **Show archived projects**. 367 1. In the **Filter by name** field, provide the project's name. 368 1. Click the link to the project to open its **Details** page. 369 370Next, to unarchive the project: 371 3721. Navigate to your project's **Settings > General**. 3731. Under **Advanced**, click **Expand**. 3741. In the **Unarchive project** section, click the **Unarchive project** button. 3751. Confirm the action when asked to. 376 377#### Renaming a repository 378 379NOTE: 380Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to rename a 381repository. Not to be confused with a project's name where it can also be 382changed from the [general project settings](#general-project-settings). 383 384A project's repository name defines its URL (the one you use to access the 385project via a browser) and its place on the file disk where GitLab is installed. 386 387To rename a repository: 388 3891. Navigate to your project's **Settings > General**. 3901. Under **Advanced**, click **Expand**. 3911. Under **Change path**, update the repository's path. 3921. Click **Change path**. 393 394Remember that this can have unintended side effects since everyone with the 395old URL can't push or pull. Read more about what happens with the 396[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). 397 398#### Transferring an existing project into another namespace 399 400NOTE: 401Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) 402to transfer a project. 403 404You can transfer an existing project into a [group](../../group/index.md) if: 405 406- You have at least **Maintainer** [role](../../permissions.md#project-members-permissions) in that group. 407- You're at least an **Owner** of the project to be transferred. 408- The group to which the project is being transferred to must allow creation of new projects. 409 410To transfer a project: 411 4121. Navigate to your project's **Settings > General**. 4131. Under **Advanced**, click **Expand**. 4141. Under "Transfer project", choose the namespace you want to transfer the 415 project to. 4161. Confirm the transfer by typing the project's path as instructed. 417 418Once done, you are redirected to the new project's namespace. At this point, 419read what happens with the 420[redirects from the old project to the new one](../repository/index.md#what-happens-when-a-repository-path-changes). 421 422NOTE: 423GitLab administrators can use the administration interface to move any project to any 424namespace if needed. 425 426##### Transferring a GitLab.com project to a different subscription tier 427 428When you transfer a project from a namespace that's licensed for GitLab SaaS Premium or Ultimate to Free, some data related to the paid features is deleted. 429 430For example, [project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked, and 431[pipeline subscriptions](../../../ci/pipelines/multi_project_pipelines.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) 432and [test cases](../../../ci/test_cases/index.md) are deleted. 433 434#### Delete a project 435 436You can mark a project to be deleted. 437 438Prerequisite: 439 440- You must have at least the Owner role for a project. 441 442To delete a project: 443 4441. On the top bar, select **Menu > Projects** and find your project. 4451. On the left sidebar, select **Settings > General**. 4461. Expand **Advanced**. 4471. In the "Delete project" section, select **Delete project**. 4481. Confirm the action when asked to. 449 450This action deletes a project including all associated resources (issues, merge requests, and so on). 451 452WARNING: 453The default deletion behavior for projects was changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) 454in GitLab 12.6, and then to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. 455 456#### Delayed project deletion **(PREMIUM)** 457 458Projects in a group (not a personal namespace) can be deleted after a delay period. Multiple settings can affect whether 459delayed project deletion is enabled for a particular project: 460 461- Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion). 462 You can enable delayed project deletion as the default setting for new groups, and configure the number of days for the 463 delay. For GitLab.com, see the [GitLab.com settings](../../gitlab_com/index.md#delayed-project-deletion). 464- Group [settings](../../group/index.md#enable-delayed-project-deletion) to enabled delayed project deletion for all 465 projects in the group. 466 467##### Delete a project immediately 468 469> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. 470 471If you don't want to wait, you can delete a project immediately. 472 473Prerequisites: 474 475- You must have at least the Owner role for a project. 476- You have [marked the project for deletion](#delete-a-project). 477 478To immediately delete a project marked for deletion: 479 4801. On the top bar, select **Menu > Projects** and find your project. 4811. On the left sidebar, select **Settings > General**. 4821. Expand **Advanced**. 4831. In the "Permanently delete project" section, select **Delete project**. 4841. Confirm the action when asked to. 485 486The following are deleted: 487 488- Your project and its repository. 489- All related resources including issues and merge requests. 490 491#### Restore a project **(PREMIUM)** 492 493> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. 494 495To restore a project marked for deletion: 496 4971. Navigate to your project, and select **Settings > General > Advanced**. 4981. In the Restore project section, click the **Restore project** button. 499 500#### Removing a fork relationship 501 502Forking is a great way to [contribute to a project](../repository/forking_workflow.md) 503of which you're not a member. 504If you want to use the fork for yourself and don't need to send 505[merge requests](../merge_requests/index.md) to the upstream project, 506you can safely remove the fork relationship. 507 508WARNING: 509Once removed, the fork relationship cannot be restored. You can't send merge requests to the source, and if anyone has forked your project, their fork also loses the relationship. 510 511To do so: 512 5131. Navigate to your project's **Settings > General > Advanced**. 5141. Under **Remove fork relationship**, click the likewise-labeled button. 5151. Confirm the action by typing the project's path as instructed. 516 517NOTE: 518Only project owners have the [permissions](../../permissions.md#project-members-permissions) 519to remove a fork relationship. 520 521## Monitor settings 522 523### Alerts 524 525Configure [alert integrations](../../../operations/incident_management/integrations.md#configuration) to triage and manage critical problems in your application as [alerts](../../../operations/incident_management/alerts.md). 526 527### Incidents 528 529#### Alert integration 530 531Automatically [create](../../../operations/incident_management/incidents.md#create-incidents-automatically), [notify on](../../../operations/incident_management/paging.md#email-notifications), and [resolve](../../../operations/incident_management/incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. 532 533#### PagerDuty integration 534 535[Create incidents in GitLab for each PagerDuty incident](../../../operations/incident_management/incidents.md#create-incidents-via-the-pagerduty-webhook). 536 537#### Incident settings 538 539[Manage Service Level Agreements for incidents](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) with an SLA countdown timer. 540 541### Error Tracking 542 543Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). 544 545### Jaeger tracing **(ULTIMATE)** 546 547Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../../../operations/tracing.md). 548 549### Status Page 550 551[Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) 552to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). 553
