Top-level project README (updated to link CI/CD guide)
from
to
via
pattern
README.md
docs/CI-CD.md
markdown link
docs/CI-CD.md
Document the Phase 7 deliverables: import command usage, pre-commit hook lifecycle, and GitHub Actions workflow for SARIF upload.
Purpose: CICD-01 and CICD-02 require the integration to be discoverable by users. Code alone is not enough — a working workflow example and hook setup walkthrough are part of the requirement.
Output: docs/CI-CD.md, README section linking to it.
@.planning/phases/07-import-cicd/07-CONTEXT.md
@README.md
Task 1: Write docs/CI-CD.md with GitHub Actions + pre-commit guide
docs/CI-CD.md
Create docs/CI-CD.md with the following sections (markdown):
1. **Title & intro** — "KeyHunter CI/CD Integration" — one paragraph explaining scope: pre-commit hooks, GitHub Actions SARIF upload, importing external scanner output.
2. **Pre-commit Hook** section:
- Install: `keyhunter hook install` (explain what file is written, where).
- Override: `--force` flag backs up existing pre-commit as `pre-commit.bak.<timestamp>`.
- Bypass a single commit: `git commit --no-verify`.
- Uninstall: `keyhunter hook uninstall`.
- Note: only scans staged files via `git diff --cached --name-only --diff-filter=ACMR`.
3. **GitHub Actions (SARIF upload to Code Scanning)** section, with a full working workflow example saved as a fenced yaml block:
```yaml
name: KeyHunter
on:
push:
branches: [main]
pull_request:
jobs:
scan:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install KeyHunter
run: |
curl -sSL https://github.com/salvacybersec/keyhunter/releases/latest/download/keyhunter_linux_amd64.tar.gz | tar -xz
sudo mv keyhunter /usr/local/bin/
- name: Scan repository
run: keyhunter scan . --output sarif > keyhunter.sarif
continue-on-error: true
- name: Upload SARIF to GitHub Code Scanning
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: keyhunter.sarif
category: keyhunter
```
- Explain `continue-on-error: true` — scan exits 1 on findings; we want the SARIF upload step to still run. The findings show up in the Security tab.
- Explain the required `security-events: write` permission.
4. **Importing External Scanner Output** section:
- Running TruffleHog then importing:
```
trufflehog filesystem . --json > trufflehog.json
keyhunter import --format=trufflehog trufflehog.json
```
- Gitleaks JSON:
```
gitleaks detect -f json -r gitleaks.json
keyhunter import --format=gitleaks gitleaks.json
```
- Gitleaks CSV:
```
gitleaks detect -f csv -r gitleaks.csv
keyhunter import --format=gitleaks-csv gitleaks.csv
```
- Dedup guarantee: re-running the same import is idempotent.
5. **Exit Codes** section — table of 0/1/2 semantics for CI integration.
Keep the whole file under ~200 lines. No emojis.
test -f docs/CI-CD.md && grep -q "upload-sarif" docs/CI-CD.md && grep -q "keyhunter hook install" docs/CI-CD.md && grep -q "keyhunter import --format=trufflehog" docs/CI-CD.md
- docs/CI-CD.md exists with all 5 sections
- Required strings present (upload-sarif, hook install, import --format=trufflehog)
Task 2: Update README.md with CI/CD integration link
README.md
Read current README.md first.
Add (or update if a stub section exists) a "CI/CD Integration" H2 section that:
- Contains 2-4 sentences summarizing pre-commit hook + GitHub SARIF upload support.
- Links to `docs/CI-CD.md` for the full guide.
- Mentions `keyhunter import` for TruffleHog/Gitleaks consolidation.
Place the section after any existing "Installation" / "Usage" section and before "Development" or "License" sections. If those anchors don't exist, append near the end but before "License".
Do not rewrite unrelated parts of the README.
<success_criteria>
CICD-01 and CICD-02 are discoverable end-to-end: a user landing on the README can find CI/CD guidance, follow it to docs/CI-CD.md, and copy a working GitHub Actions workflow + pre-commit setup.
</success_criteria>
After completion, create `.planning/phases/07-import-cicd/07-06-SUMMARY.md`.
