Commit 255d4edf authored by Evan Read's avatar Evan Read

Merge branch 'selhorn-runner-4' into 'master'

Docs: Updated capitalization of runner

See merge request gitlab-org/gitlab!40047
parents b3f5fa02 97a12e11
......@@ -80,7 +80,7 @@ Once you're familiar with how GitLab CI/CD works, see the
for all the attributes you can set and use.
NOTE: **Note:**
GitLab CI/CD and [shared runners](runners/README.md#shared-runners) are enabled in GitLab.com and available for all users, limited only to the [user's pipelines quota](../user/gitlab_com/index.md#shared-runners).
GitLab CI/CD and [shared runners](runners/README.md#shared-runners) are enabled on GitLab.com and available for all users, limited only by the [pipeline quota](../user/gitlab_com/index.md#shared-runners).
## Concepts
......@@ -93,7 +93,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy
| [Environments](environments/index.md) | Deploy your application to different environments (e.g., staging, production). |
| [Job artifacts](pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. |
| [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. |
| [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own GitLab Runners to execute your scripts. |
| [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own runners to execute your scripts. |
## Configuration
......@@ -108,7 +108,7 @@ GitLab CI/CD supports numerous configuration options:
| [Pipeline triggers](triggers/README.md) | Trigger pipelines through the API. |
| [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. |
| [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. |
| [Optimize GitLab and Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repositories. |
| [Optimize GitLab and GitLab Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repositories. |
| [`.gitlab-ci.yml` full reference](yaml/README.md) | All the attributes you can use with GitLab CI/CD. |
Note that certain operations can only be performed according to the
......
......@@ -59,7 +59,7 @@ The rest of this section illustrates how to configure environments and deploymen
an example scenario. It assumes you have already:
- Created a [project](../../gitlab-basics/create-project.md) in GitLab.
- Set up [a Runner](../runners/README.md).
- Set up [a runner](../runners/README.md).
In the scenario:
......@@ -138,9 +138,9 @@ In summary, with the above `.gitlab-ci.yml` we have achieved the following:
job will deploy our code to a staging server while the deployment
will be recorded in an environment named `staging`.
#### Environment variables and Runner
#### Environment variables and runners
Starting with GitLab 8.15, the environment name is exposed to the Runner in
Starting with GitLab 8.15, the environment name is exposed to the runner in
two forms:
- `$CI_ENVIRONMENT_NAME`. The name given in `.gitlab-ci.yml` (with any variables
......@@ -154,7 +154,7 @@ If you change the name of an existing environment, the:
- `$CI_ENVIRONMENT_SLUG` variable will remain unchanged to prevent unintended side
effects.
Starting with GitLab 9.3, the environment URL is exposed to the Runner via
Starting with GitLab 9.3, the environment URL is exposed to the runner via
`$CI_ENVIRONMENT_URL`. The URL is expanded from either:
- `.gitlab-ci.yml`.
......@@ -317,14 +317,14 @@ including:
However, you cannot use variables defined:
- Under `script`.
- On the Runner's side.
- On the runner's side.
There are also other variables that are unsupported in the context of `environment:name`.
For more information, see [Where variables can be used](../variables/where_variables_can_be_used.md).
#### Example configuration
GitLab Runner exposes various [environment variables](../variables/README.md) when a job runs, so
Runners expose various [environment variables](../variables/README.md) when a job runs, so
you can use them as environment names.
In the following example, the job will deploy to all branches except `master`:
......@@ -525,7 +525,7 @@ The complete example provides the following workflow to developers:
- Push the branch to GitLab.
- Create a merge request.
Behind the scenes, GitLab Runner will:
Behind the scenes, the runner will:
- Pick up the changes and start running the jobs.
- Run the jobs sequentially as defined in `stages`:
......@@ -700,7 +700,7 @@ stop_review:
```
Setting the [`GIT_STRATEGY`](../yaml/README.md#git-strategy) to `none` is necessary in the
`stop_review` job so that the [GitLab Runner](https://docs.gitlab.com/runner/) won't
`stop_review` job so that the [runner](https://docs.gitlab.com/runner/) won't
try to check out the code after the branch is deleted.
When you have an environment that has a stop action defined (typically when
......
......@@ -26,7 +26,7 @@ terminals are available when using your own group or project runner.
Two things need to be configured for the interactive web terminal to work:
- The Runner needs to have [`[session_server]` configured
- The runner needs to have [`[session_server]` configured
properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section)
- If you are using a reverse proxy with your GitLab instance, web terminals need to be
[enabled](../../administration/integration/terminal.md#enabling-and-disabling-terminal-support)
......
......@@ -41,7 +41,7 @@ This significantly speeds up fetching of changes from Git repositories,
especially if the repository has a very long backlog consisting of number
of big files as we effectively reduce amount of data transfer.
The following example makes GitLab Runner shallow clone to fetch only a given branch;
The following example makes the runner shallow clone to fetch only a given branch;
it does not fetch any other branches nor tags.
```yaml
......@@ -226,15 +226,15 @@ with other concurrent jobs running.
### Store custom clone options in `config.toml`
Ideally, all job-related configuration should be stored in `.gitlab-ci.yml`.
However, sometimes it is desirable to make these schemes part of Runner configuration.
However, sometimes it is desirable to make these schemes part of the runner's configuration.
In the above example of Forks, making this configuration discoverable for users may be preferred,
but this brings administrative overhead as the `.gitlab-ci.yml` needs to be updated for each branch.
In such cases, it might be desirable to keep the `.gitlab-ci.yml` clone path agnostic, but make it
a configuration of Runner.
a configuration of the runner.
We can extend our [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html)
with the following specification that will be used by Runner if `.gitlab-ci.yml` will not override it:
with the following specification that will be used by the runner if `.gitlab-ci.yml` will not override it:
```toml
concurrent = 4
......@@ -255,7 +255,7 @@ concurrent = 4
volumes = ["/builds:/builds", "/cache:/cache"]
```
This makes the cloning configuration to be part of given Runner
This makes the cloning configuration to be part of the given runner
and does not require us to update each `.gitlab-ci.yml`.
## Pre-clone step
......
......@@ -22,7 +22,7 @@ Pipelines comprise:
- Jobs, which define *what* to do. For example, jobs that compile or test code.
- Stages, which define *when* to run the jobs. For example, stages that run tests after stages that compile the code.
Jobs are executed by [Runners](../runners/README.md). Multiple jobs in the same stage are executed in parallel,
Jobs are executed by [runners](../runners/README.md). Multiple jobs in the same stage are executed in parallel,
if there are enough concurrent runners.
If *all* jobs in a stage succeed, the pipeline moves on to the next stage.
......@@ -562,5 +562,5 @@ To illustrate its life cycle:
which retains the checkout-SHA of the associated pipeline record.
This persistent ref stays intact during the pipeline execution,
even if the commit history of the `example` branch has been overwritten by force-push.
1. GitLab Runner fetches the persistent pipeline ref and gets source code from the checkout-SHA.
1. The runner fetches the persistent pipeline ref and gets source code from the checkout-SHA.
1. When the pipeline finished, its persistent ref is cleaned up in a background process.
......@@ -57,12 +57,12 @@ The default value is 60 minutes. Decrease the time limit if you want to impose
a hard limit on your jobs' running time or increase it otherwise. In any case,
if the job surpasses the threshold, it is marked as failed.
### Timeout overriding on Runner level
### Timeout overriding for runners
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17221) in GitLab 10.7.
Project defined timeout (either specific timeout set by user or the default
60 minutes timeout) may be [overridden on Runner level](../runners/README.md#set-maximum-job-timeout-for-a-runner).
60 minutes timeout) may be [overridden for runners](../runners/README.md#set-maximum-job-timeout-for-a-runner).
## Maximum artifacts size **(CORE ONLY)**
......
......@@ -35,15 +35,15 @@ You can call issue numbers, user names, branch names,
pipeline and commit IDs, and much more.
Predefined environment variables are provided by GitLab
for the local environment of the Runner.
for the local environment of the runner.
GitLab reads the `.gitlab-ci.yml` file and sends the information
to the Runner, where the variables are exposed. The Runner then runs the script commands.
to the runner, where the variables are exposed. The runner then runs the script commands.
### Use predefined environment variables
You can choose one of the existing predefined variables
to be output by the Runner.
to be output by the runner.
This example shows how to output a job's stage by using the predefined variable `CI_JOB_STAGE`.
......@@ -57,7 +57,7 @@ test_variable:
- echo $CI_JOB_STAGE
```
In this case, the Runner outputs the `stage` for the
In this case, the runner outputs the `stage` for the
job `test_variable`, which is `test`:
![Output `$CI_JOB_STAGE`](img/ci_job_stage_output_example.png)
......@@ -84,7 +84,7 @@ When you need a specific custom environment variable, you can
[set it up in the UI](#create-a-custom-variable-in-the-ui), in [the API](../../api/project_level_variables.md),
or directly [in the `.gitlab-ci.yml` file](#create-a-custom-variable-in-gitlab-ciyml).
The variables are used by the Runner any time the pipeline runs.
The variables are used by the runner any time the pipeline runs.
You can also [override variable values manually for a specific pipeline](../pipelines/index.md#specifying-variables-when-running-manual-jobs).
There are two types of variables: **Variable** and **File**. You cannot set types in
......@@ -145,7 +145,7 @@ The output is:
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11.
For variables with the type **Variable**, the Runner creates an environment variable
For variables with the type **Variable**, the runner creates an environment variable
that uses the key for the name and the value for the value.
There are [some predefined variables](#custom-variables-validated-by-gitlab) of this type,
......@@ -155,8 +155,8 @@ which may be further validated. They appear when you add or update a variable in
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11.
For variables with the type **File**, the Runner creates an environment variable that uses the key for the name.
For the value, the Runner writes the variable value to a temporary file and uses this path.
For variables with the type **File**, the runner creates an environment variable that uses the key for the name.
For the value, the runner writes the variable value to a temporary file and uses this path.
You can use tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)
and [`kubectl`](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable)
......@@ -250,7 +250,7 @@ All variables are set as environment variables in the build environment, and
they are accessible with normal methods that are used to access such variables.
In most cases `bash` or `sh` is used to execute the job script.
To access environment variables, use the syntax for your Runner's [shell](https://docs.gitlab.com/runner/executors/).
To access environment variables, use the syntax for your runner's [shell](https://docs.gitlab.com/runner/executors/).
| Shell | Usage |
|----------------------|------------------------------------------|
......@@ -445,7 +445,7 @@ To add an instance-level variable:
1. Click the **Add variable** button, and fill in the details:
- **Key**: Must be one line, using only letters, numbers, or `_` (underscore), with no spaces.
- **Value**: [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected Runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed.
- **Value**: [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed.
- **Type**: `File` or `Variable`.
- **Protect variable** (Optional): If selected, the variable is only available in pipelines that run on protected branches or tags.
- **Mask variable** (Optional): If selected, the variable's **Value** is not shown in job logs. The variable is not saved if the value does not meet the [masking requirements](#masked-variable-requirements).
......@@ -608,7 +608,7 @@ Choose the branch you want to run the pipeline for, then add a variable and its
![Override variable value](img/override_variable_manual_pipeline.png)
The Runner overrides the value previously set and uses the custom
The runner overrides the value previously set and uses the custom
value for this specific pipeline.
![Manually overridden variable output](img/override_value_via_manual_pipeline_output.png)
......@@ -825,7 +825,7 @@ output **will** contain the content of all your variables and any other
secrets! The output **will** be uploaded to the GitLab server and made visible
in job logs!
By default, GitLab Runner hides most of the details of what it is doing when
By default, the runner hides most of the details of what it is doing when
processing a job. This behavior keeps job logs short, and prevents secrets
from being leaked into the log unless your script writes them to the screen.
......
......@@ -12,7 +12,7 @@ For an introduction on this subject, read through the
Some of the predefined environment variables are available only if a minimum
version of [GitLab Runner](https://docs.gitlab.com/runner/) is used. Consult the table below to find the
version of Runner required.
version of GitLab Runner that's required.
NOTE: **Note:**
Starting with GitLab 9.0, we have deprecated some variables. Read the
......@@ -119,7 +119,7 @@ Kubernetes-specific environment variables are detailed in the
| `CI_RUNNER_EXECUTABLE_ARCH` | all | 10.6 | The OS/architecture of the GitLab Runner executable (note that this is not necessarily the same as the environment of the executor) |
| `CI_RUNNER_ID` | 8.10 | 0.5 | The unique ID of runner being used |
| `CI_RUNNER_REVISION` | all | 10.6 | GitLab Runner revision that is executing the current job |
| `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | First eight characters of GitLab Runner's token used to authenticate new job requests. Used as Runner's unique ID |
| `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | First eight characters of GitLab Runner's token used to authenticate new job requests. Used as runner's unique ID |
| `CI_RUNNER_TAGS` | 8.10 | 0.5 | The defined runner tags |
| `CI_RUNNER_VERSION` | all | 10.6 | GitLab Runner version that is executing the current job |
| `CI_SERVER` | all | all | Mark that job is executed in CI environment |
......
......@@ -18,13 +18,13 @@ This document describes where and how the different types of variables can be us
There are two places defined variables can be used. On the:
1. GitLab side, in `.gitlab-ci.yml`.
1. The runner side, in `config.toml`.
1. The GitLab Runner side, in `config.toml`.
### `.gitlab-ci.yml` file
| Definition | Can be expanded? | Expansion place | Description |
|:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in Runner's `config.toml` and variables created in job's `script`. |
| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. |
| `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). |
| `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). |
| `variables` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
......@@ -39,13 +39,13 @@ There are two places defined variables can be used. On the:
### `config.toml` file
NOTE: **Note:**
You can read more about `config.toml` in the [Runner's docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html).
You can read more about `config.toml` in the [GitLab Runner docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html).
| Definition | Can be expanded? | Description |
|:-------------------------------------|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------|
| `runners.environment` | yes | The variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.kubernetes.pod_labels` | yes | The Variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.kubernetes.pod_annotations` | yes | The Variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.environment` | yes | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.kubernetes.pod_labels` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
| `runners.kubernetes.pod_annotations` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) |
## Expansion mechanisms
......@@ -59,7 +59,7 @@ There are three expansion mechanisms:
The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`.
Each form is handled in the same way, no matter which OS/shell will finally handle the job,
since the expansion is done in GitLab before any Runner will get the job.
since the expansion is done in GitLab before any runner will get the job.
### GitLab Runner internal variable expansion mechanism
......@@ -67,7 +67,7 @@ since the expansion is done in GitLab before any Runner will get the job.
variables from triggers, pipeline schedules, and manual pipelines.
- Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`).
The Runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle
The runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle
only variables defined as `$variable` and `${variable}`. What's also important, is that
the expansion is done only once, so nested variables may or may not work, depending on the
ordering of variables definitions.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment