CI/CD Integration

The dotreq CLI authenticates from environment variables in CI/CD environments, enabling AI-powered workflows in GitHub Actions and other automation pipelines.

Use Cases

• Automated bug fixing: Linear issue → Claude Code → PR
• Feature implementation: Spec-driven development triggered by issue labels
• Test generation: AI writes tests referencing requirements
• Requirements validation: Style checking in CI pipelines

Authentication

The CLI discovers credentials from project-settings.json in your local .requirements/ directory when it’s present. In CI — where no settings file is checked in — the CLI falls back to environment variables automatically, no flag required, and prints a notice to stderr:

dotreq sync --repo-contributes
dotreq report --source cloud

The environment variables it reads:

If only one is set, the command returns a clear error naming both.

Important: A settings file on disk always wins over these environment variables, so a local checkout is never overridden by an ambient environment. The environment is used only when no settings file is found.

GitHub Actions Configuration

Step 1: Add Secrets

Add these secrets to your GitHub repository:

• DOTREQ_PROJECT_ID — Your project slug
• DOTREQ_PROJECT_SECRET — Your project secret

Get these from your project’s project-settings.json or by running dotrequirements link.

Step 2: Install the CLI

In your workflow, install the CLI so dotreq is on the PATH:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'
 
- name: Install dotrequirements CLI
  run: npm install -g @popoverai/dotrequirements

If your project already depends on @popoverai/dotrequirements, installing your dependencies is enough — invoke it as npx dotreq instead.

Step 3: Use with Claude Code Action

Expose the credentials to the action as environment variables, and make sure Bash is in the allowed tools so Claude can run the CLI:

- uses: anthropics/claude-code-action@v1
  env:
    DOTREQ_PROJECT_ID: ${{ secrets.DOTREQ_PROJECT_ID }}
    DOTREQ_PROJECT_SECRET: ${{ secrets.DOTREQ_PROJECT_SECRET }}
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    prompt_file: /tmp/claude-prompt.txt
    claude_args: "--allowedTools Read,Write,Edit,Bash,Glob,Grep,WebFetch,WebSearch"

Claude runs dotreq verbs directly; with the two secrets set and no settings file in the runner, cloud commands like dotreq sync --repo-contributes authenticate automatically.

Available Commands in CI/CD

All CLI verbs work in CI/CD when credentials are provided:

Always Available (No Auth Required)

• dotreq list [--untested] — Get summary of all requirements (--untested filters to coverage gaps)
• dotreq get <id> — Get requirement tree with coverage info
• dotreq search <query> [--regex] — Search by text or regex
• dotreq validate — Check file syntax offline
• dotreq create-requirement-document — Get Markdown template
• dotreq report (default --source local) — Coverage from local cache

Require Authentication (settings file or the two env vars)

• dotreq style-check <file> --source cloud — Hosted style review
• dotreq review-test <test-file> --source cloud — Hosted semantic test review
• dotreq sync — Reconcile the repo and the cloud
• dotreq report --source cloud — Coverage from cloud-persisted record

CI pipelines typically don’t have a subagent to run the in-conversation review flow, so the review verbs use --source cloud for the hosted reviewer — see Agent Workflow.

Example: Linear Integration

This example workflow triggers when a claude-feature label is added to a Linear issue:

name: Claude Linear
 
on:
  repository_dispatch:
    types: [claude-fix, claude-feature]
 
jobs:
  claude-linear:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Install dotrequirements CLI
        run: npm install -g @popoverai/dotrequirements
 
      - uses: anthropics/claude-code-action@v1
        env:
          DOTREQ_PROJECT_ID: ${{ secrets.DOTREQ_PROJECT_ID }}
          DOTREQ_PROJECT_SECRET: ${{ secrets.DOTREQ_PROJECT_SECRET }}
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Implement this feature using the spec-driven workflow:
            1. Compose requirements with the dotreq CLI
            2. Style-review with `dotreq style-check <file> --source cloud`
            3. Implement the feature
            4. Write tests referencing requirements
            5. Create a PR
          claude_args: "--allowedTools Read,Write,Edit,Bash,Glob,Grep,WebFetch,WebSearch"

Security Considerations

• File wins over environment: a project-settings.json on disk always takes precedence over the environment variables, so a local checkout is never overridden by an ambient environment
• Secret isolation: Inject credentials as environment variables at runtime so nothing is committed to the repository
• Scoped secrets: Consider creating CI-specific project secrets with labels (e.g., “GitHub Actions”) that can be rotated independently