From c50eefe87afeeb6e79586a5ee5f34e8c99563325 Mon Sep 17 00:00:00 2001 From: Kevin Nowald Date: Wed, 4 Sep 2024 16:56:01 +0200 Subject: [PATCH] docs: clarify gitlab_runner_registration_token requirement --- README.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 7997f9d..31feb15 100644 --- a/README.md +++ b/README.md @@ -12,25 +12,27 @@ This role requires Ansible 2.13 or higher. Role Variables -------------- -- `gitlab_runner_package_name` - **Since Gitlab 10.x** The package name of `gitlab-ci-multi-runner` has been renamed to `gitlab-runner`. In order to install a version < 10.x you will need to define this variable `gitlab_runner_package_name: gitlab-ci-multi-runner`. -- `gitlab_runner_wanted_version` or `gitlab_runner_package_version` - To install a specific version of the gitlab runner (by default it installs the latest). -On Mac OSX and Windows, use e.g. `gitlab_runner_wanted_version: 12.4.1`. -On Linux, use `gitlab_runner_package_version` instead. -- `gitlab_runner_concurrent` - The maximum number of global jobs to run concurrently. Defaults to the number of processor cores. -- `gitlab_runner_registration_token` - The GitLab registration token. If this is specified, each runner will be registered to a GitLab server. Deprecating in gitlab version 16.0 and removed in 18.0. -- `gitlab_runner_registration_token_type` - Gitlab runner registration token type -Set "authentication-token" to register runner with --token option (new workflow https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html) -Set "registration-token" to register runner with --registration-token option (deprecating in gitlab 16.0 but still usable and deleted in 18.0) -For gitlab version >= 16.0 it is advisable to specify token for each runner in 'gitlab_runner_runners' section and set this variable to "authentication-token". +- `gitlab_runner_package_name` - **As of GitLab 10.x**, the package name `gitlab-ci-multi-runner` has been renamed to `gitlab-runner`. To install a version earlier than 10.x, define the variable `gitlab_runner_package_name: gitlab-ci-multi-runner`. +- `gitlab_runner_wanted_version` or `gitlab_runner_package_version` - Use these to install a specific version of the GitLab Runner (by default, the latest version is installed). + - On macOS and Windows, use `gitlab_runner_wanted_version: 12.4.1` (example). + - On Linux, use `gitlab_runner_package_version` instead. +- `gitlab_runner_concurrent` - Defines the maximum number of jobs that can run concurrently. Defaults to the number of processor cores. +- `gitlab_runner_registration_token` - The GitLab registration token. If specified, this will register each runner with a GitLab server. **Note**: This token can only be used globally if `gitlab_runner_registration_token_type` is set to the deprecated `registration-token`. Otherwise, you must specify a `token` for each item in `gitlab_runner_runners`, as shown in the example playbook below. This token is deprecated in GitLab version 16.0 and will be removed in version 18.0. +- `gitlab_runner_registration_token_type` - Specifies the type of registration token to use for GitLab Runner registration: + - Set to "authentication-token" to register the runner with the `--token` option (following the new workflow: https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html). + - Set to "registration-token" to register the runner with the `--registration-token` option. This is deprecated in GitLab 16.0 but remains usable until it is removed in version 18.0. + - For GitLab version 16.0 and above, it is recommended to specify a token for each runner in the `gitlab_runner_runners` section and set this variable to "authentication-token". - `gitlab_runner_coordinator_url` - The GitLab coordinator URL. Defaults to `https://gitlab.com`. -- `gitlab_runner_sentry_dsn` - Enable tracking of all system level errors to Sentry -- `gitlab_runner_listen_address` - Enable `/metrics` endpoint for Prometheus scraping. -- `gitlab_runner_runners` - A list of gitlab runners to register & configure. Defaults to a single shell executor. -- `gitlab_runner_skip_package_repo_install`- Skip the APT or YUM repository installation (by default, false). You should provide a repository containing the needed packages before running this role. -- `gitlab_runner_config_update_mode`- Set to `by_config_toml` (default) if this role should apply config changes by updating the `config.toml` itself or set it to `by_registering` if config changes should be applied by unregistering and regeistering the runner in case the config has changed. -- `gitlab_unregister_runner_executors_which_are_not_longer_configured` - Set to `true` if executors should be unregistered from a runner in case it is are not longer configured in ansible. Default: `false` - -See the [`defaults/main.yml`](https://github.com/riemers/ansible-gitlab-runner/blob/master/defaults/main.yml) file listing all possible options which you can be passed to a runner registration command. +- `gitlab_runner_sentry_dsn` - Enables tracking of system-level errors to Sentry. +- `gitlab_runner_listen_address` - Enables the `/metrics` endpoint for Prometheus scraping. +- `gitlab_runner_runners` - A list of GitLab runners to register and configure. By default, this is set to a single shell executor. +- `gitlab_runner_skip_package_repo_install` - Skips the installation of the APT or YUM repository (default: false). You should ensure that the necessary packages are available in your repository before running this role. +- `gitlab_runner_config_update_mode` - Defines how configuration updates are applied: + - Set to `by_config_toml` (default) to apply configuration changes directly by updating the `config.toml` file. + - Set to `by_registering` if changes should be applied by unregistering and re-registering the runner when configuration changes. +- `gitlab_unregister_runner_executors_which_are_not_longer_configured` - Set to `true` if executors should be unregistered from a runner when they are no longer configured in Ansible. Default: `false`. + +See the [defaults/main.yml](https://github.com/riemers/ansible-gitlab-runner/blob/master/defaults/main.yml) file for a list of all possible options that can be passed to a runner registration command. ### Gitlab Runners cache For each gitlab runner in gitlab_runner_runners you can set cache options. At the moment role support s3, azure and gcs types.