Build Flow Action

One workflow. Full CI, security, packaging, containers, and releases — safe by default.

Build Flow Action is the orchestration layer by WG Technology Labs that coordinates your entire build and release lifecycle through a single reusable workflow call.

Without Build Flow, teams must manually wire separate workflows for CI, security scanning, package publishing, container builds, and releases. This leads to:

• Unsafe release ordering (publishing a release before artifacts are built)
• Duplicated workflow boilerplate across repositories
• Inconsistent CI checks and security gates
• Visible GitHub Releases with missing production artifacts

Build Flow eliminates these problems with one rule: build and validate first, release last.

Add one workflow file to your repository. That's it.

# .github/workflows/build-flow.yml
name: Build Flow

on:
  pull_request:
    branches: [dev, main]
  push:
    branches: [dev, main]

jobs:
  build-flow:
    uses: wgtechlabs/build-flow-action/.github/workflows/app.yml@main
    secrets: inherit

Build Flow auto-detects your project from lockfiles and manifests. Zero-config gives you CI validation, security scanning, and release finalization. Package and container flows in app.yml stay opt-in via enable-package and enable-container.

For production repositories, pin reusable workflow references to a release tag or commit SHA instead of @main.

permissions:
  contents: write          # release commits, tags, and changelog
  packages: write          # GitHub Packages / GHCR
  id-token: write          # npm trusted publishing
  pull-requests: write     # default PR comments from primitives
  security-events: write   # CodeQL + container SARIF upload
  actions: read            # CodeQL

jobs:
  build-flow:
    uses: wgtechlabs/build-flow-action/.github/workflows/app.yml@main
    secrets: inherit
    with:
      ci-profile: auto
      enable-package: true        # opt-in: publish to npm/GitHub Packages
      package-npm-auth-method: oidc
      enable-container: true      # opt-in: publish to Docker Hub/GHCR
      container-registry: docker-hub
      publish-dev-artifacts: false
      publish-pr-artifacts: false
      publish-manual-artifacts: false

Configure npm trusted publishing before the first publish. This example validates development changes and publishes artifacts only from eligible main pushes.

jobs:
  ci:
    uses: wgtechlabs/build-flow-action/.github/workflows/ci.yml@main
    secrets: inherit
    with:
      ci-profile: auto

Set container-images to build distinct images with the same planned version and finalized source commit. Build Flow publishes one GitHub release only after every configured image publishes successfully. This does not require monorepo mode.

with:
  enable-container: true
  container-registry: ghcr
  container-release-platforms: linux/amd64
  container-images: |
    [
      {"image-name": "my-app", "build-args": "SERVICE=app"},
      {"image-name": "my-browser", "build-args": "SERVICE=browser"}
    ]

Both images use the shared Dockerfile and build context; the Dockerfile must use the SERVICE build argument to select its app or browser stage. See the complete multi-image example and image definition schema.

All profiles support overriding individual commands via ci-*-command inputs.

When you call app.yml, Build Flow runs this dependency graph:

1. Context Detection     → determines branch, event, and policy
2. CI Gate               → install, lint, typecheck, test, build + Gitleaks (matrix support)
3. Version Plan (main)   → release primitive dry run produces immutable version metadata
4. Source Finalization  → waits for CI + CodeQL, updates versions, and creates the release tag
  ├── 5a. Package Publishing   → consumes the planned version and finalized source
  ├── 5b. Container Publishing → all images consume the planned tag and finalized source
   └── 6. Release Publication  → creates GitHub Release LAST after every enabled artifact publishes
   CodeQL (after CI)     → required before source finalization or artifact publication

Default behavior (zero-config): CI + security on main. Enable a package or container flow to publish artifacts and finalize a release. When enabled (or when using package.yml / container.yml directly), artifact publishing defaults to allowed on main, dev, PR, manual, and published release events unless you set a publish-*-artifacts input to false.

An enabled CodeQL scan must succeed before source finalization or any artifact publishing. A deliberately disabled scan, or one with no detected languages, may be skipped. Failed or cancelled scans block publication.

Key behaviors:

• Immutable main releases — a dry-run release plan supplies one version to every planned artifact and finalization
• Release is always last — no public release until every enabled artifact job succeeds; packages must publish to every selected registry
• Smart check visibility — only relevant checks appear on your PRs (no skipped noise)
• Matrix validation — test across multiple runtime versions automatically
• Ecosystem caching — dependency caching for npm, pip, Go modules

container.yml delegates to app.yml with container publishing enabled. Its existing inputs and artifact-published output remain available; it also accepts container-images and shared Dockerfile, context, build argument, platform, and push settings. Use app.yml for the full primitive configuration, including custom container security options.

Usage pattern — these are reusable workflows. Reference them with:

uses: wgtechlabs/build-flow-action/.github/workflows/<workflow>@main

For production safety, prefer:

uses: wgtechlabs/build-flow-action/.github/workflows/<workflow>@v0
# or pin to a full commit SHA

