Skip to content

usage.md

Latest commit

 

History

History
325 lines (265 loc) · 10.7 KB

usage.md

File metadata and controls

325 lines (265 loc) · 10.7 KB
Raw

Usage Guide

Detailed reference for all workflows and actions in this pipeline library.

Prerequisites

  • Repository must be in the Leberkas-org GitHub organization (or fork this repo for your own org)
  • Copy starter files from starter/ directory to your repo root
  • Commit messages must follow Conventional Commits format

Workflow Reference

build-test.yml

Build and test a .NET solution with optional code coverage.

Usage:

jobs:
  build:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/build-test.yml@v0
    with:
      solution-path: MyProject.slnx

Inputs:

Input Required Default Description
dotnet-version-file no ./src/global.json Path to global.json
solution-path no *.slnx Path to .slnx or .sln (relative to working-directory)
working-directory no ./src Working directory for build and test commands (should contain global.json)
build-configuration no Release Build configuration
coverage-enabled no true Generate coverage reports
test-result-directory no testresults Test output directory
extra-apt-packages no "" Extra apt packages (e.g. libmsquic)
cache-enabled no true Enable NuGet dependency caching
sonar-enabled no false Enable SonarCloud analysis
sonar-project-key no "" SonarCloud project key
sonar-organization no "" SonarCloud organization

Secrets:

Secret Required Description
sonar-token if sonar-enabled SonarCloud authentication token

Usage with extra apt packages:

jobs:
  build:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/build-test.yml@v0
    with:
      solution-path: TurboHTTP.slnx
      extra-apt-packages: libmsquic

Usage with SonarCloud:

jobs:
  build:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/build-test.yml@v0
    with:
      solution-path: MyProject.slnx
      sonar-enabled: true
      sonar-project-key: my-org_my-project
      sonar-organization: my-org
    secrets:
      sonar-token: ${{ secrets.SONAR_TOKEN }}

Usage with custom working directory:

jobs:
  build:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/build-test.yml@v0
    with:
      solution-path: MyProject.slnx
      working-directory: ./custom/path
      dotnet-version-file: ./custom/path/global.json

nuget-publish.yml

Pack and publish NuGet packages. Typically called by release.yml, not directly.

Inputs:

Input Required Default Description
dotnet-version-file no ./src/global.json Path to global.json
solution-path yes — Path to .slnx or .sln (relative to working-directory)
working-directory no ./src Working directory for build and pack commands (should contain global.json)
version yes — SemVer version
tag-name yes — Git tag for release attachment
package-output-directory no ./packages Output directory
nuget-source no https://api.nuget.org/v3/index.json NuGet feed URL
trusted-publishing no false Use OIDC trusted publishing instead of API key
cache-enabled no true Enable NuGet dependency caching
cache-dependency-path no **/packages.lock.json Glob pattern for NuGet cache key

Secrets:

Secret Required Description
nuget-api-key if not trusted-publishing NuGet.org API key
nuget-username if trusted-publishing NuGet.org username

docker-build-push.yml

Build and push Docker images. Typically called by release.yml, not directly.

Inputs:

Input Required Default Description
dockerfile-path no ./Dockerfile Path to Dockerfile
context no . Docker build context
image-name yes — Image name
registry no ghcr.io Registry URL
version yes — SemVer version
platforms no linux/amd64 Target platforms
build-args no "" Build arguments

Secrets:

Secret Required Description
registry-username yes Registry username
registry-password yes Registry password/token

release.yml

Orchestrates release-please, NuGet publishing, Docker publishing, and docs deployment.

Usage (NuGet with API key):

jobs:
  release:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/release.yml@v0
    with:
      nuget-publish: true
      solution-path: MyProject.slnx
    secrets:
      nuget-api-key: ${{ secrets.NUGET_SECRET }}

Usage (NuGet with trusted publishing):

jobs:
  release:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/release.yml@v0
    with:
      nuget-publish: true
      nuget-trusted-publishing: true
      solution-path: MyProject.slnx
    secrets:
      nuget-username: ${{ secrets.NUGET_USER }}

Usage (Docker only):

