Document how to specify environment variables during manual pipeline run and more
This commit is contained in:
parent
d66d548ce2
commit
5d8adad87d
4 changed files with 57 additions and 37 deletions
|
@ -9,7 +9,7 @@ you may need to enable pipeline triggering in your project's
|
||||||
|
|
||||||
## Pipelines
|
## Pipelines
|
||||||
|
|
||||||
A pipeline is a group of [jobs][] that get executed in [stages][](batches).
|
A pipeline is a group of [jobs] that get executed in [stages].
|
||||||
All of the jobs in a stage are executed in parallel (if there are enough
|
All of the jobs in a stage are executed in parallel (if there are enough
|
||||||
concurrent [Runners]), and if they all succeed, the pipeline moves on to the
|
concurrent [Runners]), and if they all succeed, the pipeline moves on to the
|
||||||
next stage. If one of the jobs fails, the next stage is not (usually)
|
next stage. If one of the jobs fails, the next stage is not (usually)
|
||||||
|
@ -29,17 +29,17 @@ There are three types of pipelines that often use the single shorthand of "pipel
|
||||||
|
|
||||||
![Types of Pipelines](img/types-of-pipelines.svg)
|
![Types of Pipelines](img/types-of-pipelines.svg)
|
||||||
|
|
||||||
1. **CI Pipeline**: Build and test stages defined in `.gitlab-ci.yml`
|
1. **CI Pipeline**: Build and test stages defined in `.gitlab-ci.yml`.
|
||||||
2. **Deploy Pipeline**: Deploy stage(s) defined in `.gitlab-ci.yml` The flow of deploying code to servers through various stages: e.g. development to staging to production
|
1. **Deploy Pipeline**: Deploy stage(s) defined in `.gitlab-ci.yml` The flow of deploying code to servers through various stages: e.g. development to staging to production.
|
||||||
3. **Project Pipeline**: Cross-project CI dependencies [triggered via API][triggers], particularly for micro-services, but also for complicated build dependencies: e.g. api -> front-end, ce/ee -> omnibus.
|
1. **Project Pipeline**: Cross-project CI dependencies [triggered via API][triggers], particularly for micro-services, but also for complicated build dependencies: e.g. api -> front-end, ce/ee -> omnibus.
|
||||||
|
|
||||||
## Development workflows
|
## Development workflows
|
||||||
|
|
||||||
Pipelines accommodate several development workflows:
|
Pipelines accommodate several development workflows:
|
||||||
|
|
||||||
1. **Branch Flow** (e.g. different branch for dev, qa, staging, production)
|
1. **Branch Flow** (e.g. different branch for dev, qa, staging, production).
|
||||||
2. **Trunk-based Flow** (e.g. feature branches and single master branch, possibly with tags for releases)
|
1. **Trunk-based Flow** (e.g. feature branches and single master branch, possibly with tags for releases).
|
||||||
3. **Fork-based Flow** (e.g. merge requests come from forks)
|
1. **Fork-based Flow** (e.g. merge requests come from forks).
|
||||||
|
|
||||||
Example continuous delivery flow:
|
Example continuous delivery flow:
|
||||||
|
|
||||||
|
@ -57,6 +57,16 @@ Pipelines are defined in `.gitlab-ci.yml` by specifying [jobs] that run in
|
||||||
|
|
||||||
See the reference [documentation for jobs](yaml/README.md#jobs).
|
See the reference [documentation for jobs](yaml/README.md#jobs).
|
||||||
|
|
||||||
|
## Manually executing pipelines
|
||||||
|
|
||||||
|
Pipelines can be manually executed, with predefined or manually-specified [variables](variables/README.md).
|
||||||
|
|
||||||
|
To execute a pipeline manually:
|
||||||
|
|
||||||
|
1. Navigate to your project's **CI/CD > Pipelines**.
|
||||||
|
1. Click on the **Run Pipeline** button.
|
||||||
|
1. Select the branch to run the pipeline for and enter any environment variables required for the pipeline run.
|
||||||
|
|
||||||
## Seeing pipeline status
|
## Seeing pipeline status
|
||||||
|
|
||||||
You can find the current and historical pipeline runs under your project's
|
You can find the current and historical pipeline runs under your project's
|
||||||
|
@ -112,9 +122,9 @@ Then, there is the pipeline mini graph which takes less space and can give you a
|
||||||
quick glance if all jobs pass or something failed. The pipeline mini graph can
|
quick glance if all jobs pass or something failed. The pipeline mini graph can
|
||||||
be found when you visit:
|
be found when you visit:
|
||||||
|
|
||||||
- the pipelines index page
|
- The pipelines index page.
|
||||||
- a single commit page
|
- A single commit page.
|
||||||
- a merge request page
|
- A merge request page.
|
||||||
|
|
||||||
That way, you can see all related jobs for a single commit and the net result
|
That way, you can see all related jobs for a single commit and the net result
|
||||||
of each stage of your pipeline. This allows you to quickly see what failed and
|
of each stage of your pipeline. This allows you to quickly see what failed and
|
||||||
|
@ -142,9 +152,9 @@ jobs. Click to expand them.
|
||||||
The basic requirements is that there are two numbers separated with one of
|
The basic requirements is that there are two numbers separated with one of
|
||||||
the following (you can even use them interchangeably):
|
the following (you can even use them interchangeably):
|
||||||
|
|
||||||
- a space
|
- A space (` `)
|
||||||
- a slash (`/`)
|
- A slash (`/`)
|
||||||
- a colon (`:`)
|
- A colon (`:`)
|
||||||
|
|
||||||
>**Note:**
|
>**Note:**
|
||||||
More specifically, [it uses][regexp] this regular expression: `\d+[\s:\/\\]+\d+\s*`.
|
More specifically, [it uses][regexp] this regular expression: `\d+[\s:\/\\]+\d+\s*`.
|
||||||
|
@ -252,11 +262,12 @@ A strict security model is enforced when pipelines are executed on
|
||||||
The following actions are allowed on protected branches only if the user is
|
The following actions are allowed on protected branches only if the user is
|
||||||
[allowed to merge or push](../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings)
|
[allowed to merge or push](../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings)
|
||||||
on that specific branch:
|
on that specific branch:
|
||||||
- run **manual pipelines** (using Web UI or Pipelines API)
|
|
||||||
- run **scheduled pipelines**
|
- Run **manual pipelines** (using [Web UI](#manually-executing-pipelines) or Pipelines API).
|
||||||
- run pipelines using **triggers**
|
- Run **scheduled pipelines**.
|
||||||
- trigger **manual actions** on existing pipelines
|
- Run pipelines using **triggers**.
|
||||||
- **retry/cancel** existing jobs (using Web UI or Pipelines API)
|
- Trigger **manual actions** on existing pipelines.
|
||||||
|
- **Retry/cancel** existing jobs (using Web UI or Pipelines API).
|
||||||
|
|
||||||
**Variables** marked as **protected** are accessible only to jobs that
|
**Variables** marked as **protected** are accessible only to jobs that
|
||||||
run on protected branches, avoiding untrusted users to get unintended access to
|
run on protected branches, avoiding untrusted users to get unintended access to
|
||||||
|
|
|
@ -34,7 +34,7 @@ Some of the predefined environment variables are available only if a minimum
|
||||||
version of [GitLab Runner][runner] is used. Consult the table below to find the
|
version of [GitLab Runner][runner] is used. Consult the table below to find the
|
||||||
version of Runner required.
|
version of Runner required.
|
||||||
|
|
||||||
>**Note:**
|
NOTE: **Note:**
|
||||||
Starting with GitLab 9.0, we have deprecated some variables. Read the
|
Starting with GitLab 9.0, we have deprecated some variables. Read the
|
||||||
[9.0 Renaming](#9-0-renaming) section to find out their replacements. **You are
|
[9.0 Renaming](#9-0-renaming) section to find out their replacements. **You are
|
||||||
strongly advised to use the new variables as we will remove the old ones in
|
strongly advised to use the new variables as we will remove the old ones in
|
||||||
|
@ -109,7 +109,7 @@ To follow conventions of naming across GitLab, and to further move away from the
|
||||||
`build` term and toward `job` CI variables have been renamed for the 9.0
|
`build` term and toward `job` CI variables have been renamed for the 9.0
|
||||||
release.
|
release.
|
||||||
|
|
||||||
>**Note:**
|
NOTE: **Note:**
|
||||||
Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are
|
Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are
|
||||||
strongly advised to use the new variables as we will remove the old ones in
|
strongly advised to use the new variables as we will remove the old ones in
|
||||||
future GitLab releases.**
|
future GitLab releases.**
|
||||||
|
@ -131,7 +131,7 @@ future GitLab releases.**
|
||||||
|
|
||||||
## `.gitlab-ci.yml` defined variables
|
## `.gitlab-ci.yml` defined variables
|
||||||
|
|
||||||
>**Note:**
|
NOTE **Note:**
|
||||||
This feature requires GitLab Runner 0.5.0 or higher and GitLab CI 7.14 or higher.
|
This feature requires GitLab Runner 0.5.0 or higher and GitLab CI 7.14 or higher.
|
||||||
|
|
||||||
GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in the
|
GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in the
|
||||||
|
@ -215,9 +215,15 @@ Protected variables can be added by going to your project's
|
||||||
|
|
||||||
Once you set them, they will be available for all subsequent pipelines.
|
Once you set them, they will be available for all subsequent pipelines.
|
||||||
|
|
||||||
|
### Manually-specified variables
|
||||||
|
|
||||||
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/44059) in GitLab 10.8.
|
||||||
|
|
||||||
|
Variables can be specified for a single pipeline run when a [manual pipeline](../pipelines.md#manually-executing-pipelines) is created.
|
||||||
|
|
||||||
## Deployment variables
|
## Deployment variables
|
||||||
|
|
||||||
>**Note:**
|
NOTE: **Note:**
|
||||||
This feature requires GitLab CI 8.15 or higher.
|
This feature requires GitLab CI 8.15 or higher.
|
||||||
|
|
||||||
[Project services](../../user/project/integrations/project_services.md) that are
|
[Project services](../../user/project/integrations/project_services.md) that are
|
||||||
|
|
|
@ -8,10 +8,10 @@ This document describes where and how the different types of variables can be us
|
||||||
|
|
||||||
## Variables usage
|
## Variables usage
|
||||||
|
|
||||||
There are basically two places where you can use any defined variables:
|
There are two places defined variables can be used. On the:
|
||||||
|
|
||||||
1. On GitLab's side there's `.gitlab-ci.yml`
|
1. GitLab side, in `.gitlab-ci.yml`.
|
||||||
1. On the Runner's side there's `config.toml`
|
1. The runner side, in `config.toml`.
|
||||||
|
|
||||||
### `.gitlab-ci.yml` file
|
### `.gitlab-ci.yml` file
|
||||||
|
|
||||||
|
@ -56,8 +56,8 @@ since the expansion is done in GitLab before any Runner will get the job.
|
||||||
### GitLab Runner internal variable expansion mechanism
|
### GitLab Runner internal variable expansion mechanism
|
||||||
|
|
||||||
- **Supported:** project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and
|
- **Supported:** project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and
|
||||||
variables from triggers and pipeline schedules
|
variables from triggers, pipeline schedules, and manual pipelines.
|
||||||
- **Not supported:** variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`)
|
- **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
|
only variables defined as `$variable` and `${variable}`. What's also important, is that
|
||||||
|
@ -80,11 +80,10 @@ are using a different variables syntax.
|
||||||
`.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules).
|
`.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers and pipeline schedules).
|
||||||
- The `script` may also use all variables defined in the lines before. So, for example, if you define
|
- The `script` may also use all variables defined in the lines before. So, for example, if you define
|
||||||
a variable `export MY_VARIABLE="test"`:
|
a variable `export MY_VARIABLE="test"`:
|
||||||
|
- In `before_script`, it will work in the following lines of `before_script` and
|
||||||
- in `before_script`, it will work in the following lines of `before_script` and
|
all lines of the related `script`.
|
||||||
all lines of the related `script`
|
- In `script`, it will work in the following lines of `script`.
|
||||||
- in `script`, it will work in the following lines of `script`
|
- In `after_script`, it will work in following lines of `after_script`.
|
||||||
- in `after_script`, it will work in following lines of `after_script`
|
|
||||||
|
|
||||||
## Persisted variables
|
## Persisted variables
|
||||||
|
|
||||||
|
@ -107,7 +106,7 @@ The following variables are known as "persisted":
|
||||||
|
|
||||||
They are:
|
They are:
|
||||||
|
|
||||||
- **supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner"
|
- **Supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner".
|
||||||
- **not supported:**
|
- **Not supported:**
|
||||||
- by the definitions [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "GitLab"
|
- By the definitions [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "GitLab".
|
||||||
- in the `only` and `except` [variables expressions](README.md#variables-expressions)
|
- In the `only` and `except` [variables expressions](README.md#variables-expressions).
|
||||||
|
|
|
@ -157,6 +157,10 @@ into your `README.md`:
|
||||||
![coverage](https://gitlab.com/gitlab-org/gitlab-ce/badges/master/coverage.svg?job=coverage)
|
![coverage](https://gitlab.com/gitlab-org/gitlab-ce/badges/master/coverage.svg?job=coverage)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
[Environment variables](../../../ci/variables/README.html#variables) can be set in an environment to be available to a runner.
|
||||||
|
|
||||||
[var]: ../../../ci/yaml/README.md#git-strategy
|
[var]: ../../../ci/yaml/README.md#git-strategy
|
||||||
[coverage report]: #test-coverage-parsing
|
[coverage report]: #test-coverage-parsing
|
||||||
[timeout overriding]: ../../../ci/runners/README.html#setting-maximum-job-timeout-for-a-runner
|
[timeout overriding]: ../../../ci/runners/README.html#setting-maximum-job-timeout-for-a-runner
|
||||||
|
|
Loading…
Reference in a new issue