Merge branch 'docs/gb/cross-project-pipeline-triggers' into 'master'

Add basic docs about cross-project pipeline triggers

See merge request gitlab-org/gitlab-ee!9337

doc/ci/multi_project_pipelines.md

@@ -32,7 +32,7 @@ Let's assume you deploy your web app from different projects in GitLab:
 
 With Multi-Project Pipelines, you can visualize the entire pipeline, including all stages of builds and tests for the three projects.
 
-## How it works
+## Triggering multi-project pipelines through API
 
 When you use the [`CI_JOB_TOKEN` to trigger pipelines](triggers/README.md#ci-job-token), GitLab
 recognizes the source of the job token, and thus internally ties these pipelines
@@ -40,3 +40,113 @@ together, allowing you to visualize their relationships on pipeline graphs.
 
 These relationships are displayed in the pipeline graph by showing inbound and
 outbound connections for upstream and downstream pipeline dependencies.
+
+## Creating multi-project pipelines from `.gitlab-ci.yml`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
+
+### Triggering a downstream pipeline using a bridge job
+
+Before GitLab 11.8, it was necessary to implement a pipeline job that was
+responsible for making the API request [to trigger a pipeline](triggers/README.md#creating-cross-project-pipeline-through-API)
+in a different project.
+
+In GitLab 11.8, GitLab provides a new CI/CD configuration syntax to make this
+task easier, and avoid needing GitLab Runner for triggering cross-project
+pipelines. The following illustrates configuring a bridge job:
+
+```yaml
+rspec:
+  stage: test
+  script: bundle exec rspec
+
+staging:
+  variables:
+    ENVIRONMENT: staging
+  stage: deploy
+  trigger: my/deployment
+```
+
+In the example above, as soon as `rspec` job succeeds in the `test` stage,
+the `staging` bridge job is going to be started. The initial status of this
+job will be `pending`. GitLab will create a downstream pipeline in the
+`my/deployment` project and, as soon as the pipeline gets created, the
+`staging` job will succeed. `my/deployment` is a full path to that project.
+
+The user that created the upstream pipeline needs to have access rights to the
+downstream project (`my/deployment` in this case). If a downstream project can
+not be found, or a user does not have access rights to create pipeline there,
+the `staging` job is going to be marked as _failed_.
+
+Caution: **Caution:**
+`staging` will succeed as soon as a downstream pipeline gets created.
+GitLab does not support status attribution yet, however adding first-class
+`trigger` configuration syntax is ground work for implementing
+[status attribution](https://gitlab.com/gitlab-org/gitlab-ce/issues/39640).
+
+NOTE: **Note:**
+Bridge jobs do not support every configuration entry that a user can use
+in the case of regular jobs. Bridge jobs will not to be picked by a Runner,
+thus there is no point in adding support for `script`, for example. If a user
+tries to use unsupported configuration syntax, YAML validation will fail upon
+pipeline creation.
+
+### Specifying a downstream pipeline branch
+
+It is possible to specify a branch name that a downstream pipeline will use:
+
+```yaml
+rspec:
+  stage: test
+  script: bundle exec rspec
+
+staging:
+  stage: deploy
+  trigger:
+    project: my/deployment
+    branch: stable-11-2
+```
+
+Use a `project` keyword to specify full path to a downstream project. Use
+a `branch` keyword to specify a branch name.
+
+GitLab will use a commit that is currently on the HEAD of the branch when
+creating a downstream pipeline.
+
+### Passing variables to a downstream pipeline
+
+Sometimes you might want to pass variables to a downstream pipeline.
+You can do that using the `variables` keyword, just like you would when
+defining a regular job.
+
+```yaml
+rspec:
+  stage: test
+  script: bundle exec rspec
+
+staging:
+  variables:
+    ENVIRONMENT: staging
+  stage: deploy
+  trigger: my/deployment
+```
+
+The `ENVIRONMENT` variable will be passed to every job defined in a downstream
+pipeline. It will be available as an environment variable when GitLab Runner picks a job.
+
+### Limitations
+
+Because bridge jobs are a little different to regular jobs, it is not
+possible to use exactly the same configuration syntax here, as one would
+normally do when defining a regular job that will be picked by a runner.
+
+Some features are not implemented yet. For example, support for environments.
+
+[Configuration keywords](yaml/README.md) available for bridge jobs are:
+
+- `trigger` (to define a downstream pipeline trigger)
+- `stage`
+- `allow_failure`
+- `only` and `except`
+- `when`
+- `extends`

doc/ci/yaml/README.md

@@ -77,6 +77,7 @@ A job is defined by a list of parameters that define the job behavior.
 | [coverage](#coverage)                            | no       | Define code coverage settings for a given job |
 | [retry](#retry)                                  | no       | Define when and how many times a job can be auto-retried in case of a failure |
 | [parallel](#parallel)                            | no       | Defines how many instances of a job should be run in parallel |
+| [trigger](#trigger)                              | no       | Defines a downstream pipeline trigger |
 
 ## `image` and `services`
 
@@ -1531,6 +1532,48 @@ test:
   parallel: 5
 ```
 
+## `trigger`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8.
+
+`trigger` allows you to define downstream pipeline trigger. When a job created
+from `trigger` definition is started by GitLab, a downstream pipeline gets
+created.
+
+Learn more about [multi-project pipelines](../multi_project_pipelines.md#creating-cross-project-pipelines-from-gitlab-ci-yml).
+
+### Simple `trigger` syntax
+
+The most simple way to configure a downstream trigger to use `trigger` keyword
+with a full path to a downstream project:
+
+```yaml
+rspec:
+  stage: test
+  script: bundle exec rspec
+
+staging:
+  stage: deploy
+  trigger: my/deployment
+```
+
+### Complex `trigger` syntax
+
+It is possible to configure a branch name that GitLab will use to create
+a downstream pipeline with:
+
+```yaml
+rspec:
+  stage: test
+  script: bundle exec rspec
+
+staging:
+  stage: deploy
+  trigger:
+    project: my/deployment
+    branch: stable
+```
+
 ## `include`
 
 > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5.
@@ -2315,7 +2358,9 @@ You can see that the hidden keys are conveniently used as templates.
 ## Triggers
 
 Triggers can be used to force a rebuild of a specific branch, tag or commit,
-with an API call.
+with an API call when a pipeline gets created using a trigger token.
+
+Not to be confused with [`trigger`](#trigger).
 
 [Read more in the triggers documentation.](../triggers/README.md)