diff options
Diffstat (limited to 'doc/ci/runners')
| -rw-r--r-- | doc/ci/runners/configure_runners.md | 56 | ||||
| -rw-r--r-- | doc/ci/runners/runners_scope.md | 12 | ||||
| -rw-r--r-- | doc/ci/runners/saas/macos_saas_runner.md | 2 | ||||
| -rw-r--r-- | doc/ci/runners/saas/windows_saas_runner.md | 8 |
4 files changed, 59 insertions, 19 deletions
diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index d826b28acce..60e21653a45 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -160,7 +160,7 @@ the GitLab instance. To determine this: ### Determine the IP address of a specific runner To can find the IP address of a runner for a specific project, -you must have the [Owner role](../../user/permissions.md#project-members-permissions) for the +you must have the Owner role for the project. 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. @@ -187,7 +187,7 @@ the appropriate dependencies to run Rails test suites. 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](../../user/permissions.md#project-members-permissions) for the project. +To change this, you must have the Owner role for the project. To make a runner pick untagged jobs: @@ -291,6 +291,7 @@ globally or for individual jobs: - [`GIT_CHECKOUT`](#git-checkout) - [`GIT_CLEAN_FLAGS`](#git-clean-flags) - [`GIT_FETCH_EXTRA_FLAGS`](#git-fetch-extra-flags) +- [`GIT_SUBMODULE_UPDATE_FLAGS`](#git-submodule-update-flags) - [`GIT_DEPTH`](#shallow-cloning) (shallow cloning) - [`GIT_CLONE_PATH`](#custom-build-directories) (custom build directories) - [`TRANSFER_METER_FREQUENCY`](#artifact-and-cache-settings) (artifact/cache meter update frequency) @@ -331,10 +332,6 @@ try to preserve worktrees and try to re-use them by default. This has limitations when using the [Docker Machine executor](https://docs.gitlab.com/runner/executors/docker_machine.html). -It does not work for [the `kubernetes` executor](https://docs.gitlab.com/runner/executors/kubernetes.html), -but a [feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3847) exists. -The `kubernetes` executor always clones into an temporary directory. - A Git strategy of `none` also re-uses the local working copy, but skips all Git operations normally done by GitLab. GitLab Runner pre-clone scripts are also skipped, if present. This strategy could mean you need to add `fetch` and `checkout` commands @@ -382,6 +379,8 @@ For this feature to work correctly, the submodules must be configured - a relative path to another repository on the same GitLab server. See the [Git submodules](../git_submodules.md) documentation. +You can provide additional flags to control advanced behavior using [`GIT_SUBMODULE_UPDATE_FLAGS`](#git-submodule-update-flags). + ### Git checkout > Introduced in GitLab Runner 9.3. @@ -442,14 +441,14 @@ script: > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) in GitLab Runner 13.1. -The `GIT_FETCH_EXTRA_FLAGS` variable is used to control the behavior of +Use the `GIT_FETCH_EXTRA_FLAGS` variable to control the behavior of `git fetch`. You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section. `GIT_FETCH_EXTRA_FLAGS` accepts all options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command. However, `GIT_FETCH_EXTRA_FLAGS` flags are appended after the default flags that can't be modified. The default flags are: -- [GIT_DEPTH](#shallow-cloning). +- [`GIT_DEPTH`](#shallow-cloning). - The list of [refspecs](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec). - A remote called `origin`. @@ -475,6 +474,47 @@ git fetch origin $REFSPECS --depth 50 --prune Where `$REFSPECS` is a value provided to the runner internally by GitLab. +### Git submodule update flags + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3192) in GitLab Runner 14.8. + +Use the `GIT_SUBMODULE_UPDATE_FLAGS` variable to control the behavior of `git submodule update` +when [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) is set to either `normal` or `recursive`. +You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section. + +`GIT_SUBMODULE_UPDATE_FLAGS` accepts all options of the +[`git submodule update`](https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-update--init--remote-N--no-fetch--no-recommend-shallow-f--force--checkout--rebase--merge--referenceltrepositorygt--depthltdepthgt--recursive--jobsltngt--no-single-branch--ltpathgt82308203) +subcommand. However, note that `GIT_SUBMODULE_UPDATE_FLAGS` flags are appended after a few default flags: + +- `--init`, if [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) was set to `normal` or `recursive`. +- `--recursive`, if [`GIT_SUBMODULE_STRATEGY`](#git-submodule-strategy) was set to `recursive`. +- [`GIT_DEPTH`](#shallow-cloning). See the default value below. + +Git honors the last occurrence of a flag in the list of arguments, so manually +providing them in `GIT_SUBMODULE_UPDATE_FLAGS` will also override these default flags. + +You can use this variable to fetch the latest remote `HEAD` instead of the commit tracked, +in the repository, or to speed up the checkout by fetching submodules in multiple parallel jobs: + +```yaml +variables: + GIT_SUBMODULE_STRATEGY: recursive + GIT_SUBMODULE_UPDATE_FLAGS: --remote --jobs 4 +script: + - ls -al .git/modules/ +``` + +The configuration above results in `git submodule update` being called this way: + +```shell +git submodule update --init --depth 50 --recursive --remote --jobs 4 +``` + +WARNING: +You should be aware of the implications for the security, stability, and reproducibility of +your builds when using the `--remote` flag. In most cases, it is better to explicitly track +submodule commits as designed, and update them using an auto-remediation/dependency bot. + ### Shallow cloning > Introduced in GitLab 8.9 as an experimental feature. diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index f76a767abec..7cfd8e50f6c 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -55,7 +55,7 @@ To enable shared runners: ### Disable shared runners You can disable shared runners for individual projects or for groups. -You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the project +You must have the Owner role for the project or group. To disable shared runners for a project: @@ -144,7 +144,7 @@ Group runners process jobs by using a first in, first out ([FIFO](https://en.wik ### Create a group runner You can create a group runner for your self-managed GitLab instance or for GitLab.com. -You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the group. +You must have the Owner role for the group. To create a group runner: @@ -160,7 +160,7 @@ To create a group runner: You can view and manage all runners for a group, its subgroups, and projects. You can do this for your self-managed GitLab instance or for GitLab.com. -You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the group. +You must have the Owner role for the group. 1. Go to the group where you want to view the runners. 1. Go to **Settings > CI/CD** and expand the **Runners** section. @@ -183,7 +183,7 @@ From this page, you can edit, pause, and remove runners from the group, its subg ### Pause or remove a group runner You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com. -You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the group. +You must have the Owner role for the group. 1. Go to the group you want to remove or pause the runner for. 1. Go to **Settings > CI/CD** and expand the **Runners** section. @@ -213,7 +213,7 @@ A fork *does* copy the CI/CD settings of the cloned repository. ### Create a specific runner You can create a specific runner for your self-managed GitLab instance or for GitLab.com. -You must have the [Owner role](../../user/permissions.md#project-members-permissions) for the project. +You must have the Owner role for the project. To create a specific runner: @@ -227,7 +227,7 @@ To create a specific runner: A specific runner is available in the project it was created for. An administrator can enable a specific runner to apply to additional projects. -- You must have the [Owner role](../../user/permissions.md#group-members-permissions) for the +- You must have the Owner role for the project. - The specific runner must not be [locked](#prevent-a-specific-runner-from-being-enabled-for-other-projects). diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index 40c4deb51aa..bfe408f4485 100644 --- a/doc/ci/runners/saas/macos_saas_runner.md +++ b/doc/ci/runners/saas/macos_saas_runner.md @@ -12,7 +12,7 @@ Use these runners to build, test, and deploy apps for the Apple ecosystem (macOS of all the capabilities of the GitLab single DevOps platform and not have to manage or operate a build environment. -SaaS runners on macOS are in [Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +SaaS runners on macOS are in [Beta](../../../policy/alpha-beta-support.md#beta-features) and shouldn't be relied upon for mission-critical production jobs. ## Quickstart diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index b08be14dbc3..dddb3afee7c 100644 --- a/doc/ci/runners/saas/windows_saas_runner.md +++ b/doc/ci/runners/saas/windows_saas_runner.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SaaS runners on Windows (beta) **(FREE SAAS)** -SaaS runners on Windows are in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +SaaS runners on Windows are in [beta](../../../policy/alpha-beta-support.md#beta-features) and shouldn't be used for production workloads. During this beta period, the [shared runner quota for CI/CD minutes](../../pipelines/cicd_minutes.md) @@ -15,14 +15,14 @@ change when the beta period ends, as discussed in this [related issue](https://g Windows runners on GitLab.com autoscale by launching virtual machines on the Google Cloud Platform. This solution uses an -[autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md) +[autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/blob/main/docs/README.md) developed by GitLab for the [custom executor](https://docs.gitlab.com/runner/executors/custom.html). Windows runners execute your CI/CD jobs on `n1-standard-2` instances with 2 vCPUs and 7.5 GB RAM. You can find a full list of available Windows packages in the [package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/main/cookbooks/preinstalled-software/README.md). We want to keep iterating to get Windows runners in a stable state and -[generally available](https://about.gitlab.com/handbook/product/gitlab-the-product/#generally-available-ga). +[generally available](../../../policy/alpha-beta-support.md#generally-available-ga). You can follow our work towards this goal in the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/2162). @@ -127,7 +127,7 @@ test: ## Limitations and known issues - All the limitations mentioned in our [beta - definition](https://about.gitlab.com/handbook/product/#beta). + definition](../../../policy/alpha-beta-support.md#beta-features). - 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 |