This document describes the continuous integration and continuous deployment (CI/CD) system for the maxGraph repository. The pipeline automates testing, building, documentation generation, and release publishing across multiple operating systems and deployment targets.
For information about the manual release preparation steps, see Release Process. For details on the development build system used locally, see Build System and Dual Format Output.
The CI/CD system implements three primary workflows:
All workflows are triggered automatically based on repository events (push, pull request, tag creation) and coordinate through reusable workflow components and GitHub Actions artifacts.
Sources: .github/workflows/build.yml .github/workflows/generate-website.yml .github/workflows/create-github-release.yml .github/workflows/publish-npm-package.yml
Workflow Execution Flow
This diagram shows how the five GitHub Actions workflows interact with trigger events, reusable components, and deployment targets. The build.yml and generate-website.yml workflows run on every push to main and on pull requests. The create-github-release.yml and publish-npm-package.yml workflows are triggered only when version tags (matching v*) are pushed to the repository.
Sources: .github/workflows/build.yml1-98 .github/workflows/generate-website.yml1-67 .github/workflows/create-github-release.yml1-150 .github/workflows/publish-npm-package.yml1-21
The build.yml workflow is the primary continuous integration workflow that runs comprehensive quality checks on every push to the main branch and on all pull requests.
The workflow activates when specific paths are modified:
.github/workflows/build.yml3-31
| Path Pattern | Purpose |
|---|---|
.github/actions/build-setup/**/* | Setup action changes |
.github/workflows/build.yml | Workflow self-modification |
.eslint* | Linting configuration |
packages/**/* | All package source code |
!packages/**/*.md | Excludes markdown files |
!packages/website/**/* | Excludes website (has separate workflow) |
tsconfig.json | TypeScript configuration |
Matrix Build Execution
The build job uses a matrix strategy to run tests on three operating systems in parallel. The fail-fast: false setting ensures all OS builds complete even if one fails, providing comprehensive cross-platform validation.
Sources: .github/workflows/build.yml34-42
The main build job executes the following steps in sequence:
.github/workflows/build.yml43-84
Build Job Step Sequence
Each step in the build job serves as a quality gate. Failure at any step blocks the pipeline and prevents the build_examples job from executing.
Sources: .github/workflows/build.yml43-84
After the primary build job succeeds, the build_examples job runs on all three operating systems:
.github/workflows/build.yml87-97
The job invokes the reusable _reusable_build_examples.yml workflow with an artifact name pattern examples-{runner}-{sha}, ensuring OS-specific example builds are preserved separately.
Sources: .github/workflows/build.yml87-97
The build workflow enforces five critical quality gates that must pass before code can be merged:
npm run test-check -w packages/core
Validates that test files compile correctly with TypeScript, ensuring type safety in test code.
npm test -w packages/core -- --coverage
Executes the Jest test suite with coverage reporting. Coverage reports are uploaded as artifacts to test-coverage-{OS}-{sha} for each operating system.
Sources: .github/workflows/build.yml53-61
npm test -w packages/ts-support
Runs tests in the @maxgraph/ts-support package to verify that the library compiles with TypeScript 3.8.2, maintaining backward compatibility with older TypeScript versions.
Sources: .github/workflows/build.yml62-63
npm run check:circular-dependencies -w packages/core
Uses Madge to analyze the compiled JavaScript output and detect circular dependencies in the module graph. Circular dependencies can cause initialization issues and are blocked at CI time.
Sources: .github/workflows/build.yml76-77
npm run check:npm-package -w packages/core
Runs @arethetypeswrong/cli to validate the npm package structure, checking for common issues with:
Sources: .github/workflows/build.yml82-84
npm run lint
Executes ESLint and Prettier checks across the entire monorepo, enforcing code style consistency.
Sources: .github/workflows/build.yml79-80
The generate-website.yml workflow builds the Docusaurus documentation site, generates API docs with TypeDoc, compiles the Storybook demo, and deploys to GitHub Pages.
Website Generation and Deployment Flow
The workflow generates the website for both PRs (for preview) and main branch pushes (for deployment). The artifact name differs based on the trigger: gh-pages for deployment-bound builds, or website-pr-{number}-{sha} for PR previews.
Sources: .github/workflows/generate-website.yml1-67
The workflow uses dynamic concurrency grouping:
.github/workflows/generate-website.yml37-41
This allows parallel builds for different branches/PRs while canceling redundant runs for the same ref.
The deploy job requires specific GitHub token permissions:
.github/workflows/generate-website.yml54-58
| Permission | Purpose |
|---|---|
contents: read | Checkout repository |
pages: write | Deploy to GitHub Pages |
id-token: write | Verify deployment source via OIDC |
Sources: .github/workflows/generate-website.yml54-67
The create-github-release.yml workflow triggers when a version tag matching v* is pushed, creating a draft GitHub release with pre-built artifacts.
Release Creation Job Flow
The workflow first extracts the version from the tag name, then builds examples and website in parallel, and finally creates a draft release with both artifacts attached.
Sources: .github/workflows/create-github-release.yml1-150
.github/workflows/create-github-release.yml9-19
The compute_environment_variables job strips the v prefix from the tag name:
This converts v0.2.0 to 0.2.0 for use in artifact names and milestone queries.
.github/workflows/create-github-release.yml49-63
The workflow queries the GitHub GraphQL API to find the milestone number matching the version:
The milestone number is used to generate the "Fixed issues" link in the release notes template.
.github/workflows/create-github-release.yml84-149
The workflow creates a draft release with a pre-filled markdown template that includes:
The generateReleaseNotes: true option automatically generates a changelog from merged PRs based on the .github/release.yml configuration.
Sources: .github/workflows/create-github-release.yml84-149
The publish-npm-package.yml workflow publishes the @maxgraph/core package to the NPM registry using OIDC trusted publisher authentication.
NPM Publishing Flow
The workflow uses GitHub's OIDC token to authenticate with NPM's trusted publisher system, eliminating the need for long-lived tokens stored as secrets.
Sources: .github/workflows/publish-npm-package.yml1-21
.github/workflows/publish-npm-package.yml9-10
The job requests an id-token: write permission, which allows GitHub Actions to generate an OIDC token that NPM trusts for package publishing.
.github/workflows/publish-npm-package.yml20
The --provenance flag generates SLSA provenance attestation, creating a cryptographically signed record of:
This provenance is visible on the NPM package page, providing supply chain transparency.
Sources: .github/workflows/publish-npm-package.yml1-21
The CI/CD system uses two reusable workflows to reduce duplication across the build, release, and website generation processes.
This workflow builds all example packages and uploads them as a single artifact.
.github/workflows/_reusable_build_examples.yml1-42
| Input | Type | Required | Default | Purpose |
|---|---|---|---|---|
artifact-name | string | yes | - | Name for the uploaded artifact |
runner | string | no | ubuntu-24.04 | Runner OS to use |
Example Build Pipeline
The workflow first builds the core library (which the examples depend on), then executes the build-all-examples.bash script, and uploads the resulting dist directories.
Sources: .github/workflows/_reusable_build_examples.yml1-42
This workflow generates the complete documentation website, including TypeDoc API docs and Storybook demos.
.github/workflows/_reusable_generate_website.yml1-68
| Input | Type | Required | Purpose |
|---|---|---|---|
artifact-name | string | yes | If gh-pages, creates a special GitHub Pages artifact. Otherwise, creates a zipped artifact with maxGraph subdirectory structure. |
Website Generation Pipeline
The workflow builds API documentation with TypeDoc, compiles Storybook, copies both into the website's generated resources directory, and builds the Docusaurus site. The upload strategy depends on whether the artifact is for GitHub Pages deployment or for attachment to a release.
Sources: .github/workflows/_reusable_generate_website.yml1-68
.github/workflows/_reusable_generate_website.yml22-23
The command npm run docs:api -w packages/core executes TypeDoc to generate API documentation for the core library. TypeDoc organizes the documentation into 24 categories (Animation, Graph, Layout, Serialization, Style, etc.) based on the core library's module structure.
.github/workflows/_reusable_generate_website.yml28-29
The extra:copy-gen-resources script copies:
packages/website/docs/generated/api-docs/packages/website/docs/generated/demo/This allows Docusaurus to embed external resources during its build process.
.github/workflows/_reusable_generate_website.yml40-57
For release artifacts (non-GitHub Pages), the workflow creates a directory structure:
artifact-output/
├── index.html # Redirect to maxGraph/index.html
└── maxGraph/ # Actual website content
├── index.html
├── assets/
└── ...
This matches the expected structure for offline documentation archives attached to GitHub releases.
Sources: .github/workflows/_reusable_generate_website.yml40-57
The .github/actions/build-setup composite action provides standardized environment setup for all workflows.
.github/actions/build-setup/action.yml1-21
Build Setup Actions
The action ensures consistent Node.js version (from .nvmrc) and dependency installation across all workflows.
| Flag | Purpose |
|---|---|
--prefer-offline | Use cache when possible to speed up installation |
--audit false | Skip security audit during CI (separate workflow can handle this) |
--ignore-scripts | Skip postinstall scripts for security and speed |
--no-fund | Suppress funding messages in CI output |
Sources: .github/actions/build-setup/action.yml1-21
The CI/CD system produces and manages multiple artifact types across different workflows.
| Artifact Pattern | Produced By | Content | Purpose |
|---|---|---|---|
test-coverage-{OS}-{sha} | build.yml | packages/core/coverage/lcov-report | Test coverage reports per OS |
storybook-{OS}-{sha} | build.yml | packages/html/dist/ | Built Storybook demo per OS |
examples-{OS}-{sha} | build.yml | All example package dist directories | Built examples for validation |
maxgraph_{VERSION}_examples.zip | create-github-release.yml | All example package dist directories | Release artifact |
maxgraph_{VERSION}_website.zip | create-github-release.yml | Complete website with subdirectory | Release artifact |
gh-pages | generate-website.yml | packages/website/build/ | GitHub Pages deployment |
website-pr-{number}-{sha} | generate-website.yml | Website with maxGraph subdirectory | PR preview artifact |
Sources: .github/workflows/build.yml57-74 .github/workflows/create-github-release.yml21-35 .github/workflows/generate-website.yml49
GitHub Actions artifacts have default retention periods:
Sources: .github/workflows/build.yml57-74 .github/workflows/create-github-release.yml65-89
The CI/CD pipeline deploys to three distinct targets depending on the workflow and trigger.
Deployment Target Conditions
Each deployment target has specific trigger conditions and workflow sources. GitHub Pages receives automatic updates on every main branch push, while releases and npm publishes occur only when version tags are created.
Sources: .github/workflows/generate-website.yml51-66 .github/workflows/create-github-release.yml4-6 .github/workflows/publish-npm-package.yml3-5
URL: https://maxgraph.github.io/maxGraph/
.github/workflows/generate-website.yml51-66
The deployment uses actions/deploy-pages@v4 with specific permissions:
pages: write - Deploy content to GitHub Pagesid-token: write - Verify deployment authenticity via OIDCThe deployment only occurs when:
push or workflow_dispatch eventsrefs/heads/main.github/workflows/create-github-release.yml84-106
Each release includes two attached zip files:
maxgraph_{VERSION}_examples.zip - All built examplesmaxgraph_{VERSION}_website.zip - Offline documentation archiveThe release is created as a draft, requiring manual editing and publishing by maintainers. Upon publication, a discussion is automatically created in the "Announces" category.
Package: @maxgraph/core
.github/workflows/publish-npm-package.yml20
The package is published with:
--provenance - SLSA provenance attestation--access public - Required for scoped packagesThe publish operation uses NPM's trusted publisher authentication via GitHub OIDC tokens, eliminating the need for stored credentials.
Sources: .github/workflows/generate-website.yml51-66 .github/workflows/create-github-release.yml84-106 .github/workflows/publish-npm-package.yml20
Refresh this wiki