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 integrates into any GitHub Actions workflow in minutes. By default you need nothing more than a single uses: line — the action reads your composer.lock to detect the right Mago version and places the mago binary on the runner’s PATH, ready to use in the very next step. The guide below walks you from a minimal snippet to a complete, production-ready lint workflow.
1

Add the action to your workflow

The simplest possible setup omits every input. The action will look for carthage-software/mago in your composer.lock, and install that version automatically. If no entry is found, it falls back to the latest stable release.
- name: Setup Mago
  uses: nhedger/setup-mago@v1

- name: Run Mago
  run: mago lint --reporting-format=github
The --reporting-format=github flag emits annotations directly in the GitHub Actions UI, highlighting lint violations inline on the diff.
The action uses the GitHub API to resolve and download Mago releases. By default it authenticates with the job’s built-in GITHUB_TOKEN. In repositories with very high workflow concurrency, you may hit the anonymous API rate limit — pass an explicit token input to avoid this:
- name: Setup Mago
  uses: nhedger/setup-mago@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
2

Choose a version

Automatic detection (recommended) — omit the version input and the action resolves the version for you using the following priority order:
  1. The version input, if provided.
  2. The version of carthage-software/mago pinned in composer.lock.
  3. The version constraint in composer.json (require-dev or require).
  4. The latest stable release as a final fallback.
If your composer.lock or composer.json lives in a subdirectory, point the action to it with working-directory:
- name: Setup Mago
  uses: nhedger/setup-mago@v1
  with:
    working-directory: ./backend
Explicit version — pin a specific release when you want full control over upgrades, regardless of what’s in your Composer files:
- name: Setup Mago
  uses: nhedger/setup-mago@v1
  with:
    version: "0.7.0"
Latest version — always install the newest stable release:
- name: Setup Mago
  uses: nhedger/setup-mago@v1
  with:
    version: latest
Pinning the version via composer.lock (the default, no-input approach) is the most reliable option — it guarantees CI always uses the exact same version as your local development environment.
3

Run Mago commands

Once the action completes, the mago binary is available on the PATH for all subsequent steps in the job. Use it like any locally-installed CLI tool:
# Lint the project and surface violations as GitHub annotations
mago lint --reporting-format=github

# Format all PHP files in place
mago format

# Run static analysis on the project
mago analyze
On Windows runners the same commands work without modification — Setup Mago downloads the correct .zip archive and installs the mago.exe binary transparently.

​
Complete Workflow Example

The workflow below puts all three steps together in a realistic CI pipeline. It triggers on every push and pull request, checks out the code, installs Mago using the version from composer.lock, and runs the linter with GitHub-native annotations. 
# .github/workflows/lint.yaml
name: Lint

on:
  push:
  pull_request:

jobs:
  lint:
    name: Mago Lint
    runs-on: ubuntu-latest

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

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

      - name: Lint
        run: mago lint --reporting-format=github
Save this file to .github/workflows/lint.yaml in your repository. From the next push onward, every pull request will display Mago lint annotations directly on the changed files.

Build docs developers (and LLMs) love

Get started for freeTalk to us