gitlab-org--gitlab-foss/doc/user/admin_area/settings/continuous_integration.md

15 KiB

stage group info type
Verify Pipeline Execution 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 reference

Continuous Integration and Deployment Admin Area settings (FREE SELF)

The Admin Area has the instance settings for Auto DevOps, runners, and job artifacts.

Auto DevOps

To enable (or disable) Auto DevOps for all projects:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Check (or uncheck to disable) the box that says Default to Auto DevOps pipeline for all projects.
  4. Optionally, set up the Auto DevOps base domain which is used for Auto Deploy and Auto Review Apps.
  5. Hit Save changes for the changes to take effect.

From now on, every existing project and newly created ones that don't have a .gitlab-ci.yml, uses the Auto DevOps pipelines.

If you want to disable it for a specific project, you can do so in its settings.

Enable shared runners for new projects

You can set all new projects to have the instance's shared runners available by default.

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Continuous Integration and Deployment.
  4. Select the Enable shared runners for new projects checkbox.

Any time a new project is created, the shared runners are available.

Shared runners CI/CD minutes

As an administrator you can set either a global or namespace-specific limit on the number of CI/CD minutes you can use.

Enable a specific runner for multiple projects

To enable a specific runner for one or more projects:

  1. On the top bar, select Menu > Admin.
  2. From the left sidebar, select Overview > Runners.
  3. Select the runner you want to edit.
  4. In the top right, select Edit ({pencil}).
  5. Under Restrict projects for this runner, search for a project.
  6. To the left of the project, select Enable.
  7. Repeat this process for each additional project.

Add a message for shared runners

To display details about the instance's shared runners in all projects' runner settings:

  1. On the top bar, select Menu > Admin.

  2. On the left sidebar, select Settings > CI/CD.

  3. Expand Continuous Integration and Deployment.

  4. Enter text, including Markdown if you want, in the Shared runner details field. For example:

    Shared runner details input

To view the rendered details:

  1. On the top bar, select Menu > Project and select any group or project.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Runners.

Shared runner details example

Maximum artifacts size

The maximum size of the job artifacts can be set at:

For the setting on GitLab.com, see Artifacts maximum size.

The value is in MB and the default is 100MB per job. To change it at the:

  • Instance level:

    1. On the top bar, select Menu > Admin.
    2. On the left sidebar, select Settings > CI/CD > Continuous Integration and Deployment.
    3. Change the value of Maximum artifacts size (MB).
    4. Select Save changes for the changes to take effect.
  • Group level (this overrides the instance setting):

    1. Go to the group's Settings > CI/CD > General Pipelines.
    2. Change the value of Maximum artifacts size (in MB).
    3. Select Save changes for the changes to take effect.
  • Project level (this overrides the instance and group settings):

    1. Go to the project's Settings > CI/CD > General Pipelines.
    2. Change the value of maximum artifacts size (in MB).
    3. Select Save changes for the changes to take effect.

NOTE: The setting at all levels is only available to GitLab administrators.

Default artifacts expiration

The default expiration time of the job artifacts can be set in the Admin Area of your GitLab instance. The syntax of duration is described in artifacts:expire_in and the default value is 30 days.

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Change the value of default expiration time.
  4. Select Save changes for the changes to take effect.

This setting is set per job and can be overridden in .gitlab-ci.yml. To disable the expiration, set it to 0. The default unit is in seconds.

NOTE: Any changes to this setting applies to new artifacts only. The expiration time is not be updated for artifacts created before this setting was changed. The administrator may need to manually search for and expire previously-created artifacts, as described in the troubleshooting documentation.

Keep the latest artifacts for all jobs in the latest successful pipelines

Introduced in GitLab 13.9.

When enabled (default), the artifacts of the most recent pipeline for each Git ref (branches and tags) are locked against deletion and kept regardless of the expiry time.

When disabled, the latest artifacts for any new successful or fixed pipelines are allowed to expire.

This setting takes precedence over the project level setting. If disabled at the instance level, you cannot enable this per-project.

To disable the setting:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Continuous Integration and Deployment.
  4. Clear the Keep the latest artifacts for all jobs in the latest successful pipelines checkbox.
  5. Select Save changes

When you disable the feature, the latest artifacts do not immediately expire. A new pipeline must run before the latest artifacts can expire and be deleted.

NOTE: All application settings have a customizable cache expiry interval which can delay the settings affect.

Archive jobs

Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some of the capabilities of the jobs (metadata stored in the database needed to run the job), but persisting the traces and artifacts for auditing purposes.

