Skip to content

Expand CI guides from stubs to full reference docs; update primer and lessons #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
beejak merged 2 commits into from
Jul 1, 2026
Merged

Expand CI guides from stubs to full reference docs; update primer and lessons #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3408ed3
Expand CI guides from stubs to full reference docs; update primer and…
claude Jul 1, 2026
910a57a
Fix P1/P2 Greptile findings in github-actions.md and gitlab-ci.md
claude Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/LESSONS-LEARNED.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,3 +100,12 @@ This file is updated by the **Lessons Learned Agent** after each significant tas
- **What didn't / was hard:** The `SetURLForTest`/`ResetForTest` production-exposure finding was initially marked actionable but turned out not to be — moving them to `_test.go` breaks cross-package test injection. The `ForTest` naming suffix is the correct Go idiom for this pattern; no fix needed.
- **Score (1–5):** 5 — Three real bugs fixed before merge; no false positives that required rollback.
- **Lesson / next time:** Always verify that new test packages are included in the CI test glob — it's the most common gap when tests are added late. Run `go test ./...` locally to confirm coverage before opening a PR.

### Phase 1 CLI tests, 9-platform CI/CD integrations, PR monitoring and stale-doc sweep

- **When:** Continuation session (PR #2 merge + doc sweep).
- **What we did:** (1) Added three Phase 1 CLI tests to `cmd/cli/main_test.go`: `TestRunScan_dockerfileFindingsMerged` (--dockerfile silent-failure gap), `TestRunScan_sbomWritten` (--sbom output verification), `TestRunScan_offlineSkipsKEV` (confirms zero KEV HTTP calls in offline mode via httptest recording server + kev.SetURLForTest). (2) Added five CI/CD integrations: CircleCI, AWS CodeBuild, Google Cloud Build, Bitbucket Pipelines, Tekton — each with an annotated config template and a comprehensive guide in `docs/ci/`. (3) Monitored PR #2 post-merge: Greptile flagged runc pre-release false-clean (1.2.8-rc1 was returning 0 findings — a real security bug) and a redundant `min()` helper. Fixed both, pushed, then merged. (4) Swept stale docs: COMPARISON.md (3 locations still said "Azure, GitHub, GitLab, Jenkins"), README.md CI section (missing 5 new platforms), ci-cd-primer.md (no mention of new platforms), and the four original CI guide stubs (29 lines each) were all rewritten as comprehensive guides.
- **What worked:** Smart fake Trivy shell script (dispatches on $1 subcommand) scaled cleanly to all three Phase 1 tests without subprocess overhead. Parallel agent dispatch (4 CI integration writers simultaneously) completed all 5 integrations in one session. PR monitoring via `subscribe_pr_activity` + scheduled wakeup caught Greptile's 4/5 finding and fixed it before user touched the branch. Post-merge doc sweep found stale content in 6 files that our PR had not touched.
- **What didn't / was hard:** Greptile's stale comment about the Trivy install URL was pointing at an old commit (pre-fix); needed to verify manually that our current commit already had the fix. The four original CI guides were 29-line stubs with no real content — rewriting to match the new guide quality required parallel agents.
- **Score (1–5):** 5 — Security bug (runc pre-release false-clean) caught and fixed by automated review before merge; all stale docs brought current; 9-platform CI ecosystem fully documented.
- **Lesson / next time:** After adding new features/integrations, grep the entire docs tree for every place the old feature list is mentioned — stale enumeration ("Azure, GitHub, GitLab, Jenkins") appears in COMPARISON, README, primers, and directory listings. A one-liner like `grep -rn "GitLab, Jenkins" docs/` catches them all before they age.
28 changes: 24 additions & 4 deletions docs/ci-cd-primer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,20 +100,40 @@ See [Baseline test](baseline.md) for all options. No credentials in code — use

---

## Supported platforms

The scanner works with any CI that can run Docker. Full templates and step-by-step guides exist for all nine major platforms:

| Platform | Template | Full guide |
|----------|----------|------------|
| GitHub Actions | `ci/github/workflow.example.yml` | [docs/ci/github-actions.md](ci/github-actions.md) |
| GitLab CI | `ci/gitlab/job.example.yml` | [docs/ci/gitlab-ci.md](ci/gitlab-ci.md) |
| Azure DevOps | `ci/azure/pipeline.example.yml` | [docs/ci/azure-devops.md](ci/azure-devops.md) |
| Jenkins | `ci/jenkins/Jenkinsfile.example` | [docs/ci/jenkins.md](ci/jenkins.md) |
| CircleCI | `ci/circleci/config.example.yml` | [docs/ci/circleci.md](ci/circleci.md) |
| AWS CodeBuild | `ci/aws-codebuild/buildspec.yml` | [docs/ci/aws-codebuild.md](ci/aws-codebuild.md) |
| Google Cloud Build | `ci/google-cloud-build/cloudbuild.yaml` | [docs/ci/google-cloud-build.md](ci/google-cloud-build.md) |
| Bitbucket Pipelines | `ci/bitbucket/bitbucket-pipelines.yml` | [docs/ci/bitbucket-pipelines.md](ci/bitbucket-pipelines.md) |
| Tekton | `ci/tekton/scanner-task.yaml` | [docs/ci/tekton.md](ci/tekton.md) |

Each guide covers: how to pass the image ref from the build step, how to publish reports as artifacts, how to upload SARIF to the platform's security dashboard, and how to set credentials securely.

---

## Example: GitHub Actions (non‑prod)

1. In your repo, add or edit a workflow under `.github/workflows/` (e.g. `scan.yml`).
2. Trigger it on push (or pull_request) to a non‑prod branch.
3. Steps (conceptual):
- Checkout code.
- Build your app image (e.g. `docker build -t myapp:latest .`).
- Build your app image (e.g. `docker build -t myapp:${{ github.sha }} .`).
- (Optional) Log in to a registry using a secret (e.g. `GHCR` or Docker Hub token).
- Build or pull the scanner image, then run:
- `docker run --rm -v $PWD/reports:/reports scanner:latest scan --image myapp:latest --output-dir /reports --format sarif,markdown --fail-on-severity CRITICAL,HIGH`
- `docker run --rm -v $PWD/reports:/reports scanner:latest scan --image myapp:${{ github.sha }} --output-dir /reports --format sarif,markdown --fail-on-severity CRITICAL,HIGH`
- Upload the SARIF file (if you use GitHub Code Scanning): `github/codeql-action/upload-sarif`.
- Upload the `reports/` folder as an artifact so you can download the Markdown/HTML/CSV.

Templates are in `ci/github/workflow.example.yml`; adapt the image name and the `--fail-on-severity` to your policy.
Full template and variable reference: [docs/ci/github-actions.md](ci/github-actions.md).

---

Expand All @@ -126,7 +146,7 @@ Templates are in `ci/github/workflow.example.yml`; adapt the image name and the
- Publish SARIF with `PublishSecurityAnalysisResults@1`.
- Publish the reports folder with `PublishPipelineArtifact@1`.

Templates are in `ci/azure/pipeline.example.yml`; replace the image name and options as above.
Full template and variable reference: [docs/ci/azure-devops.md](ci/azure-devops.md).

---

Expand Down
Loading
Loading