go-devops/docs/publishers.md

title	description
Release Publishers	Release orchestration, changelog generation, eight publisher backends, and .core/release.yaml configuration.

Release Publishers

The release/ package orchestrates the full release pipeline: version detection from git tags, changelog generation from commit history, and publishing to multiple distribution targets. Configuration lives in .core/release.yaml.

How it works

The build and release stages are deliberately separate, allowing CI pipelines to build once and publish to multiple targets independently.

core build           # 1. Compile artefacts into dist/
core build release   # 2. Version + changelog + publish (requires --we-are-go-for-launch)

The release pipeline runs these steps:

1. Resolve version — from git tags on HEAD, or increment the latest tag's patch version.
2. Scan artefacts — find pre-built files in dist/.
3. Generate changelog — parse conventional commit messages since the previous tag.
4. Publish — iterate configured publishers, calling Publisher.Publish() on each.

Version detection

DetermineVersion(dir) checks in priority order:

1. Git tag on HEAD (exact match).
2. Most recent tag with patch version incremented (e.g. v1.2.3 becomes v1.2.4).
3. Default v0.0.1 if no tags exist.

Pre-release suffixes are stripped when incrementing.

Changelog generation

Generate() in changelog.go reads the git log since the previous tag and groups entries by conventional commit prefix:

Prefix	Section
feat:	Features
fix:	Bug Fixes
perf:	Performance
refactor:	Refactoring

The changelog section in release.yaml controls which prefixes are included or excluded.

Publisher interface

All publishers implement:

type Publisher interface {
    Name() string
    Publish(ctx context.Context, release *Release, pubCfg PublisherConfig,
            relCfg ReleaseConfig, dryRun bool) error
}

When dryRun is true, publishers log what they would do without making external calls.

Publisher backends

GitHub Releases (github.go)

Creates a GitHub Release via the API and uploads artefact files as release assets.

publishers:
  - type: github
    draft: false
    prerelease: false

Docker (docker.go)

Runs docker buildx build --push to a configured container registry. Supports multi-platform images.

publishers:
  - type: docker
    registry: ghcr.io
    image: myorg/myapp

Homebrew (homebrew.go)

Generates a Ruby formula file and commits it to a Homebrew tap repository.

publishers:
  - type: homebrew
    tap: myorg/homebrew-tap
    formula: myapp

npm (npm.go)

Runs npm publish to the npm registry.

publishers:
  - type: npm
    registry: https://registry.npmjs.org

AUR (aur.go)

Generates a PKGBUILD and .SRCINFO, then pushes to the Arch User Repository git remote.

publishers:
  - type: aur
    package: myapp

Scoop (scoop.go)

Generates a JSON manifest and commits it to a Scoop bucket repository.

publishers:
  - type: scoop
    bucket: myorg/scoop-bucket

Chocolatey (chocolatey.go)

Generates a .nuspec file and calls choco push.

publishers:
  - type: chocolatey
    package: myapp

LinuxKit (linuxkit.go)

Builds and uploads LinuxKit multi-format VM images (ISO, qcow2, raw, VMDK).

publishers:
  - type: linuxkit
    formats:
      - qcow2
      - iso

.core/release.yaml reference

version: 1

project:
  name: my-app
  repository: myorg/my-app     # GitHub owner/repo (auto-detected from git remote)

changelog:
  include:                      # Conventional commit types to include
    - feat
    - fix
    - perf
    - refactor
  exclude:                      # Types to exclude
    - chore
    - docs
    - style
    - test
    - ci

publishers:                     # List of publisher configurations
  - type: github
    draft: false
    prerelease: false

# Optional: SDK generation (see sdk-generation.md)
sdk:
  spec: openapi.yaml
  languages: [typescript, python, go, php]
  output: sdk
  diff:
    enabled: true
    fail_on_breaking: false

Field reference

Field	Type	Description
version	int	Config schema version (always 1)
project.name	string	Project name
project.repository	string	Git remote in owner/repo format
changelog.include	[]string	Conventional commit prefixes to include in the changelog
changelog.exclude	[]string	Prefixes to exclude
publishers	[]PublisherConfig	List of publisher configurations
publishers[].type	string	Publisher type: github, docker, homebrew, npm, aur, scoop, chocolatey, linuxkit
sdk	SDKConfig	Optional SDK generation settings (see SDK Generation)

Generated configuration

core setup repo generates a default release.yaml with sensible defaults for the detected project type:

• Go/Wails projects get changelog rules for feat, fix, perf, refactor and a GitHub publisher.
• PHP projects get feat, fix, perf and a GitHub publisher.
• Other projects get feat, fix and a GitHub publisher.

Adding a new publisher

1. Create release/publishers/myplatform.go.
2. Implement Publisher:
   • Name() returns the platform name (matches the type field in release.yaml).
   • Publish(ctx, release, pubCfg, relCfg, dryRun) performs the publication. When dryRun is true, log intent and return nil.
3. Register the publisher in release/config.go.
4. Write release/publishers/myplatform_test.go with dry-run tests. Verify command arguments, generated file content, and interface compliance.