Quick guide mac-yml Open a macOS tmate debug session in GitHub Actions.md

Quick guide: mac.yml — Open a macOS tmate debug session in GitHub Actions

This tiny GitHub Actions workflow lets you start an interactive remote debugging session on a macOS runner using tmate. It’s handy when a job fails only on macOS and you want to hop into the running environment to inspect files, processes, or reproduce the problem live.

What the workflow does

name: Mac Debug (tmate)
on: workflow_dispatch           # manual trigger
jobs:
  debug:
    runs-on: macos-14           # e.g. macOS Sonoma
    timeout-minutes: 60         # auto-cancel after 60 minutes
    steps:
      - uses: actions/checkout@v4
      - name: Open tmate session
        uses: mxschmitt/action-tmate@v3
        with:
          limit-access-to-actor: true   # restrict connection URL to the PR runner only

• workflow_dispatch — lets you start the workflow manually from the Actions UI (no push or PR needed).
• runs-on: macos-14 — selects a macOS runner (comment notes Sonoma as an example).
• timeout-minutes: 60 — prevents leaving an idle session running forever.
• actions/checkout@v4 — checks out the repository so you can inspect the repo contents during the session.
• mxschmitt/action-tmate@v3 — opens a tmate session on the runner so you can connect remotely.
• limit-access-to-actor: true — important security setting: the tmate connection URL is restricted so only the person who triggered the run (the actor) can connect.

How to use it

1. Open the repository’s Actions tab and choose Mac Debug (tmate), then click Run workflow (or trigger via a PR if you set that up).
2. When the job starts, the tmate action prints the connection information in the job logs (a short-lived URL or SSH details).
3. Use the provided URL/credentials to connect and inspect the live runner session.

Security tips

• Keep limit-access-to-actor: true enabled when possible so the session isn’t publicly accessible.
• Trigger tmate sessions only when needed and use timeout-minutes to limit exposure.
• Don’t type or expose secrets directly in the interactive session. Treat the runner as ephemeral and untrusted for sensitive long-term operations.
• Monitor who triggers the workflow and consider restricting who can dispatch workflows in repository settings.

Quick improvements & variations

• Increase timeout-minutes if you expect longer interactive debugging, but balance that against security risk.
• Add extra setup steps before opening tmate (install tools, reproduce failing steps) so the environment is ready.
• Use self-hosted macOS runners if you need specific hardware or software not available on GitHub-hosted macOS images.

Bottom line

This workflow is a simple, practical way to debug tricky macOS-only CI problems interactively. With sensible access limits and short timeouts, it provides a powerful shortcut to reproduce and fix issues that are hard to diagnose from logs alone.