CircleCI reference
CircleCI reference
CircleCI configs live at `.circleci/config.yml`. The required header is `version: 2.1`. The body is divided into `orbs:` (reusable bundles), `executors:` (named runner definitions), `commands:` (named groups of steps), `jobs:` (the actual work), and `workflows:` (the DAG that ties jobs together).
Expression syntax uses `<< pipeline.* >>` for pipeline values and `<< parameters.* >>` / `<< matrix.* >>` inside parameterised jobs. Built-in steps include `checkout`, `run`, `save_cache`, `restore_cache`, `store_artifacts`, `store_test_results`, `persist_to_workspace`, `attach_workspace`, and `setup_remote_docker`.
Top-level keys
| Key | Purpose |
|---|---|
| version | Must be 2.1 for modern features. |
| orbs | Map of named orb imports. |
| executors | Named executor definitions. |
| commands | Named groups of steps callable from jobs. |
| jobs.<id>.docker / machine / macos | Pick the executor. |
| jobs.<id>.steps | Ordered list of steps. |
| jobs.<id>.parameters | Job parameters (used by matrix or by `commands:`). |
| jobs.<id>.parallelism | Test split across N containers. |
| workflows.<name>.jobs | List of job invocations forming the DAG. |
| workflows.<name>.triggers | Schedule triggers; pipeline-level triggers. |
Minimal example
version: 2.1
jobs:
test:
docker: [{ image: cimg/node:20.10 }]
steps:
- checkout
- run: npm ci
- run: npm test
workflows:
main:
jobs: [test]Context variables
The same concept goes by a different name on every platform. Use this table when porting expressions and conditions.
| Concept | GitHub Actions | GitLab CI | CircleCI | Bitbucket |
|---|---|---|---|---|
| Branch name | github.ref_name | $CI_COMMIT_REF_NAME | << pipeline.git.branch >> | $BITBUCKET_BRANCH |
| Commit SHA | github.sha | $CI_COMMIT_SHA | << pipeline.git.revision >> | $BITBUCKET_COMMIT |
| Tag name | github.ref_name | $CI_COMMIT_TAG | << pipeline.git.tag >> | $BITBUCKET_TAG |
| Repository slug | github.repository | $CI_PROJECT_PATH | << pipeline.project.git_url >> | $BITBUCKET_REPO_FULL_NAME |
| Run / pipeline id | github.run_id | $CI_PIPELINE_ID | << pipeline.id >> | $BITBUCKET_BUILD_NUMBER |
| Triggering event | github.event_name | $CI_PIPELINE_SOURCE | << pipeline.trigger_source >> | (implicit; check pipelines.* section) |
| Actor / user | github.actor | $GITLAB_USER_LOGIN | $CIRCLE_USERNAME | $BITBUCKET_STEP_TRIGGERER_UUID |
| Workspace path | github.workspace | $CI_PROJECT_DIR | $CIRCLE_WORKING_DIRECTORY | $BITBUCKET_CLONE_DIR |
| PR / MR source branch | github.head_ref | $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME | $CIRCLE_BRANCH (head ref) | $BITBUCKET_PR_DESTINATION_BRANCH (target only) |
| PR / MR target branch | github.base_ref | $CI_MERGE_REQUEST_TARGET_BRANCH_NAME | (not directly exposed) | $BITBUCKET_PR_DESTINATION_BRANCH |
Related Tools
YAML Formatter
Format and validate YAML. Convert YAML to JSON or JSON to YAML. Supports 2 and 4 space indentation.
Cron Builder
Visual builder for cron-job schedules.
Gitignore Generator
Generate .gitignore files for any language, framework, or IDE — 100+ templates, 100% client-side.
JSON Schema Generator
Generate a JSON Schema from one or more sample JSONs — drafts 2020-12, 2019-09, 7, 6, 4. Detects formats (date-time, email, uuid, ipv4, uri), extracts $defs, validates with AJV, and exports to YAML, TypeScript, and Zod. 100% in your browser.
AI Coding Rules
Curated rules-file library and generator for Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, Aider, Continue, and Cody. Browse 20 hand-crafted .cursorrules / CLAUDE.md / copilot-instructions.md files for popular stacks, build a custom one with the wizard, or convert any rules file between AI-tool formats.