summaryrefslogtreecommitdiff
path: root/doc/ci/pipelines
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ci/pipelines')
-rw-r--r--doc/ci/pipelines/index.md27
-rw-r--r--doc/ci/pipelines/merge_request_pipelines.md4
-rw-r--r--doc/ci/pipelines/multi_project_pipelines.md21
-rw-r--r--doc/ci/pipelines/parent_child_pipelines.md32
-rw-r--r--doc/ci/pipelines/pipeline_artifacts.md20
-rw-r--r--doc/ci/pipelines/schedules.md10
-rw-r--r--doc/ci/pipelines/settings.md2
7 files changed, 74 insertions, 42 deletions
diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md
index 69e974406e2..24e518b1f69 100644
--- a/doc/ci/pipelines/index.md
+++ b/doc/ci/pipelines/index.md
@@ -77,7 +77,7 @@ You can also configure specific aspects of your pipelines through the GitLab UI.
- [Pipeline schedules](schedules.md).
- [Custom CI/CD variables](../variables/index.md#custom-cicd-variables).
-### Ref Specs for Runners
+### Ref specs for runners
When a runner picks a pipeline job, GitLab provides that job's metadata. This includes the [Git refspecs](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec),
which indicate which ref (branch, tag, and so on) and commit (SHA1) are checked out from your
@@ -87,9 +87,9 @@ This table lists the refspecs injected for each pipeline type:
| Pipeline type | Refspecs |
|--------------- |---------------------------------------- |
-| Pipeline for Branches | `+<sha>:refs/pipelines/<id>` and `+refs/heads/<name>:refs/remotes/origin/<name>` |
-| pipeline for Tags | `+<sha>:refs/pipelines/<id>` and `+refs/tags/<name>:refs/tags/<name>` |
-| [Pipeline for Merge Requests](../pipelines/merge_request_pipelines.md) | `+<sha>:refs/pipelines/<id>` |
+| pipeline for branches | `+<sha>:refs/pipelines/<id>` and `+refs/heads/<name>:refs/remotes/origin/<name>` |
+| pipeline for tags | `+<sha>:refs/pipelines/<id>` and `+refs/tags/<name>:refs/tags/<name>` |
+| [pipeline for merge requests](../pipelines/merge_request_pipelines.md) | `+<sha>:refs/pipelines/<id>` |
The refs `refs/heads/<name>` and `refs/tags/<name>` exist in your
project repository. GitLab generates the special ref `refs/pipelines/<id>` during a
@@ -127,6 +127,11 @@ you can filter the pipeline list by:
[Starting in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/26621), you can change the
pipeline column to display the pipeline ID or the pipeline IID.
+If you use VS Code to edit your GitLab CI/CD configuration, the
+[GitLab Workflow VS Code extension](../../user/project/repository/vscode.md) helps you
+[validate your configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration)
+and [view your pipeline status](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue).
+
### Run a pipeline manually
Pipelines can be manually executed, with predefined or manually-specified [variables](../variables/index.md).
@@ -150,7 +155,7 @@ The pipeline now executes the jobs as configured.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7.
-You can use the [`value` and `description`](../yaml/index.md#prefill-variables-in-manual-pipelines)
+You can use the [`value` and `description`](../yaml/index.md#variablesdescription)
keywords to define
[pipeline-level (global) variables](../variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file)
that are prefilled when running a pipeline manually.
@@ -159,7 +164,7 @@ In pipelines triggered manually, the **Run pipelines** page displays all top-lev
with a `description` and `value` defined in the `.gitlab-ci.yml` file. The values
can then be modified if needed, which overrides the value for that single pipeline run.
-The description is displayed below the variable. It can be used to explain what
+The description is displayed next to the variable. It can be used to explain what
the variable is used for, what the acceptable values are, and so on:
```yaml
@@ -229,6 +234,15 @@ This functionality is only available:
- For users with at least the Developer role.
- If the stage contains [manual actions](#add-manual-interaction-to-your-pipeline).
+### Skip a pipeline
+
+To push a commit without triggering a pipeline, add `[ci skip]` or `[skip ci]`, using any
+capitalization, to your commit message.
+
+Alternatively, if you are using Git 2.10 or later, use the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd).
+The `ci.skip` push option does not skip merge request
+pipelines.
+
### Delete a pipeline
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24851) in GitLab 12.7.
@@ -391,6 +405,7 @@ be found when you go to:
- The pipelines index page.
- A single commit page.
- A merge request page.
+- The [pipeline editor](../pipeline_editor/index.md), [in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/337514) and later.
Pipeline mini graphs allow you to 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
diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md
index 5b40744aa79..119633d38e2 100644
--- a/doc/ci/pipelines/merge_request_pipelines.md
+++ b/doc/ci/pipelines/merge_request_pipelines.md
@@ -45,7 +45,7 @@ To do this, you can use [`rules`](#use-rules-to-run-pipelines-for-merge-requests
### Use `rules` to run pipelines for merge requests
GitLab recommends that you use the `rules` keyword, which is available in
-[`workflow:rules` templates](../yaml/index.md#workflowrules-templates).
+[`workflow:rules` templates](../yaml/workflow.md#workflowrules-templates).
### Use `only` or `except` to run pipelines for merge requests
@@ -199,7 +199,7 @@ If you are seeing two pipelines when using `only/except`, please see the caveats
related to using `only/except` above (or, consider moving to `rules`).
In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201845),
-you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/index.md#switch-between-branch-pipelines-and-merge-request-pipelines).
+you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines).
After a merge request is open on the branch, the pipeline switches to a merge request pipeline.
### Two pipelines created when pushing an invalid CI configuration file
diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md
index 184961f4c95..30b3bc2e277 100644
--- a/doc/ci/pipelines/multi_project_pipelines.md
+++ b/doc/ci/pipelines/multi_project_pipelines.md
@@ -88,7 +88,7 @@ The keywords available for use in trigger jobs are:
- [`only` and `except`](../yaml/index.md#only--except)
- [`when`](../yaml/index.md#when) (only with a value of `on_success`, `on_failure`, or `always`)
- [`extends`](../yaml/index.md#extends)
-- [`needs`](../yaml/index.md#needs), but not [cross project artifact downloads with `needs`](../yaml/index.md#cross-project-artifact-downloads-with-needs)
+- [`needs`](../yaml/index.md#needs), but not [`needs:project`](../yaml/index.md#needsproject)
#### Specify a downstream pipeline branch
@@ -154,7 +154,7 @@ trigger-downstream:
trigger: my/project
```
-You can stop global variables from reaching the downstream pipeline by using the [`inherit` keyword](../yaml/index.md#inherit).
+You can stop global variables from reaching the downstream pipeline by using the [`inherit:variables` keyword](../yaml/index.md#inheritvariables).
In this example, the `MY_GLOBAL_VAR` variable is not available in the triggered pipeline:
```yaml
@@ -190,7 +190,7 @@ the ones defined in the upstream project take precedence.
#### Pass CI/CD variables to a downstream pipeline by using variable inheritance
-You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job) and [cross project artifact downloads](../yaml/index.md#cross-project-artifact-downloads-with-needs).
+You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job) and [`needs:project`](../yaml/index.md#needsproject).
In the upstream pipeline:
@@ -254,21 +254,6 @@ trigger_job:
strategy: depend
```
-#### Mirror status from upstream pipeline
-
-You can mirror the pipeline status from an upstream pipeline to a bridge job by
-using the `needs:pipeline` keyword. The latest pipeline status from the default branch is
-replicated to the bridge job.
-
-For example:
-
-```yaml
-upstream_bridge:
- stage: test
- needs:
- pipeline: other/project
-```
-
### Create multi-project pipelines by using the API
> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) to GitLab Free in 12.4.
diff --git a/doc/ci/pipelines/parent_child_pipelines.md b/doc/ci/pipelines/parent_child_pipelines.md
index e48728a904a..64f4160c963 100644
--- a/doc/ci/pipelines/parent_child_pipelines.md
+++ b/doc/ci/pipelines/parent_child_pipelines.md
@@ -81,7 +81,8 @@ microservice_a:
trigger:
include:
- project: 'my-group/my-pipeline-library'
- file: 'path/to/ci-config.yml'
+ ref: 'main'
+ file: '/path/to/child-pipeline.yml'
```
The maximum number of entries that are accepted for `trigger:include:` is three.
@@ -98,7 +99,7 @@ microservice_a:
strategy: depend
```
-## Merge Request child pipelines
+## Merge request child pipelines
To trigger a child pipeline as a [Merge Request Pipeline](merge_request_pipelines.md) we need to:
@@ -149,7 +150,7 @@ microservice_a:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9.
Instead of running a child pipeline from a static YAML file, you can define a job that runs
-your own script to generate a YAML file, which is then [used to trigger a child pipeline](../yaml/index.md#trigger-child-pipeline-with-generated-configuration-file).
+your own script to generate a YAML file, which is then used to trigger a child pipeline.
This technique can be very powerful in generating pipelines targeting content that changed or to
build a matrix of targets and architectures.
@@ -171,6 +172,31 @@ configuration for jobs, like scripts, that use the Windows runner would use `\`.
In GitLab 12.9, the child pipeline could fail to be created in certain cases, causing the parent pipeline to fail.
This is [resolved](https://gitlab.com/gitlab-org/gitlab/-/issues/209070) in GitLab 12.10.
+### Dynamic child pipeline example
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9.
+
+You can trigger a child pipeline from a [dynamically generated configuration file](../pipelines/parent_child_pipelines.md#dynamic-child-pipelines):
+
+```yaml
+generate-config:
+ stage: build
+ script: generate-ci-config > generated-config.yml
+ artifacts:
+ paths:
+ - generated-config.yml
+
+child-pipeline:
+ stage: test
+ trigger:
+ include:
+ - artifact: generated-config.yml
+ job: generate-config
+```
+
+The `generated-config.yml` is extracted from the artifacts and used as the configuration
+for triggering the child pipeline.
+
## Nested child pipelines
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) in GitLab 13.4.
diff --git a/doc/ci/pipelines/pipeline_artifacts.md b/doc/ci/pipelines/pipeline_artifacts.md
index 55555571f97..b174b6af9f9 100644
--- a/doc/ci/pipelines/pipeline_artifacts.md
+++ b/doc/ci/pipelines/pipeline_artifacts.md
@@ -7,20 +7,24 @@ type: reference, howto
# Pipeline artifacts **(FREE)**
-Pipeline artifacts are files created by GitLab after a pipeline finishes. These are different than [job artifacts](job_artifacts.md) because they are not explicitly managed by the `.gitlab-ci.yml` definitions.
+Pipeline artifacts are files created by GitLab after a pipeline finishes. Pipeline artifacts are
+different to [job artifacts](job_artifacts.md) because they are not explicitly managed by
+`.gitlab-ci.yml` definitions.
-Pipeline artifacts are used by the [test coverage visualization feature](../../user/project/merge_requests/test_coverage_visualization.md) to collect coverage information. It uses the [`artifacts: reports`](../yaml/index.md#artifactsreports) CI/CD keyword.
+Pipeline artifacts are used by the [test coverage visualization feature](../../user/project/merge_requests/test_coverage_visualization.md)
+to collect coverage information. It uses the [`artifacts: reports`](../yaml/index.md#artifactsreports) CI/CD keyword.
## Storage
-Pipeline artifacts are saved to disk or object storage. They count towards a project's [storage usage quota](../../user/usage_quotas.md#storage-usage-quota). The **Artifacts** on the Usage Quotas page is the sum of all job artifacts and pipeline artifacts.
+Pipeline artifacts are saved to disk or object storage. They count towards a project's [storage usage quota](../../user/usage_quotas.md#storage-usage-quota).
+The **Artifacts** on the Usage Quotas page is the sum of all job artifacts and pipeline artifacts.
## When pipeline artifacts are deleted
-Pipeline artifacts are deleted either:
+Pipeline artifacts from:
-- Seven days after creation.
-- After another pipeline runs successfully, if they are from the most recent successful
- pipeline.
+- The latest pipeline are kept forever.
+- Pipelines superseded by a newer pipeline are deleted seven days after their creation date.
-This deletion may take up to two days.
+It can take up to two days for GitLab to delete pipeline artifacts from when they are due to be
+deleted.
diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md
index 90494a715ea..692460120fe 100644
--- a/doc/ci/pipelines/schedules.md
+++ b/doc/ci/pipelines/schedules.md
@@ -12,14 +12,16 @@ Pipelines are normally run based on certain conditions being met. For example, w
Pipeline schedules can be used to also run [pipelines](index.md) at specific intervals. For example:
-- Every month on the 22nd for a certain branch.
-- Once every day.
+- Every month on the 22nd (cron example: `0 0 22 * *`) for a certain branch.
+- Every month on the 2nd Monday (cron example: `0 0 * * 1#2`).
+- Every other Sunday at 0900 hours (cron example: `0 9 * * sun%2`).
+- Once every day (cron example: `0 0 * * *`).
+
+Schedule timing is configured with cron notation, parsed by [Fugit](https://github.com/floraison/fugit).
In addition to using the GitLab UI, pipeline schedules can be maintained using the
[Pipeline schedules API](../../api/pipeline_schedules.md).
-Schedule timing is configured with cron notation, parsed by [Fugit](https://github.com/floraison/fugit).
-
## Prerequisites
In order for a scheduled pipeline to be created successfully:
diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md
index e14c1aa621f..a8ecb5e0d74 100644
--- a/doc/ci/pipelines/settings.md
+++ b/doc/ci/pipelines/settings.md
@@ -78,7 +78,7 @@ To avoid this scenario:
1. Select the **Skip outdated deployment jobs** checkbox.
1. Select **Save changes**.
-Older deployment job are skipped when a new deployment starts.
+Older deployment jobs are skipped when a new deployment starts.
For more information, see [Deployment safety](../environments/deployment_safety.md).
View Lorry Controller Status