Follow-up from "Draft: Add missing runner variables to predefined list"

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Work on this issue
• Close this issue

There are three variables that are undocumented, and we need to find a place (within the runner docs, it seems), to document them.

The key details from the discussion at !83972 (comment 894590345) wtih @tmaczukin:

1. They are not predefined variables. They are configuration variables just like for example RUNNER_EXECUTOR. We encourage everyone to configure things through config.toml but in theory you could provide a lot of settings through environment variables when starting GitLab Runner process - this is how our CLI library works.

   The variables are mostly useful when registering a new runner, as you can provide different configuration values with flags (e.g., gitlab-runner register ... --executor docker ...) or by preparing an environment variable before calling registration command (e.g., RUNNER_EXECUTOR=docker; gitlab-runner register ...). We take usage of this in our Helm Chart where most of the settings for registration are prepared with the environment variables and only few of them are configured explicitly by CLI flags.

2. These variables are also used internally by the runner to pass specific configuration to the job execution environment. This is what's described at https://docs.gitlab.com/runner/configuration/tls-self-signed.html page that you've linked.

   The only things that these variables have in common with predefined variables is that they are exported in the job environment and their names start with CI_ (which given this discussion seems to be a bad choice for the name, but changing it now would be probably too complicated).

   But again - these are not predefined variables understood in the same way as for example CI_RUNNER_VERSION, CI_PROJECT_PATH or CI_REPOSITORY_URL. Predefined variables are exported in favor of the user, so that the user may take usage of them in the job scripting. This is the main purpose. CI_SERVER_TLS_* main reason of existence was totally different 🙂

3. Having said all of that, I see that CI_SERVER_TLS_CA_FILE was already in the table, which I haven't noticed previously.

   I have a mixed feelings about this. The nature of these variables is different than the other predefined variables. But from the other side - they are available for the user in the job execution, and who knows - maybe someone makes usage of them?

   So while the main purpose of having these variables is to configure runner itself and to pass some configuration from Runner to job environment for the purpose of configuring git and gitlab-runner-helper - maybe it's worth documenting it? 🤔

   The biggest problem I thin is that these variables are conditional. Variables like CI_SERVER_PORT or CI_REPOSITORY_URL are filled-up always. CI_SERVER_TLS_CA_FILE however will be present only if it was explicitly configured in Runner's configuration or if job's GitLab instance itself is using HTTPS (in that case, even if not configured, Runner will discover that fact and will build a CA verification chain basing on the HTTP response). CI_SERVER_TLS_CERT_FILE and CI_SERVER_TLS_KEY_FILE will be present only if configured by the Runner administrator.

   The table for now contains name of the variable, mention of GitLab and GitLab Runner versions where the variable is present and it's description. Any idea how we could clearly mark the conditional nature of these variables?