Start Building for Free

Pipelines overview

4 weeks ago7 min read
Server v4.x
Server v3.x
On This Page

CircleCI pipelines are the highest-level unit of work, and they are described by a configuration file, for example, for example, .circleci/config.yml. Triggers can be set up to automate when a pipeline will be triggered. Pipelines coordinate the execution of workflows and jobs to build, test, and deploy your code. Workflows can be conditional, based on filters, job requirements, and pipeline parameters.

Pipelines include your workflows, which coordinate your jobs. Pipelines have a fixed, linear lifecycle, and are associated with a specific actor. Pipelines trigger when a change is pushed to a project that has a CircleCI configuration file included, and can also be scheduled, triggered manually through the CircleCI app, or using the API.


When visiting your CircleCI dashboard, you are shown a list of recently-triggered pipelines for your organization.

Screenshot of the pipelines dashboard in the CircleCI app

Pipeline architecture

A pipeline is composed of workflows, which are composed of jobs. By navigating from a pipeline to a specific job, you can access your job output, test results, and artifacts through several tabs.

Job tab options in the CircleCI web app

The output of each job can be opened in a new tab (in either raw or formatted styling) with a unique link, making it shareable between team members.

Download and share job step output

Configuration sources and project triggers

Set up configuration sources and project triggers to define when and how pipelines are automatically triggered for a project. These triggers may be from external services (inbound webhooks), or from commits or tags on a version control system.

Configuration source

Configuration sources define the units of work that can be run within your projects. Each configuration source defines the location of a pipeline configuration file, and can be set up to be used when triggering a pipeline. Configuration sources can be associated with one or more triggers.

A project can have one or more configuration sources. The default location for a CircleCI configuration file is .circleci/config.yml. If you authenticated through the GitHub App, you can set the location to any path to a *.yml file.

When you create a project in CircleCI and connect it to a repository, a configuration source is set up for you automatically, and connected to a configuration file. The connected configuration file will be either a file you commit yourself or one generated by CircleCI based on the code in your project.

Configuration source

Add a configuration source

Add a configuration source

To add a configuration source, follow these steps:

  1. In the CircleCI web app, click on Projects in the sidebar

  2. Click on the ellipsis next to your project () and then click Project Settings

  3. Select Configuration in the sidebar

  4. Click Add Configuration Source

  5. Complete the form fields and options:

    • Give your configuration source a descriptive name, for example Run tests and deploy

    • Under Configuration Source select the platform that matches where your project is set up (for example, GitHub App)

    • Authorize your connection if this is not already showing with a

    • Select your repository

    • Select a fallback branch to use in case the triggering event does not have a triggering branch. This branch will be used if you trigger this pipeline via inbound webhook.

    • Enter the path to your configuration file relative to the root of your repository. For example, .circleci/config.yml. If you are integrated through the GitHub App, you can enter any path to a .yml file, and the file can have any name you choose.

  6. Click Save

Once you have set up a configuration source you need to set up a project trigger to connect it to. This is described in the following section.

Project triggers

Triggers are rules to define that a configuration source should be run on a given event. A project can have one or more triggers, which are associated with events from a source of change. The most common type of trigger is a VCS event, for example a push to a branch on a GitHub repository, but any system that can emit outbound webhooks can also be set up as a pipeline trigger. A trigger can have only one configuration source but a configuration source can have multiple triggers.

A trigger kicks off a pipeline to run the workflows defined by your connected configuration source.

Add a project trigger

To add a project trigger for a configuration source, follow these steps:

VS Code extension

If you use Visual Studio Code, you can also monitor and interact with your pipelines directly from VS Code with the official CircleCI extension. The extension allows you to customize which projects and pipelines you want to follow, as well as view job logs and test results, download artifacts, approve, re-run, and debug jobs with SSH, and get notified when your workflows fail or need approval.

Screenshot showing the detailed view of a failed test

The CircleCI VS Code extension is available to download on the VS Code marketplace.

Next steps

Find out more about triggering pipelines in the Triggers Overview.

Suggest an edit to this page

Make a contribution
Learn how to contribute