diff options
Diffstat (limited to 'doc/ci/pipelines')
20 files changed, 875 insertions, 1 deletions
diff --git a/doc/ci/pipelines/img/collapsible_log_v12_6.png b/doc/ci/pipelines/img/collapsible_log_v12_6.png Binary files differnew file mode 100644 index 00000000000..24b2c83f7c1 --- /dev/null +++ b/doc/ci/pipelines/img/collapsible_log_v12_6.png diff --git a/doc/ci/pipelines/img/job_failure_reason.png b/doc/ci/pipelines/img/job_failure_reason.png Binary files differnew file mode 100644 index 00000000000..d44b8e6d1be --- /dev/null +++ b/doc/ci/pipelines/img/job_failure_reason.png diff --git a/doc/ci/pipelines/img/manual_job_variables.png b/doc/ci/pipelines/img/manual_job_variables.png Binary files differnew file mode 100644 index 00000000000..a5ed351fdcd --- /dev/null +++ b/doc/ci/pipelines/img/manual_job_variables.png diff --git a/doc/ci/pipelines/img/pipeline-delete.png b/doc/ci/pipelines/img/pipeline-delete.png Binary files differnew file mode 100644 index 00000000000..d9dba1f455d --- /dev/null +++ b/doc/ci/pipelines/img/pipeline-delete.png diff --git a/doc/ci/pipelines/img/pipeline_incremental_rollout.png b/doc/ci/pipelines/img/pipeline_incremental_rollout.png Binary files differnew file mode 100644 index 00000000000..b3498e9a5a5 --- /dev/null +++ b/doc/ci/pipelines/img/pipeline_incremental_rollout.png diff --git a/doc/ci/pipelines/img/pipelines.png b/doc/ci/pipelines/img/pipelines.png Binary files differnew file mode 100644 index 00000000000..a604fcb2587 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines.png diff --git a/doc/ci/pipelines/img/pipelines_duration_chart.png b/doc/ci/pipelines/img/pipelines_duration_chart.png Binary files differnew file mode 100644 index 00000000000..0be7539ba0a --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_duration_chart.png diff --git a/doc/ci/pipelines/img/pipelines_grouped.png b/doc/ci/pipelines/img/pipelines_grouped.png Binary files differnew file mode 100644 index 00000000000..82814754747 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_grouped.png diff --git a/doc/ci/pipelines/img/pipelines_index.png b/doc/ci/pipelines/img/pipelines_index.png Binary files differnew file mode 100644 index 00000000000..e168e7e23df --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_index.png diff --git a/doc/ci/pipelines/img/pipelines_mini_graph.png b/doc/ci/pipelines/img/pipelines_mini_graph.png Binary files differnew file mode 100644 index 00000000000..8656b02f60d --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_mini_graph.png diff --git a/doc/ci/pipelines/img/pipelines_mini_graph_simple.png b/doc/ci/pipelines/img/pipelines_mini_graph_simple.png Binary files differnew file mode 100644 index 00000000000..d00a8313088 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_mini_graph_simple.png diff --git a/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png b/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png Binary files differnew file mode 100644 index 00000000000..3a4e5453360 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png diff --git a/doc/ci/pipelines/img/pipelines_settings_badges.png b/doc/ci/pipelines/img/pipelines_settings_badges.png Binary files differnew file mode 100644 index 00000000000..3bdc6374c15 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_settings_badges.png diff --git a/doc/ci/pipelines/img/pipelines_settings_test_coverage.png b/doc/ci/pipelines/img/pipelines_settings_test_coverage.png Binary files differnew file mode 100644 index 00000000000..13ed69be810 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_settings_test_coverage.png diff --git a/doc/ci/pipelines/img/pipelines_success_chart.png b/doc/ci/pipelines/img/pipelines_success_chart.png Binary files differnew file mode 100644 index 00000000000..10602b75eeb --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_success_chart.png diff --git a/doc/ci/pipelines/img/pipelines_test_coverage_build.png b/doc/ci/pipelines/img/pipelines_test_coverage_build.png Binary files differnew file mode 100644 index 00000000000..7eaba1a256f --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_test_coverage_build.png diff --git a/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png b/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png Binary files differnew file mode 100644 index 00000000000..fbcd612f3f2 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md new file mode 100644 index 00000000000..a823793a995 --- /dev/null +++ b/doc/ci/pipelines/index.md @@ -0,0 +1,566 @@ +--- +type: reference +--- + +# Creating and using CI/CD pipelines + +> Introduced in GitLab 8.8. + +NOTE: **Tip:** +Watch our +["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) +webcast to see a comprehensive demo of GitLab CI/CD pipeline. + +## Introduction + +Pipelines are the top-level component of continuous integration, delivery, and deployment. + +Pipelines comprise: + +- Jobs that define what to run. For example, code compilation or test runs. +- Stages that define when and how to run. For example, that tests run only after code compilation. + +Multiple jobs in the same stage are executed by [Runners](../runners/README.md) in parallel, if there are enough concurrent [Runners](../runners/README.md). + +If all the jobs in a stage: + +- Succeed, the pipeline moves on to the next stage. +- Fail, the next stage is not (usually) executed and the pipeline ends early. + +NOTE: **Note:** +If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter), +you may need to enable pipeline triggering in your project's +**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. + +### Simple pipeline example + +As an example, imagine a pipeline consisting of four stages, executed in the following order: + +- `build`, with a job called `compile`. +- `test`, with two jobs called `test` and `test2`. +- `staging`, with a job called `deploy-to-stage`. +- `production`, with a job called `deploy-to-prod`. + +## Visualizing pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5742) in GitLab 8.11. + +Pipelines can be complex structures with many sequential and parallel jobs. + +To make it easier to understand the flow of a pipeline, GitLab has pipeline graphs for viewing pipelines +and their statuses. + +Pipeline graphs can be displayed in two different ways, depending on the page you +access the graph from. + +NOTE: **Note:** +GitLab capitalizes the stages' names when shown in the pipeline graphs (below). + +### Regular pipeline graphs + +Regular pipeline graphs show the names of the jobs of each stage. Regular pipeline graphs can +be found when you are on a [single pipeline page](#accessing-pipelines). For example: + + + +### Pipeline mini graphs + +Pipeline mini graphs take less space and can tell you at a +quick glance if all jobs passed or something failed. The pipeline mini graph can +be found when you navigate to: + +- The pipelines index page. +- A single commit page. +- A merge request page. + +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 +fix it. + +Stages in pipeline mini graphs are collapsible. Hover your mouse over them and click to expand their jobs. + +| Mini graph | Mini graph expanded | +|:-------------------------------------------------------------|:---------------------------------------------------------------| +|  |  | + +### Job ordering in pipeline graphs + +Job ordering depends on the type of pipeline graph. For [regular pipeline graphs](#regular-pipeline-graphs), jobs are sorted by name. + +For [pipeline mini graphs](#pipeline-mini-graphs) ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9760) +in GitLab 9.0), jobs are sorted by severity and then by name. + +The order of severity is: + +- failed +- warning +- pending +- running +- manual +- scheduled +- canceled +- success +- skipped +- created + +For example: + + + +### Expanding and collapsing job log sections + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14664) in GitLab +> 12.0. + +Job logs are divided into sections that can be collapsed or expanded. Each section will display +the duration. + +In the following example: + +- Two sections are collapsed and can be expanded. +- Three sections are expanded and can be collapsed. + + + +#### Custom collapsible sections + +You can create collapsible sections in job logs by manually outputting special codes +that GitLab will use to determine what sections to collapse: + +- Section start marker: `section_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER` +- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + +You must add these codes to the script section of the CI configuration. For example, +using `echo`: + +```yaml +job1: + script: + - echo -e "section_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section" + - echo 'this line should be hidden when collapsed' + - echo -e "section_end:`date +%s`:my_first_section\r\e[0K" +``` + +In the example above: + +- `date +%s`: The Unix timestamp (for example `1560896352`). +- `my_first_section`: The name given to the section. +- `\r\e[0K`: Prevents the section markers from displaying in the rendered (colored) + job log, but they are displayed in the raw job log. To see them, in the top right + of the job log, click **{doc-text}** (**Show complete raw**). + - `\r`: carriage return. + - `\e[0K`: clear line ANSI escape code. + +Sample raw job log: + +```plaintext +section_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section +this line should be hidden when collapsed +section_end:1560896353:my_first_section\r\e[0K +``` + +### Pipeline success and duration charts + +> - Introduced in GitLab 3.1.1 as Commit Stats, and later renamed to Pipeline Charts. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/issues/38318) to CI / CD Analytics in GitLab 12.8. + +GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline ran. To view this information, go to **Analytics > CI / CD Analytics**. + +View successful pipelines: + + + +View pipeline duration history: + + + +## Pipeline quotas + +Each user has a personal pipeline quota that tracks the usage of shared runners in all personal projects. +Each group has a [usage quota](../../subscriptions/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group. + +When a pipeline is triggered, regardless of who triggered it, the pipeline quota for the project owner's [namespace](../../user/group/index.md#namespaces) is used. In this case, the namespace can be the user or group that owns the project. + +### How pipeline duration is calculated + +Total running time for a given pipeline excludes retries and pending +(queued) time. + +Each job is represented as a `Period`, which consists of: + +- `Period#first` (when the job started). +- `Period#last` (when the job finished). + +A simple example is: + +- A (1, 3) +- B (2, 4) +- C (6, 7) + +In the example: + +- A begins at 1 and ends at 3. +- B begins at 2 and ends at 4. +- C begins at 6 and ends at 7. + +Visually, it can be viewed as: + +```text +0 1 2 3 4 5 6 7 + AAAAAAA + BBBBBBB + CCCC +``` + +The union of A, B, and C is (1, 4) and (6, 7). Therefore, the total running time is: + +```text +(4 - 1) + (7 - 6) => 4 +``` + +## Configuring pipelines + +Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.yml`](../yaml/README.md) file for each project. + +In particular: + +- Jobs are the [basic configuration](../yaml/README.md#introduction) component. +- Stages are defined using the [`stages`](../yaml/README.md#stages) keyword. + +For all available configuration options, see the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md). + +### Settings and schedules + +In addition to configuring jobs through `.gitlab-ci.yml`, additional configuration options are available +through the GitLab UI: + +- Pipeline settings for each project. For more information, see [Pipeline settings](settings.md). +- Schedules for pipelines. For more information, see [Pipeline schedules](schedules.md). + +### Grouping jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6242) in GitLab 8.12. + +If you have many similar jobs, your [pipeline graph](#visualizing-pipelines) becomes long and hard +to read. + +For that reason, similar jobs can automatically be grouped together. +If the job names are formatted in certain ways, they will be collapsed into +a single group in regular pipeline graphs (not the mini graphs). + +You'll know when a pipeline has grouped jobs if you don't see the retry or +cancel button inside them. Hovering over them will show the number of grouped +jobs. Click to expand them. + + + +#### Configuring grouping + +In the pipeline [configuration file](../yaml/README.md), job names must include two numbers separated with one of +the following (you can even use them interchangeably): + +- A space. +- A slash (`/`). +- A colon (`:`). + +NOTE: **Note:** +More specifically, it uses [this](https://gitlab.com/gitlab-org/gitlab/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) regular expression: `\d+[\s:\/\\]+\d+\s*`. + +#### How grouping works + +The jobs will be ordered by comparing those two numbers from left to right. You +usually want the first to be the index and the second the total. + +For example, the following jobs will be grouped under a job named `test`: + +- `test 0 3` +- `test 1 3` +- `test 2 3` + +The following jobs will be grouped under a job named `test ruby`: + +- `test 1:2 ruby` +- `test 2:2 ruby` + +The following jobs will be grouped under a job named `test ruby` as well: + +- `1/3 test ruby` +- `2/3 test ruby` +- `3/3 test ruby` + +### Pipelines for merge requests + +GitLab supports configuring pipelines that run only for merge requests. For more information, see +[Pipelines for merge requests](../merge_request_pipelines/index.md). + +### Badges + +Pipeline status and test coverage report badges are available and configurable for each project. + +For information on adding pipeline badges to projects, see [Pipeline badges](settings.md#pipeline-badges). + +## Multi-project pipelines + +Pipelines for different projects can be combined together into [Multi-project pipelines](../multi_project_pipelines.md). + +[Multi-project pipeline graphs](../multi_project_pipelines.md#multi-project-pipeline-visualization-premium) help +you visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)** + +## Parent-child pipelines + +Complex pipelines can be broken down into one parent pipeline that can trigger +multiple child sub-pipelines, which all run in the same project and with the same SHA. + +For more information, see [Parent-Child pipelines](../parent_child_pipelines.md). + +## Working with pipelines + +In general, pipelines are executed automatically and require no intervention once created. + +However, there are instances where you'll need to interact with pipelines. These are documented below. + +### Manually executing pipelines + +Pipelines can be manually executed, with predefined or manually-specified [variables](../variables/README.md). + +You might do this if the results of a pipeline (for example, a code build) is required outside the normal +operation of the pipeline. + +To execute a pipeline manually: + +1. Navigate to your project's **CI/CD > Pipelines**. +1. Click on the **Run Pipeline** button. +1. On the **Run Pipeline** page: + 1. Select the branch to run the pipeline for in the **Create for** field. + 1. Enter any [environment variables](../variables/README.md) required for the pipeline run. + 1. Click the **Create pipeline** button. + +The pipeline will execute the jobs as configured. + +#### Using a query string + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24146) in GitLab 12.5. + +Variables on the **Run Pipeline** page can be pre-populated by passing variable keys and values +in a query string appended to the `pipelines/new` URL. The format is: + +```plaintext +.../pipelines/new?ref=<branch>&var[<variable_key>]=<value>&file_var[<file_key>]=<value> +``` + +The following parameters are supported: + +- `ref`: specify the branch to populate the **Run for** field with. +- `var`: specify a `Variable` variable. +- `file_var`: specify a `File` variable. + +For each `var` or `file_var`, a key and value are required. + +For example, the query string +`.../pipelines/new?ref=my_branch&var[foo]=bar&file_var[file_foo]=file_bar` will pre-populate the +**Run Pipeline** page as follows: + +- **Run for** field: `my_branch`. +- **Variables** section: + - Variable: + - Key: `foo` + - Value: `bar` + - File: + - Key: `file_foo` + - Value: `file_bar` + +### Accessing pipelines + +You can find the current and historical pipeline runs under your project's +**CI/CD > Pipelines** page. You can also access pipelines for a merge request by navigating +to its **Pipelines** tab. + + + +Clicking on a pipeline will bring you to the **Pipeline Details** page and show +the jobs that were run for that pipeline. From here you can cancel a running pipeline, +retry jobs on a failed pipeline, or [delete a pipeline](#deleting-a-single-pipeline). + +### Accessing individual jobs + +When you access a pipeline, you can see the related jobs for that pipeline. + +Clicking on an individual job will show you its job log, and allow you to: + +- Cancel the job. +- Retry the job. +- Erase the job log. + +### Seeing the failure reason for jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17782) in GitLab 10.7. + +When a pipeline fails or is allowed to fail, there are several places where you +can quickly check the reason it failed: + +- In the pipeline graph, on the pipeline detail view. +- In the pipeline widgets, in the merge requests and commit pages. +- In the job views, in the global and detailed views of a job. + +In each place, if you hover over the failed job you can see the reason it failed. + + + +From [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814), +you can also see the reason it failed on the Job detail page. + +### Manual actions from pipeline graphs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7931) in GitLab 8.15. + +Manual actions, configured using the [`when:manual`](../yaml/README.md#whenmanual) parameter, +allow you to require manual interaction before moving forward in the pipeline. + +You can do this straight from the pipeline graph. Just click on the play button +to execute that particular job. + +For example, your pipeline start automatically, but require manual action to +[deploy to production](../environments.md#configuring-manual-deployments). In the example below, the `production` +stage has a job with a manual action. + + + +### Specifying variables when running manual jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30485) in GitLab 12.2. + +When running manual jobs you can supply additional job specific variables. + +You can do this from the job page of the manual job you want to run with +additional variables. + +This is useful when you want to alter the execution of a job by using +environment variables. + + + +### Delay a job in a pipeline graph + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4. + +When you do not want to run a job immediately, you can use the [`when:delayed`](../yaml/README.md#whendelayed) parameter to +delay a job's execution for a certain period. + +This is especially useful for timed incremental rollout where new code is rolled out gradually. + +For example, if you start rolling out new code and: + +- Users do not experience trouble, GitLab can automatically complete the deployment from 0% to 100%. +- Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline + and [rolling](../environments.md#retrying-and-rolling-back) back to the last stable version. + + + +### Using the API + +GitLab provides API endpoints to: + +- Perform basic functions. For more information, see [Pipelines API](../../api/pipelines.md). +- Maintain pipeline schedules. For more information, see [Pipeline schedules API](../../api/pipeline_schedules.md). +- Trigger pipeline runs. For more information, see: + - [Triggering pipelines through the API](../triggers/README.md). + - [Pipeline triggers API](../../api/pipeline_triggers.md). + +### Start multiple manual actions in a stage + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27188) in GitLab 11.11. + +Multiple manual actions in a single stage can be started at the same time using the "Play all manual" button. +Once the user clicks this button, each individual manual action will be triggered and refreshed +to an updated status. + +This functionality is only available: + +- For users with at least Developer access. +- If the the stage contains [manual actions](#manual-actions-from-pipeline-graphs). + +### Deleting a single pipeline + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24851) in GitLab 12.7. + +Users with [owner permissions](../../user/permissions.md) in a project can delete a pipeline +by clicking on the pipeline in the **CI/CD > Pipelines** to get to the **Pipeline Details** +page, then using the **Delete** button. + + + +CAUTION: **Warning:** +Deleting a pipeline will expire all pipeline caches, and delete all related objects, +such as builds, logs, artifacts, and triggers. **This action cannot be undone.** + +## Most Recent Pipeline + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/50499) in GitLab 12.3. + +There's a link to the latest pipeline for the last commit of a given branch at `/project/pipelines/[branch]/latest`. Also, `/project/pipelines/latest` will redirect you to the latest pipeline for the last commit on the project's default branch. + +## Security on protected branches + +A strict security model is enforced when pipelines are executed on +[protected branches](../../user/project/protected_branches.md). + +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 the [Web UI](#manually-executing-pipelines) or pipelines API). +- Run scheduled pipelines. +- Run pipelines using triggers. +- Trigger manual actions on existing pipelines. +- Retry or cancel existing jobs (using the Web UI or pipelines API). + +**Variables** marked as **protected** are accessible only to jobs that +run on protected branches, preventing untrusted users getting unintended access to +sensitive information like deployment credentials and tokens. + +**Runners** marked as **protected** can run jobs only on protected +branches, avoiding untrusted code to be executed on the protected runner and +preserving deployment keys and other credentials from being unintentionally +accessed. In order to ensure that jobs intended to be executed on protected +runners will not use regular runners, they must be tagged accordingly. + +## Persistent pipeline refs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17043) in GitLab 12.4. + +Previously, you'd have encountered unexpected pipeline failures when you force-pushed +a branch to its remote repository. To illustrate the problem, suppose you've had the current workflow: + +1. A user creates a feature branch named `example` and pushes it to a remote repository. +1. A new pipeline starts running on the `example` branch. +1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository. +1. A new pipeline starts running on the `example` branch again, however, + the previous pipeline (2) fails because of `fatal: reference is not a tree:` error. + +This is because the previous pipeline cannot find a checkout-SHA (which associated with the pipeline record) +from the `example` branch that the commit history has already been overwritten by the force-push. +Similarly, [Pipelines for merged results](../merge_request_pipelines/pipelines_for_merged_results/index.md) +might have failed intermittently due to [the same reason](../merge_request_pipelines/pipelines_for_merged_results/index.md#intermittently-pipelines-fail-by-fatal-reference-is-not-a-tree-error). + +As of GitLab 12.4, we've improved this behavior by persisting pipeline refs exclusively. +To illustrate its life cycle: + +1. A pipeline is created on a feature branch named `example`. +1. A persistent pipeline ref is created at `refs/pipelines/<pipeline-id>`, + which retains the checkout-SHA of the associated pipeline record. + This persistent ref stays intact during the pipeline execution, + even if the commit history of the `example` branch has been overwritten by force-push. +1. GitLab Runner fetches the persistent pipeline ref and gets source code from the checkout-SHA. +1. When the pipeline finished, its persistent ref is cleaned up in a background process. + +NOTE: **NOTE**: At this moment, this feature is on by default and can be manually disabled +by disabling `depend_on_persistent_pipeline_ref` feature flag. If you're interested in +manually disabling this behavior, please ask the administrator +to execute the following commands in rails console. + +```shell +> sudo gitlab-rails console # Login to Rails console of GitLab instance. +> project = Project.find_by_full_path('namespace/project-name') # Get the project instance. +> Feature.disable(:depend_on_persistent_pipeline_ref, project) # Disable the feature flag for specific project +> Feature.disable(:depend_on_persistent_pipeline_ref) # Disable the feature flag system-wide +``` diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index ea98638ae53..92cf1985d86 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -12,7 +12,7 @@ Cron notation is parsed by [Fugit](https://github.com/floraison/fugit). Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository. -Pipeline schedules can be used to also run [pipelines](../pipelines.md) at specific intervals. For example: +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. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md new file mode 100644 index 00000000000..53a529493d2 --- /dev/null +++ b/doc/ci/pipelines/settings.md @@ -0,0 +1,308 @@ +--- +type: reference, howto +--- + +# Pipelines settings + +To reach the pipelines settings navigate to your project's +**Settings > CI/CD**. + +The following settings can be configured per project. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s). +Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII). + +## Git strategy + +With Git strategy, you can choose the default way your repository is fetched +from GitLab in a job. + +There are two options. Using: + +- `git clone`, which is slower since it clones the repository from scratch + for every job, ensuring that the local working copy is always pristine. +- `git fetch`, which is faster as it re-uses the local working copy (falling + back to clone if it doesn't exist). + +The default Git strategy can be overridden by the [GIT_STRATEGY variable](../yaml/README.md#git-strategy) +in `.gitlab-ci.yml`. + +## Git shallow clone + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28919) in GitLab 12.0. + +NOTE: **Note**: +As of GitLab 12.0, newly created projects will automatically have a default +`git depth` value of `50`. + +It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning +a repository. Setting a limit to `git depth` can speed up Pipelines execution. Maximum +allowed value is `1000`. + +To disable shallow clone and make GitLab CI/CD fetch all branches and tags each time, +keep the value empty or set to `0`. + +This value can also be [overridden by `GIT_DEPTH`](../large_repositories/index.md#shallow-cloning) variable in `.gitlab-ci.yml` file. + +## Timeout + +Timeout defines the maximum amount of time in minutes that a job is able run. +This is configurable under your project's **Settings > CI/CD > General pipelines settings**. +The default value is 60 minutes. Decrease the time limit if you want to impose +a hard limit on your jobs' running time or increase it otherwise. In any case, +if the job surpasses the threshold, it is marked as failed. + +### Timeout overriding on Runner level + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17221) in GitLab 10.7. + +Project defined timeout (either specific timeout set by user or the default +60 minutes timeout) may be [overridden on Runner level](../runners/README.md#setting-maximum-job-timeout-for-a-runner). + +## Maximum artifacts size **(CORE ONLY)** + +For information about setting a maximum artifact size for a project, see +[Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only). + +## Custom CI configuration path + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12509) in GitLab 9.4. +> - [Support for external `.gitlab-ci.yml` locations](https://gitlab.com/gitlab-org/gitlab/issues/14376) introduced in GitLab 12.6. + +By default we look for the `.gitlab-ci.yml` file in the project's root +directory. If needed, you can specify an alternate path and file name, including locations outside the project. + +To customize the path: + +1. Go to the project's **Settings > CI / CD**. +1. Expand the **General pipelines** section. +1. Provide a value in the **Custom CI configuration path** field. +1. Click **Save changes**. + +If the CI configuration is stored within the repository in a non-default +location, the path must be relative to the root directory. Examples of valid +paths and file names include: + +- `.gitlab-ci.yml` (default) +- `.my-custom-file.yml` +- `my/path/.gitlab-ci.yml` +- `my/path/.my-custom-file.yml` + +If the CI configuration will be hosted on an external site, the URL link must end with `.yml`: + +- `http://example.com/generate/ci/config.yml` + +If the CI configuration will be hosted in a different project within GitLab, the path must be relative +to the root directory in the other project, with the group and project name added to the end: + +- `.gitlab-ci.yml@mygroup/another-project` +- `my/path/.my-custom-file.yml@mygroup/another-project` + +Hosting the configuration file in a separate project allows stricter control of the +configuration file. For example: + +- Create a public project to host the configuration file. +- Give write permissions on the project only to users who are allowed to edit the file. + +Other users and projects will be able to access the configuration file without being +able to edit it. + +## Test coverage parsing + +If you use test coverage in your code, GitLab can capture its output in the +job log using a regular expression. In the pipelines settings, search for the +"Test coverage parsing" section. + + + +Leave blank if you want to disable it or enter a ruby regular expression. You +can use <https://rubular.com> to test your regex. + +If the pipeline succeeds, the coverage is shown in the merge request widget and +in the jobs table. + + + + + +A few examples of known coverage tools for a variety of languages can be found +in the pipelines settings page. + +### Removing color codes + +Some test coverage tools output with ANSI color codes that won't be +parsed correctly by the regular expression and will cause coverage +parsing to fail. + +If your coverage tool doesn't provide an option to disable color +codes in the output, you can pipe the output of the coverage tool through a +small one line script that will strip the color codes off. + +For example: + +```shell +lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' +``` + +## Visibility of pipelines + +Pipeline visibility is determined by: + +- Your current [user access level](../../user/permissions.md). +- The **Public pipelines** project setting under your project's **Settings > CI/CD > General pipelines**. + +NOTE: **Note:** +If the project visibility is set to **Private**, the [**Public pipelines** setting will have no effect](../enable_or_disable_ci.md#per-project-user-setting). + +This also determines the visibility of these related features: + +- Job output logs +- Job artifacts +- The [pipeline security dashboard](../../user/application_security/security_dashboard/index.md#pipeline-security-dashboard) **(ULTIMATE)** + +If **Public pipelines** is enabled (default): + +- For **public** projects, anyone can view the pipelines and related features. +- For **internal** projects, any logged in user can view the pipelines + and related features. +- For **private** projects, any project member (guest or higher) can view the pipelines + and related features. + +If **Public pipelines** is disabled: + +- For **public** projects, anyone can view the pipelines, but only members + (reporter or higher) can access the related features. +- For **internal** projects, any logged in user can view the pipelines. + However, only members (reporter or higher) can access the job related features. +- For **private** projects, only project members (reporter or higher) + can view the pipelines or access the related features. + +## Auto-cancel pending pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9362) in GitLab 9.1. + +If you want all pending non-HEAD pipelines on branches to auto-cancel each time +a new pipeline is created, such as after a Git push or manually from the UI, +you can enable this in the project settings: + +1. Go to **{settings}** **Settings > CI / CD**. +1. Expand **General Pipelines**. +1. Check the **Auto-cancel redundant, pending pipelines** checkbox. +1. Click **Save changes**. + +## Skip older, pending deployment jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/25276) in GitLab 12.9. + +Your project may have multiple concurrent deployment jobs that are +scheduled to run within the same time frame. + +This can lead to a situation where an older deployment job runs after a +newer one, which may not be what you want. + +To avoid this scenario: + +1. Go to **{settings}** **Settings > CI / CD**. +1. Expand **General pipelines**. +1. Check the **Skip older, pending deployment jobs** checkbox. +1. Click **Save changes**. + +The pending deployment jobs will be skipped. + +## Pipeline Badges + +In the pipelines settings page you can find pipeline status and test coverage +badges for your project. The latest successful pipeline will be used to read +the pipeline status and test coverage values. + +Visit the pipelines settings page in your project to see the exact link to +your badges, as well as ways to embed the badge image in your HTML or Markdown +pages. + + + +### Pipeline status badge + +Depending on the status of your job, a badge can have the following values: + +- pending +- running +- passed +- failed +- skipped +- canceled +- unknown + +You can access a pipeline status badge image using the following link: + +```text +https://example.gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg +``` + +### Test coverage report badge + +GitLab makes it possible to define the regular expression for [coverage report](#test-coverage-parsing), +that each job log will be matched against. This means that each job in the +pipeline can have the test coverage percentage value defined. + +The test coverage badge can be accessed using following link: + +```text +https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg +``` + +If you would like to get the coverage report from a specific job, you can add +the `job=coverage_job_name` parameter to the URL. For example, the following +Markdown code will embed the test coverage report badge of the `coverage` job +into your `README.md`: + +```markdown + +``` + +### Badge styles + +Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Currently two styles are available: + +#### Flat (default) + +```text +https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat +``` + + + +#### Flat square + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30120) in GitLab 11.8. + +```text +https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square +``` + + + +## Environment Variables + +[Environment variables](../variables/README.md#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner. + +## Deploy Keys + +With Deploy Keys, GitLab allows you to import SSH public keys. You can then have +read only or read/write access to your project from the machines the keys were generated from. + +SSH keys added to your project settings will be used for continuous integration, +staging, or production servers. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> |