Profiles auto-detect from lockfiles (auto) or can be set explicitly. Each profile includes sensible defaults and dependency caching.

# Node/Bun — auto-detects .nvmrc/.node-version for version pinning
ci-profile: node-bun
ci-install-command: bun install --frozen-lockfile
ci-test-command: bun test

# Python
ci-profile: python
ci-runtime-version: '3.13'
ci-matrix-versions: '["3.11","3.12","3.13"]'
ci-install-command: pip install -r requirements.txt
ci-test-command: pytest -q

# Go
ci-profile: go
ci-runtime-version: '1.23'
ci-test-command: go test ./...

# Rust
ci-profile: rust
ci-build-command: cargo build
ci-test-command: cargo test

# Java
ci-profile: java
ci-matrix-versions: '["17","21"]'
ci-build-command: ./gradlew build

# C/C++
ci-profile: c-cpp
ci-build-command: cmake -S . -B build && cmake --build build
ci-test-command: ctest --test-dir build --output-on-failure

# Custom — bring your own commands
ci-profile: custom
ci-setup-command: ./scripts/ci/setup.sh
ci-install-command: ./scripts/ci/install.sh
ci-lint-command: ./scripts/ci/lint.sh
ci-test-command: ./scripts/ci/test.sh

All CI jobs default to ubuntu-latest. Override with ci-runs-on for macOS, Windows, or self-hosted runners:

ci-runs-on: macos-latest
ci-runtime-version: '22'
ci-matrix-versions: '["20","22"]'

Source of truth: .github/workflows/app.yml (on.workflow_call.inputs).

container-images accepts a JSON array of 1–256 objects. Unknown keys and non-string values are rejected before release planning.

The resolved JSON, including shared defaults copied into each image, is limited to 900 KiB measured as UTF-16. This leaves room for policy outputs within GitHub's job output limit. Oversized configurations fail before builds start; use fewer images or smaller shared defaults.

Registry, tag, security, and publishing settings are shared across images. Leaving container-images empty retains single-image behavior; a one-item array also retains the existing skip and comment behavior.

With more than one image and pushing enabled, every image must report publication to at least one selected registry. A failed, cancelled, skipped, or unpublished image prevents the shared GitHub release. Bot detection or commit filtering that skips an image fails the requested publishing batch. Already-published images are not rolled back if another image fails.

For builds without publication, set container-push-enabled: false; this disables the batch publication requirement and prevents the GitHub release. On main, also set release-dry-run: true to run the build without finalizing the source and tag.

Multi-image builds disable the primitive's PR and vulnerability comments because concurrent images would update the same comment. Results remain in each job's logs and summary. SARIF categories receive per-image suffixes so scans remain separate. Single-image comments and categories are unchanged.

Container checks use the static base name Container flow so disabled or policy-skipped jobs remain readable before matrix expansion. GitHub appends matrix details to executed checks. The Run container primitive (<image-name>) step identifies each image; image details also remain in the logs and summary.

Package GitHub Releases require a successful package job and publication to every registry selected by package-registry. For monorepos, every result must succeed in every selected registry; planned releases must also cover the exact planned package names and versions. The primitive's artifact-published output retains its meaning of publication to at least one registry. Partial publication blocks the GitHub Release but does not roll back packages already published.

app.yml and package.yml support automatic npm releases through GitHub Actions OIDC. The package job uses Package Build Flow v2.3.0, pinned to fac4cc6f61889fbc33849df87f20aa81a2a41bf2. Use a Build Flow release or immutable commit containing package-npm-auth-method; upgrading the primitive alone does not upgrade an older Build Flow pin.

Before publishing:

1. Ensure the npm package exists. A new package needs the one-time first publication below.
2. In the package's npm settings, configure a GitHub Actions trusted publisher for the calling repository and workflow filename, such as build.yml. Use only the filename, not .github/workflows/build.yml or this repository's app.yml. Match the publishing job's environment if one is configured. Each package in a monorepo needs its own trust configuration.
3. Explicitly allow npm publish for that trusted publisher. Stage-only permission requires a maintainer's approval for each version; it does not permit unattended direct releases.
4. Grant id-token: write in the caller and select package-npm-auth-method: oidc. Keep packages: write when also publishing to GitHub Packages.

The package job installs Node 24.21.0 and npm 11.21.0 when OIDC is selected for npm or both registries. These exceed npm's minimum requirements of Node 22.14.0 and npm 11.5.1. This publication runtime is separate from the CI compatibility matrix. Bun remains available for installation, tests, builds, and packing; the npm CLI supplies the OIDC publication transport. Use GitHub-hosted runners. npm setup requirements

The caller and reusable publishing job both need OIDC permission. The package job inherits the caller grant, including any additional scopes granted for other features; other jobs keep their own explicit permissions. Keep the caller permission map minimal and never use write-all. See the permission tradeoff. The package's repository.url must identify the calling GitHub repository. Configuring trust does not prove publication: verify the registry version and workflow results after the first run.

