Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Sample config.yml Files

2 months ago6 min read
Cloud
Server v4.x
Server v3.x
On This Page

This document provides sample .circleci/config.yml files that you can use as a starting point when setting up projects, or to better understand different ways to orchestrate jobs using workflows and filters. For information on all configuration elements available to you, see the Configuration reference page.

If you would like to get set up quickly, see our language-specific quickstart guides:

Tools for editing configuration files

CircleCI has created an extension for Visual Studio Code that reduces context switching between the web app and VS Code through a set of helpful features.

The VS Code extension reduces the time to create, modify, and troubleshoot configuration files through real-time syntax validation, highlighting, and autocomplete suggestions. Authenticating the extension with your CircleCI account will also allow you to visualize and manage your CircleCI pipelines directly from your code editor, and be notified of workflow status changes.

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

Simple configuration examples

Concurrent workflow

The configuration example below shows a concurrent workflow in which the build and test jobs run at the same time. Both jobs are run in Docker containers using the base image provided by CircleCI.

  • Refer to the Workflows document for complete details about orchestrating job runs with concurrent, sequential, and manual approval workflows.
  • Refer to the Developer Hub convenience images page to find out about available Docker images for running your jobs.

This image shows the workflow view for the following configuration example:

Concurrent Workflow Graph

version: 2.1

# Define the jobs we want to run for this project
jobs:
  build:
    docker:
      - image: cimg/base:2023.03
    steps:
      - checkout
      - run: echo "this is the build job"
  test:
    docker:
      - image: cimg/base:2023.03
    steps:
      - checkout
      - run: echo "this is the test job"

# Orchestrate our job run sequence
workflows:
  build_and_test:
    jobs:
      - build
      - test

Sequential workflow

The configuration example below shows a sequential workflow where the build job runs, and then the test job runs once build has completed. This is achieved by using the requires key, and specifying the test job “requires” the build job in order to run. Both jobs are run in Docker containers using the base image provided by CircleCI.

  • Refer to the Workflows document for complete details about orchestrating job runs with concurrent, sequential, and manual approval workflows.
  • Refer to the developer hub convenience images page to find out about available Docker images for running your jobs.

This image shows the workflow view for the following configuration example, in which jobs run sequentially (one after the other):

Sequential Workflow Graph

version: 2.1

# Define the jobs we want to run for this project
jobs:
  build:
    docker:
      - image: cimg/base:2023.03
    steps:
      - checkout
      - run: echo "this is the build job"
  test:
    docker:
      - image: cimg/base:2023.03
    steps:
      - checkout
      - run: echo "this is the test job"

# Orchestrate our job run sequence
workflows:
  build_and_test:
    jobs:
      - build
      - test:
          requires:
            - build

Approval job

The example below shows a sequential workflow with an approval step. The build job runs, then the test job, then a hold job, with type: approval ensuring the workflow waits for manual approval in the CircleCI web app before the deploy job can run. All jobs run in Docker containers using the base image provided by CircleCI.

  • Refer to the Workflows document for complete details about orchestrating job runs with concurrent, sequential, and manual approval workflows.
  • Refer to the developer hub convenience images page to find out about available Docker images for running your jobs.

This image shows the workflow view for the following configuration example. This image has three parts to show the approval popup that appears when you click on a hold step in the app, and then the workflow view again once the hold job has been approved and the deploy job has run:

Approval Workflow Graph

version: 2.1

# Define the jobs we want to run for this project
jobs:
  build:
    docker:
      - image: cimg/base:2023.03
    steps:
      - checkout
      - run: echo "this is the build job"
  test:
    docker:
      - image: cimg/base:2023.03
    steps:
      - checkout
      - run: echo "this is the test job"
  deploy:
    docker:
      - image: cimg/base:2023.03
    steps:
      - checkout
      - run: echo "this is the deploy job"

# Orchestrate our job run sequence
workflows:
  build_and_test:
    jobs:
      - build
      - test:
          requires:
            - build
      - hold:
          type: approval
          requires:
            - build
            - test
      - deploy:
          requires:
            - hold

Sample configuration with sequential workflow and secondary Docker container

Following is a sample .circleci/config.yml file using the following configuration features:

  • A sequential workflow
  • An orb
  • A secondary services container
  • Workspaces
  • Storing artifacts
version: 2.1

orbs:
  node: circleci/node@3.0.0

jobs:
  build:
    working_directory: ~/mern-starter
    # Reuse Docker container specification given by the node Orb
    executor: node/default
    steps:
      - checkout
      # Install the latest npm - the node Orb takes care of it
      - node/install-npm
      # Install dependencies - the node Orb take care of installation and dependency caching
      - node/install-packages:
          app-dir: ~/mern-starter
          cache-path: node_modules
          override-ci-command: npm i
      # Save workspace for subsequent jobs (i.e. test)
      - persist_to_workspace:
          root: .
          paths:
            - .

  test:
    docker:
      # The primary container is an instance of the first image listed. The job's commands run in this container.
      - image: cimg/node:current
      # The secondary container is an instance of the second listed image which is run in a common network where ports exposed on the primary container are available on localhost.
      - image: mongo:4.2
    steps:
      # Reuse the workspace from the build job
      - attach_workspace:
          at: .
      - run:
          name: Demonstrate that Mongo DB is available as localhost
          command: |
            curl -sSJL https://www.mongodb.org/static/pgp/server-4.2.asc | sudo apt-key add -
            echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.2 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.2.list
            sudo apt update
            sudo apt install mongodb-org
            mongo localhost --eval "db.serverStatus()"
      - run:
          name: Test
          command: npm test
      - run:
          name: Generate code coverage
          command: './node_modules/.bin/nyc report --reporter=text-lcov'
      # You can specify either a single file or a directory to store as artifacts
      - store_artifacts:
          path: test-results.xml
          destination: deliverable.xml
      - store_artifacts:
          path: coverage
          destination: coverage

workflows:
  build_and_test:
    jobs:
      - build
      - test:
          requires:
            - build

This example shows a sequential workflow with the test job configured to run only on the main branch. Refer to the Workflows document for complete details about orchestrating job runs with concurrent, sequential, and manual approval workflows.

Sample configuration with fan-in/fan-out workflow

Below are two sample configurations for a Fan-in/Fan-out workflow.

Fan-in-out

Note: a job can only run when its dependencies are satisfied therefore it requires the dependencies of all upstream jobs. This means only the immediate upstream dependencies need to be specified in the requires: blocks.

Sample configuration with multiple executor types

It is possible to use multiple executor types in the same workflow.

In Example-1 each push will build and test the project on Linux, Windows and macOS.

In Example-2 each push of an iOS project will be built on macOS, and additional iOS tools ( SwiftLint and Danger) will be run in Docker.

See also

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.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

Creative Commons License

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.