Commit b16dd6f0 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'specify-variables-manual-pipeline' into 'master'

Document how to specify environment variables during manual pipeline run and more

Closes #46364

See merge request gitlab-org/gitlab-ce!21548
parents d66d548c 5d8adad8
...@@ -9,7 +9,7 @@ you may need to enable pipeline triggering in your project's ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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. ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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.** ...@@ -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 ...@@ -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
...@@ -567,4 +573,4 @@ Below you can find supported syntax reference: ...@@ -567,4 +573,4 @@ Below you can find supported syntax reference:
[builds-policies]: ../yaml/README.md#only-and-except-complex [builds-policies]: ../yaml/README.md#only-and-except-complex
[gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token [gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token
[registry]: ../../user/project/container_registry.md [registry]: ../../user/project/container_registry.md
[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories [dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories
\ No newline at end of file
...@@ -8,10 +8,10 @@ This document describes where and how the different types of variables can be us ...@@ -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. ...@@ -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. ...@@ -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": ...@@ -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`: ...@@ -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
......
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