Working with 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.

What are pipelines?

CircleCI Pipelines encompass the full set of workflows you run when triggering work on your projects in CircleCI. Workflows coordinate the jobs defined within your project configuration.

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 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.

Giving feedback

If you have feedback, suggestions, 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.

Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.