Skip to content

packages-github.md

Latest commit

 

History

History
145 lines (107 loc) · 5.53 KB

packages-github.md

File metadata and controls

145 lines (107 loc) · 5.53 KB
Raw

GitHub Binary Installer

Install CLI tools directly from GitHub Releases at runtime. Covers Go, Rust, shell, and other binary-distributed tools not available via apk / pip / npm.

Closes #741.

Install Syntax

github:owner/repo[@tag]

Examples:

  • github:cli/cli → latest release
  • github:jesseduffield/lazygit@v0.42.0 → specific version
  • github:sharkdp/fd@v9.0.0 → specific version with dot separator

How It Works

  1. Fetches release metadata from the GitHub API
  2. Auto-selects asset matching linux + current arch (amd64 / arm64)
  3. Streams download to a temp file, enforcing a max size cap
  4. Verifies SHA256 if the publisher ships checksums.txt / SHA256SUMS
  5. Validates ELF magic bytes + 64-bit class + machine matches runtime arch
  6. Extracts archive safely (tar.gz / zip / raw binary) with path-traversal + zip-bomb guards
  7. Installs to /app/data/.runtime/bin/ (prepended to $PATH)
  8. Persists a manifest for later listing + uninstall

Usage

Web UI

  1. Admin Settings → Packages page
  2. Scroll to GitHub Binaries section
  3. Enter owner/repo[@tag] or click Browse releases to pick a version
  4. Click Install

HTTP API

# Install
curl -X POST http://gateway/v1/packages/install \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"package": "github:jesseduffield/lazygit@v0.42.0"}'

# List installed (includes pip/npm/system + github)
curl http://gateway/v1/packages -H "Authorization: Bearer $ADMIN_TOKEN"

# Browse releases (picker UI uses this)
curl 'http://gateway/v1/packages/github-releases?repo=cli/cli&limit=10' \
  -H "Authorization: Bearer $VIEWER_TOKEN"

# Uninstall
curl -X POST http://gateway/v1/packages/uninstall \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"package": "github:lazygit"}'

Admin Configuration

All configuration is driven by environment variables — never place the token in config.json.

Env var Default Notes
GOCLAW_PACKAGES_GITHUB_TOKEN "" Optional PAT: rate 60/hr → 5000/hr + private repo access
GOCLAW_PACKAGES_MAX_ASSET_SIZE_MB 200 Applies to both download cap and 2× uncompressed cap
GOCLAW_PACKAGES_GITHUB_ALLOWED_ORGS "" Comma-separated allowlist (empty = all orgs allowed)
GOCLAW_PACKAGES_GITHUB_BIN_DIR /app/data/.runtime/bin Where extracted binaries land
GOCLAW_PACKAGES_GITHUB_MANIFEST {bin_dir}/../github-packages.json Manifest path

Token scopes:

  • public-only repos: no scopes required
  • private repos: repo
  • org-SSO-enforced repos: must be SSO-authorized PAT

Security

  • HTTPS-only downloads with SSRF host allowlist: github.com, api.github.com, objects.githubusercontent.com, release-assets.githubusercontent.com, codeload.github.com
  • Every redirect hop re-validated (blocks redirect-based host escape)
  • Literal IP hostnames (v4 / v6) always rejected (blocks cloud-metadata access)
  • SHA256 verification when publisher ships checksums.txt / SHA256SUMS (constant-time compare)
  • ELF magic + 64-bit class + machine-arch validation before chmod +x
  • Path-traversal prevention in archive extraction (rejects .., absolute, Windows drive, null byte)
  • Zip-bomb guard (cumulative uncompressed bytes capped at 2× max asset size)
  • Symlink / hardlink entries skipped, never written
  • Admin-only API + master-scope guard on install/uninstall
  • Picker endpoint /v1/packages/github-releases throttled per user (30 req/min, burst 10) to protect GitHub API quota; anonymous fallback keyed by remote IP. Response is 429 Too Many Requests with Retry-After: 60 when tripped.
  • Token never logged (startup log prints token_set=bool)

Troubleshooting

"glibc not found" / segfault on execution

GoClaw runs on Alpine Linux (musl libc). Many Go/Rust binaries target glibc.

Fix: pick a musl-compatible release asset. Look for names containing:

  • *-musl.tar.gz (explicit musl)
  • *-linux-static* (fully static)
  • Go binaries with CGO_ENABLED=0 typically work out of the box

Known-good musl releases:

  • ripgrep: ripgrep-*-x86_64-unknown-linux-musl.tar.gz
  • starship: starship-x86_64-unknown-linux-musl.tar.gz
  • gh: gh_*_linux_amd64.tar.gz (static)

"no matching asset found"

Asset naming doesn't fit the heuristic. Open the release page and confirm assets exist for linux + your arch. Workaround: file an upstream issue asking for standard linux_amd64 / linux_arm64 naming.

"arch mismatch"

Binary is amd64 but runtime is arm64 (or vice versa). Pick a release asset matching the host arch — the release picker UI filters automatically.

"rate limit exceeded"

Anonymous GitHub API is capped at 60 req/hr. Set GOCLAW_PACKAGES_GITHUB_TOKEN to bump to 5000/hr.

"checksum mismatch"

Hard-fail. Indicates tampered download or publisher re-signing without updating the release. Do not force-install; report upstream.

Limitations (Phase 1)

  • Linux-only (Lite/Desktop editions not yet supported)
  • Docker edition only (runtime dir /app/data/.runtime/bin)
  • Installs all top-level executables in an archive (no interactive picker if archive contains multiple binaries)
  • No version history / rollback — re-installing replaces in place
  • Global manifest (not per-tenant)

See Also