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 examples below cover the most common ways to integrate Setup Mago into a GitHub Actions workflow. Every snippet is complete and ready to paste — adjust the mago command at the end to match whatever subcommand your project uses (lint, format, check, etc.).

​
Automatic version detection

The simplest possible setup: omit the version input entirely and let the action read the Mago version from your composer.lock. This is the recommended approach for most projects because the installed CLI version always matches the version pinned in your lockfile. 
steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Setup Mago
    uses: nhedger/setup-mago@v1

  - name: Run Mago
    run: mago lint --reporting-format=github
Commit your composer.lock to version control to ensure consistent Mago versions across all contributors and CI runs. The action reads packages-dev in the lockfile and installs the exact version recorded there.

​
Latest version

Explicitly request the newest stable release of the Mago CLI. Use this when you always want the latest features and are not pinning a specific version in your Composer files. 
steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Setup Mago (latest)
    uses: nhedger/setup-mago@v1
    with:
      version: latest

  - name: Run Mago
    run: mago lint --reporting-format=github
version: latest bypasses Composer file detection entirely. The action fetches all published stable releases from GitHub and installs the highest one.

​
Specific version

Pin the action to a known Mago release. This is useful in security-sensitive pipelines or when you need to reproduce an exact CI environment regardless of what is in composer.lock. 
steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Setup Mago 0.7.0
    uses: nhedger/setup-mago@v1
    with:
      version: "0.7.0"

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

​
Monorepo — pointing at a subdirectory

In a monorepo where the PHP project lives in a subdirectory, use working-directory to tell the action where to find composer.lock and composer.json. The Mago binary is still added to the PATH globally, so the run step can invoke mago from any directory. 
steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Setup Mago
    uses: nhedger/setup-mago@v1
    with:
      working-directory: "./packages/api"

  - name: Run Mago
    working-directory: ./packages/api
    run: mago lint --reporting-format=github
working-directory only affects where the action looks for Composer files during version detection. It does not change the working directory of subsequent run steps — set working-directory on those steps separately if needed.

​
Matrix build across operating systems

Run Mago on Linux, macOS, and Windows in parallel to verify your code passes on every platform that GitHub Actions supports. Setup Mago automatically downloads the correct binary for each runner. 
name: Lint

on: [push, pull_request]

jobs:
  lint:
    name: Lint (${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Mago
        uses: nhedger/setup-mago@v1

      - name: Run Mago
        run: mago lint --reporting-format=github
Setting fail-fast: false allows all three OS jobs to finish even if one fails, giving you a complete picture of cross-platform compatibility in a single run.

​
Custom GitHub token

If your workflow hits GitHub API rate limits — which can happen in large organizations with many concurrent CI runs — supply a Personal Access Token (PAT) via the token input. Store the PAT as a repository or organization secret. 
steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Setup Mago
    uses: nhedger/setup-mago@v1
    with:
      token: ${{ secrets.MY_PAT }}

  - name: Run Mago
    run: mago lint --reporting-format=github
The default value of token is ${{ github.token }}, so referencing ${{ secrets.GITHUB_TOKEN }} explicitly is equivalent and requires no additional setup. A custom PAT is only necessary when the default token’s rate limit is insufficient.

Build docs developers (and LLMs) love

Get started for freeTalk to us