diff options
Diffstat (limited to 'doc/ci/runners/runners_scope.md')
| -rw-r--r-- | doc/ci/runners/runners_scope.md | 151 |
1 files changed, 93 insertions, 58 deletions
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. |