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.

The nhedger/setup-mago action installs the Mago PHP toolchain CLI on GitHub Actions runners. It runs on Node.js 24, supports Linux, macOS, and Windows, and can automatically detect the correct Mago version from your project’s composer.lock or composer.json before falling back to the latest published release.

​
Action Metadata

FieldValue
NameSetup Mago
Authornhedger
DescriptionSetup the Mago CLI in GitHub Actions
Runs usingnode24
Entry pointdist/index.mjs

​
Usage

Add the action to any workflow step. All inputs are optional in practice — the built-in github.token is used by default and the version is auto-detected from your project’s dependencies. 
- uses: nhedger/setup-mago@v1
  with:
    version: ""
    token: ${{ github.token }}
    working-directory: ""

​
Automatic version detection

Omit the version input to let the action resolve the Mago version from your project’s lock file or manifest: 
- name: Setup Mago
  uses: nhedger/setup-mago@v1

- name: Run Mago
  run: mago lint --reporting-format=github

​
Latest version

Explicitly request the latest stable release: 
- name: Setup Mago CLI
  uses: nhedger/setup-mago@v1
  with:
    version: latest

- name: Run Mago
  run: mago lint --reporting-format=github

​
Specific version

Pin to an exact release by supplying a bare semver string: 
- name: Setup Mago CLI
  uses: nhedger/setup-mago@v1
  with:
    version: 0.7.0

- name: Run Mago
  run: mago lint --reporting-format=github

​
Inputs

​
version
string
default:"\"\""
The version of the Mago CLI to install. Accepts:
  • "" (empty string, default) — triggers automatic version detection from your project’s composer.lock or composer.json; falls back to latest if no version is found
  • "latest" — installs the highest stable release
  • A bare semver string such as "0.7.0" — installs that exact release
Version strings must not include a v prefix (use "0.7.0", not "v0.7.0").
​
token
string
default:"${{ github.token }}"
required
A GitHub token used to authenticate API requests against the carthage-software/mago repository. The action uses the GitHub API to enumerate releases and locate the correct binary asset.The default ${{ github.token }} is sufficient for most workflows. For high-traffic repositories that may hit unauthenticated rate limits, supply a Personal Access Token (PAT):
token: ${{ secrets.MY_PAT }}
​
working-directory
string
default:"\"\""
The directory the action searches for composer.lock and composer.json when performing automatic version detection. Defaults to the current working directory when left empty.Use this input when your PHP project root is not at the repository root:
working-directory: "backend"
If the specified directory does not exist on the runner, the action emits a warning and falls back to the current working directory.

​
Version Resolution

When version is not explicitly set, the action resolves which Mago release to install by walking through the following steps in order:
1

Explicit version input

If the version input is non-empty, it is used directly. The value may be "latest" or a bare semver string (e.g. "0.7.0").
2

composer.lock

The action reads composer.lock in the working directory and searches packages-dev for a package whose name equals "carthage-software/mago". If found, the locked version string is used.
3

composer.json

If no lock file entry is found, the action reads composer.json and checks the require-dev key first, then require, for "carthage-software/mago".
  • If the value is an exact version, it is used directly.
  • If the value is a version range (e.g. "^0.7.0"), the action fetches all published Mago releases from the GitHub API and returns the highest version satisfying the range.
Using a version range in composer.json causes an additional GitHub API call to enumerate all releases. Pin to an exact version to avoid this and suppress the associated warning.
4

Fallback to latest

If none of the above steps yield a version, the action queries the GitHub API for all non-draft, non-prerelease Mago releases, sorts them in descending semver order, and installs the highest available stable release.

​
Download Behavior

Once the target version is resolved, the action downloads the correct pre-compiled binary from the carthage-software/mago GitHub Releases page.

​
Asset naming convention

Release assets follow this pattern: 
mago-{version}-{arch}-{os-target}.{ext}
The runner architecture is mapped before constructing the asset name:
Runner archAsset arch
x64x86_64
arm64aarch64
The full platform-specific patterns are:
PlatformAsset filename pattern
Linuxmago-{version}-{arch}-unknown-linux-musl.tar.gz
macOSmago-{version}-{arch}-apple-darwin.tar.gz
Windowsmago-{version}-{arch}-pc-windows-msvc.zip

​
Installation

After the archive is downloaded:
  1. .tar.gz archives (Linux and macOS) are extracted with extractTar.
  2. .zip archives (Windows) are extracted with extractZip.
  3. The extracted binary (mago on Linux/macOS, mago.exe on Windows) is set to permission mode 755.
  4. The directory containing the binary is added to PATH via @actions/core addPath, making mago available to all subsequent steps in the job.

Build docs developers (and LLMs) love

Get started for freeTalk to us