diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-13 15:09:21 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-13 15:09:21 +0000 |
| commit | c36152ff8c41fad2f413f253eb7ac5c927e47c56 (patch) | |
| tree | bbf300da207de3e8bbf272d44111ceedb18f5833 /doc | |
| parent | 286fe61013674fe2d245ffc8d2233baf09923e70 (diff) | |
| download | gitlab-ce-c36152ff8c41fad2f413f253eb7ac5c927e47c56.tar.gz | |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
55 files changed, 1041 insertions, 938 deletions
diff --git a/doc/README.md b/doc/README.md index 198f37c9ea1..95a8b09dd07 100644 --- a/doc/README.md +++ b/doc/README.md @@ -238,7 +238,7 @@ The following documentation relates to the DevOps **Verify** stage: | [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Integration with GitLab. | | [JUnit test reports](ci/junit_test_reports.md) | Display JUnit test reports on merge requests. | | [Multi-project pipelines](ci/multi_project_pipelines.md) **(PREMIUM)** | Visualize entire pipelines that span multiple projects, including all cross-project inter-dependencies. | -| [Pipeline Graphs](ci/pipelines.md#visualizing-pipelines) | Visualize builds. | +| [Pipeline Graphs](ci/pipelines/index.md#visualizing-pipelines) | Visualize builds. | | [Review Apps](ci/review_apps/index.md) | Preview changes to your application right from a merge request. | <div align="right"> diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 52b6867a310..8cd10f5ea4e 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -17,4 +17,4 @@ GitLab’s [security features](../security/README.md) may also help you meet rel |**[Audit logs](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives admins the ability to view any modifications made within the GitLab server in an advanced audit log system, so you can control, analyze, and track every change.|Premium+|| |**[Auditor users](auditor_users.md)**<br>Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance.|Premium+|| |**[Credentials inventory](../user/admin_area/credentials_inventory.md)**<br>With a credentials inventory, GitLab administrators can keep track of the credentials used by all of the users in their GitLab instance. |Ultimate|| -|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners-premium) and [custom CI Configuration Paths](../user/project/pipelines/settings.md#custom-ci-configuration-path)**<br> GitLab Silver and Premium users can leverage GitLab's cross-project YAML configuration's to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles.|Premium+|| +|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners-premium) and [custom CI Configuration Paths](../ci/pipelines/settings.md#custom-ci-configuration-path)**<br> GitLab Silver and Premium users can leverage GitLab's cross-project YAML configuration's to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles.|Premium+|| diff --git a/doc/api/projects.md b/doc/api/projects.md index 5b769ca4ce9..a00bd442872 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1174,7 +1174,7 @@ PUT /projects/:id | `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | | `build_coverage_regex` | string | no | Test coverage parsing | | `ci_config_path` | string | no | The path to CI config file | -| `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../user/project/pipelines/settings.md#git-shallow-clone) | +| `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#git-shallow-clone) | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | | `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | | `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | diff --git a/doc/ci/README.md b/doc/ci/README.md index 1ec91dd8522..fe88b414702 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -80,13 +80,13 @@ GitLab CI/CD supports numerous configuration options: | Configuration | Description | |:--------------|:-------------| -| [Pipelines](pipelines.md) | Structure your CI/CD process through pipelines. | +| [Pipelines](pipelines/index.md) | Structure your CI/CD process through pipelines. | | [Environment variables](variables/README.md) | Reuse values based on a variable/value key pair. | | [Environments](environments.md) | Deploy your application to different environments (e.g., staging, production). | | [Job artifacts](pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. | | [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. | | [Schedule pipelines](pipelines/schedules.md) | Schedule pipelines to run as often as you need. | -| [Custom path for `.gitlab-ci.yml`](../user/project/pipelines/settings.md#custom-ci-configuration-path) | Define a custom path for the CI/CD configuration file. | +| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-ci-configuration-path) | Define a custom path for the CI/CD configuration file. | | [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules.| | [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. | | [Pipelines triggers](triggers/README.md) | Trigger pipelines through the API. | @@ -149,7 +149,7 @@ As a GitLab administrator, you can change the default behavior of GitLab CI/CD for: - An [entire GitLab instance](../user/admin_area/settings/continuous_integration.md). -- Specific projects, using [pipelines settings](../user/project/pipelines/settings.md). +- Specific projects, using [pipelines settings](pipelines/settings.md). See also: diff --git a/doc/ci/environments.md b/doc/ci/environments.md index ff4096600e0..2268ab309c3 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -47,7 +47,7 @@ can even access a [web terminal](#web-terminals) for your environment from withi Configuring environments involves: -1. Understanding how [pipelines](pipelines.md) work. +1. Understanding how [pipelines](pipelines/index.md) work. 1. Defining environments in your project's [`.gitlab-ci.yml`](yaml/README.md) file. 1. Creating a job configured to deploy your application. For example, a deploy job configured with [`environment`](yaml/README.md#environment) to deploy your application to a [Kubernetes cluster](../user/project/clusters/index.md). diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index 7d039ab1aeb..ffdffcc88bd 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -60,7 +60,7 @@ You can use other versions of Scala and SBT by defining them in Add the `Coverage was \[\d+.\d+\%\]` regular expression in the **Settings ➔ Pipelines ➔ Coverage report** project setting to -retrieve the [test coverage](../../user/project/pipelines/settings.md#test-coverage-report-badge) +retrieve the [test coverage](../pipelines/settings.md#test-coverage-report-badge) rate from the build trace and have it displayed with your jobs. **Pipelines** must be enabled for this option to appear. diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index 2678936ae70..f3e9efae7d4 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -48,7 +48,7 @@ There are some high level differences between the products worth mentioning: - on push - on [schedule](../pipelines/schedules.md) - - from the [GitLab UI](../pipelines.md#manually-executing-pipelines) + - from the [GitLab UI](../pipelines/index.md#manually-executing-pipelines) - by [API call](../triggers/README.md) - by [webhook](../triggers/README.md#triggering-a-pipeline-from-a-webhook) - by [ChatOps](../chatops/README.md) @@ -83,6 +83,29 @@ There are some high level differences between the products worth mentioning: own environment, which will be slower and may be less consistent. We have extensive docs on [how to use the Container Registry](../../user/packages/container_registry/index.md). - Totally stuck and not sure where to turn for advice? The [GitLab community forum](https://forum.gitlab.com/) can be a great resource. +## Agents vs. Runners + +Both Jenkins agents and GitLab Runners are the hosts that run jobs. To convert the +Jenkins agent, simply uninstall it and then [install and register the runner](../runners/README.md). +Runners do not require much overhead, so you can size them similarly to the Jenkins +agents you were using. + +There are some important differences in the way Runners work in comparison to agents: + +- Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/README.md#shared-specific-and-group-runners). + They will self-select jobs from the scopes you've defined automatically. +- You can also [use tags](../runners/README.md#using-tags) for finer control, and + associate runners with specific jobs. For example, you can use a tag for jobs that + require dedicated, more powerful, or specific hardware. +- GitLab has [autoscaling for Runners](https://docs.gitlab.com/runner/configuration/autoscale.html) + which will let configure them to be provisioned as needed, and scaled down when not. + This is similar to ephemeral agents in Jenkins. + +If you are using `gitlab.com`, you can take advantage of our [shared Runner fleet](../../user/gitlab_com/index.md#shared-runners) +to run jobs without provisioning your own Runners. We are investigating making them +[available for self-managed instances](https://gitlab.com/gitlab-org/customers-gitlab-com/issues/414) +as well. + ## Groovy vs. YAML Jenkins Pipelines are based on [Groovy](https://groovy-lang.org/), so the pipeline specification is written as code. diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md index c82f0ab3a42..1595f4d4427 100644 --- a/doc/ci/junit_test_reports.md +++ b/doc/ci/junit_test_reports.md @@ -9,7 +9,7 @@ Requires GitLab Runner 11.2 and above. ## Overview -It is very common that a [CI/CD pipeline](pipelines.md) contains a +It is very common that a [CI/CD pipeline](pipelines/index.md) contains a test job that will verify your code. If the tests fail, the pipeline fails and users get notified. The person that works on the merge request will have to check the job logs and see where the @@ -42,13 +42,15 @@ JUnit test reports, where: - The base branch is the target branch (usually `master`). - The head branch is the source branch (the latest pipeline in each merge request). -The reports panel has a summary showing how many tests failed and how many were fixed. -If no comparison can be done because data for the base branch is not available, -the panel will just show the list of failed tests for head. +The reports panel has a summary showing how many tests failed, how many had errors +and how many were fixed. If no comparison can be done because data for the base branch +is not available, the panel will just show the list of failed tests for head. -There are three types of results: +There are four types of results: 1. **Newly failed tests:** Test cases which passed on base branch and failed on head branch +1. **Newly encountered errors:** Test cases which passed on base branch and failed due to a + test error on head branch 1. **Existing failures:** Test cases which failed on base branch and failed on head branch 1. **Resolved failures:** Test cases which failed on base branch and passed on head branch diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index bab93392587..6dbc8f98247 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -115,7 +115,7 @@ unexpected timing. For example, when a source or target branch is advanced. In this case, the pipeline fails because of `fatal: reference is not a tree:` error, which indicates that the checkout-SHA is not found in the merge ref. -This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../pipelines.md#persistent-pipeline-refs). +This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../pipelines/index.md#persistent-pipeline-refs). You should be able to create pipelines at any timings without concerning the error. ## Using Merge Trains **(PREMIUM)** diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index d56935dc3a3..6a4dff635ad 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -40,7 +40,7 @@ With Multi-Project Pipelines you can visualize the entire pipeline, including al > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2121) in [GitLab Premium 9.3](https://about.gitlab.com/releases/2017/06/22/gitlab-9-3-released/#multi-project-pipeline-graphs). When you configure GitLab CI for your project, you can visualize the stages of your -[jobs](pipelines.md#configuring-pipelines) on a [pipeline graph](pipelines.md#visualizing-pipelines). +[jobs](pipelines/index.md#configuring-pipelines) on a [pipeline graph](pipelines/index.md#visualizing-pipelines).  diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index cf872b0ee1d..edebd12f07a 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -1,566 +1,5 @@ --- -type: reference +redirect_to: 'pipelines/index.md' --- -# 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](../user/project/pipelines/settings.md). -- Schedules for pipelines. For more information, see [Pipeline schedules](../user/project/pipelines/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](../user/project/pipelines/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 -``` +This document was moved to [another location](pipelines/index.md). diff --git a/doc/ci/img/collapsible_log_v12_6.png b/doc/ci/pipelines/img/collapsible_log_v12_6.png Binary files differindex 24b2c83f7c1..24b2c83f7c1 100644 --- a/doc/ci/img/collapsible_log_v12_6.png +++ b/doc/ci/pipelines/img/collapsible_log_v12_6.png diff --git a/doc/ci/img/job_failure_reason.png b/doc/ci/pipelines/img/job_failure_reason.png Binary files differindex d44b8e6d1be..d44b8e6d1be 100644 --- a/doc/ci/img/job_failure_reason.png +++ b/doc/ci/pipelines/img/job_failure_reason.png diff --git a/doc/ci/img/manual_job_variables.png b/doc/ci/pipelines/img/manual_job_variables.png Binary files differindex a5ed351fdcd..a5ed351fdcd 100644 --- a/doc/ci/img/manual_job_variables.png +++ b/doc/ci/pipelines/img/manual_job_variables.png diff --git a/doc/ci/img/pipeline-delete.png b/doc/ci/pipelines/img/pipeline-delete.png Binary files differindex d9dba1f455d..d9dba1f455d 100644 --- a/doc/ci/img/pipeline-delete.png +++ b/doc/ci/pipelines/img/pipeline-delete.png diff --git a/doc/ci/img/pipeline_incremental_rollout.png b/doc/ci/pipelines/img/pipeline_incremental_rollout.png Binary files differindex b3498e9a5a5..b3498e9a5a5 100644 --- a/doc/ci/img/pipeline_incremental_rollout.png +++ b/doc/ci/pipelines/img/pipeline_incremental_rollout.png diff --git a/doc/ci/img/pipelines.png b/doc/ci/pipelines/img/pipelines.png Binary files differindex a604fcb2587..a604fcb2587 100644 --- a/doc/ci/img/pipelines.png +++ b/doc/ci/pipelines/img/pipelines.png diff --git a/doc/ci/img/pipelines_duration_chart.png b/doc/ci/pipelines/img/pipelines_duration_chart.png Binary files differindex 0be7539ba0a..0be7539ba0a 100644 --- a/doc/ci/img/pipelines_duration_chart.png +++ b/doc/ci/pipelines/img/pipelines_duration_chart.png diff --git a/doc/ci/img/pipelines_grouped.png b/doc/ci/pipelines/img/pipelines_grouped.png Binary files differindex 82814754747..82814754747 100644 --- a/doc/ci/img/pipelines_grouped.png +++ b/doc/ci/pipelines/img/pipelines_grouped.png diff --git a/doc/ci/img/pipelines_index.png b/doc/ci/pipelines/img/pipelines_index.png Binary files differindex e168e7e23df..e168e7e23df 100644 --- a/doc/ci/img/pipelines_index.png +++ b/doc/ci/pipelines/img/pipelines_index.png diff --git a/doc/ci/img/pipelines_mini_graph.png b/doc/ci/pipelines/img/pipelines_mini_graph.png Binary files differindex 8656b02f60d..8656b02f60d 100644 --- a/doc/ci/img/pipelines_mini_graph.png +++ b/doc/ci/pipelines/img/pipelines_mini_graph.png diff --git a/doc/ci/img/pipelines_mini_graph_simple.png b/doc/ci/pipelines/img/pipelines_mini_graph_simple.png Binary files differindex d00a8313088..d00a8313088 100644 --- a/doc/ci/img/pipelines_mini_graph_simple.png +++ b/doc/ci/pipelines/img/pipelines_mini_graph_simple.png diff --git a/doc/ci/img/pipelines_mini_graph_sorting.png b/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png Binary files differindex 3a4e5453360..3a4e5453360 100644 --- a/doc/ci/img/pipelines_mini_graph_sorting.png +++ b/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png diff --git a/doc/user/project/pipelines/img/pipelines_settings_badges.png b/doc/ci/pipelines/img/pipelines_settings_badges.png Binary files differindex 3bdc6374c15..3bdc6374c15 100644 --- a/doc/user/project/pipelines/img/pipelines_settings_badges.png +++ b/doc/ci/pipelines/img/pipelines_settings_badges.png diff --git a/doc/user/project/pipelines/img/pipelines_settings_test_coverage.png b/doc/ci/pipelines/img/pipelines_settings_test_coverage.png Binary files differindex 13ed69be810..13ed69be810 100644 --- a/doc/user/project/pipelines/img/pipelines_settings_test_coverage.png +++ b/doc/ci/pipelines/img/pipelines_settings_test_coverage.png diff --git a/doc/ci/img/pipelines_success_chart.png b/doc/ci/pipelines/img/pipelines_success_chart.png Binary files differindex 10602b75eeb..10602b75eeb 100644 --- a/doc/ci/img/pipelines_success_chart.png +++ b/doc/ci/pipelines/img/pipelines_success_chart.png diff --git a/doc/user/project/pipelines/img/pipelines_test_coverage_build.png b/doc/ci/pipelines/img/pipelines_test_coverage_build.png Binary files differindex 7eaba1a256f..7eaba1a256f 100644 --- a/doc/user/project/pipelines/img/pipelines_test_coverage_build.png +++ b/doc/ci/pipelines/img/pipelines_test_coverage_build.png diff --git a/doc/user/project/pipelines/img/pipelines_test_coverage_mr_widget.png b/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png Binary files differindex fbcd612f3f2..fbcd612f3f2 100644 --- a/doc/user/project/pipelines/img/pipelines_test_coverage_mr_widget.png +++ 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. --> diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 83b3ec44314..0ea37e26224 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -23,7 +23,7 @@ that you can consider for use in your project. You may want to familiarize yourself with these prior to getting started. GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) service. For each commit or push to trigger your CI -[pipeline](../pipelines.md), you must: +[pipeline](../pipelines/index.md), you must: - Add a [`.gitlab-ci.yml` file](#creating-a-gitlab-ciyml-file) to your repository's root directory. - Ensure your project is configured to use a [Runner](#configuring-a-runner). diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 91b4000b74a..7e1aae4709a 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -422,4 +422,4 @@ You can find the IP address of a Runner for a specific project by: [register]: https://docs.gitlab.com/runner/register/ [protected branches]: ../../user/project/protected_branches.md [protected tags]: ../../user/project/protected_tags.md -[project defined timeout]: ../../user/project/pipelines/settings.html#timeout +[project defined timeout]: ../pipelines/settings.md#timeout diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index 804970e08f2..b3a97d34575 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -37,7 +37,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/) NOTE: **Note:** The private key will not be displayed in the job log, unless you enable [debug logging](../variables/README.md#debug-logging). You might also want to -check the [visibility of your pipelines](../../user/project/pipelines/settings.md#visibility-of-pipelines). +check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines). ## SSH keys when using the Docker executor diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index cbc6b9947b3..5a6d30a1079 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -169,7 +169,7 @@ You can either set the variable directly in the `.gitlab-ci.yml` file or through the UI. NOTE: **Note:** -It is possible to [specify variables when running manual jobs](../pipelines.md#specifying-variables-when-running-manual-jobs). +It is possible to [specify variables when running manual jobs](../pipelines/index.md#specifying-variables-when-running-manual-jobs). #### Via `.gitlab-ci.yml` @@ -185,14 +185,19 @@ For a deeper look into them, see [`.gitlab-ci.yml` defined variables](#gitlab-ci #### Via the UI -From the UI, navigate to your project's **Settings > CI/CD** and -expand **Variables**. Create a new variable by choosing its **type**, naming -it in the field **Input variable key**, and defining its value in the -**Input variable value** field: +From within the UI, you can add or update custom environment variables: - +1. Go to your project's **Settings > CI/CD** and expand the **Variables** section. +1. Click the **Add variable** button. In the **Add variable** modal, fill in the details: -You'll also see the option to mask and/or protect your variables. + - **Key**: Must be one line, with no spaces, using only letters, numbers, `-` or `_`. + - **Value**: No limitations. + - **Type**: `File` or `Variable`. + - **Environment scope**: `All`, or specific environments. + - **Protect variable** (Optional): If selected, the variable will only be available in pipelines that run on protected branches or tags. + - **Mask variable** (Optional): If selected, the variable's **Value** will be masked in job logs. The variable will fail to save if the value does not meet the [masking requirements](#masked-variables). + +After a variable is created, you can update any of the details by clicking on the **{pencil}** **Edit** button. Once you've set the variables, call them from the `.gitlab-ci.yml` file: @@ -460,7 +465,7 @@ limitations with the current Auto DevOps scripting environment. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/44059) in GitLab 10.8. -[Manually triggered pipelines](../pipelines.md#manually-executing-pipelines) allow you to override the value of a current variable. +[Manually triggered pipelines](../pipelines/index.md#manually-executing-pipelines) allow you to override the value of a current variable. For instance, suppose you added a [custom variable `$TEST`](#creating-a-custom-environment-variable) @@ -616,7 +621,7 @@ variables that were set, etc. Before enabling this, you should ensure jobs are visible to [team members only](../../user/permissions.md#project-features). You should -also [erase](../pipelines.md#accessing-individual-jobs) all generated job logs +also [erase](../pipelines/index.md#accessing-individual-jobs) all generated job logs before making them visible again. To enable debug logs (traces), set the `CI_DEBUG_TRACE` variable to `true`: diff --git a/doc/ci/variables/img/new_custom_variables_example.png b/doc/ci/variables/img/new_custom_variables_example.png Binary files differdeleted file mode 100644 index bb60e6bab21..00000000000 --- a/doc/ci/variables/img/new_custom_variables_example.png +++ /dev/null diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index e0c41d821a6..9224d73b58b 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -4,7 +4,7 @@ type: reference # GitLab CI/CD Pipeline Configuration Reference -GitLab CI/CD [pipelines](../pipelines.md) are configured using a YAML file called `.gitlab-ci.yml` within each project. +GitLab CI/CD [pipelines](../pipelines/index.md) are configured using a YAML file called `.gitlab-ci.yml` within each project. The `.gitlab-ci.yml` file defines the structure and order of the pipelines and determines: @@ -2735,7 +2735,7 @@ test: ``` The job-level timeout can exceed the -[project-level timeout](../../user/project/pipelines/settings.md#timeout) but can not +[project-level timeout](../pipelines/settings.md#timeout) but can not exceed the Runner-specific timeout. ### `parallel` @@ -2906,7 +2906,7 @@ starting, at the cost of reduced parallelization. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23464) in GitLab 12.3. `interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`. -This value will only be used if the [automatic cancellation of redundant pipelines feature](../../user/project/pipelines/settings.md#auto-cancel-pending-pipelines) +This value will only be used if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines) is enabled. When enabled, a pipeline on the same branch will be canceled when: diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 7d884737f5b..9e419be9419 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -21,6 +21,12 @@ and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8e78ea7f326b2ef6 Everything covered in this deep dive was accurate as of GitLab 11.9, and while specific details may have changed since then, it should still serve as a good introduction. +## GraphiQL + +GraphiQL is an interactive GraphQL API explorer where you can play around with existing queries. +You can access it in any GitLab environment on `https://<your-gitlab-site.com>/-/graphql-explorer`. +For example, the one for [GitLab.com](https://gitlab.com/-/graphql-explorer). + ## Authentication Authentication happens through the `GraphqlController`, right now this @@ -335,7 +341,7 @@ field :id, GraphQL::ID_TYPE, description: 'ID of the resource' Descriptions of fields and arguments are viewable to users through: -- The [GraphiQL explorer](../api/graphql/#graphiql). +- The [GraphiQL explorer](#graphiql). - The [static GraphQL API reference](../api/graphql/#reference). ### Description styleguide diff --git a/doc/development/logging.md b/doc/development/logging.md index a90d78ba8d9..f10737da766 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -112,20 +112,57 @@ importer progresses. Here's what to do: all messages might have `current_user_id` and `project_id` to make it easier to search for activities by user for a given time. -1. Do NOT mix and match types. Elasticsearch won't be able to index your - logs properly if you [mix integer and string - types](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html#_avoiding_type_gotchas): +#### Implicit schema for JSON logging + +When using something like Elasticsearch to index structured logs, there is a +schema for the types of each log field (even if that schema is implicit / +inferred). It's important to be consistent with the types of your field values, +otherwise this might break the ability to search/filter on these fields, or even +cause whole log events to be dropped. While much of this section is phrased in +an Elasticsearch-specific way, the concepts should translate to many systems you +might use to index structured logs. GitLab.com uses Elasticsearch to index log +data. + +Unless a field type is explicitly mapped, Elasticsearch will infer the type from +the first instance of that field value it sees. Subsequent instances of that +field value with different types will either fail to be indexed, or in some +cases (scalar/object conflict), the whole log line will be dropped. + +GitLab.com's logging Elasticsearch sets +[`ignore_malformed`](https://www.elastic.co/guide/en/elasticsearch/reference/current/ignore-malformed.html), +which allows documents to be indexed even when there are simpler sorts of +mapping conflict (for example, number / string), although indexing on the affected fields +will break. + +Examples: - ```ruby - # BAD - logger.info(message: "Import error", error: 1) - logger.info(message: "Import error", error: "I/O failure") - ``` +```ruby +# GOOD +logger.info(message: "Import error", error_code: 1, error: "I/O failure") - ```ruby - # GOOD - logger.info(message: "Import error", error_code: 1, error: "I/O failure") - ``` +# BAD +logger.info(message: "Import error", error: 1) +logger.info(message: "Import error", error: "I/O failure") + +# WORST +logger.info(message: "Import error", error: "I/O failure") +logger.info(message: "Import error", error: { message: "I/O failure" }) +``` + +List elements must be the same type: + +```ruby +# GOOD +logger.info(a_list: ["foo", "1", "true"]) + +# BAD +logger.info(a_list: ["foo", 1, true]) +``` + +Resources: + +- [Elasticsearch mapping - avoiding type gotchas](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html#_avoiding_type_gotchas) +- [Elasticsearch mapping types]( https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html) ## Multi-destination Logging diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 3f202115b4c..776ac252b76 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -176,9 +176,15 @@ Removing a column: ```ruby include Gitlab::Database::MigrationHelpers -def change +def up with_lock_retries do - remove_column :users, :full_name, :string + remove_column :users, :full_name + end +end + +def down + with_lock_retries do + add_column :users, :full_name, :string end end ``` @@ -188,11 +194,17 @@ Removing a foreign key: ```ruby include Gitlab::Database::MigrationHelpers -def change +def up with_lock_retries do remove_foreign_key :issues, :projects end end + +def down + with_lock_retries do + add_foreign_key :issues, :projects + end +end ``` Changing default value for a column: @@ -200,11 +212,17 @@ Changing default value for a column: ```ruby include Gitlab::Database::MigrationHelpers -def change +def up with_lock_retries do change_column_default :merge_requests, :lock_version, from: nil, to: 0 end end + +def down + with_lock_retries do + change_column_default :merge_requests, :lock_version, from: 0, to: nil + end +end ``` ### When to use the helper method @@ -231,6 +249,8 @@ Example changes: **Note:** `with_lock_retries` method **cannot** be used with `disable_ddl_transaction!`. +**Note:** `with_lock_retries` method **cannot** be used within the `change` method, you must manually define the `up` and `down` methods to make the migration reversible. + ### How the helper method works 1. Iterate 50 times. diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 941e83782b2..0ca05fe0cda 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -354,7 +354,7 @@ features, and the instance will be read / write again. ## CI pipeline minutes -CI pipeline minutes are the execution time for your [pipelines](../ci/pipelines.md) on GitLab's shared runners. Each [GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota of CI pipeline minutes. +CI pipeline minutes are the execution time for your [pipelines](../ci/pipelines/index.md) on GitLab's shared runners. Each [GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota of CI pipeline minutes. Quotas apply to: diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 4e75102d808..50b2fbeaa60 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -1375,7 +1375,7 @@ increasing the rollout up to 100%. If `INCREMENTAL_ROLLOUT_MODE` is set to `manual` in your project, then instead of the standard `production` job, 4 different -[manual jobs](../../ci/pipelines.md#manual-actions-from-pipeline-graphs) +[manual jobs](../../ci/pipelines/index.md#manual-actions-from-pipeline-graphs) will be created: 1. `rollout 10%` diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index bdb5125e5aa..1244f0da0e9 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -53,7 +53,7 @@ To change it at the: 1. Change the value of **maximum artifacts size (in MB)**. 1. Press **Save changes** for the changes to take effect. -- [Project level](../../project/pipelines/settings.md) (this will override the instance and group settings): +- [Project level](../../../ci/pipelines/settings.md) (this will override the instance and group settings): 1. Go to the project's **Settings > CI / CD > General Pipelines**. 1. Change the value of **maximum artifacts size (in MB)**. @@ -152,7 +152,7 @@ Area of your GitLab instance (`.gitlab-ci.yml` if not set): 1. Input the new path in the **Default CI configuration path** field. 1. Hit **Save changes** for the changes to take effect. -It is also possible to specify a [custom CI configuration path for a specific project](../../project/pipelines/settings.md#custom-ci-configuration-path). +It is also possible to specify a [custom CI configuration path for a specific project](../../../ci/pipelines/settings.md#custom-ci-configuration-path). <!-- ## Troubleshooting diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index da36d7ff95c..131247910ab 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -13,7 +13,7 @@ features and can be accessed through a project's sidebar nav.  -The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines.md) to determine the configuration +The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) to determine the configuration state of each feature. If a job with the expected security report artifact exists in the pipeline, the feature is considered configured. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 7f06eebc806..4f7284fb05b 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -420,7 +420,7 @@ read through the documentation on the [new CI/CD permissions model](project/new_ The permission to merge or push to protected branches is used to define if a user can run CI/CD pipelines and execute actions on jobs that are related to those branches. -See [Security on protected branches](../ci/pipelines.md#security-on-protected-branches) +See [Security on protected branches](../ci/pipelines/index.md#security-on-protected-branches) for details about the pipelines security model. ## LDAP users permissions diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index c9228cd79a6..aaf70e4e4d6 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -75,5 +75,5 @@ You can also configure badges via the GitLab API. As in the settings, there is a distinction between endpoints for badges on the [project level](../../api/project_badges.md) and [group level](../../api/group_badges.md). -[pipeline status]: pipelines/settings.md#pipeline-status-badge -[test coverage]: pipelines/settings.md#test-coverage-report-badge +[pipeline status]: ../../ci/pipelines/settings.md#pipeline-status-badge +[test coverage]: ../../ci/pipelines/settings.md#test-coverage-report-badge diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index c9d7d723eb5..4594d415fa0 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -20,7 +20,7 @@ NOTE: **Scalable app deployment with GitLab and Google Cloud Platform** Using the GitLab project Kubernetes integration, you can: - Use [Review Apps](../../../ci/review_apps/index.md). -- Run [pipelines](../../../ci/pipelines.md). +- Run [pipelines](../../../ci/pipelines/index.md). - [Deploy](#deploying-to-a-kubernetes-cluster) your applications. - Detect and [monitor Kubernetes](#kubernetes-monitoring). - Use it with [Auto DevOps](#auto-devops). diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index b8ba5e89949..cf9ac15f5ac 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -102,5 +102,5 @@ back to both GitLab and GitHub when completed. NOTE: **Note:** If you don't commit very often to your project, you may want to use -[scheduled pipelines](../pipelines/schedules.md) to run the job on a regular +[scheduled pipelines](../../../ci/pipelines/schedules.md) to run the job on a regular basis. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index ea36092168d..3a356ec0418 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -66,15 +66,15 @@ When you create a project in GitLab, you'll have access to a large number of - [Auto Deploy](../../topics/autodevops/index.md#auto-deploy): Configure GitLab CI/CD to automatically set up your app's deployment - [Enable and disable GitLab CI](../../ci/enable_or_disable_ci.md) - - [Pipelines](../../ci/pipelines.md): Configure and visualize + - [Pipelines](../../ci/pipelines/index.md): Configure and visualize your GitLab CI/CD pipelines from the UI - - [Scheduled Pipelines](pipelines/schedules.md): Schedule a pipeline + - [Scheduled Pipelines](../../ci/pipelines/schedules.md): Schedule a pipeline to start at a chosen time - - [Pipeline Graphs](../../ci/pipelines.md#visualizing-pipelines): View your + - [Pipeline Graphs](../../ci/pipelines/index.md#visualizing-pipelines): View your entire pipeline from the UI - - [Job artifacts](pipelines/job_artifacts.md): Define, + - [Job artifacts](../../ci/pipelines/job_artifacts.md): Define, browse, and download job artifacts - - [Pipeline settings](pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job), + - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job), timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project with a Kubernetes cluster diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index ddc9e427ac2..5a8ce6a4f84 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -14,7 +14,7 @@ Code Quality: - Uses [Code Climate Engines](https://codeclimate.com), which are free and open source. Code Quality doesn't require a Code Climate subscription. -- Runs in [pipelines](../../../ci/pipelines.md) using a Docker image built in the +- Runs in [pipelines](../../../ci/pipelines/index.md) using a Docker image built in the [GitLab Code Quality](https://gitlab.com/gitlab-org/security-products/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/security-products/codequality/-/tree/master/codeclimate_defaults). - Can make use of a [template](#example-configuration). diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index e0bf32baea6..8281de33e5f 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -94,14 +94,14 @@ or link to useful information directly in the merge request page: | [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests | | [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. | | [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | -| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../pipelines/job_artifacts.md) in merge requests. | +| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | | [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | | [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | | [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | | [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | | [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | | [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | -| [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines) | View the status of pipelines within the merge request, including the deployment process. | +| [Pipeline Graphs](../../../ci/pipelines/index.md#visualizing-pipelines) | View the status of pipelines within the merge request, including the deployment process. | ### Security Reports **(ULTIMATE)** diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index f3f791a3e22..bb9192e3600 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -120,7 +120,7 @@ be disabled. If the pipeline fails to deploy, the deployment info will be hidden  -For more information, [read about pipelines](../../../ci/pipelines.md). +For more information, [read about pipelines](../../../ci/pipelines/index.md). ### Merge when pipeline succeeds (MWPS) diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 5892a1be494..c23eaebcbe9 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -2,4 +2,4 @@ redirect_to: '../../../ci/pipelines/job_artifacts.md' --- -This document was moved to [pipelines/job_artifacts.md](../../../ci/pipelines/job_artifacts.md). +This document was moved to [another location](../../../ci/pipelines/job_artifacts.md). diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index f67f0896de4..af4cbe13aba 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -1,308 +1,5 @@ --- -type: reference, howto +redirect_to: '../../../ci/pipelines/settings.md' --- -# 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](../../../ci/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`](../../../ci/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](../../../ci/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](../../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](../../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](../../../ci/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](../../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](../../../ci/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. --> +This document was moved to [another location](../../../ci/pipelines/settings.md). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index ab6b4e7f858..14feb189964 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -187,7 +187,7 @@ Additionally, direct pushes to the protected branch are denied if a rule is matc The permission to merge or push to protected branches is used to define if a user can run CI/CD pipelines and execute actions on jobs that are related to those branches. -See [Security on protected branches](../../ci/pipelines.md#security-on-protected-branches) +See [Security on protected branches](../../ci/pipelines/index.md#security-on-protected-branches) for details about the pipelines security model. ## Changelog |
