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

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

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
+[dependent-repositories]: ../../user/project/new_ci_build_permissions_model.md#dependent-repositories

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).

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