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.

Setup Mago exposes three inputs that control which version of the Mago CLI is installed, how GitHub API requests are authenticated, and where the action looks for Composer files. All inputs are optional in everyday use — the built-in defaults are designed to work out of the box for most PHP projects without any additional configuration.

​
version

​
version
string
The version of the Mago CLI to install. Accepts a specific semver version string such as "0.7.0", the special string "latest", or an empty string (the default) to trigger automatic version detection from Composer files.When left empty or omitted, the action resolves the version by inspecting composer.lock, then composer.json, and finally falls back to "latest". See Version Detection for the full resolution chain.Default: "" (empty string — triggers auto-detection)Example values:
  • "0.7.0" — install a specific release
  • "latest" — always install the newest stable release
  • "" — auto-detect from Composer files (default)
Passing version: latest is an explicit instruction to install the newest stable release and bypasses all Composer file detection. It is not the same as omitting the input, even though both may end up installing the same version when no lockfile entry exists.

​
token

​
token
string
A GitHub token used to authenticate requests to the GitHub API. The action queries the GitHub API when resolving "latest", when resolving a version range found in composer.json, and when downloading the Mago CLI binary from GitHub Releases.Defaults to the automatic job token (${{ github.token }}), which is sufficient for the vast majority of workflows. If your workflow runs frequently and hits GitHub API rate limits, you can supply a Personal Access Token (PAT) with public_repo scope.Default: ${{ github.token }}Example values:
  • ${{ github.token }} — default, no additional setup required
  • ${{ secrets.GITHUB_TOKEN }} — equivalent to the default when referenced via secrets
  • ${{ secrets.MY_PAT }} — a PAT stored as a repository secret
The default ${{ github.token }} token is automatically provided by GitHub Actions and requires no extra configuration. Only switch to a PAT if you see 403 rate-limit errors in your workflow logs.

​
working-directory

​
working-directory
string
The directory the action searches for composer.lock and composer.json when auto-detecting the Mago version. Accepts any path relative to the workspace root or an absolute path.When left empty or omitted, the action uses the current working directory of the runner (typically the root of the checked-out repository). Set this input when your PHP project — and its Composer files — lives in a subdirectory, as is common in monorepos.Default: "" (uses the current working directory)Example values:
  • "./my-php-app" — subdirectory relative to the workspace root
  • "packages/api" — nested subdirectory in a monorepo
If the path specified in 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.

​
Full example with all inputs

The following workflow step shows all three inputs used together. In practice you would only specify the inputs you need to override. 
- name: Setup Mago
  uses: nhedger/setup-mago@v1
  with:
    version: "0.7.0"
    token: ${{ secrets.GITHUB_TOKEN }}
    working-directory: "./my-php-app"

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

​
Inputs at a glance

InputRequiredDefaultDescription
versionNo*""Version to install. Empty triggers auto-detection.
tokenNo*${{ github.token }}GitHub token for API requests.
working-directoryNo""Directory to search for Composer files.
* Both version and token are marked required: true in action.yaml, but each provides a default value ("" and ${{ github.token }} respectively), so neither needs to be set manually in normal workflows.

Build docs developers (and LLMs) love

Get started for freeTalk to us