Aide-mémoire CircleCI

Aide-mémoire CircleCI

Installation

Plateforme	Commande
Linux (curl)	`curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/master/install.sh \
Linux (snap)	sudo snap install circleci
macOS (Homebrew)	brew install circleci
macOS (curl)	`curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/master/install.sh \
Windows (Chocolatey)	choco install circleci-cli
Windows (Scoop)	scoop install circleci
Verify Installation	circleci version
Initial Setup	circleci setup
Update CLI	circleci update

Commandes de base

Commande	Description
circleci config validate	Validate your .circleci/config.yml file
circleci config validate -c path/to/config.yml	Valider un fichier de configuration spécifique
circleci config process .circleci/config.yml	Traiter et développer la configuration (résoudre les orbs)
circleci local execute	Exécuter un job localement à l’aide de Docker
circleci local execute --job job-name	Exécuter un travail spécifique localement
circleci follow	Lister tous les projets suivis
circleci follow github/org/repo	Suivre un projet spécifique
circleci project info github/org/repo	Obtenir les informations du projet
circleci pipeline run github/org/repo	Déclencher un nouveau pipeline
circleci pipeline run github/org/repo --branch develop	Déclencher le pipeline sur une branche spécifique
circleci pipeline list github/org/repo	Lister les pipelines récents pour un projet
circleci pipeline get <pipeline-id>	Obtenir les détails d’un pipeline spécifique
circleci build list github/org/repo	Lister les builds récents d’un projet
circleci build get <build-number>	Obtenir des informations sur un build spécifique
circleci build cancel <build-number>	Annuler un build en cours

Utilisation avancée

Commande	Description
circleci pipeline run github/org/repo --parameters '{"key":"value"}'	Déclencher le pipeline avec des paramètres
circleci local execute --env VAR1=value1 --env VAR2=value2	Exécuter localement avec des variables d’environnement
circleci context list github org-name	Lister tous les contextes pour une organisation
circleci context create github org-name context-name	Créer un nouveau contexte
circleci context show github org-name context-name	Afficher les détails du contexte
circleci context delete github org-name context-name	Supprimer un contexte
circleci context env-var list github org-name context-name	Lister les variables d’environnement dans un contexte
circleci context env-var store github org-name context-name VAR_NAME	Stocker la variable d’environnement dans le contexte
circleci orb list	Lister tous les orbs publics disponibles
circleci orb search <query>	Rechercher des orbs par mot-clé
circleci orb info namespace/orb@version	Obtenez des informations détaillées sur un orb
circleci orb source namespace/orb@version	Afficher le code source d’un orb
circleci orb create namespace/orb	Créer un nouvel orb
circleci orb publish path/to/orb.yml namespace/orb@dev:first	Publier la version de développement d’un orb
circleci orb publish promote namespace/orb@dev:first patch	Promouvoir orb en production (version de patch)
circleci orb validate path/to/orb.yml	Valider une configuration d’orb
circleci api graphql-query --query '{ me { id name } }'	Exécuter une requête d’API GraphQL
circleci api get /me	Effectuer une requête GET sur l’API REST
circleci diagnostic	Exécuter des vérifications de diagnostic sur la configuration CLI
circleci config pack src/ > orb.yml	Regrouper les fichiers source orb dans un seul fichier YAML

Configuration

Structure de base du fichier de configuration

Le fichier de configuration CircleCI est situé à .circleci/config.ymlà la racine de votre dépôt.

version: 2.1

# Define reusable execution environments
executors:
  node-executor:
    docker:
      - image: cimg/node:18.16
    resource_class: medium
    working_directory: ~/project

# Define reusable command sequences
commands:
  install-deps:
    steps:
      - restore_cache:
          keys:
            - v1-deps-{{ checksum "package-lock.json" }}
      - run: npm ci
      - save_cache:
          key: v1-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules

# Define jobs
jobs:
  build:
    executor: node-executor
    steps:
      - checkout
      - install-deps
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist

  test:
    executor: node-executor
    steps:
      - checkout
      - install-deps
      - run: npm test
      - store_test_results:
          path: test-results

# Define workflows
workflows:
  build-and-test:
    jobs:
      - build
      - test:
          requires:
            - build

Configuration de l’exécuteur Docker

jobs:
  build:
    docker:
      - image: cimg/python:3.11
        auth:
          username: $DOCKERHUB_USERNAME
          password: $DOCKERHUB_PASSWORD
        environment:
          FLASK_ENV: development
      - image: cimg/postgres:14.0
        environment:
          POSTGRES_USER: testuser
          POSTGRES_DB: testdb
    resource_class: large
    steps:
      - checkout
      - run: python app.py

Configuration de l’exécuteur Machine

jobs:
  build:
    machine:
      image: ubuntu-2204:2023.04.2
      docker_layer_caching: true
    resource_class: large
    steps:
      - checkout
      - run: docker build -t myapp .

