diff options
Diffstat (limited to 'doc/ci/runners')
| -rw-r--r-- | doc/ci/runners/configure_runners.md | 291 | ||||
| -rw-r--r-- | doc/ci/runners/index.md | 5 | ||||
| -rw-r--r-- | doc/ci/runners/new_creation_workflow.md | 6 | ||||
| -rw-r--r-- | doc/ci/runners/register_runner.md | 11 | ||||
| -rw-r--r-- | doc/ci/runners/runners_scope.md | 58 | ||||
| -rw-r--r-- | doc/ci/runners/saas/gpu_saas_runner.md | 2 | ||||
| -rw-r--r-- | doc/ci/runners/saas/linux_saas_runner.md | 2 | ||||
| -rw-r--r-- | doc/ci/runners/saas/macos_saas_runner.md | 14 | ||||
| -rw-r--r-- | doc/ci/runners/saas/windows_saas_runner.md | 2 |
9 files changed, 229 insertions, 162 deletions
diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index bca0b50563a..3b21d865d8b 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring runners **(FREE ALL)** @@ -11,53 +11,79 @@ If you have installed your own runners, you can configure and secure them in Git If you need to configure runners on the machine where you installed GitLab Runner, see [the GitLab Runner documentation](https://docs.gitlab.com/runner/configuration/). -## Manually clear the runner cache +## Set the maximum job timeout -Read [clearing the cache](../caching/index.md#clearing-the-cache). +You can specify a maximum job timeout for each runner to prevent projects +with longer job timeouts from using the runner. The maximum job timeout is +used of it is shorter than the job timeout defined in the project. -## Set maximum job timeout for a runner +### For a shared runner -For each runner, you can specify a *maximum job timeout*. This timeout, -if smaller than the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run), takes precedence. +Prerequisites: + +- You must be an administrator. + +On GitLab.com, you cannot override the job timeout for shared runners and must use the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) instead. + +To set the maximum job timeout: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner, you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). +1. Select **Save changes**. + +### For a group runner + +Prerequisites: + +- You must have the Owner role for the group. -This feature can be used to prevent your shared runner from being overwhelmed -by a project that has jobs with a long timeout (for example, one week). +To set the maximum job timeout: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). +1. Select **Save changes**. -On GitLab.com, you cannot override the job timeout for shared runners and must use the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run). +### For a project runner + +Prerequisites: + +- You must have the Owner role for the project. To set the maximum job timeout: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. -1. Select your project runner to edit the settings. -1. Enter a value under **Maximum job timeout**. Must be 10 minutes or more. If not - defined, the [project's job timeout setting](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) - is used. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). If not defined, the [job timeout for the project](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) is used instead. 1. Select **Save changes**. -How this feature works: +## How maximum job timeout works **Example 1 - Runner timeout bigger than project timeout** -1. You set the _maximum job timeout_ for a runner to 24 hours -1. You set the _CI/CD Timeout_ for a project to **2 hours** -1. You start a job -1. The job, if running longer, times out after **2 hours** +1. You set the _maximum job timeout_ for a runner to 24 hours. +1. You set the _CI/CD Timeout_ for a project to **2 hours**. +1. You start a job. +1. The job, if running longer, times out after **2 hours**. **Example 2 - Runner timeout not configured** -1. You remove the _maximum job timeout_ configuration from a runner -1. You set the _CI/CD Timeout_ for a project to **2 hours** -1. You start a job -1. The job, if running longer, times out after **2 hours** +1. You remove the _maximum job timeout_ configuration from a runner. +1. You set the _CI/CD Timeout_ for a project to **2 hours**. +1. You start a job. +1. The job, if running longer, times out after **2 hours**. **Example 3 - Runner timeout smaller than project timeout** -1. You set the _maximum job timeout_ for a runner to **30 minutes** -1. You set the _CI/CD Timeout_ for a project to 2 hours -1. You start a job -1. The job, if running longer, times out after **30 minutes** +1. You set the _maximum job timeout_ for a runner to **30 minutes**. +1. You set the _CI/CD Timeout_ for a project to 2 hours. +1. You start a job. +1. The job, if running longer, times out after **30 minutes**. ## Set `script` and `after_script` timeouts @@ -66,7 +92,7 @@ How this feature works: To control the amount of time `script` and `after_script` runs before it terminates, you can set specify a timeout. For example, you can specify a timeout to terminate a long-running `script` early, so that artifacts and caches can still be uploaded -before the [job timeout](#set-maximum-job-timeout-for-a-runner) is exceeded. +before the job timeout is exceeded. - To set a timeout for `script`, use the job variable `RUNNER_SCRIPT_TIMEOUT`. - To set a timeout for `after_script`, and override the default of 5 minutes, use the job variable `RUNNER_AFTER_SCRIPT_TIMEOUT`. @@ -105,26 +131,11 @@ of shared runners on large GitLab instances. This ensures that you control access to your GitLab instances and secure [runner executors](https://docs.gitlab.com/runner/executors/). If certain executors run a job, the file system, the code the runner executes, -and the runner authentication token may be exposed. This means that anyone that runs jobs +and the runner authentication token may be exposed. This means that anyone who runs jobs on a _shared runner_ can access another user's code that runs on the runner. Users with access to the runner authentication token can use it to create a clone of a runner and submit false jobs in a vector attack. For more information, see [Security Considerations](https://docs.gitlab.com/runner/security/). -### Prevent runners from revealing sensitive information - -To ensure runners don't reveal sensitive information, you can configure them to only run jobs -on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md). - -To prevent runners from revealing sensitive information: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > CI/CD**. -1. Expand **Runners**. -1. Find the runner you want to protect or unprotect. Make sure the runner is enabled. -1. Select **Edit** (**{pencil}**). -1. Select the **Protected** checkbox. -1. Select **Save changes**. - ### Using shared runners in forked projects When a project is forked, the job settings related to jobs are copied. If you have shared runners @@ -163,6 +174,23 @@ After you reset the registration token, it is no longer valid and does not regis any new runners to the project. You should also update the registration token in tools you use to provision and register new values. +## Authentication token security + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/377902) in GitLab 15.5. Feature flag `enforce_runner_token_expires_at` removed. + +Each runner has an [runner authentication token](../../api/runners.md#registration-and-authentication-tokens) +to connect with the GitLab instance. + +To help prevent the token from being compromised, you can have the +token rotate automatically at specified intervals. When the tokens are rotated, +they are updated for each runner, regardless of the runner's status (`online` or `offline`). + +No manual intervention should be required, and no running jobs should be affected. + +If you need to manually update the runner authentication token, you can run a +command to [reset the token](https://docs.gitlab.com/runner/commands/#gitlab-runner-reset-token). + ### Reset the runner authentication token If a runner authentication token is revealed, an attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). @@ -179,37 +207,131 @@ To reset the runner authentication token: - [Create a project runner](runners_scope.md#create-a-project-runner-with-a-runner-authentication-token). 1. Optional. To verify that the previous runner authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). -## Use tags to control which jobs a runner can run +### Automatically rotate runner authentication tokens + +You can specify an interval for runner authentication tokens to rotate. +This rotation helps ensure the security of the tokens assigned to your runners. + +Prerequisites: + +- Runners must use [GitLab Runner 15.3 or later](https://docs.gitlab.com/runner/#gitlab-runner-versions). +- You must be an administrator. + +To automatically rotate runner authentication tokens: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD**. +1. Expand **Continuous Integration and Deployment**. +1. Set a **Runners expiration** time for runners, leave empty for no expiration. +1. Select **Save changes**. + +Before the interval expires, runners automatically request a new runner authentication token. + +## Prevent runners from revealing sensitive information + +To ensure runners don't reveal sensitive information, you can configure them to only run jobs +on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md). + +Runners configured to run jobs on protected branches cannot run jobs in [merge request pipelines](../pipelines/merge_request_pipelines.md). + +### For a shared runner + +Prerequisites: + +- You must be an administrator. + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +### For a group runner + +Prerequisites: + +- You must have the Owner role for the group. + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +### For a project runner + +Prerequisites: + +- You must have the Owner role for the project. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > CI/CD**. +1. Expand **Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +## Control jobs that a runner can run -You can use [tags](../yaml/index.md#tags) to ensure that runners only run the jobs they are equipped -to run. For example, you can specify the `rails` tag for runners that have the dependencies to run +You can use [tags](../yaml/index.md#tags) to control the jobs a runner can run. +For example, you can specify the `rails` tag for runners that have the dependencies to run Rails test suites. GitLab CI/CD tags are different to Git tags. GitLab CI/CD tags are associated with runners. Git tags are associated with commits. -### Set a runner to run untagged jobs +### For a shared runner + +Prerequisites: + +- You must be an administrator. + +To set the maximum job timeout: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `rails`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. +1. Select **Save changes**. + +### For a group runner -When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** -[tagged jobs](../yaml/index.md#tags). -To change this, you must have the Owner role for the project. +Prerequisites: + +- You must have the Owner role for the group. + +To set the maximum job timeout: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `ruby`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. +1. Select **Save changes**. + +### For a project runner + +Prerequisites: -To make a runner pick untagged jobs: +- You must have the Owner role for the project. + +To set a runner to run tagged jobs: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. -1. Find the runner you want to pick untagged jobs and make sure it's enabled. -1. Select **Edit** (**{pencil}**). -1. Select the **Run untagged jobs** checkbox. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `ruby`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. 1. Select **Save changes**. -NOTE: -The runner tags list cannot be empty when it's not allowed to pick untagged jobs. - -Below are some example scenarios of different variations. +### How the runner uses tags -### Runner runs only tagged jobs +#### Runner runs only tagged jobs The following examples illustrate the potential impact of the runner being set to run only tagged jobs. @@ -229,7 +351,7 @@ Example 3: 1. The runner is configured to run only tagged jobs and has the `docker` tag. 1. A job that has no tags defined is executed and stuck. -### Runner is allowed to run untagged jobs +#### Runner is allowed to run untagged jobs The following examples illustrate the potential impact of the runner being set to run tagged and untagged jobs. @@ -246,7 +368,7 @@ Example 2: 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is stuck. -### A runner and a job have multiple tags +#### A runner and a job have multiple tags The selection logic that matches the job and runner is based on the list of `tags` defined in the job. @@ -273,7 +395,9 @@ Example 3: You can use tags to run different jobs on different platforms. For example, if you have an OS X runner with tag `osx` and a Windows runner with tag -`windows`, you can run a job on each platform: +`windows`, you can run a job on each platform. + +Update the `tags` field in the `config.toml`: ```yaml windows job: @@ -295,7 +419,7 @@ osx job: > Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/35742). -You can use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: +In the `.gitlab-ci.yml` file, use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: ```yaml variables: @@ -786,7 +910,7 @@ variables: NOTE: Zip archives are the only supported artifact type. Follow [the issue for details](https://gitlab.com/gitlab-org/gitlab/-/issues/367203). -GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The filename is as follows: `{ARTIFACT_NAME}-metadata.json` where `ARTIFACT_NAME` is what was defined as the [name for the artifact](../jobs/job_artifacts.md#with-a-dynamically-defined-name) in the CI file. The filename, however, defaults to `artifacts-metadata.json` if no name was given to the build artifacts. +GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The file name is as follows: `{ARTIFACT_NAME}-metadata.json` where `ARTIFACT_NAME` is what was defined as the [name for the artifact](../jobs/job_artifacts.md#with-a-dynamically-defined-name) in the CI file. The file name, however, defaults to `artifacts-metadata.json` if no name was given to the build artifacts. ### Attestation format @@ -795,7 +919,7 @@ The attestation metadata is generated in the [in-toto attestation format](https: | Field | Value | | ------ | ------ | | `_type` | `https://in-toto.io/Statement/v0.1` | -| `subject.name` | The filename of the artifact. | +| `subject.name` | The file name of the artifact. | | `subject.digest.sha256` | The artifact's `sha256` checksum. | | `predicateType` | `https://slsa.dev/provenance/v0.2` | | `predicate.buildType` | `https://gitlab.com/gitlab-org/gitlab-runner/-/blob/{GITLAB_RUNNER_VERSION}/PROVENANCE.md`. For example v15.0.0 | @@ -911,40 +1035,3 @@ setting. `FASTZIP_EXTRACTOR_CONCURRENCY` controls how many files are decompressed at once. Files from a zip archive can natively be read from concurrency, so no additional memory is allocated in addition to what the decompressor requires. This defaults to the number of CPUs available. - -## Authentication token security - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/377902) in GitLab 15.5. Feature flag `enforce_runner_token_expires_at` removed. - -Each runner has an [runner authentication token](../../api/runners.md#registration-and-authentication-tokens) -to connect with the GitLab instance. - -To help prevent the token from being compromised, you can have the -token rotate automatically at specified intervals. When the tokens are rotated, -they are updated for each runner, regardless of the runner's status (`online` or `offline`). - -No manual intervention should be required, and no running jobs should be affected. - -If you need to manually update the runner authentication token, you can run a -command to [reset the token](https://docs.gitlab.com/runner/commands/#gitlab-runner-reset-token). - -### Automatically rotate runner authentication tokens - -You can specify an interval for runner authentication tokens to rotate. -This rotation helps ensure the security of the tokens assigned to your runners. - -Prerequisites: - -- Ensure your runners are using [GitLab Runner 15.3 or later](https://docs.gitlab.com/runner/#gitlab-runner-versions). - -To automatically rotate runner authentication tokens: - -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **Continuous Integration and Deployment** -1. Set a **Runners expiration** time for runners, leave empty for no expiration. -1. Select **Save**. - -Before the interval expires, runners automatically request a new runner authentication token. diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 7e597264e1e..1df93ed8896 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner SaaS -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Runner SaaS **(FREE SAAS)** @@ -21,7 +20,7 @@ For more information about the cost factor applied to the machine type based on The number of minutes you can use on these runners depends on the [maximum number of units of compute](../pipelines/cicd_minutes.md) in your [subscription plan](https://about.gitlab.com/pricing/). -[Untagged](../../ci/runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) jobs automatically run in containers +[Untagged](../../ci/runners/configure_runners.md#control-jobs-that-a-runner-can-run) jobs automatically run in containers on the `small` Linux runners. The objective is to make 90% of CI/CD jobs start executing in 120 seconds or less. The error rate should be less than 0.5%. diff --git a/doc/ci/runners/new_creation_workflow.md b/doc/ci/runners/new_creation_workflow.md index 022f7af11ec..c870a89a77a 100644 --- a/doc/ci/runners/new_creation_workflow.md +++ b/doc/ci/runners/new_creation_workflow.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating to the new runner registration workflow **(FREE ALL)** @@ -29,7 +29,7 @@ you can let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab For the new runner registration workflow, you: -1. [Create a runner](register_runner.md) directly in the GitLab UI. +1. [Create a runner](runners_scope.md) directly in the GitLab UI. 1. Receive a runner authentication token. 1. Use the runner authentication token instead of the registration token when you register a runner with this configuration. Runner managers registered in multiple hosts appear @@ -141,7 +141,7 @@ process is started. ## Creating runners programmatically -In GitLab 15.11 and later, you can use the [POST /user/runners REST API](../../api/users.md#create-a-runner) +In GitLab 15.11 and later, you can use the [POST /user/runners REST API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner as an authenticated user. This should only be used if the runner configuration is dynamic or not reusable. If the runner configuration is static, you should reuse the runner authentication token of an existing runner. diff --git a/doc/ci/runners/register_runner.md b/doc/ci/runners/register_runner.md deleted file mode 100644 index bca11682258..00000000000 --- a/doc/ci/runners/register_runner.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'runners_scope.md' -remove_date: '2023-09-21' ---- - -This document was moved to [another location](runners_scope.md). - -<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> -<!-- 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/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 6b6493db2c4..48f6a22e9b3 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage runners **(FREE ALL)** @@ -40,7 +39,7 @@ If you are using GitLab.com: > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/389269) in GitLab 16.0. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed. -Prerequisite: +Prerequisites: - You must be an administrator. @@ -48,9 +47,8 @@ When you create a runner, it is assigned a runner authentication token that you To create a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Select **New instance runner**. 1. Select the operating system where GitLab Runner is installed. 1. In the **Tags** section, in the **Tags** field, enter the job tags to specify jobs the runner can run. @@ -65,7 +63,7 @@ To create a shared runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for a limited period of time during registration. After you register the runner, @@ -78,14 +76,13 @@ The ability to pass a runner registration token, and support for certain configu [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). -Prerequisite: +Prerequisites: - You must be an administrator. To create a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. Select **Register an instance runner**. 1. Copy the registration token. @@ -93,14 +90,13 @@ To create a shared runner: ### Pause or resume a shared runner -Prerequisite: +Prerequisites: - You must be an administrator. You can pause a runner so that it does not accept jobs from groups and projects in the GitLab instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or filter the runner list. 1. In the runner list, to the right of the runner: @@ -109,7 +105,7 @@ You can pause a runner so that it does not accept jobs from groups and projects ### Delete shared runners -Prerequisite: +Prerequisites: - You must be an administrator. @@ -119,8 +115,7 @@ jobs, you can [pause](#pause-or-resume-a-shared-runner) the runner instead. To delete a single or multiple shared runners: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or filter the list of runners. 1. Delete the shared runner: @@ -263,7 +258,7 @@ To create a group runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for only a short period of time during registration. @@ -295,7 +290,7 @@ how to [register a runner](https://docs.gitlab.com/runner/register/#register-wit > Ability for users with the Maintainer role to view group runners [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384179) in GitLab 16.4. -Prerequisite: +Prerequisites: - You must have the Maintainer or Owner role for the group. @@ -324,7 +319,7 @@ those in other groups: ### Pause or resume a group runner -Prerequisite: +Prerequisites: - You must be an administrator or have the Owner role for the group. @@ -342,7 +337,7 @@ instance. If you pause a group runner that is used by multiple projects, the run > Multiple runner deletion [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361721/) in GitLab 15.6. -Prerequisite: +Prerequisites: - You must be an administrator or have the Owner role for the group. @@ -365,7 +360,7 @@ To delete a single or multiple group runners: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363012) in GitLab 15.1. -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -457,7 +452,7 @@ To create a project runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for only a short period of time during registration. @@ -469,7 +464,7 @@ The ability to pass a runner registration token, and support for certain configu [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. @@ -487,7 +482,7 @@ The runner is now enabled for the project. ### Pause or resume a project runner -Prerequisite: +Prerequisites: - You must be an administrator, or have the Maintainer role for the project. @@ -588,9 +583,8 @@ runners are considered. queued for longer than the median value, and half of the jobs queued for less than the median value. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Select **View metrics**. ## Determine which runners need to be upgraded **(ULTIMATE ALL)** @@ -607,8 +601,7 @@ To determine which runners need to be upgraded: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > Runners**. - For the instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. Above the list of runners, view the status: @@ -631,15 +624,14 @@ different places. ### Determine the IP address of a shared runner -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To determine the IP address of a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Find the runner in the table and view the **IP Address** column.  diff --git a/doc/ci/runners/saas/gpu_saas_runner.md b/doc/ci/runners/saas/gpu_saas_runner.md index 6dc9d8c9534..e9313c65f11 100644 --- a/doc/ci/runners/saas/gpu_saas_runner.md +++ b/doc/ci/runners/saas/gpu_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GPU-enabled SaaS runners **(PREMIUM SAAS)** diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index 23a9b26a8d7..2534db79795 100644 --- a/doc/ci/runners/saas/linux_saas_runner.md +++ b/doc/ci/runners/saas/linux_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Linux **(FREE SAAS)** diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index b503fea4f2f..03c23680c1c 100644 --- a/doc/ci/runners/saas/macos_saas_runner.md +++ b/doc/ci/runners/saas/macos_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on macOS **(PREMIUM SAAS BETA)** @@ -36,11 +36,11 @@ GitLab SaaS provides a set of VM images for macOS. You can execute your build in one of the following images, which you specify in your `.gitlab-ci.yml` file. Each image runs a specific version of macOS and Xcode. -| VM image | Status | -|----------------------------|--------| -| `macos-12-xcode-14` | `GA` | -| `macos-13-xcode-14` | `GA` | -| `macos-14-xcode-15` | `Beta` | +| VM image | Status | | +|----------------------------|--------|--------------| +| `macos-12-xcode-14` | `GA` | | +| `macos-13-xcode-14` | `GA` | [Preinstalled Software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/blob/main/toolchain/macos-13.yml) | +| `macos-14-xcode-15` | `Beta` | [Preinstalled Software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/blob/main/toolchain/macos-14.yml) | If no image is specified, the macOS runner uses `macos-13-xcode-14`. @@ -48,7 +48,7 @@ If no image is specified, the macOS runner uses `macos-13-xcode-14`. macOS and Xcode follow a yearly release cadence, during which GitLab increments its versions synchronously. GitLab typically supports multiple versions of preinstalled tools. For more information, see the [full list of preinstalled software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/tree/main/toolchain). -When Apple releases a new macOS version, GitLab releases a new `stable` image based on the OS in the next release, +When Apple releases a new macOS version, GitLab releases a new `stable` image based on the OS in the next release, which is in Beta. With the release of the first patch to macOS, the `stable` image becomes Generally Available (GA). As only two GA images are supported at a time, the prior OS version becomes deprecated and is deleted after three months in accordance with the [supported image lifecycle](../index.md#supported-image-lifecycle). diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index 108388f22c8..fd1d5ba1ab7 100644 --- a/doc/ci/runners/saas/windows_saas_runner.md +++ b/doc/ci/runners/saas/windows_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Windows **(FREE SAAS BETA)** |