Skip to content

Commit 7da8f9b

Browse files
dividedminddividedmind
committed
doc: Add documentation of release manifests implementation
This documents the implementation of release manifests (as designed in #2346) currently in place, with specific sections for consuming software (such as IDE plugins) and mirror operators (such as enterprise system administrators).
1 parent e93760d commit 7da8f9b

1 file changed

Lines changed: 105 additions & 0 deletions

File tree

‎architecture/release-manifests.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
layout: docs
3+
title: Docs - Reference - Release Manifests
4+
description: "Reference guide for AppMap release manifests used for version discovery and automated mirroring."
5+
toc: true
6+
reference: true
7+
---
8+
9+
# Release Manifests
10+
11+
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.
12+
13+
## Overview
14+
15+
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.
16+
17+
## Two-Tier Manifest System
18+
19+
For every release, two types of manifests are generated:
20+
21+
1. **Versioned Manifest:** An immutable record of a specific release.
22+
* Naming convention: `[tool]-v[version].json` (e.g., `appmap-v3.197.1.json`)
23+
2. **Latest Pointer Manifest:** A "floating" manifest that always points to the most recent stable release.
24+
* Naming convention: `[tool]-latest.json` (e.g., `appmap-latest.json`)
25+
26+
## Discovery URLs
27+
28+
Clients can discover releases by fetching manifests directly from GitHub's raw content service.
29+
30+
| Tool | Type | Discovery URL |
31+
| :--- | :--- | :--- |
32+
| **AppMap CLI** | Latest | `https://raw.githubusercontent.com/getappmap/appmap-js/release-manifests/appmap-latest.json` |
33+
| **AppMap CLI** | Versioned | `https://raw.githubusercontent.com/getappmap/appmap-js/release-manifests/appmap-v<VERSION>.json` |
34+
| **Scanner** | Latest | `https://raw.githubusercontent.com/getappmap/appmap-js/release-manifests/scanner-latest.json` |
35+
| **Scanner** | Versioned | `https://raw.githubusercontent.com/getappmap/appmap-js/release-manifests/scanner-v<VERSION>.json` |
36+
37+
## Manifest Format
38+
39+
The manifest is a JSON object containing the release tag and an array of assets.
40+
41+
```json
42+
{
43+
"tag_name": "@appland/appmap-v3.197.1",
44+
"assets": [
45+
{
46+
"name": "appmap-linux-x64",
47+
"url": "https://github.com/getappmap/appmap-js/releases/download/%40appland/appmap-v3.197.1/appmap-linux-x64",
48+
"digest": "sha256:405dbec9eb9e1bece9bc8acac56c33c5f404f7023f6df2918a770451c8173d25"
49+
},
50+
...
51+
]
52+
}
53+
```
54+
55+
### Fields
56+
57+
* **`tag_name`**: The exact GitHub release tag associated with this manifest.
58+
* **`assets`**: An array of objects representing the available platform-specific binaries.
59+
* **`name`**: The filename of the asset.
60+
* **`url`**: The direct download URL for the asset.
61+
* **`digest`**: The SHA256 checksum of the asset, prefixed with `sha256:`.
62+
63+
## Asset Naming Convention
64+
65+
The `assets` array contains the platform-specific binaries for the release. The `name` of each asset is strictly constructed using the following convention:
66+
67+
`[tool]-[os]-[arch][extension]`
68+
69+
* **`tool`**: The name of the distributed tool (`appmap` or `scanner`).
70+
* **`os`**: The target operating system (`linux`, `macos`, or `win`).
71+
* **`arch`**: The target architecture (`x64` or `arm64`).
72+
* **`extension`**: Executable file extension, present only for Windows (`.exe`).
73+
74+
### Available Assets
75+
76+
For each release of a tool, the following standard set of binaries is generated and included in the manifest:
77+
78+
* `[tool]-linux-x64`
79+
* `[tool]-linux-arm64`
80+
* `[tool]-macos-x64`
81+
* `[tool]-macos-arm64`
82+
* `[tool]-win-x64.exe`
83+
84+
## Security & Integrity
85+
86+
The manifest system enhances security by providing a built-in mechanism for integrity verification.
87+
88+
1. **Chain of Trust:** The manifest itself is generated and published by a trusted CI/CD process (GitHub Actions) within the official repository.
89+
2. **Integrity Verification:** Clients MUST verify the downloaded binary against the `digest` provided in the manifest before execution.
90+
91+
## Enterprise Mirroring
92+
93+
This architecture is designed to simplify the process of mirroring AppMap assets within secure or air-gapped enterprise environments.
94+
95+
### Mirroring Workflow
96+
97+
1. **Fetch Manifest:** Download the official manifest from the `latest` discovery URL.
98+
2. **Download & Verify:** For each asset listed in the manifest:
99+
* Download the file from the provided `url`.
100+
* Verify its integrity using the `digest`.
101+
3. **Upload to Internal Host:** Upload the verified assets to your internal artifact repository or web server.
102+
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.
103+
5. **Configure Clients:** Point your AppMap extensions or CLI tools to use your internal manifest URL.
104+
105+
By preserving the original `digest`, you maintain the chain of trust even when the assets are hosted on internal infrastructure.

0 commit comments

Comments
 (0)