GitHub Action

madr-lint は複合 GitHub Action を提供しており、違反ごとに PR diff アノテーション を 出力します。エラーと警告がプルリクエストの diff にインラインで表示されます。

クイックスタート

.github/workflows/adr-lint.yml

name: ADR lint

on:
  pull_request:
    paths:
      - 'docs/adr/**'
  push:
    branches: [main]

jobs:
  madr-lint:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22   # madr-lint は Node ≥22 が必要です
      - uses: knktkc/madr-lint@v0
        with:
          path: docs/adr

v0 タグが付く（最初の npm リリース）まで は @main を指定してください： uses: knktkc/madr-lint@main

error 重大度の診断があると action は非ゼロで終了し、ジョブを自動的に失敗させます。

入力

入力	デフォルト	説明
path	（config / docs/adr）	lint するパス（ファイルまたはディレクトリ）
version	latest	インストールする madr-lint の npm バージョンまたは dist-tag
working-directory	.	action を実行するディレクトリ
args	（なし）	madr-lint にそのまま渡す追加 CLI 引数

例

特定のバージョンを固定する:

      - uses: knktkc/madr-lint@v0
        with:
          version: '0.1.0'
          path: docs/adr

警告をエラーとして扱う（警告があれば失敗）:

      - uses: knktkc/madr-lint@v0
        with:
          path: docs/adr
          args: '--max-warnings 0'

モノレポ — 複数ディレクトリを lint する:

      - uses: knktkc/madr-lint@v0
        with:
          path: 'services/api/docs/adr services/web/docs/adr'

前提条件

この action は Node 自体をインストールしません。事前に actions/setup-node を追加し、 node-version: 22（以上）を設定してください（上記の例を参照）。

SARIF を code scanning にアップロードする（上級者向け）

検出結果を Security → Code scanning タブに表示し、PR を超えて永続化したい場合は、 --format sarif フラグで SARIF レポートをアップロードしてください：

jobs:
  madr-lint:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Lint ADRs (SARIF)
        run: npx madr-lint --format sarif docs/adr > madr-lint.sarif
        continue-on-error: true
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: madr-lint.sarif

ヒント

• paths: でトリガーを絞り込み、ADR が変更されたときだけジョブが実行されるようにします。
• 設定ファイルをコミットして（設定 を参照）、ローカルと CI の 実行結果を一致させます。
• ファイル単位のキャッシュは CI ランナーに持ち込まないようにします（これはローカルでの 高速化のためのものです）。CI でのコールドランはすでに十分高速です。