flog
Documentation menu

Release builds

Flog release artifacts are produced by the same scripts/release entry point locally and in the release container. The command requires an explicit version and full source commit:

make release VERSION=1.2.3 REVISION=0123456789abcdef0123456789abcdef01234567

The build runs formatting checks, vet, the complete test suite, and the race suite before compiling anything release-looking. It cross-compiles static Linux and macOS binaries for amd64 and arm64 with CGO_ENABLED=0, -trimpath, disabled VCS auto-stamping, and an injected version. On Linux/amd64 it executes the native binary and verifies flog --version before publishing the staged directory.

First public release lock schema gate#

Before the first public Flog release, deliberately advance the sole supported flog.lock schema from prerelease version 0 to stable version 1. Update the constant, parser/writer diagnostics, fixtures, and documentation together. This is a one-time stability marker, not a dependency-graph change and not a number that follows the Flog package version.

Coordinate the same change in Primate: regenerate or mechanically relabel its reviewed lock as appropriate for the final schema, prove that targets, importers, package snapshots, resolutions, integrity values, and canonical bytes apart from the schema number remain intended, then commit the Flog and Primate changes through their normal review tasks. Do not release while Primate still requires schema version 0. After that first release, increment the lock schema only for meaningful incompatible format changes.

When run from a Git checkout, the command also requires the supplied revision to equal HEAD and rejects tracked, staged, or untracked source changes. The container context excludes .git; Repopack instead supplies SOURCE_SHA from the exact immutable Job source revision.

Each deterministic archive is named flog-<version>-<os>-<arch>.tar.gz and contains:

  • flog, mode 0755;
  • LICENSE, mode 0644; and
  • BUILD-INFO.json, recording the version, exact 40-character source revision, operating system, and architecture.

SHA256SUMS is generated only after all four archives and the native smoke test succeed. The completed staging directory replaces the requested output only after validation; activation failure restores an earlier artifact set and removes partial staging data. Directory replacement uses two renames and can have a brief gap while the previous directory is held as a rollback backup.

Container build#

The root Containerfile is release-only. Repopack passes the Job Run's full, immutable source commit as SOURCE_SHA. Semantic releases additionally pass the declared, non-secret FLOG_VERSION build argument. If no semantic version is supplied outside the release Job, the container uses the explicit development version 0.0.0-dev.<12-character-source-prefix>.

A local equivalent is:

podman build \
  --build-arg SOURCE_SHA="$(git rev-parse HEAD)" \
  --build-arg FLOG_VERSION=1.2.3 \
  --output type=local,dest=container-output \
  .

The final image is scratch and contains only /release. The Repopack Job uses execution.artifact_only, so it extracts that path without starting a runtime container. The image cannot publish, promote a channel, or deploy anything.

Repopack Job#

rp.toml defines the local release builder using the committed root Containerfile. Repopack Job 1 uses the same Containerfile, enables artifact-only execution, and exposes only /release. Its current configuration tracks master, makes new Run artifacts public, and defines FLOG_VERSION with an empty default. Each accepted master advance therefore dispatches a build from that advance's immutable full SHA. With the empty version argument, the Containerfile labels those artifacts 0.0.0-dev.<12-character-source-prefix>.

Triggered Runs are public development builds, not semantic releases. To build an explicitly versioned release candidate or release, invoke the same Job manually from a full immutable source SHA and supply the semantic version:

rp job run 1 \
  --source <40-character-source-sha> \
  --build-arg FLOG_VERSION=1.2.3 \
  --attach

Before relying on automatic behavior, inspect the live Job configuration with rp --json job show 1; trigger, argument-default, and artifact-access settings are operational configuration rather than repository state.

Artifact access is snapshotted when each Run starts. Runs 1 and 2 were created with project-only access and remain project-only. Triggered Runs 3 and 4 were created after public access was enabled and are public. Later Runs use the access configured when they start; changing the Job does not retroactively change an existing Run.

After a successful run, authenticated project members can download its artifact set with:

rp job artifacts 1 <run-number> --output dist

For a public Run, anyone can list its immutable artifacts and obtain individual download URLs without authentication from:

https://repopack.com/api/v0/jobs/1/runs/<run-number>/artifacts?project=flog

Verify SHA256SUMS, the four archive names, each archive's three normalized entries, and the native Linux binary's version output. Automatic builds and public artifact hosting do not promote stable or prerelease channels and do not update the flog.run installer. Those remain explicit separate operations. The artifact-only Job cannot perform promotion, modify the installer, or deploy anything.

See installer and release channels for the immutable version manifest, explicit stable/prerelease promotion procedure, and canonical checksum-verifying installer. No Job Run is selected as latest implicitly.

The Job was exercised from an exact task commit with an explicit test version. Its downloaded checksum manifest verified all four archives; each archive had normalized metadata and contained only BUILD-INFO.json, LICENSE, and the executable. The native Linux/amd64 executable reported the injected version and its build information recorded the full requested source SHA.