To set the duration for which the jobs are considered as old and expired:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand the Continuous Integration and Deployment section.
  4. Set the value of Archive jobs.
  5. Hit Save changes for the changes to take effect.

After that time passes, the jobs are archived in the background and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: 15 days, 1 month, 2 years.

For the value set for GitLab.com, see Scheduled job archiving.

Protect CI/CD variables by default

To set all new CI/CD variables as protected by default:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Select Protect CI/CD variables by default.

Default CI/CD configuration file

Introduced in GitLab 12.5.

The default CI/CD configuration file and path for new projects can be set in the Admin Area of your GitLab instance (.gitlab-ci.yml if not set):

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Input the new file and path in the Default CI/CD configuration file field.
  4. Hit Save changes for the changes to take effect.

It is also possible to specify a custom CI/CD configuration file for a specific project.

Set CI/CD limits

Introduced in GitLab 14.10.

You can configure some CI/CD limits from the Admin Area:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand the Continuous Integration and Deployment section.
  4. In the CI/CD limits section, you can set the following limits:
    • Maximum number of jobs in a single pipeline
    • Total number of jobs in currently active pipelines
    • Maximum number of active pipelines per project
    • Maximum number of pipeline subscriptions to and from a project
    • Maximum number of pipeline schedules
    • Maximum number of DAG dependencies that a job can have
    • Maximum number of runners registered per group
    • Maximum number of runners registered per project

Enable or disable the pipeline suggestion banner

By default, a banner displays in merge requests with no pipeline suggesting a walkthrough on how to add one.

Suggest pipeline banner

To enable or disable the banner:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Select or clear the Enable pipeline suggestion banner checkbox.
  4. Select Save changes.

Required pipeline configuration (ULTIMATE SELF)

Moved from GitLab Premium to GitLab Ultimate in 15.0.

NOTE: An alternative compliance solution is available. We recommend this alternative solution because it provides greater flexibility, allowing required pipelines to be assigned to specific compliance framework labels.

You can set a CI/CD template as a required pipeline configuration for all projects on a GitLab instance. You can use a template from:

  • The default CI/CD templates.

  • A custom template stored in an instance template repository.

    NOTE: When you use a configuration defined in an instance template repository, nested include: keywords (including include:file, include:local, include:remote, and include:template) do not work.

The project CI/CD configuration merges into the required pipeline configuration when a pipeline runs. The merged configuration is the same as if the required pipeline configuration added the project configuration with the include keyword. To view a project's full merged configuration, View the merged YAML in the pipeline editor.

To select a CI/CD template for the required pipeline configuration:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand the Required pipeline configuration section.
  4. Select a CI/CD template from the dropdown.
  5. Select Save changes.

Package Registry configuration

npm Forwarding (PREMIUM SELF)

GitLab administrators can disable the forwarding of npm requests to npmjs.com.

To disable it:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand the Package Registry section.
  4. Clear the checkbox Forward npm package requests to the npm Registry if the packages are not found in the GitLab Package Registry.
  5. Select Save changes.

PyPI Forwarding (PREMIUM SELF)

GitLab administrators can disable the forwarding of PyPI requests to pypi.org.

To disable it:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand the Package Registry section.
  4. Clear the checkbox Forward PyPI package requests to the PyPI Registry if the packages are not found in the GitLab Package Registry.
  5. Select Save changes.

Package file size limits

GitLab administrators can adjust the maximum allowed file size for each package type.

To set the maximum file size:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand the Package Registry section.
  4. Find the package type you would like to adjust.
  5. Enter the maximum file size, in bytes.
  6. Select Save size limits.

Prevent users from registering runners

Introduced in GitLab 14.1.

FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to enable the feature flag named runner_registration_control. On GitLab.com, this feature is not available.

GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI.

By default, all members of a project and group are able to register runners.

To change this:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand Runner registration.
  4. Clear the checkbox if you don't want to display runner registration information in the UI for group or project members.
  5. Select Save changes.

WARNING: When the registration sections are hidden in the UI, members of the project or group that need to register runners must contact the administrators. If you plan to prevent registration, ensure users have access to the runners they need to run jobs.

Troubleshooting

413 Request Entity Too Large

When build jobs fail with the following error, increase the maximum artifacts size.

Uploading artifacts as "archive" to coordinator... too large archive <job-id> responseStatus=413 Request Entity Too Large status=413" at end of a build job on pipeline when trying to store artifacts to <object-storage>.