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.

Stable lock schema#

The first public Flog release uses stable flog.lock schema version 1. This is a one-time stability marker for the finalized prerelease schema-0 format, not a dependency-graph change and not a number that follows the Flog package version.

Flog release readiness is established by this repository's schema, lock, compatibility tests, and release checks. Downstream projects own their lock migrations and release gates; no particular downstream lock is a prerequisite for a Flog release. After the 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 Run artifacts do not publish a Repopack Release, promote stable or prerelease channels, or update the flog.run installer. Those remain explicit, guarded Release operations. The artifact-only Job cannot publish or promote a Release, modify the installer, or deploy anything.

See installer and release channels for rp release prepare/publish, explicit channel promotion, the website's strict adapter from public Repopack Release records to Flog's text manifests, and the canonical checksum-verifying installer. No Job Run is selected as latest implicitly and the website keeps no second mutable channel file.

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.

npm publication canary#

Repository tests use mock npm registries and never establish that current npm credentials, web authentication, OTP policy, scoped public access, or metadata propagation work live. Before publishing rcompat with a new Flog release, obtain explicit operator approval and publish a disposable version under a disposable scope. Verify the challenge flow, authenticated and anonymous metadata, artifact integrity, public visibility, and machine-readable summary before proceeding. Do not describe a release as live-npm validated when that canary was not approved and completed.