From 5d8adad87d11f12eb361a6465bc1e385c21346fe Mon Sep 17 00:00:00 2001 From: Evan Read Date: Fri, 7 Sep 2018 20:40:44 +0000 Subject: Document how to specify environment variables during manual pipeline run and more --- doc/ci/pipelines.md | 47 +++++++++++++++---------- doc/ci/variables/README.md | 16 ++++++--- doc/ci/variables/where_variables_can_be_used.md | 27 +++++++------- doc/user/project/pipelines/settings.md | 4 +++ 4 files changed, 57 insertions(+), 37 deletions(-) (limited to 'doc') diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index 4e964af97f5..ea47d676edb 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -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 diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 115e6e390c9..f11949da64e 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -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 diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index b2b4a26bdda..b0d2ea6484d 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -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). diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 14f2e522f01..15eacc48dfe 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -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 -- cgit v1.2.3