How to Configure the DESIGN.md Linter to Run in Your CI Pipeline

The DESIGN.md CLI (@google/design.md) provides a built-in lint sub-command that exits with a non-zero status code when validation errors are detected, making it ready for immediate integration into any continuous integration pipeline.

The google-labs-code/design.md repository ships with a dedicated command-line interface that validates DESIGN.md files against the official specification. Because the tool is packaged as an npm-compatible module, you can integrate it into GitHub Actions, GitLab CI, CircleCI, or any other platform that supports Node.js runtimes. This guide covers the exact file paths, commands, and configuration patterns needed to enforce DESIGN.md standards automatically on every pull request.

Understanding the CLI Architecture

The linting functionality is implemented in packages/cli/src/commands/lint.ts. This command imports the core validation logic via the lint(content) function from packages/cli/src/linter/index.ts, reads the target DESIGN.md file, and executes the linter. When errors are found, the CLI sets process.exitCode = 1 (as seen in the source), which signals to CI systems that the job has failed.

The tool is distributed as the @google/design.md package and executes via Bun (the repository's package manager) or standard npx calls.

Configuring GitHub Actions

The repository includes a reference workflow in .github/workflows/test.yml that demonstrates best practices. To configure the linter in your own GitHub Actions workflow, replicate the following pattern:

1. Checkout the repository code.
2. Install Bun (version 1.3.9 matches the monorepo's packageManager field).
3. Install dependencies using bun install to pull all workspace dependencies, including the CLI.
4. Execute the lint task using bun run lint, which invokes the Turborepo task defined in the root package.json.

Here is a minimal workflow configuration that lints a specific DESIGN.md file:

name: CI – Lint DESIGN.md

on:
  push:
    branches: ['**']
  pull_request:

jobs:
  designmd-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.3.9

      - name: Install dependencies
        run: bun install

      - name: Lint DESIGN.md
        run: bun run lint -- ./examples/atmospheric-glass/DESIGN.md

The bun run lint command triggers the "lint": "turbo lint" script, which ultimately executes the CLI's design.md lint command. Because the CLI handles exit codes internally, GitHub Actions will automatically mark the job as failed when validation errors are present.

Integrating with Other CI Platforms

For GitLab CI, CircleCI, Jenkins, or other platforms, you can bypass the Turborepo wrapper and invoke the CLI directly. After installing Bun, run:

bun install
npx @google/design.md lint path/to/DESIGN.md

To generate machine-readable output for CI logs and reporting dashboards:

npx @google/design.md lint ./examples/totality-festival/DESIGN.md --format json

Windows Agent Support

For Windows-based CI runners, use the designmd alias instead of the full package name. Configure your package.json with a script entry:

{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

Then invoke bun run design:lint or npm run design:lint in your Windows CI steps.

Key Implementation Files

These source files define the linting behavior you are configuring:

• packages/cli/src/commands/lint.ts – The CLI command implementation that reads input files, runs the linter, and manages exit codes.
• packages/cli/src/linter/index.ts – Exports the core lint function that performs the actual validation against the DESIGN.md specification.
• packages/cli/src/linter/spec-config.yaml – Contains the central specification rules; modifications to this file affect the validation criteria used in your CI pipeline.
• .github/workflows/test.yml – The reference GitHub Actions workflow that demonstrates the lint step alongside tests and smoke checks.

Summary

Configuring the DESIGN.md linter in your CI pipeline ensures every pull request validates against the official specification automatically:

• The CLI in packages/cli/src/commands/lint.ts exits with code 1 when errors are detected, causing CI jobs to fail without additional scripting.
• Use bun run lint to execute the Turborepo task, or call npx @google/design.md lint directly for custom CI configurations.
• The tool supports JSON output formatting for integration with CI reporting systems.
• Windows CI agents can use the designmd command alias for cross-platform compatibility.

Frequently Asked Questions

How does the DESIGN.md linter report errors in CI?

The linter sets process.exitCode = 1 when any validation errors are found, as implemented in packages/cli/src/commands/lint.ts. This standard Unix exit code causes CI platforms like GitHub Actions, GitLab CI, and CircleCI to automatically mark the job as failed without requiring custom error handling scripts.

Can I use npm instead of Bun to run the DESIGN.md linter?

While the google-labs-code/design.md repository uses Bun as its package manager, you can install the CLI globally or locally using npm with npm install @google/design.md and then run npx @google/design.md lint. However, the reference workflow uses Bun to ensure compatibility with the monorepo's workspace configuration and dependency resolution.

What files should the DESIGN.md linter target in a CI pipeline?

Configure the linter to validate any file named DESIGN.md or files matching your project's specific pattern. The CLI accepts file paths as arguments, such as bun run lint -- ./examples/atmospheric-glass/DESIGN.md, allowing you to target specific directories or use glob patterns depending on your CI environment's capabilities.

How do I configure the linter rules for DESIGN.md validation?

The linting rules are defined in packages/cli/src/linter/spec-config.yaml within the source repository. When using the published CLI package, these rules are bundled automatically. To customize validation criteria, you would need to fork the repository, modify the spec-config.yaml file, and reference your custom build in the CI pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}