Techcle Wiki

Github Actions

3 min read

GitHub Actions Integration Guide

CascadeGuard generates a complete GitHub Actions CI/CD pipeline for your image repository. Running cg tools generate emits four workflow files under .github/workflows/.

Generated workflows

build-image.yaml — Reusable build workflow

A workflow_call workflow that builds, scans, attests, and signs a single image. It is called by the other workflows rather than triggered directly.

Steps performed:

  1. Check out source code
  2. Set up Docker Buildx
  3. Build the image
  4. Scan with Grype and Trivy
  5. Generate an SBOM with Syft
  6. Sign the image and attest the SBOM with Cosign (keyless, via Sigstore)
  7. Push to the registry

ci.yaml — PR checks and main-branch pipeline

Triggered on:

  • push to main
  • All pull_request events

On pull requests: builds the matrix of all images and runs scans. Does not push or sign.

On merge to main: builds, scans, signs, and pushes every image in images.yaml.

Matrix build: Every image defined in images.yaml gets its own parallel job. Adding a new image to images.yaml and re-running generate-ci automatically includes it in the matrix.

scheduled-scan.yaml — Nightly CVE re-scan

Triggered by:

  • A nightly cron schedule
  • Manual workflow_dispatch

Re-scans every currently published image against the latest vulnerability databases — without rebuilding. If a newly disclosed CVE is found in a published image, this workflow opens a GitHub Issue with details.

This ensures you are notified of new vulnerabilities even between scheduled rebuilds.

release.yaml — Tag-triggered release

Triggered by tag pushes matching v* (e.g. v1.2.3).

  1. Builds and signs all images
  2. Pushes to the registry with the release tag
  3. Creates a GitHub Release with a changelog

Regenerating pipelines

Whenever you change images.yaml (add, remove, or rename images), regenerate the CI files:

cg tools generate

Commit the updated workflow files. The matrix builds will automatically reflect the change on the next run.

Note: The generated files include a header comment — # Auto-generated by CascadeGuard — do not edit by hand. — to make their origin clear. Any manual edits will be overwritten on the next cg tools generate run.

Required repository secrets and permissions

Secret / PermissionUsed byPurpose
GITHUB_TOKENAll workflowsRegistry push, Cosign keyless signing, issue creation
id-token: writebuild-image.yaml, release.yamlRequired for Cosign keyless signing via OIDC
packages: writebuild-image.yamlPush images to GitHub Container Registry (ghcr.io)
issues: writescheduled-scan.yamlOpen issues when new CVEs are found

No additional secrets are required for the default configuration when using GitHub Container Registry. For private registries, add appropriate login secrets and customise the workflow templates.

Platform configuration

The target CI platform is controlled by .cascadeguard.yaml in your state repository root:

# .cascadeguard.yaml
ci:
  platform: github   # default

You can also pass --platform to override at runtime:

cg tools generate --platform github

GitLab CI support is planned for a future release.

See also

Graph View