Utilisation des Orbs

version: 2.1

orbs:
  node: circleci/node@5.1.0
  aws-cli: circleci/aws-cli@3.1.0
  slack: circleci/slack@4.12.0

jobs:
  deploy:
    executor: node/default
    steps:
      - checkout
      - node/install-packages
      - aws-cli/setup
      - run: npm run deploy
      - slack/notify:
          event: pass
          template: success_tagged_deploy_1

Filtres de workflow et planification

workflows:
  version: 2
  build-deploy:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test
          filters:
            branches:
              only:
                - main
                - /release\/.*/
            tags:
              only: /^v.*/
  
  nightly:
    triggers:
      - schedule:
          cron: "0 0 * * *"
          filters:
            branches:
              only: main
    jobs:
      - test

Parallélisme et répartition des tests

jobs:
  test:
    docker:
      - image: cimg/node:18.16
    parallelism: 4
    steps:
      - checkout
      - run: npm ci
      - run:
          name: Run Tests
          command: |
            TESTFILES=$(circleci tests glob "tests/**/*.test.js" | \
                        circleci tests split --split-by=timings)
            npm test $TESTFILES
      - store_test_results:
          path: test-results

Classes de ressources

jobs:
  small-job:
    docker:
      - image: cimg/base:stable
    resource_class: small  # 1 vCPU, 2GB RAM
  
  large-job:
    docker:
      - image: cimg/base:stable
    resource_class: large  # 4 vCPU, 8GB RAM
  
  xlarge-job:
    docker:
      - image: cimg/base:stable
    resource_class: xlarge  # 8 vCPU, 16GB RAM

Cas d’utilisation courants

Cas d’utilisation 1 : Pipeline d’application Node.js multi-étapes

version: 2.1

orbs:
  node: circleci/node@5.1.0

jobs:
  build:
    executor: node/default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Build Application
          command: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist
            - node_modules

  test:
    executor: node/default
    steps:
      - checkout
      - attach_workspace:
          at: .
      - run:
          name: Run Unit Tests
          command: npm test
      - store_test_results:
          path: test-results

  deploy-staging:
    executor: node/default
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Deploy to Staging
          command: npm run deploy:staging

workflows:
  build-test-deploy:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy-staging:
          requires:
            - test
          filters:
            branches:
              only: develop

Cas d’utilisation 2 : Construction et envoi d’image Docker

version: 2.1

orbs:
  docker: circleci/docker@2.2.0

jobs:
  build-and-push:
    executor: docker/docker
    steps:
      - setup_remote_docker:
          docker_layer_caching: true
      - checkout
      - docker/check
      - docker/build:
          image: myorg/myapp
          tag: ${CIRCLE_SHA1},latest
      - docker/push:
          image: myorg/myapp
          tag: ${CIRCLE_SHA1},latest

workflows:
  build-deploy:
    jobs:
      - build-and-push:
          context: docker-hub-creds
          filters:
            branches:
              only: main

Cas d’utilisation 3 : Tests parallèles avec répartition des tests

version: 2.1

jobs:
  test:
    docker:
      - image: cimg/python:3.11
    parallelism: 8
    steps:
      - checkout
      - run: pip install -r requirements.txt
      - run:
          name: Run Tests in Parallel
          command: |
            TESTFILES=$(circleci tests glob "tests/**/test_*.py" | \
                        circleci tests split --split-by=timings)
            pytest $TESTFILES \
              --junitxml=test-results/junit.xml \
              --cov=app \
              --cov-report=html
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: htmlcov

workflows:
  test:
    jobs:
      - test

Cas d’utilisation 4 : Workflow conditionnel avec paramètres

version: 2.1

parameters:
  run-integration-tests:
    type: boolean
    default: false
  deployment-environment:
    type: string
    default: "staging"

jobs:
  unit-test:
    docker:
      - image: cimg/node:18.16
    steps:
      - checkout
      - run: npm ci
      - run: npm run test:unit

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

  deploy:
    docker:
      - image: cimg/node:18.16
    parameters:
      environment:
        type: string
    steps:
      - checkout
      - run: npm ci
      - run: npm run deploy:<< parameters.environment >>

workflows:
  test-and-deploy:
    jobs:
      - unit-test
      - integration-test:
          when: << pipeline.parameters.run-integration-tests >>
      - deploy:
          environment: << pipeline.parameters.deployment-environment >>
          requires:
            - unit-test
          filters:
            branches:
              only: main

Cas d’utilisation 5 : Monorepo avec filtrage de chemin

version: 2.1

setup: true

orbs:
  path-filtering: circleci/path-filtering@0.1.3

workflows:
  setup-workflow:
    jobs:
      - path-filtering/filter:
          base-revision: main
          config-path: .circleci/continue-config.yml
          mapping: |
            services/api/.* api-build true
            services/web/.* web-build true
            packages/.* all-build true

continue-config.yml :

version: 2.1