OIDC publication does not need NPM_TOKEN. GitHub Packages uses the built-in GITHUB_TOKEN and is separate from GHCR container publication. Installing private dependencies may require separate read credentials; npm publishing trust does not authorize installation. This input does not configure dependency credentials. Keep any required read credentials separate from publishing authentication.

When upgrading to a Build Flow revision that supports this input, set package-npm-auth-method explicitly in the same change. Older revisions reject the new input:

• OIDC: configure trust, add the caller permission, and set package-npm-auth-method: oidc. No npm publishing secret is required. Remove obsolete publishing credentials only after verifying the new path and checking whether other workflows still use them.
• Token: set package-npm-auth-method: token and provide NPM_TOKEN through repository/organization secrets or an explicit reusable-workflow secret mapping. npm still supports granular tokens subject to their permissions and package policy. A stage-only token cannot authorize this action's direct publish command.

For automatic production releases, set publish-dev-artifacts, publish-pr-artifacts, and publish-manual-artifacts to false, as in the examples. CI and security checks still validate those events. OIDC changes authentication; it does not change the requirement for every selected registry and the complete package job to succeed before the GitHub Release.

npm requires an existing package before configuring its trusted publisher. Build and review the initial tarball, then have a maintainer publish it once using interactive npm login and 2FA:

npm login --registry=https://registry.npmjs.org
npm publish ./path/to/reviewed-package.tgz --access public --registry=https://registry.npmjs.org

Verify the published version, configure trust, and use OIDC for subsequent versions. Do not retry the already published version. If a version was published to only one selected registry, recover the missing registry separately before creating its GitHub Release; publication is not atomic.

A staged first publication followed by maintainer approval is also possible. Build Flow uses direct publication and does not implement staging or approval polling. Keep account 2FA enabled; npm's setting to disallow traditional publishing tokens is compatible with a trusted publisher allowed to run npm publish.

When using secrets: inherit, Build Flow automatically picks up the following secrets from your repository or organization:

GHCR (GitHub Container Registry) authentication uses the built-in GITHUB_TOKEN automatically — no extra secret is needed unless you set GHCR_TOKEN to override it.

GitHub Packages also uses the built-in GITHUB_TOKEN. GHCR_TOKEN is a container credential override, not an npm or GitHub Packages credential.

This example keeps Build Flow orchestration while tuning package, container, and release primitives directly through app.yml passthrough inputs.

name: Build Flow

on:
  push:
    branches: [dev, main]
  pull_request:
    branches: [dev, main]

permissions:
  contents: write
  packages: write
  id-token: write
  pull-requests: write
  security-events: write
  actions: read

jobs:
  build-flow:
    uses: wgtechlabs/build-flow-action/.github/workflows/app.yml@main
    secrets: inherit
    with:
      enable-package: true
      enable-container: true
      enable-release: true

      package-registry: both
      package-npm-auth-method: oidc
      package-monorepo: true
      package-paths: "packages/core/package.json,packages/cli/package.json"
      publish-dev-artifacts: false
      publish-pr-artifacts: false
      publish-manual-artifacts: false

      container-registry: both
      container-dockerfile: ./ops/docker/Dockerfile
      container-context: ./apps/api
      container-floating-tags: true
      container-tag-prefix: api-

      release-monorepo: true
      release-unified-version: false
      release-per-package-changelog: true
      release-root-changelog: true
      release-sync-version-files: true

Build Flow's reusable workflows request the permissions their primitives need, but a called workflow can never exceed the permissions of the caller. Missing caller permissions can prevent the called workflow from starting or cause an operation to fail. Declare the scopes needed by your enabled features:

A CI-only or container-only caller does not need OIDC permission for this feature. For a full app flow, use the block shown in With Package and Container Publishing.

Build Flow orchestrates these WG Technology Labs primitives:

• wgtechlabs/release-build-flow-action — release automation
• wgtechlabs/package-build-flow-action — package publishing (npm, GitHub Packages)
• wgtechlabs/container-build-flow-action — container publishing (Docker Hub, GHCR)

You don't need to install these separately — Build Flow calls them internally with safe sequencing and policy gates, and now exposes their full configurable input surface through orchestration passthroughs.

Build Flow includes security scanning out of the box:

• Gitleaks — detects secrets committed to your repository (enabled by default)
• CodeQL — static analysis for vulnerabilities (enabled by default, language auto-detected)

Both are enabled by default. Gitleaks runs as part of the CI gate and blocks releases if secrets are detected. CodeQL runs after the CI gate and must succeed before source finalization or artifact publication. A disabled scan or one with no detected languages may be skipped; a failed or cancelled scan blocks publication.

Build Flow is designed for the Clean Flow workflow:

See the examples/ directory for complete workflow files:

• examples/app.yml — full orchestration (Node/Bun project)
• examples/minimal.yml — zero-config auto-detect
• examples/ci-only.yml — CI validation only
• examples/package-only.yml — package flow (Node.js project)
• examples/container-only.yml — container flow (C/C++ project)

• docs/architecture.md — design philosophy and orchestration model
• docs/roadmap.md — planned features and improvements

MIT