Agent releases

Package integration

The app package does not contain agent executables. Its agent-release.json pin records:

  • The agent version, Go compiler, protocol and capabilities.
  • The URL, size and SHA-256 hash of the Linux amd64 and arm64 binaries.

devpush-agent version --json reports a running agent's version, protocol, capabilities and platform.

Published binaries, checksums and the app package are attached to their matching GitHub Release.

Download behavior

Installers and update timers call the dashboard's download endpoint. The endpoint redirects to the pinned GitHub Release asset, and the installer verifies the pinned checksum. Object storage is not involved. If the pinned release is unavailable, installation readiness fails.

On Node, DEVPUSH_AGENT_BINARY_DIR overrides release downloads with trusted custom or offline builds. Both Linux architectures must be present. Checksums are calculated from the local files, and these files are not treated as official releases. Docker sets this directory to /repo/bin and serves the binaries built into the image. Workers always use the release.

Prepare a release

Set the application version in app/package.json. Use the compiler pinned in agent/go.mod and app/agent-release.json:

pnpm agent:release:prepare
pnpm agent:release:verify
pnpm agent:test

Preparation does the following:

  • Builds both Linux binaries with CGO and VCS/build-path stamping disabled.
  • Reads protocol and capability metadata from the real agent CLI.
  • Writes the pin, bin/agent-release.json and bin/SHA256SUMS.

Verification requires matching artifacts for both architectures. The Docker agent builder uses the same compiler. Commit the source changes and the generated pin together.

Publish

Create the release commit with its version, changelog and generated agent manifest, then push a matching v{version} tag. GitHub Actions handles publication; no manual npm publish is needed. The workflow:

  1. Builds with the pinned compiler.
  2. Runs both binaries, using QEMU for ARM64, and checks their metadata and hashes.
  3. Runs the app and agent checks.
  4. Attaches the binaries, manifest, checksums and app package tarball to a GitHub Release.
  5. Downloads the public agent assets and verifies their published checksums.
  6. Publishes the verified app package to npm through trusted publishing.

Tags with a prerelease suffix (for example, v1.0.0-beta.4) produce prereleases and do not replace the latest stable release.

The workflow rejects mismatched tags or pins and never overwrites an existing release. Dashboard deployment is separate.

If an installation has no local binaries, publish the release before you enroll servers. Don't rename the manifest URLs unless you rebuild the release artifacts.

npm authenticates GitHub Actions through OIDC, without a stored npm token. Prereleases use the beta npm tag; stable releases use latest. The package trusts hunvreus/devpush, workflow release.yml, with direct publishing enabled.