diff --git a/CHANGELOG.md b/CHANGELOG.md index 70211d7..f028494 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file. ## Unreleased +- Add v0.2 adoption examples for advisory, config/baseline, and blocking rollout modes. + ## 0.2.0 - 2026-07-05 - Add config file support for rule disabling, severity overrides, path excludes, and narrow suppressions. diff --git a/README.md b/README.md index f795ef2..08cf6ce 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,9 @@ jobs: output: awi-guard-report.md ``` -See [docs/adoption.md](docs/adoption.md) for rollout guidance. SARIF upload examples are available in [examples/sarif-upload.yml](examples/sarif-upload.yml). +See [docs/adoption.md](docs/adoption.md) for rollout guidance. Ready-to-copy +workflow examples are available in [examples](examples), including advisory, +config/baseline, blocking, and SARIF upload modes. ## Current maturity @@ -111,6 +113,7 @@ See: - [docs/configuration.md](docs/configuration.md) - [docs/baselines-and-suppressions.md](docs/baselines-and-suppressions.md) +- [examples](examples) ## Package smoke test diff --git a/docs/adoption.md b/docs/adoption.md index ca8aac8..faacd0b 100644 --- a/docs/adoption.md +++ b/docs/adoption.md @@ -40,6 +40,17 @@ jobs: See [configuration](configuration.md) and [baselines and suppressions](baselines-and-suppressions.md). +## Ready-to-copy Examples + +Use the examples that match your rollout stage: + +- [Advisory mode](../examples/advisory.yml): start here to collect findings without failing CI. +- [Config and baseline mode](../examples/config-and-baseline.yml): use this when known findings need planned cleanup. +- [Blocking mode](../examples/fail-on-high.yml): use this when the workflow is quiet enough to fail on high and critical findings. +- [SARIF upload](../examples/sarif-upload.yml): use this when you want code scanning alerts. + +Example config and baseline files are available in [examples](../examples). + ## Responsible Use Only scan repositories you own or are authorized to assess. Do not mass-report findings to public projects. Use synthetic examples for demos and issue reports. diff --git a/docs/baselines-and-suppressions.md b/docs/baselines-and-suppressions.md index c0e9d57..77e1768 100644 --- a/docs/baselines-and-suppressions.md +++ b/docs/baselines-and-suppressions.md @@ -4,12 +4,17 @@ Baselines and suppressions are both ways to manage accepted findings, but they s Use a baseline when a repository has existing findings and you want CI to focus on new findings. Use a suppression when a specific finding has been reviewed and accepted for a documented reason. +See [config and baseline workflow example](../examples/config-and-baseline.yml), +[example config](../examples/awi-guard.config.example.yml), and +[example baseline](../examples/awi-guard.baseline.example.json) for a practical +GitHub Actions setup. + ## Baselines Create a baseline from the current scan: ```bash -npx agentic-workflow-guard scan --write-baseline awi-guard.baseline.json +npx @jin0/agentic-workflow-guard scan --write-baseline awi-guard.baseline.json ``` When `--write-baseline` is used without an explicit `--fail-on`, the scan exits successfully after writing the baseline. @@ -17,7 +22,7 @@ When `--write-baseline` is used without an explicit `--fail-on`, the scan exits Use it in later scans: ```bash -npx agentic-workflow-guard scan --baseline awi-guard.baseline.json +npx @jin0/agentic-workflow-guard scan --baseline awi-guard.baseline.json ``` Baseline files use stable fingerprints: diff --git a/docs/configuration.md b/docs/configuration.md index 4c5ca8a..3618fed 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -3,7 +3,7 @@ `agentic-workflow-guard` works without a config file. Add `awi-guard.config.yml` when a repository needs rule overrides, path excludes, or narrow suppressions. ```bash -npx agentic-workflow-guard scan --config awi-guard.config.yml +npx @jin0/agentic-workflow-guard scan --config awi-guard.config.yml ``` ## Example diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..02bad6a --- /dev/null +++ b/examples/README.md @@ -0,0 +1,26 @@ +# Examples + +These examples show common `v0.2` adoption paths. Start with advisory mode, use +config and baselines to manage known findings, then move to blocking mode once +the workflow is quiet. + +| Example | Use when | +| --- | --- | +| [advisory.yml](advisory.yml) | You want visibility without failing CI yet | +| [config-and-baseline.yml](config-and-baseline.yml) | You have existing findings and want CI to focus on new risk | +| [fail-on-high.yml](fail-on-high.yml) | You are ready to block high and critical findings | +| [sarif-upload.yml](sarif-upload.yml) | You want code scanning alerts from SARIF output | + +## Example Config and Baseline Files + +- [awi-guard.config.example.yml](awi-guard.config.example.yml) shows rule + overrides, path excludes, and a narrow suppression. +- [awi-guard.baseline.example.json](awi-guard.baseline.example.json) shows the + baseline file shape. Generate real baselines with: + +```bash +npx @jin0/agentic-workflow-guard scan --write-baseline awi-guard.baseline.json +``` + +Keep suppressions and baselines narrow. Prefer fixing high-risk workflow patterns +when possible. diff --git a/examples/advisory.yml b/examples/advisory.yml new file mode 100644 index 0000000..663e709 --- /dev/null +++ b/examples/advisory.yml @@ -0,0 +1,26 @@ +name: Agentic Workflow Guard advisory + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + awi-guard: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: jinyounghub/agentic-workflow-guard@v0 + with: + paths: .github/workflows + fail-on: never + format: markdown + output: awi-guard-report.md + - uses: actions/upload-artifact@v4 + if: always() + with: + name: awi-guard-report + path: awi-guard-report.md diff --git a/examples/awi-guard.baseline.example.json b/examples/awi-guard.baseline.example.json new file mode 100644 index 0000000..4234467 --- /dev/null +++ b/examples/awi-guard.baseline.example.json @@ -0,0 +1,10 @@ +{ + "version": 1, + "findings": [ + { + "id": "R107", + "file": ".github/workflows/ai-review.yml", + "fingerprint": "0123456789abcdef01234567" + } + ] +} diff --git a/examples/awi-guard.config.example.yml b/examples/awi-guard.config.example.yml new file mode 100644 index 0000000..c5982ab --- /dev/null +++ b/examples/awi-guard.config.example.yml @@ -0,0 +1,13 @@ +rules: + R107: + severity: medium + +exclude: + paths: + - ".github/workflows/generated/**" + +suppressions: + - id: R104 + file: ".github/workflows/ai-review.yml" + reason: "AI output is rendered as report text and is not executed." + expires: "2026-12-31" diff --git a/examples/config-and-baseline.yml b/examples/config-and-baseline.yml new file mode 100644 index 0000000..c490e07 --- /dev/null +++ b/examples/config-and-baseline.yml @@ -0,0 +1,28 @@ +name: Agentic Workflow Guard with config and baseline + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + awi-guard: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: jinyounghub/agentic-workflow-guard@v0 + with: + paths: .github/workflows + config: awi-guard.config.yml + baseline: awi-guard.baseline.json + fail-on: high + format: markdown + output: awi-guard-report.md + - uses: actions/upload-artifact@v4 + if: always() + with: + name: awi-guard-report + path: awi-guard-report.md diff --git a/examples/fail-on-high.yml b/examples/fail-on-high.yml index 5ed4774..0da6dad 100644 --- a/examples/fail-on-high.yml +++ b/examples/fail-on-high.yml @@ -1,7 +1,9 @@ -name: Agentic Workflow Guard fail on high +name: Agentic Workflow Guard blocking on: pull_request: + push: + branches: [main] permissions: contents: read @@ -15,5 +17,5 @@ jobs: with: paths: .github/workflows fail-on: high - format: sarif - output: awi-guard.sarif + format: markdown + output: awi-guard-report.md