Documentation structure for LLMs (llms.txt)

No-op job recipes

Cloud Server

A no-op job performs no actions and consumes no credits. These recipes show how to use no-op jobs to structure your workflows.

Use no-op jobs to create a cleaner workflow graph

Goal

You may want to organize your workflow graph to make it more readable without adding additional build time or consuming credits. Using no-op jobs can help create a cleaner structure for complex workflows with many dependencies.

The following snippet shows how your workflow configuration might look without using a no-op job:

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm ci
      - run: npm run build

  test-unit:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm run test:unit

  test-integration:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm run test:integration

  test-e2e:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm run test:e2e

  deploy:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm run deploy

workflows:
  build-test-deploy:
    jobs:
      - build
      - test-unit:
          requires:
            - build
      - test-integration:
          requires:
            - build
      - test-e2e:
          requires:
            - build
      - deploy:
          requires:
            - test-unit
            - test-integration
            - test-e2e

Notice how the deploy job needs to explicitly list all three test jobs in its requires section. As your workflow grows, this list could become longer and more difficult to maintain.

Here is the workflow graph for this config:

Workflow graph showing snippet without `no-op` job
Figure 1. Workflow graph before adding no-op job

Steps

  1. Add a no-op job to your CircleCI configuration file.

    jobs:
      test-coordinator:
        type: no-op
    
      test-unit:
        docker:
          - image: cimg/node:20.10
        steps:
          - checkout
          - run: npm run test:unit
    
      test-integration:
        docker:
          - image: cimg/node:20.10
        steps:
          - checkout
          - run: npm run test:integration
    
      test-e2e:
        docker:
          - image: cimg/node:20.10
        steps:
          - checkout
          - run: npm run test:e2e
  2. Configure your workflow to use the no-op job as a coordinator for downstream jobs.

    workflows:
      build-test-deploy:
        jobs:
          - build
          - test-unit:
              requires:
                - build
          - test-integration:
              requires:
                - build
          - test-e2e:
              requires:
                - build
          - test-coordinator:
              requires:
                - test-unit
                - test-integration
                - test-e2e
          - deploy:
              requires:
                - test-coordinator

The workflow graph will now look like this:

Workflow graph showing snippet with `no-op` job
Figure 2. Workflow graph after adding no-op job

Notes

  • The no-op job performs no actions and consumes no credits. This makes it an ideal structural element in your workflow.

  • This pattern is useful when you want to visually group related jobs in the CircleCI UI.

  • Using no-op jobs can simplify workflow management when dealing with complex dependency chains.

  • Without the test-coordinator job, the deploy job would need to list all test jobs in its requires section.

Simplify GitHub required status checks with no-op jobs

Goal

You may want to simplify the management of GitHub required status checks for your branch protection rules. Use a single no-op job as a gatekeeper that depends on all your critical checks. This approach means you only need to manage a single required status check rather than multiple status checks in GitHub.

The following snippet shows how your workflow configuration might look without using a no-op job:

version: 2.1

jobs:
  lint:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm run lint

  test:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm test

  security-scan:
    docker:
      - image: cimg/node:20.10
    steps:
      - checkout
      - run: npm run security-check

workflows:
  main:
    jobs:
      - lint
      - test
      - security-scan

With this configuration, in GitHub you would need to set up branch protection rules for each job (lint, test, security-scan). You would need to update both CircleCI config and GitHub settings when adding more jobs.

Steps

  1. Add a no-op job to your CircleCI configuration file that will serve as your single required status check. In this example the no-op job is all-tests-passed:

    jobs:
      all-tests-passed:
        type: no-op
    
      lint:
        docker:
          - image: cimg/node:20.10
        steps:
          - checkout
          - run: npm run lint
    
      test:
        docker:
          - image: cimg/node:20.10
        steps:
          - checkout
          - run: npm test
    
      security-scan:
        docker:
          - image: cimg/node:20.10
        steps:
          - checkout
          - run: npm run security-check
  2. Configure your workflow to make all critical jobs prerequisites for the no-op job. The all-tests-passed will only succeed if all its required jobs succeed.

    workflows:
      main:
        jobs:
          - lint
          - test
          - security-scan
          - all-tests-passed:
              requires:
                - lint
                - test
                - security-scan
  3. In GitHub, set up a branch protection rule to require only the all-tests-passed job as a required status check. See the GitHub docs for more information on branch protection rules.

Notes

  • This approach simplifies branch protection management in GitHub by requiring only one status check.

  • When you add new checks, you only need to update the requires list for your no-op job.

  • The no-op job will succeed only if all its required jobs succeed.

  • This pattern helps keep GitHub and CircleCI configurations in sync without manual updates.