Build & Deployment Process

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• DEVELOPMENT.md
• CONTRIBUTING.md
• gulp.d/tasks/build-api-docs.js
• API_DOCS_INTEGRATION.md
• archive/deploys-overview.adoc

The CircleCI Docs Build & Deployment process is a modular pipeline designed to transform multi-repository AsciiDoc content and custom UI components into a static documentation site. Built on the Antora framework, the system separates the management of content from its visual presentation, allowing for parallel development of documentation and the site's user interface.

The process encompasses several distinct stages: UI bundling, content processing via Antora, specialized API documentation generation, and final site assembly. This pipeline is orchestrated through Gulp tasks, providing developers with automated workflows for local previewing and production builds.

Sources: ARCHITECTURE.md:14-22, README.md:12-20

Build System Architecture

The project employs a tiered build architecture where technical infrastructure and content layers are processed independently before being merged into the final output.

Pipeline Components

The build system is divided into four primary modules:

1. UI Bundle Build (ui/): Processes CSS (Tailwind), JavaScript, and Handlebars templates into a packaged ui-bundle.zip.
2. Content Processing (docs/): Antora aggregates AsciiDoc files, applies cross-references, and manages versioning.
3. API Integration (gulp.d/tasks/build-api-docs.js): A specialized pipeline that fetches live OpenAPI specs and copies static v1 documentation.
4. Site Assembly: The final stage where Gulp tasks combine the UI bundle with processed content and assets into the build/ directory.

Sources: ARCHITECTURE.md:37-55, API_DOCS_INTEGRATION.md:11-20

Build Flow Diagram

The following diagram illustrates the sequence of operations from source files to the final static site.

API Documentation Pipeline

The API documentation build is a critical sub-process that integrates two versions of the CircleCI API into the main documentation site. This task is handled by gulp.d/tasks/build-api-docs.js.

API v1 (Static)

The v1 build is a simple file operation. It verifies the existence of the api-v1/ directory and recursively copies its structure (including fonts, images, and stylesheets) to the final build path.

Sources: gulp.d/tasks/build-api-docs.js:56-74, API_DOCS_INTEGRATION.md:46-50

API v2 (Live Pipeline)

The v2 build is a sophisticated automated pipeline:

1. Fetch: Downloads the live OpenAPI JSON from https://circleci.com/api/v2/openapi.json.
2. Bundle/Dereference: Uses Redocly to resolve $ref pointers and remove unused components.
3. Code Snippets: Generates examples for cURL, Node.js, Python, Go, and Ruby.
4. Patching: Optionally applies JSON merge patches from openapi-patch.json.
5. Build: Renders the final HTML using Redocly CLI with a custom Handlebars template.

Sources: gulp.d/tasks/build-api-docs.js:93-145, API_DOCS_INTEGRATION.md:52-60

Development & Deployment Workflows

Command Reference

The project provides several npm scripts to manage the lifecycle of the build and local development environment.

Command	Description
npm run start:dev	Starts a local server with live reload and automatic rebuilds.
npm run build:docs	Executes the complete build (UI + Antora + API docs).
npm run build:ui	Rebuilds only the UI bundle (ui-bundle.zip).
npm run build:api-docs	Orchestrates the API v1 and v2 build tasks.
npm run preview:ui	Focuses on UI development with faster rebuild cycles.

Sources: DEVELOPMENT.md:46-70, CONTRIBUTING.md:77-80

Continuous Delivery (CD)

The project follows a continuous delivery model for site updates.

Deployment Visibility & Management

While the site itself is a static build, the project documentation includes details on how CircleCI manages external deployments via "CircleCI Deploys". This system provides visibility into Kubernetes and Amazon SageMaker releases.

Deployment Statuses

Components being deployed through the CircleCI platform (tracked via the docs) can reach several states:

Status	Definition
RUNNING	The deployment is currently in progress.
SUCCESS	All pods or resources are specified and available.
FAILED	Resources reached an unhealthy status.
CANCELLED	The deployment was stopped or superseded by another.
LOGGED	Deployment recorded via a "deploy marker" without full integration.

Sources: archive/deploys-overview.adoc:229-250

Summary

The CircleCI Docs build process is a highly automated pipeline that leverages Antora for technical documentation and Gulp for infrastructure tasks. By integrating live API fetching and modular UI bundling, the system ensures that documentation remains current with the CircleCI platform while providing a flexible environment for contributors and developers.

Sources: README.md:12-20, ARCHITECTURE.md:9-15