diff options
Diffstat (limited to 'doc/ci/runners')
| -rw-r--r-- | doc/ci/runners/configure_runners.md | 34 | ||||
| -rw-r--r-- | doc/ci/runners/index.md | 74 | ||||
| -rw-r--r-- | doc/ci/runners/new_creation_workflow.md | 89 | ||||
| -rw-r--r-- | doc/ci/runners/runners_scope.md | 151 | ||||
| -rw-r--r-- | doc/ci/runners/saas/linux_saas_runner.md | 2 | ||||
| -rw-r--r-- | doc/ci/runners/saas/macos/codesigning.md | 11 | ||||
| -rw-r--r-- | doc/ci/runners/saas/macos/environment.md | 11 | ||||
| -rw-r--r-- | doc/ci/runners/saas/macos_saas_runner.md | 34 | ||||
| -rw-r--r-- | doc/ci/runners/saas/windows_saas_runner.md | 21 |
9 files changed, 248 insertions, 179 deletions
diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 3e26c120f74..fd1716cc58a 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -64,9 +64,9 @@ 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 token may be exposed. This means that anyone that runs jobs +and the runner authentication token may be exposed. This means that anyone that runs jobs on a _shared runner_ can access another user's code that runs on the runner. -Users with access to the runner token can use it to create a clone of +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 @@ -76,7 +76,7 @@ on [protected branches](../../user/project/protected_branches.md), or jobs that To prevent runners from revealing sensitive information: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +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. @@ -111,7 +111,7 @@ That new runner may then be used to obtain the values of secret variables or to To reset the registration token: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your 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 **New project runner**, select the vertical ellipsis (**{ellipsis_v}**). @@ -124,19 +124,19 @@ you use to provision and register new values. ### Reset the runner authentication token -If an authentication token is revealed, an attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). +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). -To reset the authentication token: +To reset the runner authentication token: 1. Delete the runner: - [Delete a shared runner](runners_scope.md#delete-shared-runners). - [Delete a group runner](runners_scope.md#delete-a-group-runner). - [Delete a project runner](runners_scope.md#delete-a-project-runner). -1. Create a new runner so that it is assigned a new authentication token: - - [Create a shared runner](runners_scope.md#create-a-shared-runner-with-an-authentication-token). - - [Create a group runner](runners_scope.md#create-a-group-runner-with-an-authentication-token). - - [Create a project runner](runners_scope.md#create-a-project-runner-with-an-authentication-token). -1. Optional. To verify that the previous authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). +1. Create a new runner so that it is assigned a new runner authentication token: + - [Create a shared runner](runners_scope.md#create-a-shared-runner-with-a-runner-authentication-token). + - [Create a group runner](runners_scope.md#create-a-group-runner-with-a-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 @@ -874,7 +874,7 @@ defaults to the number of CPUs available. > - [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 [authentication token](../../api/runners.md#registration-and-authentication-tokens) +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 @@ -883,12 +883,12 @@ they are updated for each runner, regardless of the runner's status (`online` or No manual intervention should be required, and no running jobs should be affected. -If you need to manually update the authentication token, you can run a +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 authentication tokens +### Automatically rotate runner authentication tokens -You can specify an interval for authentication tokens to rotate. +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: @@ -897,11 +897,11 @@ Prerequisites: To automatically rotate runner authentication tokens: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +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 authentication token. +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 5427911e1ce..7e597264e1e 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -17,10 +17,15 @@ Your jobs can run on: - [Windows runners](saas/windows_saas_runner.md) ([Beta](../../policy/experiment-beta-support.md#beta)) - [macOS runners](saas/macos_saas_runner.md) ([Beta](../../policy/experiment-beta-support.md#beta)) -Refer to the compute minutes [cost factor](../../ci/pipelines/cicd_minutes.md#cost-factor) for the cost factor applied to the machine type based on size. -The number of minutes you can use on these runners depends on the [maximum number of compute minutes](../pipelines/cicd_minutes.md) +For more information about the cost factor applied to the machine type based on size, see [cost factor](../../ci/pipelines/cicd_minutes.md#cost-factor). +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 +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%. + ## How SaaS runners work When you use SaaS runners: @@ -30,9 +35,6 @@ When you use SaaS runners: - The virtual machine where your job runs has `sudo` access with no password. - The storage is shared by the operating system, the image with pre-installed software, and a copy of your cloned repository. This means that the available free disk space for your jobs to use is reduced. -- [Untagged](../../ci/runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) jobs automatically run in containers -on the `small` Linux runners. -- The objective is to make 90% of CI jobs start executing in 120 seconds or less. The error rate target will be less than 0.5%. NOTE: Jobs handled by SaaS runners on GitLab.com **time out after 3 hours**, regardless of the timeout configured in a project. @@ -67,3 +69,65 @@ takes over the task of securely deleting the virtual machine and associated data - Inbound communication from the public internet to the temporary VM is not allowed. - Firewall rules do not permit communication between VMs. - The only internal communication allowed to the temporary VMs is from the runner manager. + +## Supported image lifecycle + +For runners on macOS and Windows, you can only run jobs on supported images. You cannot bring your own image. Supported images have the following lifecycle: + +- Beta +- Generally Available +- Deprecated + +### Beta + +To gather feedback on an image prior to making the image Generally Available (GA) and to address +any issues, new images are released as Beta. Any jobs running on Beta images are not +covered by the service-level agreement. If you use Beta images, you can provide feedback +by creating an issue. + +### Generally Available + +A Generally Available (GA) image is released after the image completes a Beta phase +and is considered suitable for general use. To become GA, the +image must fulfill the following requirements: + +- Successful completion of a Beta phase by resolving all reported significant bugs +- Compatibility of installed software with the underlying OS + +Jobs running on GA images are covered by the defined service-level agreement. Over time, these images are deprecated. + +### Deprecated + +A maximum of two Generally Available (GA) images are supported at a time. After a new GA image is released, +the oldest GA image becomes deprecated. A deprecated image is no longer +updated and is deleted after 3 months in accordance with the [deprecation guidelines](../../development/deprecation_guidelines/index.md). + +## Major version changes (breaking) + +As GitLab CI/CD and Runner have evolved, certain breaking changes have been necessary. + +For GitLab 15.0 and later, all breaking changes are documented on the following page: + +- [Deprecations and removals](../../update/deprecations.md) + +The breaking changes for GitLab Runner in earlier major version releases are: + +- 14.0: No breaking changes. +- 13.0: + - [Remove Backported `os.Expand`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4915). + - [Remove Fedora 29 package support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/16158). + - [Remove macOS 32-bit support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25466). + - [Removed `debug/jobs/list?v=1` endpoint](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6361). + - [Remove support for array of strings when defining services for Docker executor](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4922). + - [Remove `--docker-services` flag on register command](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6404). + - [Remove legacy build directory caching](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4180). + - [Remove `FF_USE_LEGACY_VOLUMES_MOUNTING_ORDER` feature flag](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6581). + - [Remove support for Windows Server 1803](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6553). +- 12.0: + - [Use `refspec` to clone/fetch Git repository](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4069). + - [Old cache configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4070). + - [Old metrics server configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4072). + - [Remove `FF_K8S_USE_ENTRYPOINT_OVER_COMMAND`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4073). + - [Remove Linux distributions that reach EOL](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1130). + - [Update command line API for helper images](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4013). + - [Remove old `git clean` flow](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4175). diff --git a/doc/ci/runners/new_creation_workflow.md b/doc/ci/runners/new_creation_workflow.md index 55ff5165ff7..c4c2fbebb12 100644 --- a/doc/ci/runners/new_creation_workflow.md +++ b/doc/ci/runners/new_creation_workflow.md @@ -14,15 +14,13 @@ As with all projects, the items mentioned on this page are subject to change or The development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. -In GitLab 16.0, we introduced a new runner creation workflow that uses authentication tokens to register -runners. The legacy workflow that uses registration tokens is deprecated and will be removed in GitLab 17.0. +In GitLab 16.0, we introduced a new runner creation workflow that uses runner authentication tokens to register +runners. The legacy workflow that uses registration tokens is deprecated and will be removed in GitLab 18.0. For information about the current development status of the new workflow, see [epic 7663](https://gitlab.com/groups/gitlab-org/-/epics/7663). For information about the technical design and reasons for the new architecture, see [Next GitLab Runner Token Architecture](../../architecture/blueprints/runner_tokens/index.md). -## Feedback - If you experience problems or have concerns about the new runner registration workflow, or if the following information is not sufficient, you can let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/387993). @@ -32,8 +30,8 @@ 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. Receive an authentication token. -1. Use the authentication token instead of the registration token when you register +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 under the same runner in the GitLab UI, but with an identifying system ID. @@ -46,54 +44,63 @@ multiple runners. For more information, see [Reusing a GitLab Runner configurati ## Estimated time frame for planned changes - In GitLab 15.10 and later, you can use the new runner registration workflow. -- In GitLab 16.6, we plan to disable registration tokens. -- In GitLab 17.0, we plan to completely remove support for runner registration tokens. +- In GitLab 17.0, we plan to disable runner registration tokens. +- In GitLab 18.0, we plan to completely remove support for runner registration tokens. ## Prevent your runner registration workflow from breaking -Until GitLab 16.6, you can still use the legacy runner registration workflow. +Until GitLab 17.0, you can still use the legacy runner registration workflow. -In GitLab 16.6, the legacy runner registration workflow will be disabled automatically. You will be able to manually re-enable the legacy runner registration workflow for a limited time. For more information, see -[Using registration tokens after GitLab 16.6](#using-registration-tokens-after-gitlab-166). +In GitLab 17.0, the legacy runner registration workflow will be disabled automatically. You will be able to manually re-enable the legacy runner registration workflow for a limited time. For more information, see +[Using registration tokens after GitLab 17.0](#using-registration-tokens-after-gitlab-170). -If no action is taken before your GitLab instance is upgraded to GitLab 16.6, then your runner registration +If no action is taken before your GitLab instance is upgraded to GitLab 17.0, then your runner registration workflow will break. To avoid a broken workflow, you must: -1. [Create a shared runner](runners_scope.md#create-a-shared-runner-with-an-authentication-token) and obtain the authentication token. +1. [Create a shared runner](runners_scope.md#create-a-shared-runner-with-a-runner-authentication-token) and obtain the authentication token. 1. Replace the registration token in your runner registration workflow with the authentication token. -## Using registration tokens after GitLab 16.6 +## Using registration tokens after GitLab 17.0 -To continue using registration tokens after GitLab 16.6: +To continue using registration tokens after GitLab 17.0: -- On GitLab.com, you can manually re-enable the legacy runner registration process in the top-level group settings until GitLab 16.8. -- On GitLab self-managed, you can manually re-enable the legacy runner registration process in the Admin Area settings until GitLab 17.0. +- On GitLab.com, you can manually re-enable the legacy runner registration process in the top-level group settings until GitLab 18.0. +- On GitLab self-managed, you can manually re-enable the legacy runner registration process in the Admin Area settings until GitLab 18.0. Plans to implement a UI setting to re-enable registration tokens are proposed in [issue 411923](https://gitlab.com/gitlab-org/gitlab/-/issues/411923) +## Runners registered with a registration token will continue to work after 18.0 + +Existing runners will not be affected by these changes, they will still work even after the legacy registration method is removed. + ## Changes to the `gitlab-runner register` command syntax -The `gitlab-runner register` command will stop accepting registration tokens and instead accept new +The `gitlab-runner register` command will stop accepting registration tokens and instead accept new runner authentication tokens generated in the GitLab runners administration page. -These authentication tokens are recognizable by their `glrt-` prefix. +The runner authentication tokens are recognizable by their `glrt-` prefix. When you create a runner in the GitLab UI, you specify configuration values that were previously command-line options prompted by the `gitlab-runner register` command. These command-line options have been [deprecated](../../update/deprecations.md#registration-tokens-and-server-side-runner-arguments-in-post-apiv4runners-endpoint). -If you specify an authentication token with: +If you specify a runner authentication token with: - the `--token` command-line option, the `gitlab-runner register` command does not accept the configuration values. - the `--registration-token` command-line option, the `gitlab-runner register` command ignores the configuration values. +| Token | Registration command | +|----------------------------------------|-----------------------------------------------------------------------------------------------------------| +| Runner authentication token | `gitlab-runner register --token $RUNNER_AUTHENTICATION_TOKEN` | +| Runner registration token (deprecated) | `gitlab-runner register --registration-token $RUNNER_REGISTRATION_TOKEN <runner configuration arguments>` | + Authentication tokens have the prefix, `glrt-`. To ensure minimal disruption to your automation workflow, [legacy-compatible registration processing](https://docs.gitlab.com/runner/register/#legacy-compatible-registration-processing) -triggers if an authentication token is specified in the legacy parameter `--registration-token`. +triggers if a runner authentication token is specified in the legacy parameter `--registration-token`. Example command for GitLab 15.9: @@ -126,7 +133,7 @@ gitlab-runner register \ ## Impact on autoscaling In autoscaling scenarios such as GitLab Runner Operator or GitLab Runner Helm Chart, the -registration token is replaced with the authentication token generated from the UI. +registration token is replaced with the runner authentication token generated from the UI. This means that the same runner configuration is reused across jobs, instead of creating a runner for each job. The specific runner can be identified by the unique system ID that is generated when the runner @@ -138,33 +145,13 @@ Existing runners will continue to work as usual. This change only affects regist ## Creating runners programmatically -A new [POST /user/runners REST API](../../api/users.md#create-a-runner) was introduced in -GitLab 15.11, which allows a runner to be created in the context of an authenticated user. This should only be used in -scenarios where the runner configuration is dynamic, or not reusable. If the runner configuration is static, it is -preferable to reuse the authentication token of an existing runner. +In GitLab 15.11 and later, you can use the [POST /user/runners REST API](../../api/users.md#create-a-runner) +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. -The following snippet shows how a group runner could be created and registered with a -[Group Access Token](../../user/group/settings/group_access_tokens.md) using the new creation flow. -The process is very similar when using [Project Access Tokens](../../user/project/settings/project_access_tokens.md) -or [Personal Access Tokens](../../user/profile/personal_access_tokens.md): - -```shell -# `GROUP_ID` contains the numerical ID of the group where the runner will be created -# `GITLAB_TOKEN` can be a Personal Access Token for a group owner, or a Group Access Token on the respective group -# created with `owner` access and `api` scope. -# -# The output will be parsed by `jq` to extract the token of the newly created runner -RUNNER_TOKEN=$(curl --silent --request POST "https://gitlab.com/api/v4/user/runners" \ - --header "private-token: $GITLAB_TOKEN" \ - --data runner_type=group_type --data group_id=$GROUP_ID --data 'description=My runner' --data 'tag_list=java,linux' \ - | jq -r '.token') - -gitlab-runner register \ - --non-interactive \ - --executor "shell" \ - --url "https://gitlab.com/" \ - --token "$RUNNER_TOKEN" -``` +For instructions about how to automate runner creation and registration, see the tutorial, +[Automate runner creation and registration](../../tutorials/automate_runner_creation/index.md). ## Installing GitLab Runner with Helm chart @@ -185,7 +172,7 @@ runUntagged: true protected: true ``` -If you store the runner token in `secrets`, you must also modify them. +If you store the runner authentication token in `secrets`, you must also modify them. In the legacy runner registration workflow, fields were specified with: @@ -212,3 +199,7 @@ data: runner-registration-token: "" # need to leave as an empty string for compatibility reasons runner-token: "REDACTED" ``` + +NOTE: +If your secret management solution doesn't allow you to set an empty string for `runner-registration-token`, +you can set it to any string - it will be ignored when `runner-token` is present. diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index fff695eb606..c6387a60495 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -34,7 +34,7 @@ If you are using GitLab.com: - The shared runners consume the [compute minutes](../pipelines/cicd_minutes.md) included with your account. -### Create a shared runner with an authentication token +### Create a shared runner with a runner authentication token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383139) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_admin` [flag](../../administration/feature_flags.md) > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/389269) in GitLab 16.0. @@ -44,23 +44,32 @@ Prerequisite: - You must be an administrator. -When you create a runner, it is assigned an authentication token that you use to register it. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue. +When you create a runner, it is assigned a runner authentication token that you use to register it. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue. To create a shared runner: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **CI/CD > Runners**. 1. Select **New instance runner**. -1. Select a platform. -1. Optional. Enter configurations for the runner. -1. Select **Submit**. -1. Follow the on-screen instructions to register the runner from the command line. - -You can also [create a runner](../../api/users.md#create-a-runner) with the API to generate an authentication token. +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. + If there are no job tags for this runner, select **Run untagged**. +1. Optional. In the **Runner description** field, to add a runner description + that displays in GitLab, enter a runner description. +1. Optional. In the **Configuration** section, add additional configurations. +1. Select **Create runner**. +1. Follow the on-screen instructions to register the runner from the command line. When prompted by the command line: + - For the `GitLab instance URL`, use the URL for your GitLab instance. For example, if your project + is hosted on `gitlab.example.com/yourname/yourproject`, your GitLab instance URL is `https://gitlab.example.com`. + - 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. NOTE: -The authentication token displays in the UI for only a short period of time during registration. +The runner authentication token displays in the UI for a limited period of time during registration. After you register the runner, +the authentication token is stored in the `config.toml`. ### Create a shared runner with a registration token (deprecated) @@ -75,7 +84,7 @@ Prerequisite: To create a shared runner: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **CI/CD > Runners**. 1. Select **Register an instance runner**. @@ -90,7 +99,7 @@ Prerequisite: 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, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or filter the runner list. @@ -110,7 +119,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, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or filter the list of runners. @@ -134,7 +143,7 @@ For existing projects, an administrator must To enable shared runners for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. Turn on the **Enable shared runners for this project** toggle. @@ -143,7 +152,7 @@ To enable shared runners for a project: To enable shared runners for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. Turn on the **Enable shared runners for this group** toggle. @@ -156,7 +165,7 @@ or group. To disable shared runners for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. In the **Shared runners** area, turn off the **Enable shared runners for this project** toggle. @@ -170,7 +179,7 @@ Shared runners are automatically disabled for a project: To disable shared runners for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. Turn off the **Enable shared runners for this group** toggle. @@ -222,7 +231,7 @@ to have access to a set of runners. Group runners process jobs by using a first in, first out queue. -### Create a group runner with an authentication token +### Create a group runner with a runner authentication token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383143) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_namespace` [flag](../../administration/feature_flags.md). Disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/393919) in GitLab 16.0. @@ -233,22 +242,31 @@ Prerequisites: - You must have the Owner role for the group. You can create a group runner for your self-managed GitLab instance or for GitLab.com. -When you create a runner, it is assigned an authentication token that you use to register it. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue. +When you create a runner, it is assigned a runner authentication token that you use to register it. +The runner uses the token to authenticate with GitLab when it picks up jobs from the job queue. To create a group runner: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > Runners**. 1. Select **New group runner**. -1. Select a platform. -1. Optional. Enter configurations for the runner. -1. Select **Submit**. -1. Follow the on-screen instructions to register the runner from the command line. - -You can also [create a runner](../../api/users.md#create-a-runner) with the API to generate an authentication token. +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. + If there are no job tags for this runner, select **Run untagged**. +1. Optional. In the **Runner description** field, add a runner description + that displays in GitLab. +1. Optional. In the **Configuration** section, add additional configurations. +1. Select **Create runner**. +1. Follow the on-screen instructions to register the runner from the command line. When prompted by the command line: + - For the `GitLab instance URL`, use the URL for your GitLab instance. For example, if your project + is hosted on `gitlab.example.com/yourname/yourproject`, your GitLab instance URL is `https://gitlab.example.com`. + - 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. NOTE: -The authentication token displays in the UI for only a short period of time during registration. +The runner authentication token displays in the UI for only a short period of time during registration. ### Create a group runner with a registration token (deprecated) @@ -256,7 +274,7 @@ The authentication token displays in the UI for only a short period of time duri WARNING: The ability to pass a runner registration token, and support for certain configuration arguments was -[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. Authentication tokens +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 18.0. Authentication tokens should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). You must have the Owner role for the group. @@ -264,7 +282,7 @@ You must have the Owner role for the group. To create a group runner: 1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > Runners**. 1. In the upper-right corner, select **Register a group runner**. 1. Select **Show runner installation and registration instructions**. @@ -273,17 +291,20 @@ To create a group runner: Alternately, you can copy the registration token and follow the documentation for how to [register a runner](https://docs.gitlab.com/runner/register/). -### View and manage group runners +### View group runners + +> 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: + +- You must have the Maintainer or Owner role for the group. -You can view and manage all runners for a group, its subgroups, and projects. +You can view all runners for a group and its subgroups and projects. You can do this for your self-managed GitLab instance or for GitLab.com. -You must have the Owner role for the group. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > Runners**. -From this page, you can edit, pause, and remove runners from the group, its subgroups, and projects. - #### Filter group runners to show only inherited > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337838/) in GitLab 15.5. @@ -297,7 +318,7 @@ By default, only those that are inherited are shown. To show all runners available in the instance, including shared runners and those in other groups: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > Runners**. 1. Above the list, turn off the **Show only inherited** toggle. @@ -310,7 +331,7 @@ Prerequisite: You can pause a runner so that it does not accept jobs from subgroups and projects in the GitLab instance. If you pause a group runner that is used by multiple projects, the runner pauses for all projects. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > 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: @@ -331,7 +352,7 @@ jobs, you can [pause](#pause-or-resume-a-group-runner) the runner instead. To delete a single or multiple group runners: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > Runners**. 1. In the search box, enter the runner description or filter the list of runners. 1. Delete the group runner: @@ -344,11 +365,15 @@ To delete a single or multiple group runners: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363012) in GitLab 15.1. +Prerequisite: + +- You must have the Owner role for the group. + You can clean up group runners that have been inactive for more than three months. Group runners are those that were created at the group level. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. Turn on the **Enable stale runner cleanup** toggle. @@ -399,7 +424,7 @@ NOTE: Project runners do not get shared with forked projects automatically. A fork *does* copy the CI/CD settings of the cloned repository. -### Create a project runner with an authentication token +### Create a project runner with a runner authentication token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383143) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_namespace` [flag](../../administration/feature_flags.md). Disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/393919) in GitLab 16.0. @@ -409,23 +434,33 @@ Prerequisites: - You must have the Maintainer role for the project. -You can create a project runner for your self-managed GitLab instance or for GitLab.com. When you create a runner, it is assigned an authentication token that you use to register to the runner. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue. +You can create a project runner for your self-managed GitLab instance or for GitLab.com. When you create a runner, +it is assigned a runner authentication token that you use to register to the runner. The runner uses the token to +authenticate with GitLab when it picks up jobs from the job queue. To create a project runner: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand the **Runners** section. 1. Select **New project runner**. -1. Select a platform. -1. Optional. Enter configurations for the runner. -1. Select **Submit**. -1. Follow the on-screen instructions to register the runner from the command line. - -You can also [create a runner](../../api/users.md#create-a-runner) with the API to generate an authentication token. +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. + If there are no job tags for this runner, select **Run untagged**. +1. Optional. In the **Runner description** field, add a description for the runner + that displays in GitLab. +1. Optional. In the **Configuration** section, add additional configurations. +1. Select **Create runner**. +1. Follow the on-screen instructions to register the runner from the command line. When prompted by the command line: + - For the `GitLab instance URL`, use the URL for your GitLab instance. For example, if your project + is hosted on `gitlab.example.com/yourname/yourproject`, your GitLab instance URL is `https://gitlab.example.com`. + - 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. NOTE: -The authentication token displays in the UI for only a short period of time during registration. +The runner authentication token displays in the UI for only a short period of time during registration. ### Create a project runner with a registration token (deprecated) @@ -441,7 +476,7 @@ Prerequisite: To create a project runner: 1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to +1. On the left sidebar, select **Search or go to** and find the project where you want to use the runner. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. @@ -459,7 +494,7 @@ Prerequisite: You can pause a project runner so that it does not accept jobs from projects it's assigned to in the GitLab instance. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to +1. On the left sidebar, select **Search or go to** and find the project where you want to enable the runner. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. @@ -479,7 +514,7 @@ When you delete a project runner, it is permanently deleted from the GitLab inst no longer be used by projects. If you want to temporarily stop the runner from accepting jobs, you can [pause](#pause-or-resume-a-project-runner) the runner instead. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to +1. On the left sidebar, select **Search or go to** and find the project where you want to enable the runner. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. @@ -500,7 +535,7 @@ You must have at least the Maintainer role for: To enable a project runner for a project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to +1. On the left sidebar, select **Search or go to** and find the project where you want to enable the runner. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. @@ -520,7 +555,7 @@ but can also be changed later. To lock or unlock a project runner: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to +1. On the left sidebar, select **Search or go to** and find the project where you want to enable the runner. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. @@ -553,7 +588,7 @@ 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, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **CI/CD > Runners**. 1. Select **View metrics**. @@ -569,10 +604,10 @@ To determine which runners need to be upgraded: 1. View the list of runners: - For a group: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 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, expand the top-most chevron (**{chevron-down}**). + 1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. Select **CI/CD > Runners**. @@ -602,7 +637,7 @@ Prerequisite: To determine the IP address of a shared runner: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Admin Area**. 1. On the left sidebar, select **CI/CD > Runners**. 1. Find the runner in the table and view the **IP Address** column. diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index dd5381f3cd6..c026ccf3d22 100644 --- a/doc/ci/runners/saas/linux_saas_runner.md +++ b/doc/ci/runners/saas/linux_saas_runner.md @@ -29,7 +29,7 @@ The `small` machine type is set as default. If no [tag](../../yaml/index.md#tags the jobs will run on this default runner. All SaaS runners on Linux currently run on -[`n2d-standard`](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) gerneral-purpose compute from GCP. +[`n2d-standard`](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) general-purpose compute from GCP. The machine type and underlying processor type can change. Jobs optimized for a specific processor design could behave inconsistently. ## Container images diff --git a/doc/ci/runners/saas/macos/codesigning.md b/doc/ci/runners/saas/macos/codesigning.md deleted file mode 100644 index 7e70e984c7c..00000000000 --- a/doc/ci/runners/saas/macos/codesigning.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../macos_saas_runner.md' -remove_date: '2023-09-05' ---- - -This document was moved to [another location](../macos_saas_runner.md). - -<!-- This redirect file can be deleted after <2023-09-05>. --> -<!-- 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 -->
\ No newline at end of file diff --git a/doc/ci/runners/saas/macos/environment.md b/doc/ci/runners/saas/macos/environment.md deleted file mode 100644 index 7e70e984c7c..00000000000 --- a/doc/ci/runners/saas/macos/environment.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../macos_saas_runner.md' -remove_date: '2023-09-05' ---- - -This document was moved to [another location](../macos_saas_runner.md). - -<!-- This redirect file can be deleted after <2023-09-05>. --> -<!-- 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 -->
\ No newline at end of file diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index 44f99ed6ccc..1445ae58bd4 100644 --- a/doc/ci/runners/saas/macos_saas_runner.md +++ b/doc/ci/runners/saas/macos_saas_runner.md @@ -4,7 +4,7 @@ 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 --- -# SaaS runners on macOS (Beta) **(PREMIUM SAAS)** +# SaaS runners on macOS **(PREMIUM SAAS BETA)** SaaS runners on macOS are in [Beta](../../../policy/experiment-beta-support.md#beta) for open source programs and customers in Premium and Ultimate plans. @@ -38,28 +38,30 @@ in your `.gitlab-ci.yml` file. Each image runs a specific version of macOS and Xcode. -| VM image | Status | -|---------------------------|---------------| -| `macos-12-xcode-13` | `maintenance` | -| `macos-12-xcode-14` | `maintenance` | -| (none, awaiting macOS 13) | `beta` | +| VM image | Status | +|----------------------------|--------| +| `macos-12-xcode-13` | `GA` | +| `macos-12-xcode-14` | `GA` | +| `macos-13-xcode-14` | `Beta` | -NOTE: -If your job requires tooling or dependencies not available in our available images, those can only be installed in the job execution. +## Image update policy for macOS -## Image update policy +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 +a [full list of preinstalled software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/tree/main/toolchain). -GitLab expects to release new images based on this cadence: +GitLab provides `stable` and `latest` macOS images that follow different update patterns: -macOS updates: +- **Stable image:** The `stable` images and installed components are updated every release. Images without the `:latest` prefix are considered stable images. +- **Latest image:** The `latest` images are typically updated on a weekly cadence and use a `:latest` prefix in the image name. Using the `latest` image results in more regularly updated components and shorter update times for Homebrew or asdf. The `latest` images are used to test software components before releasing the components to the `stable` images. +By definition, the `latest` images are always Beta. +A `latest` image is not available. -- **For new OS versions:** When Apple releases a new macOS version to developers (like macOS `12`), GitLab will plan to release an image based on the OS within the next 30 business days. The image is considered `beta` and the contents of the image (including tool versions) are subject to change until the first patch release (`12.1`). The long-term name will not include `beta` (for example, `macos-12-xcode-13`), so customers are moved automatically out of beta over time. GitLab will try to minimize breaking changes between the first two minor versions but makes no guarantees. Tooling often gets critical bug fixes after the first public release of an OS version. +### Image release process -- **After the first patch release (`12.1`):** - - The image moves to `maintenance` mode. The tools GitLab builds into the image with Homebrew and asdf are frozen. GitLab continues making Xcode updates, security updates, and any non-breaking changes deemed necessary. - - The image for the previous OS version (`11`) moves to `frozen` mode. GitLab then does only unavoidable changes: security updates, runner version upgrades, and setting the production password. +When Apple releases a new macOS version, GitLab releases both `stable` and `latest` images based on the OS in the next release. Both images are Beta. -Both macOS and Xcode follow a yearly release cadence. As time goes on, GitLab increments their versions synchronously (meaning we build macOS 11 with Xcode 12, macOS 12 with Xcode 13, and so on). +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). ## Example `.gitlab-ci.yml` file diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index 8ec44b8c275..108388f22c8 100644 --- a/doc/ci/runners/saas/windows_saas_runner.md +++ b/doc/ci/runners/saas/windows_saas_runner.md @@ -4,7 +4,7 @@ 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 --- -# SaaS runners on Windows (Beta) **(FREE SAAS)** +# SaaS runners on Windows **(FREE SAAS BETA)** SaaS runner on Windows autoscale by launching virtual machines on the Google Cloud Platform. This solution uses an @@ -35,7 +35,7 @@ You can execute your job in one of the following Windows versions: | Version tag | Status | |----------------|---------------| -| `windows-1809` | `maintenance` | +| `windows-1809` | `Beta` | You can find a full list of available pre-installed software in the [pre-installed software documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/main/cookbooks/preinstalled-software/README.md). @@ -81,16 +81,15 @@ test: - echo "running scripts in the test job" ``` -## Limitations and known issues +## Known issues -- All the limitations mentioned in our [Beta definition](../../../policy/experiment-beta-support.md#beta). -- The average provisioning time for a new Windows VM is 5 minutes. - This means that you may notice slower build start times - on the Windows runner fleet during the beta. In a future - release we intend to update the autoscaler to enable - the pre-provisioning of virtual machines. This is intended to significantly reduce - the time it takes to provision a VM on the Windows fleet. You can - follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). +- For more information about support for Beta features, see [Beta](../../../policy/experiment-beta-support.md#beta). +- The average provisioning time for a new Windows virtual machine (VM) is five minutes, so + you might notice slower start times for builds on the Windows runner + fleet during the Beta. Updating the autoscaler to enable the pre-provisioning + of virtual machines is proposed in a future release. This update is intended to + significantly reduce the time it takes to provision a VM on the Windows fleet. + For more information, see [issue 32](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). - The Windows runner fleet may be unavailable occasionally for maintenance or updates. - The job may stay in a pending state for longer than the |