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

> Integrate the DESIGN.md linter into your CI pipeline effortlessly. Learn how to use the built-in lint command for automated validation and ensure code quality.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/.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`](https://github.com/google-labs-code/design.md/blob/main/package.json).

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

```yaml
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:

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

```

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

```bash
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`](https://github.com/google-labs-code/design.md/blob/main/package.json) with a script entry:

```json
{
  "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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/.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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/spec-config.yaml) file, and reference your custom build in the CI pipeline.