parameters:
  api-build:
    type: boolean
    default: false
  web-build:
    type: boolean
    default: false
  all-build:
    type: boolean
    default: false

jobs:
  build-api:
    docker:
      - image: cimg/node:18.16
    steps:
      - checkout
      - run: cd services/api && npm ci && npm run build

  build-web:
    docker:
      - image: cimg/node:18.16
    steps:
      - checkout
      - run: cd services/web && npm ci && npm run build

workflows:
  api-workflow:
    when: << pipeline.parameters.api-build >>
    jobs:
      - build-api

  web-workflow:
    when: << pipeline.parameters.web-build >>
    jobs:
      - build-web

Meilleures pratiques

• Utiliser des Orbs pour les tâches courantes : Exploitez les orbs CircleCI pour des intégrations standardisées (AWS, Docker, Slack) afin de réduire la complexité de configuration et la charge de maintenance.

• Implémenter le cache de manière stratégique : Mettez en cache les dépendances à l’aide de clés basées sur la somme de contrôle ({{ checksum "package-lock.json" }}) pour accélérer les builds tout en garantissant l’invalidation du cache lorsque les dépendances changent.

• Optimiser les classes de ressources : Choisissez des classes de ressources appropriées pour chaque tâche ; utilisez des instances plus petites pour les tâches simples et réservez des instances plus grandes pour les opérations nécessitant beaucoup de calcul comme la compilation ou les tests complexes.

• Activer le cache de couches Docker : Pour les tâches qui construisent des images Docker, activez

Note: Some sections (3-19) were left untranslated as no specific text was provided in the original input.docker_layer_caching: truepour réduire significativement les temps de construction en réutilisant les couches inchangées. circleci tests splitDiviser les Tests pour une Exécution Parallèle : Utiliser --split-by=timingspour distribuer les tests sur des conteneurs parallèles en fonction des temps d’exécution historiques, maximisant l’efficacité. persist_to_workspacepour conserver les artefacts de construction attach_workspaceau lieu de reconstruire dans les tâches suivantes, économisant du temps et garantissant la cohérence. circleci config validatepour exécuter des validations de configuration circleci local executeavant de pousser pour détecter les erreurs de syntaxe et les problèmes de configuration dès le début.

Problème	Solution
”Config file not found” error	Ensure .circleci/config.yml exists in repository root. Run circleci config validate to check file location and syntax.
Local execution fails with Docker errors	Verify Docker is running: docker ps. Ensure the CLI has access to Docker socket. On Linux, add user to docker group: sudo usermod -aG docker $USER.
”Invalid configuration” during validation	Run circleci config process .circleci/config.yml to see expanded config and identify syntax errors. Check YAML indentation (use spaces, not tabs).
Jobs not triggering on push	Verify project is followed: circleci follow github/org/repo. Check workflow filters aren’t excluding your branch. Ensure webhook is configured in VCS settings.
Workspace attachment fails	Ensure persist_to_workspace in upstream job completes successfully. Verify root and paths match between persist and attach. Check job dependencies in workflow.
Cache not restoring	Verify cache key matches between save_cache and restore_cache. Use fallback keys: keys: [v1-{{ checksum "file" }}, v1-]. Check cache hasn’t expired (30 days).
Authentication errors with CLI	Re-run circleci setup with a valid API token. Generate new token at https://app.circleci.com/settings/user/tokens. Verify token has correct permissions.
Parallel test splitting not working	Ensure test results are stored with store_test_results. Use glob patterns that match your test files. Verify parallelism is set greater than 1.
Out of memory errors	Increase resource_class to large or xlarge. Optimize memory-intensive operations. Check for memory leaks in application code.
Context environment variables not available	Verify job uses correct context in workflow: context: context-name. Check user has access to context in organization settings. Ensure variable names don’t conflict.
Orb import fails	Verify orb exists: circleci orb info namespace/orb@version. Check version is valid. For private orbs, ensure organization has access and use --org-id flag.
- run: circleci-agent step haltdans la configuration à l’endroit où vous voulez faire une pause. Réexécuter la tâche avec SSH activé. Utiliser la commande SSH fournie dans les 10 minutes avant l’expiration.

• Implémenter des Filtres de Workflow : Utiliser des filtres de branches et de tags pour contrôler quand les tâches s’exécutent, empêchant les déploiements inutiles et économisant des crédits tout en maintenant la sécurité.

• Stocker les Secrets dans des Contextes : Gérer les informations d’identification sensibles dans les contextes CircleCI plutôt que dans les variables d’environnement du projet pour une meilleure sécurité, un meilleur contrôle d’accès et une réutilisabilité entre projets.

• Surveiller et Optimiser l’Utilisation des Crédits : Examiner régulièrement les Insights et Analytics pour identifier les tâches lentes, optimiser les paramètres de parallélisme et réduire les exécutions de workflow inutiles afin de gérer efficacement les coûts.

Dépannage