Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nhedger/setup-mago/llms.txt

Use this file to discover all available pages before exploring further.

Most failures with nhedger/setup-mago fall into a small set of known categories: GitHub API rate limiting, version strings that don’t match any release, misconfigured working directories, unexpected version auto-detection results, and PATH propagation issues. The entries below cover each of these in detail.
Symptom: The action fails with an error message containing:
You have exceeded the GitHub API rate limit.
Please try again in X seconds.
If you have not already done so, you can try authenticating calls to the GitHub API
by setting the `GITHUB_TOKEN` environment variable.
Cause: The action makes GitHub API calls to the carthage-software/mago repository to find the right release and locate the correct binary asset. If those requests are unauthenticated, GitHub enforces a lower per-IP rate limit, which can be exhausted in busy CI environments or when many workflow runs trigger simultaneously.The action detects this condition by checking whether the x-ratelimit-remaining response header equals "0" on a 403 response from the GitHub API.Fix: Ensure the token input is set. The default value, ${{ github.token }}, uses the built-in job token and provides a higher authenticated rate limit that is sufficient for most repositories:
- uses: nhedger/setup-mago@v1
  with:
    token: ${{ github.token }}
For high-traffic repositories or self-hosted runners that share a GitHub App token, supply a dedicated Personal Access Token (PAT) with at least public repository read access:
- uses: nhedger/setup-mago@v1
  with:
    token: ${{ secrets.MY_PAT }}
Alternatively, you can set the GITHUB_TOKEN environment variable directly on the step, as suggested by the error message itself:
- uses: nhedger/setup-mago@v1
  env:
    GITHUB_TOKEN: ${{ secrets.MY_PAT }}
Symptom: The action fails with the error:
Version X.Y.Z of the Mago CLI does not exist.
Cause: The version string passed to the version input — or resolved through auto-detection — does not match any release tag in the carthage-software/mago repository. This can happen when:
  • The version string includes a v prefix (e.g. "v0.7.0" instead of "0.7.0").
  • The version was mistyped.
  • A pre-release or draft version was specified that is not yet publicly available.
Fix: Check the Mago releases page for the exact tag name of the release you want. Version strings must be bare semver without a v prefix:
# ✅ Correct
- uses: nhedger/setup-mago@v1
  with:
    version: "0.7.0"

# ❌ Incorrect — will fail
- uses: nhedger/setup-mago@v1
  with:
    version: "v0.7.0"
Symptom: The action emits the following warning and may install an unexpected version of Mago:
The specified working directory does not exist. Using the current working directory instead.
Cause: The path provided to the working-directory input does not exist on the runner at the time the action runs. This causes the action to silently fall back to the current working directory when searching for composer.lock and composer.json, which may not contain the expected version information.Fix: Double-check that the path is correct relative to the repository root, and ensure that the actions/checkout step runs before nhedger/setup-mago:
steps:
  - uses: actions/checkout@v4          # Must run before setup-mago
  - uses: nhedger/setup-mago@v1
    with:
      working-directory: "backend"     # Must exist after checkout
Paths in working-directory are resolved against the runner’s current working directory, which is typically the repository root after a checkout step.
Symptom: Running mago --version in a subsequent step reports a different version than expected.Cause: When the version input is left empty, the action attempts auto-detection in this order: composer.lock → composer.json → latest. If neither file contains a carthage-software/mago entry — or if working-directory points to the wrong location — the action silently falls through to latest, which may not be the version your project requires.Fix:
  • Pin the version explicitly to eliminate any ambiguity: 
    - uses: nhedger/setup-mago@v1
  with:
    version: "0.7.0"
  • Commit your composer.lock and verify that carthage-software/mago is listed under packages-dev. The action reads the version field from that entry.
  • Set working-directory if the composer.lock file lives in a subdirectory: 
    - uses: nhedger/setup-mago@v1
  with:
    working-directory: "backend"
  • If you use a version range in composer.json (e.g. "^0.7.0"), be aware that the action installs the highest published release satisfying that range. Pin to an exact version to get deterministic installs.
Symptom: A step that runs after nhedger/setup-mago fails with:
mago: command not found
Cause: The action adds the directory containing the mago binary to PATH using @actions/core addPath. In rare cases this may not take effect if:
  • A subsequent step overrides PATH entirely via a custom env: block.
  • The action itself failed silently during extraction (check the action’s own step logs for errors).
Fix: First, inspect the output of the nhedger/setup-mago step for any extraction errors. If the step completed successfully, check that no later step is replacing PATH:
steps:
  - uses: nhedger/setup-mago@v1

  # ❌ This would shadow the PATH set by setup-mago
  - run: mago lint
    env:
      PATH: /custom/bin

  # ✅ Extend PATH instead of replacing it
  - run: mago lint
    env:
      PATH: /custom/bin:${{ env.PATH }}
You can verify the binary is on PATH by adding a diagnostic step immediately after setup:
which mago    # Linux / macOS
where mago    # Windows (cmd)

Build docs developers (and LLMs) love

Get started for freeTalk to us