Setup Amp

GitHub Action to install Amp in CI via ampup

uses: edgeandnode/setup-amp@v1

Explore the docs · Report Bug · Request Feature

Install Amp with version pinning and caching. After the action runs, ampup itself, ampd, ampctl, and ampsql (when included in the release) are on PATH for all subsequent steps.

This action is a thin composite wrapper around the same install path the documentation recommends (https://ampup.sh/install followed by ampup install), so CI behaves exactly like a local install.

Example workflows

Install Amp and use it in later steps:

name: test

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Install Amp
        uses: edgeandnode/setup-amp@v1
        with:
          version: stable

      - name: Run ampd
        run: ampd --version

Install only ampup (no Amp version), and manage versions yourself in later steps — this needs no GitHub token:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Install ampup
        uses: edgeandnode/setup-amp@v1
        with:
          version: none

      - name: Install Amp with ampup
        run: ampup install v0.0.36
        env:
          GITHUB_TOKEN: ${{ secrets.AMP_GITHUB_TOKEN }}

Inputs

Input	Default	Description
version	stable	Amp version to install: stable, latest (alias for stable), nightly, an explicit release tag (e.g. v0.0.36), or none to install only ampup.
github-token	${{ github.token }}	Token used to resolve versions and download release assets. See GitHub token.
cache	true	Whether to cache the ampup-managed install directory across runs.
cache-key	(derived)	Custom cache key, replacing the automatic setup-amp-<platform>-<arch>-<resolved version> key.
cache-restore-keys	(none)	Additional cache restore keys (one per line) for partial cache restores.

Outputs

Output	Description
version	The installed Amp version as a release tag (e.g. v0.0.36), after resolving stable/nightly.
cache-hit	Whether the install directory was restored from an exact cache key match.

Version pinning

The version input is resolved to a concrete release tag of edgeandnode/amp before installing:

• stable (default) and latest resolve to the latest stable release.
• nightly resolves to the most recent nightly-* release that has downloadable assets (nightlies are sometimes published before their binaries land).
• An explicit tag (e.g. v0.0.36 or nightly-425b88a) is validated against the repository's releases and installed as-is.
• none installs only ampup itself — no Amp version is resolved, downloaded, or cached, and no GitHub token is required. Use this when a later step manages versions directly (e.g. ampup install, ampup build).

The resolved tag is exposed as the version output and used as part of the cache key, so stable and nightly caches roll over automatically when a new release is published. Unknown versions and unsupported runner platforms fail the step with a clear error message.

GitHub token

The action queries the GitHub releases API of edgeandnode/amp and lets ampup download the release assets.

While the Amp repository is private, the default workflow token only works for workflows running inside edgeandnode/amp itself. Workflows in any other repository must pass a GitHub App or fine-grained PAT token with read access to edgeandnode/amp:

- uses: edgeandnode/setup-amp@v1
  with:
    github-token: ${{ secrets.AMP_GITHUB_TOKEN }}

Once the repository is public, the default token is sufficient (it is still recommended, to avoid anonymous API rate limits).

Note on credential flow: when installing from the default repository, ampup fetches release metadata through the ampup.sh proxy (operated by Edge & Node) and attaches the token to those requests too — so the token you pass is sent to ampup.sh in addition to api.github.com. Prefer a short-lived, minimally-scoped token (a GitHub App installation token or fine-grained PAT restricted to edgeandnode/amp contents read).

Caching

With cache: true (the default), the ampup-managed install directory (~/.amp: the ampup binary, installed versions, and the active-version state) is cached with actions/cache:

• The cache is restored before installing; on an exact key match the install is an offline no-op.
• The cache is saved by a post step at the end of a successful job, keyed on setup-amp-<repo>-<platform>-<arch>-<resolved version> (the source repository is part of the key, so an AMP_REPO fork override never restores binaries built from a different repository).
• cache-key replaces the automatic key entirely; cache-restore-keys adds fallback prefixes for partial restores. After any restore, the action still runs ampup install <resolved version>, so a stale cache can never pin the wrong version.

Set cache: false to disable caching entirely.

Supported platforms

Runner	Supported
Linux x86_64 (ubuntu-latest)	✅
Linux aarch64 (ubuntu-24.04-arm)	✅
macOS aarch64 (macos-latest)	✅
macOS x86_64 (macos-15-intel)	✅
Windows	❌ (fails with a clear error)

Advanced configuration

The action honors two environment variables:

• AMP_DIR: overrides the install directory (default: $XDG_CONFIG_HOME/.amp or $HOME/.amp), the same way ampup does. The action exports the resolved value to the job environment for subsequent steps.
• AMP_REPO: overrides the source repository (default: edgeandnode/amp), useful for testing against forks. Note that this variable is interpreted by the action only (it resolves versions against it and passes it to ampup install --repo); ampup itself does not read it, so direct ampup invocations in later steps need an explicit --repo flag.

Installable components (e.g. PostgreSQL for ampd solo, ADBC drivers) will be supported through this action once ampup ships component management.

Contributing

See CONTRIBUTING.md for the development workflow (linting, script extraction and dry-runs, CI layout) and the release process.

Releasing

Releases use immutable vMAJOR.MINOR.PATCH tags. Publishing a release moves the vMAJOR and vMAJOR.MINOR tags automatically (see .github/workflows/release.yml), so users can choose their pinning granularity:

- uses: edgeandnode/setup-amp@v1        # moving major tag
- uses: edgeandnode/setup-amp@v1.0.0    # immutable release tag
- uses: edgeandnode/setup-amp@<sha>     # immutable commit

License

Business Source License 1.1 — see LICENSE.