Search Results for ""

Enabling Pipelines

This document describes how to enable the pipelines engine if you need to trigger workflows from the CircleCI API or auto-cancel workflows. Pipelines are not currently available on self hosted installations of CircleCI Server.

Getting Started

Most projects will have Pipelines enabled by default. Verify the project pipeline setting in the Advanced section of your project’s Settings page in the CircleCI app. Note: Pipelines are compatible with v2 and v2.1 configurations of CircleCI.

What are Pipelines?

Pipelines are our name for the full set of configurations you run when you trigger work on your projects in CircleCI. Pipelines contain your workflows, which coordinate jobs.

Benefits of Using Pipelines

Pipelines offer the following benefits:

  • Use the new API endpoint to trigger a pipeline
  • Use pipeline parameters to trigger conditional workflows.
  • Access to version 2.1 config, which provides:
    • Reusable config elements, including executors, commands and jobs.
    • Packaged reusable config, known as orbs.
    • Improved config validation error messages.
    • Option to enable auto-cancel, within Advanced Settings, to abort workflows when new builds are triggered on non-default branches.

Note, it is important to carefully consider the impact of enabling the auto-cancel feature, for example, if you have configured automated deployment jobs on non-default branches.

For more detailed information on pipelines and how you can use their properties in your workflows and jobs, please see the following guides:

Implications of Using Pipelines

When using pipelines, please note the following:

  • If no builds or workflows are defined, you will receive an error.

Transitioning to Pipelines

The following sections outline the process of transitioning to pipelines.

Pipelines with 2.0 Configuration

When using 2.0 configuration in combination with pipelines, CircleCI will inject the CIRCLE_COMPARE_URL environment variable into all jobs for backwards compatibility. This environment variable is generated in a different way to the version that is available in legacy jobs, and is not always available – it is not injected when there is no meaningful previous revision, for example, on the first push of commits to an empty repository, or when a new branch is created/pushed without any additional commits.

Opting In to Pipelines on a Branch

There are two main ways to try out pipelines on a branch without committing to changing the project-wide setting:

  1. Use version 2.1 configuration
  2. Use version 2.0 configuration and include the experimental stanza

Note: these methods currently apply to webhooks as well as the version 2 “pipeline trigger” API, but not the version 1.1 “job trigger” API yet. Support for using the version 1.1 API with pipelines will be announced soon.

If you have used the latest features in CircleCI version 2.1 configuration and/or orbs, then you already have pipelines enabled for your project. Also, all projects added after September 1, 2018 already have pipelines enabled by default. If your project does not yet have pipelines enabled, you can find pipelines under “Advanced Settings” in your project’s settings page. If you don’t see that option on your project’s settings page, this means your project already has pipelines enabled.

Using Version 2.1 Configuration

Using configuration version 2.1 will automatically enable the use of pipelines and allow the use of 2.1-exclusive features, for example, pipeline values.

Using the experimental Stanza

There is also a configuration stanza that you can use to enable pipelines using a version 2.0 configuration. An example of this stanza is shown below:

  pipelines: true

Giving Feedback

If you have feedback, suugestions, or comments:

  • Tweet @circleci with thoughts
  • Vote or add to our Ideas board

See Also

Refer to the Skipping and Cancelling Builds document for more details.