Skip to content

doc: Add documentation of release manifests implementation #2359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dividedmind wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc: Add documentation of release manifests implementation #2359

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 105 additions & 0 deletions architecture/release-manifests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
---
layout: docs
title: Docs - Reference - Release Manifests
description: "Reference guide for AppMap release manifests used for version discovery and automated mirroring."
toc: true
reference: true
Comment on lines +2 to +6
Copy link

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page uses the docs-site frontmatter (layout: docs, reference: true), but it lives under architecture/. All other layout: docs content appears to live under docs/ (and reference pages under docs/reference/), so as-is this may not be routed/indexed with the rest of the docs/reference section. Consider moving the file under docs/reference/ and aligning its frontmatter (e.g., title: Docs - Reference + name/step if needed) so it’s included consistently in the docs build/navigation.

Suggested change
layout: docs
title: Docs - Reference - Release Manifests
description: "Reference guide for AppMap release manifests used for version discovery and automated mirroring."
toc: true
reference: true
title: Release Manifests
description: "Reference guide for AppMap release manifests used for version discovery and automated mirroring."
toc: true

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator Author

@dividedmind dividedmind Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, but docs/reference comes from appmap.io. I kept the front matter since it doesn't hurt and we might want to merge later, but for now I didn't want it to get mixed with imported content.

---

# Release Manifests

AppMap uses a manifest-based system for distributing its core binaries (`appmap` and `scanner`). This system provides a stable, machine-readable way for clients to discover new versions, verify asset integrity, and support advanced scenarios like version pinning and enterprise mirroring.

## Overview

The release manifests are JSON files hosted on a dedicated, orphan Git branch named `release-manifests` within the `appmap-js` repository. This branch serves as the single source of truth for all release metadata, independent of the `main` branch history.

## Two-Tier Manifest System

For every release, two types of manifests are generated:

1. **Versioned Manifest:** An immutable record of a specific release.
* Naming convention: `[tool]-v[version].json` (e.g., `appmap-v3.197.1.json`)
2. **Latest Pointer Manifest:** A "floating" manifest that always points to the most recent stable release.
* Naming convention: `[tool]-latest.json` (e.g., `appmap-latest.json`)

## Discovery URLs

Clients can discover releases by fetching manifests directly from GitHub's raw content service.

| Tool | Type | Discovery URL |
| :--- | :--- | :--- |
| **AppMap CLI** | Latest | `https://raw.githubusercontent.com/getappmap/appmap-js/release-manifests/appmap-latest.json` |
| **AppMap CLI** | Versioned | `https://raw.githubusercontent.com/getappmap/appmap-js/release-manifests/appmap-v<VERSION>.json` |
| **Scanner** | Latest | `https://raw.githubusercontent.com/getappmap/appmap-js/release-manifests/scanner-latest.json` |
| **Scanner** | Versioned | `https://raw.githubusercontent.com/getappmap/appmap-js/release-manifests/scanner-v<VERSION>.json` |

## Manifest Format

The manifest is a JSON object containing the release tag and an array of assets.

```json
{
"tag_name": "@appland/appmap-v3.197.1",
"assets": [
{
"name": "appmap-linux-x64",
"url": "https://github.com/getappmap/appmap-js/releases/download/%40appland/appmap-v3.197.1/appmap-linux-x64",
"digest": "sha256:405dbec9eb9e1bece9bc8acac56c33c5f404f7023f6df2918a770451c8173d25"
},
...
Copy link

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The JSON example is labeled as json but includes an ... placeholder, which makes it invalid JSON if someone copies it into tooling. Consider either providing a complete minimal manifest example (e.g., 2 assets) or changing the code fence to a non-JSON language/highlighter that makes it clear it’s illustrative (so consumers don’t treat it as a valid schema example).

Suggested change
...
{
"name": "appmap-darwin-arm64",
"url": "https://github.com/getappmap/appmap-js/releases/download/%40appland/appmap-v3.197.1/appmap-darwin-arm64",
"digest": "sha256:7d6f4b2e0b8a6b8a2d3c4e5f60718293a4b5c6d7e8f90123456789abcdef0123"
}

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator Author

@dividedmind dividedmind Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm pretty sure people can figure this one out.

]
}
```

### Fields

* **`tag_name`**: The exact GitHub release tag associated with this manifest.
* **`assets`**: An array of objects representing the available platform-specific binaries.
* **`name`**: The filename of the asset.
* **`url`**: The direct download URL for the asset.
* **`digest`**: The SHA256 checksum of the asset, prefixed with `sha256:`.

## Asset Naming Convention

The `assets` array contains the platform-specific binaries for the release. The `name` of each asset is strictly constructed using the following convention:

`[tool]-[os]-[arch][extension]`

* **`tool`**: The name of the distributed tool (`appmap` or `scanner`).
* **`os`**: The target operating system (`linux`, `macos`, or `win`).
* **`arch`**: The target architecture (`x64` or `arm64`).
* **`extension`**: Executable file extension, present only for Windows (`.exe`).

### Available Assets

For each release of a tool, the following standard set of binaries is generated and included in the manifest:

* `[tool]-linux-x64`
* `[tool]-linux-arm64`
* `[tool]-macos-x64`
* `[tool]-macos-arm64`
* `[tool]-win-x64.exe`

## Security & Integrity

The manifest system enhances security by providing a built-in mechanism for integrity verification.
Copy link

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There’s trailing whitespace at the end of this line. It’s minor, but it can create noisy diffs and some markdown linters will flag it; please trim it.

Suggested change
The manifest system enhances security by providing a built-in mechanism for integrity verification.
The manifest system enhances security by providing a built-in mechanism for integrity verification.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator Author

@dividedmind dividedmind Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, now you're just scratching the bottom of the barrel.


1. **Chain of Trust:** The manifest itself is generated and published by a trusted CI/CD process (GitHub Actions) within the official repository.
2. **Integrity Verification:** Clients MUST verify the downloaded binary against the `digest` provided in the manifest before execution.

## Enterprise Mirroring

This architecture is designed to simplify the process of mirroring AppMap assets within secure or air-gapped enterprise environments.

### Mirroring Workflow

1. **Fetch Manifest:** Download the official manifest from the `latest` discovery URL.
2. **Download & Verify:** For each asset listed in the manifest:
* Download the file from the provided `url`.
* Verify its integrity using the `digest`.
3. **Upload to Internal Host:** Upload the verified assets to your internal artifact repository or web server.
4. **Publish Internal Manifest:** Generate a modified version of the manifest where the `url` fields point to your internal locations, while **preserving the original `digest`** values.
5. **Configure Clients:** Point your AppMap extensions or CLI tools to use your internal manifest URL.

By preserving the original `digest`, you maintain the chain of trust even when the assets are hosted on internal infrastructure.
Loading