Build

Getting Started

Purview.Build is consumed from a repository that owns its own configuration. The pipeline code lives here; consumers reference the composite action or one of the reusable workflows (or run the tool locally) and configure it with purview-build.json.

Two independent version axes

• The @ref suffix on a reusable-workflow or composite-action reference selects the workflow/action code: @main always runs the latest code, while a release tag (e.g. @v0.2.0) pins it for reproducibility. There is no @latest; the @ref is required for cross-repository references.
• The build-version input selects the installed Purview.Build tool. Omit it to install the latest stable tool from nuget.org or the organisation mirror (registered first), or pin an exact version (e.g. build-version: 0.2.0) for reproducibility.

Mixing a pinned old @ref with a floating build-version runs newer tool code through older workflow inputs.

Minimal repository setup (reusable workflow)

.github/workflows/pr.yml

name: PR
on:
  pull_request:
    branches: [main]
jobs:
  build:
    uses: purview-dev/build/.github/workflows/purview-build.yml@main
    # `build-version` is optional; when omitted, the latest stable Purview.Build
    # from nuget.org (or the organisation mirror, registered before the install)
    # is installed. Pin it (e.g. `build-version: 0.2.0`) for
    # reproducible builds.
    secrets: inherit

# .github/workflows/release.yml — release on main
name: Release
on:
  push:
    branches: [main]
concurrency:
  # Serialize releases; callers own concurrency (see Release Flow).
  group: release-${{ github.ref }}
  cancel-in-progress: false
jobs:
  release:
    uses: purview-dev/build/.github/workflows/purview-release.yml@main
    with:
      release-mode: NuGet
    secrets: inherit

For the main-as-head / release-branch model, point the release caller at the release branch instead:

on:
  push:
    branches: [release]

For the per-line release-branch model (Model C), where merging to main ships nothing and each release/<line> branch services its own line:

on:
  push:
    branches: ['release/**']
  workflow_dispatch:

jobs:
  release:
    uses: purview-dev/build/.github/workflows/purview-release.yml@main
    with:
      release-mode: NuGet
      eligibility-policy: TrunkReservesMinor
    secrets: inherit

The reusable release workflow asks the tool to evaluate eligibility and reads the verdict: an already-released version skips (the job finishes green), and a policy violation fails the job naming the rule. Merging main into release therefore releases exactly once. See Release Models.

The reusable workflows install the pinned CLI version (or the latest stable when build-version is omitted) from nuget.org; the organisation mirror is registered first, so a pinned version that NuGet.org has not indexed yet is installed from GitHub Packages. The consuming repository adds purview-build.json and a root package.json version. It does not need a copied pipeline project or package-source credentials.

Minimal repository setup (composite action)

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: purview-dev/build/.github/actions/purview-build@main
        env:
          Build__TestFilter: "/*/*/*/*[Category=Unit]"

The action’s build-version input is optional. When omitted, dotnet tool install resolves the latest stable Purview.Build from nuget.org or the organisation mirror (registered first); pass an exact version to pin the build, including one that is only on the mirror.

GitHub Packages

Restoring from the organisation’s GitHub Packages feed is automatic: the shared action and both reusable workflows register it (authenticated with GITHUB_TOKEN) before the repository’s first restore, so nothing in the repository needs to change.

Publishing to it is opt-in, directly from the repository:

1. Add permissions: { contents: write, packages: write } to .github/workflows/release.yml (a reusable workflow cannot elevate its caller, and declares no permissions of its own).
2. Set the repository variable PURVIEW_PUBLISH_GITHUB_PACKAGES=true.

The next eligible release then pushes the same packages to NuGet.org and GitHub Packages. No purview-build.json, project file, or nuget.config change. Package access for downstream repositories, retention, and failure semantics are documented in Release Flow.

Local use

dotnet new tool-manifest   # only if the repository has no .config/dotnet-tools.json
dotnet tool install Purview.Build
dotnet purview-build

Purview.Build is an ordinary .NET local tool: the manifest pins the version and dotnet tool restore installs it. Pass --version to pin explicitly; omit it to take the latest stable release.

Release a consuming repository

Releasing consists of bumping the version field in the repository’s root package.json and merging the validated pull request into the release head. The pipeline owns tagging (v{version}) and the GitHub release; maintainers must not push release tags manually. See Release Flow.

See also

• Architecture
• Configuration Reference
• Pipeline Modules
• Secrets and Environment Variables