Skip to content

Asset index

asset_index.json is portable resolution metadata for GitHub release assets. It helps ixt reconstruct download URLs without calling api.github.com when the required asset shape is already known.

It is deliberately narrow:

  • not a lockfile;
  • not a checksum file;
  • not a security policy;
  • not a registry of short names;
  • not required for normal installs.

Without an asset index, ixt still works through the live GitHub Releases API and the normal heuristic asset scorer.

User Workflow

Use this when a CI warmup job, developer machine, or shared cache has already resolved binary assets and you want to replay that metadata later.

ixt asset-index export > asset_index.json
export IXT_ASSET_INDEX="$PWD/asset_index.json"

For strict pipelines that must not call the GitHub Releases API:

export IXT_ASSET_INDEX="$PWD/asset_index.json"
export IXT_GITHUB_API=never
ixt tool apply

IXT_GITHUB_API=never disables only api.github.com. It still allows:

  • github.com/owner/repo/releases/latest redirects to discover the latest tag;
  • direct github.com/owner/repo/releases/download/... probes and downloads;
  • exact URLs already present in asset_index.json.

If no preloaded pattern, exact asset, learned cache entry, or indexed download can resolve the current platform, ixt fails explicitly instead of silently falling back to the API.

Priority

For GitHub binary resolution, ixt checks sources in this order:

  1. explicit asset_pattern from the CLI or ixt.toml;
  2. files listed in IXT_ASSET_INDEX;
  3. $IXT_HOME/config/asset_index.json;
  4. the built-in src/ixt/data/asset_index.json;
  5. learned local cache metadata (asset_patterns.json, downloads.json);
  6. GitHub Releases API, when allowed.

Multiple files in IXT_ASSET_INDEX are separated with ;:

export IXT_ASSET_INDEX="/org/asset_index.json;/project/asset_index.json"

Files are read left to right, and later entries override earlier entries for the same canonical spec.

Remote http:// or https:// URLs in IXT_ASSET_INDEX are reserved for a future version and are ignored today.

Format

Top-level keys are canonical GitHub specs:

{
  "@gh:BurntSushi/ripgrep": {
    "names": ["ripgrep"],
    "patterns": {
      "linux/x86_64": "ripgrep-{tag}-x86_64-unknown-linux-musl.tar.gz",
      "macos/aarch64": "ripgrep-{tag}-aarch64-apple-darwin.tar.gz"
    },
    "assets": {
      "linux/x86_64": {
        "tag": "14.1.1",
        "asset": "ripgrep-14.1.1-x86_64-unknown-linux-musl.tar.gz",
        "url": "https://github.com/BurntSushi/ripgrep/releases/download/14.1.1/ripgrep-14.1.1-x86_64-unknown-linux-musl.tar.gz"
      }
    }
  }
}

Rules:

  • names is optional and only links the entry back to registry aliases;
  • patterns maps os/arch to an asset-name template;
  • assets maps os/arch to exact known assets;
  • an entry must contain patterns, assets, or both.

The initial portable platform vocabulary is:

  • linux/x86_64
  • linux/aarch64
  • macos/x86_64
  • macos/aarch64

Maintainer Workflow

The built-in asset index is generated from the bundled registry by a maintainer task. This deliberately calls GitHub Releases during generation, so it is not a pre-commit hook and not a scheduled CI requirement.

task asset-index:generate
task asset-index:check

asset-index:generate rewrites src/ixt/data/asset_index.json. asset-index:check regenerates to /tmp/ixt-asset_index.json and diffs it against the committed file.

Use these tasks when the bundled registry changes or before a release where you want to refresh the built-in patterns. Pattern entries using {tag} or {version} remain useful across upstream releases as long as the project keeps the same asset naming convention.

Limits

  • GitHub release assets are indexed; GitLab specs are skipped.
  • --all-platforms only has multi-platform meaning with --from-registry. Cache-based export only knows the current platform and warns otherwise.
  • asset_index.json optimizes resolution. It does not pin versions and does not prove asset integrity.
  • IXT_GITHUB_API=never is not the future lockfile strict mode. It controls only the GitHub API fallback.

Debugging

Use verbose resolver output to see which path was used:

ixt -v tool install ripgrep
ixt -vv tool upgrade --all

The summary separates GitHub latest redirects from real GitHub API calls. With -vv, resolver traces include asset-index hits, learned-cache hits, direct URL probes, and API fallback decisions.