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.

When no explicit version is provided, Setup Mago automatically determines the correct Mago CLI version to install by inspecting your project’s Composer files. This means the version running in CI always reflects the version your project actually depends on — without any manual version management in your workflow file. The resolution follows a strict priority chain, moving from the most precise signal to the most permissive fallback.

​
Resolution Priority Chain

1

Explicit version input

If the version input is set to a non-empty string, that value is used immediately and no Composer files are read. This takes precedence over everything else.
- uses: nhedger/setup-mago@v1
  with:
    version: "0.7.0"   # used directly — Composer files are not consulted
Passing version: latest also qualifies as an explicit value and skips file detection, instructing the action to fetch and install the newest stable GitHub release.
2

Version from composer.lock

If no version input is given, the action reads composer.lock from the working directory and searches the packages-dev array for an entry whose name field equals carthage-software/mago. When found, the version field of that entry is used.
{
  "packages-dev": [
    {
      "name": "carthage-software/mago",
      "version": "0.6.2",
      "source": {
        "type": "git",
        "url": "https://github.com/carthage-software/mago.git",
        "reference": "9b59274a619c7ff1b7e77e6b525c22bf8a632ed9"
      }
    }
  ]
}
Only packages-dev is searched in composer.lock. If carthage-software/mago appears only in packages (the non-dev section), it will not be found at this step and resolution continues to the next step.
If composer.lock does not exist, is not valid JSON, or does not contain a matching entry, this step returns nothing and resolution moves on.
3

Version from composer.json

When no version can be resolved from composer.lock, the action falls back to reading composer.json from the working directory. It checks the require-dev field first, then require, looking for the key carthage-software/mago.
{
  "require-dev": {
    "carthage-software/mago": "0.6.2"
  }
}
Exact versions — if the value is a valid semver string (e.g. "0.6.2"), it is used directly.Version ranges — if the value is a valid semver range expression (e.g. "^0.6.0", ">=0.5.0 <1.0.0"), the action fetches all stable releases of carthage-software/mago from the GitHub API and selects the highest version that satisfies the range using semver.maxSatisfying.
Using a version range in composer.json triggers a warning during the action run:
Mago version specified as a range. — The version of mago detected in your composer.json file is specified as a range. We’ll install the latest version that satisfies the range. You can pin the version to a specific release to avoid this warning.
Pin carthage-software/mago to an exact version in composer.json (or rely on the exact version recorded in composer.lock) to eliminate this warning and ensure fully reproducible builds.
Draft releases and pre-releases are excluded when fetching available versions from the GitHub API. Only stable, published releases are considered when resolving a range.
If composer.json does not exist, contains no carthage-software/mago entry, or the range cannot be satisfied by any known release, this step returns nothing.
4

Fallback to latest

If none of the previous steps produce a version, the action installs the latest stable release of the Mago CLI. This is equivalent to passing version: latest explicitly.
The fallback ensures the action never fails due to a missing version specifier, but it means builds may install different Mago versions over time as new releases are published. Pinning the version via composer.lock is the recommended approach for reproducible CI.

​
The working-directory Input

By default the action searches for composer.lock and composer.json in the current working directory of the runner, which is typically the root of the checked-out repository. You can point the action at a different directory using the working-directory input. 
- uses: nhedger/setup-mago@v1
  with:
    working-directory: "./packages/api"
This is particularly useful in monorepos where the PHP project lives in a subdirectory. Both composer.lock and composer.json will be looked for inside the specified directory.
If the specified working-directory does not exist on the runner, the action logs a warning and falls back to the current working directory rather than failing the step.

​
Summary Table

ConditionVersion used
version input is setValue of version input
packages-dev in composer.lock contains carthage-software/magoExact version from lockfile
require-dev or require in composer.json contains carthage-software/mago (exact)Exact version from manifest
require-dev or require in composer.json contains carthage-software/mago (range)Highest satisfying stable release
None of the aboveLatest stable release

Build docs developers (and LLMs) love

Get started for freeTalk to us