Commit fe089f30 authored by Evan Read's avatar Evan Read Committed by Achilleas Pipinellis
Browse files

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

parent 8f91a59a7c61
......@@ -9,7 +9,7 @@ you may need to enable pipeline triggering in your project's
## 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
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)
......@@ -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)
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
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. **CI Pipeline**: Build and test stages defined in `.gitlab-ci.yml`.
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.
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
Pipelines accommodate several development workflows:
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)
3. **Fork-based Flow** (e.g. merge requests come from forks)
1. **Branch Flow** (e.g. different branch for dev, qa, staging, production).
1. **Trunk-based Flow** (e.g. feature branches and single master branch, possibly with tags for releases).
1. **Fork-based Flow** (e.g. merge requests come from forks).
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).
## 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
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
be found when you visit:
- the pipelines index page
- a single commit page
- a merge request page
- The pipelines index page.
- A single commit page.
- A merge request page.
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
......@@ -142,9 +152,9 @@ jobs. Click to expand them.
The basic requirements is that there are two numbers separated with one of
the following (you can even use them interchangeably):
- a space
- a slash (`/`)
- a colon (`:`)
- A space (` `)
- A slash (`/`)
- A colon (`:`)
>**Note:**
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
[allowed to merge or push](../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings)
on that specific branch:
- run **manual pipelines** (using Web UI or Pipelines API)
- run **scheduled pipelines**
- run pipelines using **triggers**
- trigger **manual actions** on existing pipelines
- **retry/cancel** existing jobs (using Web UI or Pipelines API)
- Run **manual pipelines** (using [Web UI](#manually-executing-pipelines) or Pipelines API).
- Run **scheduled pipelines**.
- Run pipelines using **triggers**.
- 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
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 Runner required.
>**Note:**
NOTE: **Note:**
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
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
release.
>**Note:**
NOTE: **Note:**
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
future GitLab releases.**
......@@ -131,7 +131,7 @@ future GitLab releases.**
## `.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.
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.
### 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
>**Note:**
NOTE: **Note:**
This feature requires GitLab CI 8.15 or higher.
[Project services](../../user/project/integrations/project_services.md) that are
......@@ -567,4 +573,4 @@ Below you can find supported syntax reference:
[builds-policies]: ../yaml/README.md#only-and-except-complex
[gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token
[registry]: ../../user/project/container_registry.md
[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories
\ No newline at end of file
[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories
......@@ -8,10 +8,10 @@ This document describes where and how the different types of variables can be us
## 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. On the Runner's side there's `config.toml`
1. GitLab side, in `.gitlab-ci.yml`.
1. The runner side, in `config.toml`.
### `.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
- **Supported:** project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and
variables from triggers and pipeline schedules
- **Not supported:** variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`)
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
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).
- The `script` may also use all variables defined in the lines before. So, for example, if you define
a variable `export MY_VARIABLE="test"`:
- in `before_script`, it will work in the following lines of `before_script` and
all lines of the related `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 `before_script`, it will work in the following lines of `before_script` and
all lines of the related `script`.
- In `script`, it will work in the following lines of `script`.
- In `after_script`, it will work in following lines of `after_script`.
## Persisted variables
......@@ -107,7 +106,7 @@ The following variables are known as "persisted":
They are:
- **supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner"
- **not supported:**
- 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)
- **Supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner".
- **Not supported:**
- 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).
......@@ -157,6 +157,10 @@ into your `README.md`:
![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
[coverage report]: #test-coverage-parsing
[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