circleci

circleci Best Practices

CircleCI is the backbone of our CI/CD. Adhere to these guidelines to ensure our pipelines are efficient, secure, and maintainable.

1. Code Organization & Reusability

1.1. Author and Consume Orbs for Reusability

Encapsulate common logic into orbs. This promotes DRY principles and consistent patterns across projects.

• Descriptive Naming: Use clear namespace/orb-name slugs. ❌ BAD: myorg/plugin, myorg/ci-tool ✅ GOOD: myorg/docker-publish, myorg/aws-deploy

• Semantic Versioning: Lock to specific orb versions. ❌ BAD: myorg/aws-deploy@volatile ✅ GOOD: myorg/[email protected]

• Comprehensive Descriptions: Every orb component (commands, jobs, executors, parameters) must have a clear description.

  # .circleci/orb.yml
  commands:
    my-command:
      description: "Utilize this command to echo Hello to a step in the UI."
      steps:
        - run: echo "Hello"
  

1.2. Reuse Commands, Executors, and Jobs

Within your config.yml or orbs, define reusable components to avoid duplication.

❌ BAD:

jobs:
  build-and-test:
    docker:
      - image: cimg/node:18.17.1
    steps:
      - checkout
      - run: npm install
      - run: npm test
  another-job:
    docker:
      - image: cimg/node:18.17.1
    steps:
      - checkout
      - run: npm install # Duplication
      - run: npm run build

✅ GOOD:

# .circleci/config.yml
version: 2.1
commands:
  install_deps:
    description: "Install Node.js dependencies."
    steps:
      - run: npm install

jobs:
  build-and-test:
    docker:
      - image: cimg/node:18.17.1
    steps:
      - checkout
      - install_deps
      - run: npm test
  build-app:
    docker:
      - image: cimg/node:18.17.1
    steps:
      - checkout
      - install_deps
      - run: npm run build

1.3. Use Pass-Through Parameters in Jobs

When a job uses a command or executor that accepts parameters, expose those parameters at the job level for flexibility.