Development workflow

The day-to-day cycle of writing, testing, and shipping a change to Grype.

Branching

Work happens in feature branches off main. There are no long-lived release branches — each release is a tag on main. The release.yaml workflow is the only thing that creates new tags.

Inner loop

Most contributors run code via go run for fast iteration:

# scan with current source
go run ./cmd/grype alpine:latest

# debug: enable trace logs
GRYPE_LOG_LEVEL=trace go run ./cmd/grype alpine:latest

# skip the slow online DB update if you already have one
go run ./cmd/grype --no-db-auto-update alpine:latest

For end-to-end CLI testing, use the snapshot binary:

task snapshot
./snapshot/$(uname -s | tr '[:upper:]' '[:lower:]')-build_*/grype --version

The snapshot task uses goreleaser with checksum-based source tracking, so it only rebuilds when code changes.

Generated code

Several JSON and DB schemas are generated. If you change them, regenerate before committing:

task generate

The CI lane task check-json-schema-drift and task check-db-schema-drift will fail the build if generated artifacts drift from the source.

Test loop

Local-first:

# fast feedback
task unit

# end-to-end against snapshot binary
task cli

# everything except install-test
task test

CI runs the full task validate suite via .github/workflows/validations.yaml. The same workflow runs the install acceptance test in test/install/.

Submitting a PR

1. Sign your commits (git commit -s). The --signoff flag is required.
2. Push to a fork and open a PR against main.
3. The PR title becomes a changelog entry — use the conventional commit style (feat:, fix:, chore:, etc.). chronicle parses these during release.
4. Add labels via the GitHub UI to control changelog grouping.
5. CI must be green; reviewers will not approve red PRs.

Reviewing

The team uses GitHub's review system. Re-request review after addressing comments — there is no automation that does it for you. PRs typically merge within a few days; large architectural changes may take longer.

Cutting a release

task release is interactive and requires admin approval on the GitHub Actions run. The release pipeline:

1. Generates a changelog with chronicle.
2. Builds binaries via goreleaser (configured in .goreleaser.yaml).
3. Pushes container images to ghcr.io and docker.io.
4. Updates the Homebrew tap at anchore/homebrew-grype.
5. Publishes a GitHub Release with archives.

See RELEASE.md for the full procedure including retracting a release.