jobs:
  release:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/release.yml@v0
    with:
      docker-publish: true
      docker-image-name: my-service
      docker-registry: ghcr.io
      dockerfile-path: ./src/MyService/Dockerfile
    secrets:
      registry-username: ${{ github.actor }}
      registry-password: ${{ secrets.GITHUB_TOKEN }}

Usage (NuGet + Docker):

jobs:
  release:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/release.yml@v0
    with:
      nuget-publish: true
      docker-publish: true
      solution-path: MyProject.slnx
      docker-image-name: my-service
    secrets:
      nuget-api-key: ${{ secrets.NUGET_SECRET }}
      registry-username: ${{ github.actor }}
      registry-password: ${{ secrets.GITHUB_TOKEN }}

Inputs:

Input Required Default Description
nuget-publish no false Enable NuGet publishing
nuget-trusted-publishing no false Use OIDC trusted publishing
docker-publish no false Enable Docker publishing
docs-deploy no false Enable docs deploy on release
dotnet-version-file no ./src/global.json Path to global.json
solution-path no "" Path to .slnx/.sln (relative to working-directory)
working-directory no ./src Working directory for build commands (should contain global.json)
dockerfile-path no ./Dockerfile Path to Dockerfile
docker-registry no ghcr.io Container registry
docker-image-name no "" Docker image name
docker-platforms no linux/amd64 Target platforms
docs-directory no docs Docs working directory
docs-build-command no npm run build Build script
docs-output-directory no docs/.vitepress/dist Built site path
cache-enabled no true Enable NuGet dependency caching
cache-dependency-path no **/packages.lock.json Glob pattern for NuGet cache key

Secrets:

Secret Required Description
nuget-api-key if nuget-publish without trusted publishing NuGet API key
nuget-username if nuget-trusted-publishing NuGet.org username
registry-username if docker-publish Registry username
registry-password if docker-publish Registry password

commitlint.yml

Validate PR titles and commit messages.

Usage:

jobs:
  lint:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/commitlint.yml@v0

Inputs:

Input Required Default Description
commitlint-config-file no commitlint.config.mjs Path to commitlint config

docs-build.yml

Build a VitePress (or other Node.js-based) docs site on PRs for validation.

Usage:

jobs:
  docs:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/docs-build.yml@v0

Inputs:

Input Required Default Description
docs-directory no docs Working directory containing package.json
node-version no 22 Node.js version
build-command no npm run build Build script

docs-deploy.yml

Build a docs site and deploy to GitHub Pages. Typically called by release.yml, not directly.

Inputs:

Input Required Default Description
docs-directory no docs Working directory containing package.json
node-version no 22 Node.js version
build-command no npm run build Build script
output-directory no docs/.vitepress/dist Path to built site output

release.yml — Docs Deploy Option

Add docs-deploy: true to the release workflow to deploy docs on each release:

jobs:
  release:
    uses: Leberkas-org/template.pipeline.github/.github/workflows/release.yml@v0
    with:
      nuget-publish: true
      docs-deploy: true
      solution-path: MyProject.slnx
    secrets:
      nuget-api-key: ${{ secrets.NUGET_SECRET }}

Starter Files

Copy these from starter/ to your repo root:

File Purpose
commitlint.config.mjs Enforces Conventional Commits format
release-please-config.json Configures release-please changelog sections
.release-please-manifest.json Tracks current version (start at 0.1.0)

Versioning

This library uses Git tags for versioning (v0, v0.3.0).

  • Pin to major tag for stability: @v0
  • Pin to exact tag for reproducibility: @v0.3.0
  • Pin to branch for development: @main

Commit Convention

Consumer repos must use Conventional Commits:

Prefix Version Bump Example
feat: Minor feat: add user export endpoint
fix: Patch fix: correct date parsing in reports
perf: Patch perf: cache database queries
feat!: or BREAKING CHANGE: Major feat!: redesign auth API
docs:, chore:, test:, ci:, build: None docs: update API reference
deps: None deps: bump Akka to 1.5.70

Constraints

  • Nesting limit: GitHub allows max 4 levels of workflow_call. Consumer → release.yml → nuget/docker is 3 levels. Consumers have 1 more level available.
  • Secrets: Must be explicitly passed at each level. Use secrets: inherit only within the same organization.
  • Path filters: Add paths-ignore in your consumer workflow, not in the reusable workflows.