Skip to content

Agent release format

Agent releases are published in their own repositories, independently of MeshCentral. Each release contains the binaries and a manifest describing them. MeshCentral selects its default files through agents/agent-defaults.json. Publishing an agent release does not change those defaults or deploy agents.

Tags and prereleases

For native MeshAgent builds, use version tags such as 1.2.0 for stable releases and 1.2.0-beta.1 for beta builds. A v prefix is also accepted. Agent and MeshCentral version numbers do not need to match. The release tag is separate from the agent's embedded build date and commit hash.

Mark beta releases as prereleases in GitHub. Keep beta files out of the default manifest until they are approved for general use.

Do not replace published assets or move published tags. Changed binaries, including signing changes, need a new release.

Release assets

Publish each unconfigured binary as a separate raw asset, using its established filename, such as meshagent_x86-64 or MeshService64.exe. Preserve names that distinguish libc, CPU architecture and KVM support. Default downloads require raw files, not archives.

Releases do not need a checksum file. GitHub records a SHA256 digest for each asset, and MeshCentral pins the size and SHA384 of each default file in its own agents/agent-defaults.json. Files signed or replaced in a draft before publishing need no extra step.

Publishing workflow

In MeshAgent:

  1. Push a version tag at the commit to release. This starts Agent Release. Manual runs must select an existing version tag, and the workflow must be present on the default branch.
  2. Wait for the Linux, Windows, macOS and FreeBSD builds to finish. All must succeed before the workflow creates a draft with the binaries and manifest.
  3. Review the assets and release notes, then publish the draft. Tags with a suffix, such as 1.2.0-beta.1, create prerelease drafts.

MeshCentralAndroidAgent's Android Release workflow requires a numeric tag such as 1.0.24 matching the app's versionName, without a v prefix or prerelease suffix. It requires the existing Android signing secrets and creates a draft with meshagent_android.apk, retaining the versioned APK and AAB downloads. To publish an Android testing release, mark that draft as a prerelease before publishing. Keep the signing key used by existing installations.

The Android APK supplies the server's installer download. Android app updates use Google Play or APK installation.

Neither workflow overwrites an existing release. These workflows use their repository's GITHUB_TOKEN to create the draft. Public release downloads in MeshCentral do not require a GitHub token.

Selecting MeshCentral defaults

After publishing and checking compatibility, download the approved files from the release and generate their entries from the MeshCentral repository root. The values below are examples:

node agents/release-manifest.js --repository Ylianst/MeshAgent --tag 1.2.0 \
  staging/meshagent_x86-64 staging/meshagent_x86

Add the output's release entries to agents/agent-defaults.json. The format is:

{
  "schemaVersion": 1,
  "releases": [
    {
      "repository": "owner/repository",
      "tag": "exact-release-tag",
      "files": [
        {
          "filename": "meshagent_x86-64",
          "asset": "meshagent_x86-64",
          "size": <byte length>,
          "sha384": "<96 lowercase hexadecimal characters>"
        }
      ]
    }
  ]
}

filename is the name MeshCentral expects. asset is the name attached to the GitHub release; the two names can differ. Each filename can appear only once in a manifest. MeshCentral ignores files it has no agent type for and names them in the log, so a release can carry agents that older servers do not know. The SHA384 covers the complete file, which can differ from MeshCentral's native update hash.

The manifest can combine files from different repositories and versions, so older platforms can keep their existing builds. Default downloads require public releases and use the exact tags and hashes in the manifest. Changing the defaults changes the installers and the files offered to agents that update.

Before publishing MeshCentral, its release workflow checks package contents and downloads every pinned asset to verify its size and SHA384. Missing assets, failed downloads or checksum mismatches stop the release. Agent releases can be published without a MeshCentral release.

Migrating the bundled files

The migration workflows preserve the binaries previously bundled with MeshCentral 1.2.6, including the September testing builds. They verify the original files against recorded hashes without rebuilding or signing them. The workflows must be present on their repositories' default branches before running them manually.

  1. Run Migrate bundled agents in MeshAgent with the legacy profile, and Migrate bundled Android agent in MeshCentralAndroidAgent. Each workflow creates a draft legacy-1.2.6 release.
  2. Review and publish both drafts before publishing a MeshCentral package that uses them as defaults. Keep migration releases excluded from GitHub's latest-release selection.
  3. To publish the September files for testing, run the native workflow with the september profile. Publish its testing-sep2026 draft as a prerelease and leave these files out of the default manifest. New beta builds use version tags such as 1.2.0-beta.1.

Migration tags identify the packaging commit. Each agent repository's .github/release-migration.json records the source repository, archive commit, original paths and hashes of the preserved files.

For forks, publish in the fork repositories and update the repository fields in MeshCentral's default manifest before distribution.

See Agent downloads for server configuration, offline installation and download recovery.