GitHub Actions macOS Runner Queue: 2026 Self-Hosted Acceptance Checklist

This week, diagnose the queue before adding capacity: verify the workflow labels, Runner availability, repository access, and job requirements first. Consider a self-hosted macOS Runner only when the evidence points to a controllable capacity gap or a need for a stable maintenance environment; then prove it can accept jobs, build, clean up, and recover.

This guide is for iOS and macOS developers who maintain GitHub Actions workflows and need to find why a job has not started.
It also helps platform engineers and small teams assess a self-hosted macOS Runner before relying on it.
If your only problem is a build error after a job starts, focus on the build-failure section rather than adding Runner capacity.

Why GitHub Actions macOS Runner jobs stay in the queue

“Queued” describes an outcome, not a root cause. A workflow can remain waiting because no eligible Runner can accept the job, because access or routing rules exclude the available Runner, or because the job has not yet been assigned. A build failure is a different problem: the Runner accepted the job and began executing its steps.

Capture the evidence before changing configuration:

• Save the workflow run URL and run identifier.
• Record the job name, branch, commit, and the exact runs-on value.
• Note the job’s current status and the time you checked it.
• Check whether a matching Runner is listed as online, busy, or offline.
• Save relevant workflow and Runner logs before retrying or changing labels.

This small record prevents a common troubleshooting mistake: treating every delay as a shortage of machines. A label mismatch cannot be fixed by provisioning another Mac. A missing permission will still block a newly created Runner if the repository or organization is not allowed to use it.

GitHub routes jobs using the Runner labels requested by the workflow. The documented default labels include self-hosted, an operating-system label, and an architecture label; the job must request labels that match an eligible Runner. Check the official label-routing guidance and the rules for selecting a Runner in a workflow against your actual configuration. Don’t infer the cause from a queued badge alone.

How do you confirm a self-hosted macOS Runner can accept jobs?

A machine being powered on does not prove that GitHub Actions can assign work to it. Confirm that the Runner is registered in the intended scope, has the labels the job requests, and is permitted to serve that repository or organization. GitHub’s documentation describes Runner groups and access rules; review the self-hosted Runner access controls rather than assuming registration grants access everywhere.

Then use a minimal workflow to test the route. Choose a harmless job that requests the same labels and access scope as the real workflow. Keep its steps simple: print a short diagnostic, report the operating system, and exit. If this test remains queued, investigate routing, availability, and permissions. If it starts, the basic assignment path works; move on to the real job’s environment and dependencies.

A Runner that is online but idle is not automatically healthy for every workflow. It may lack a requested label, belong to a different Runner group, or be outside the access scope. Compare the job’s runs-on labels with the Runner’s displayed labels character by character. Check for stale or misspelled custom labels, and confirm that the workflow’s repository or organization is covered by the configured access policy.

What to check when a Runner is online but the workflow does not run

Treat the workflow definition and the Runner as separate parts of the path. Start with the run and job details. Confirm that the workflow was triggered as intended, that the job is not waiting on a dependency, and that its if condition has not evaluated to false. Then inspect runs-on, Runner group selection, and repository access. A visible online Runner proves only that it has reported status; it does not prove that this particular job is eligible to use it.

Use this sequence so you don’t change several variables at once:

1. Open the exact workflow run and identify the job that is waiting.
2. Check the job’s dependencies and conditional expressions.
3. Copy the requested Runner labels from the workflow file.
4. Compare those labels with the available Runner and its group.
5. Verify that the repository or organization can use that Runner.
6. Run the minimal test workflow with the same routing requirements.
7. If the job still does not assign, enable diagnostic logging and preserve the resulting evidence.

GitHub provides instructions for enabling debug logging for workflow runs. Use it when ordinary job output does not show where execution stopped. Keep the resulting logs attached to the run record, and avoid posting secret values or sensitive environment details in a public issue.

If a job has been assigned and its steps are running, stop calling it a scheduling failure. A failed checkout, dependency download, code-signing step, or test command occurs after assignment. Capture the failed step and its log separately. That distinction helps you choose the right fix: adjust routing only when the job has not been picked up; investigate the build environment after it begins execution.

For a broader operational handoff, link your run record to the relevant Hashvps support information. Keep the workflow identifier, labels, and failure point with the question so the issue can be investigated without guessing which Runner or job you mean.

Build failures after a job starts

Once a job is running, check whether the Runner’s toolchain and project requirements agree. Xcode and macOS compatibility can constrain which machine image or operating-system release is appropriate. Apple publishes current Xcode system requirements; compare those requirements with the Xcode version selected by the workflow and the macOS version actually installed on the Runner.

Then inspect dependencies and signing separately:

• Toolchain: Record the installed Xcode version and the version selected by the workflow. Confirm that the expected developer tools are available to the job.
• Dependencies: Check whether package registries, source repositories, and required download endpoints are reachable from the Runner’s network.
• Signing: Confirm that the build step can access the expected certificate, provisioning profile, and keychain configuration. Do not print secrets or signing material into logs.
• Environment: Compare required variables, permissions, and filesystem paths with the workflow’s assumptions.
• Tests: Reproduce the failing command in the same job environment before changing the Runner pool.

A missing certificate is not evidence that the Runner is undersized. A dependency endpoint that cannot be reached is not proof that labels are wrong. Record the build error, the affected step, and any environment change separately from scheduling incidents. That gives you a useful history when the same workflow later experiences a genuine queue problem.

If you are migrating an Xcode project, use the migration as a controlled comparison. Run the same commit and workflow against the old and new environments where possible. Compare toolchain selection, dependency resolution, signing access, and test results. A successful job pickup proves that routing works; it does not prove that the new environment can reproduce the previous build.

Runner outages and recovery checks

A self-hosted Runner must stay connected and return to service after interruptions. Check the Runner process or service, the host’s network path, and the system’s startup behavior. Review the official monitoring and troubleshooting guidance for the supported operating systems and the relevant recovery checks.

Test failure and recovery deliberately before relying on the Runner:

• Confirm that you can detect when the Runner becomes unavailable.
• Disconnect network access in a controlled test, then verify that your monitoring reports the loss.
• Restore connectivity and confirm that the Runner returns to an assignable state.
• Restart the host and confirm that the Runner service starts without a person logging in and launching it manually.
• Run the minimal workflow again after recovery to verify actual job pickup.

Set alert ownership and a response path. An alert is useful only if someone knows whether to inspect the host, access policy, network, or workflow. Keep a record of the event, what recovered the Runner, and whether a queued job was eventually assigned. Don’t claim a recovery test passed just because the host restarted; verify the Runner status and complete a real test job afterward.

Check platform support before selecting an operating system or architecture. GitHub documents its self-hosted Runner requirements and supported platforms. Use that documentation as the boundary for a supported setup, then verify your own workflow against the actual host. A platform being technically available does not establish that your particular Xcode project, signing process, or dependency chain will work on it.

Workspace and credential cleanup after a job

A successful build can still leave a security or reliability problem behind. Inspect what remains after both successful and failed jobs. Look for checkout contents, generated artifacts, temporary files, caches, logs, and credentials. Decide which items are safe to retain and which must be removed before another workflow can use the environment.

Pay special attention to shared workspaces. If separate workflows or repositories can run on the same host, confirm that one job cannot read another job’s files or signing material. A cache can speed up later work, but it should not become a path for retaining credentials or private build output. Define the cache contents and invalidation rules deliberately; don’t assume that an operating-system cache is automatically safe to share.

Validate cleanup with a harmless test file and a test credential or marker created specifically for the check. After the job completes, verify that the file is gone and that temporary credentials are no longer usable. Repeat the inspection after a failed job, because cleanup behavior can differ when a step exits early. Never use a production signing secret as a cleanup test.

For teams handling secrets in CI, connect this check to a documented secret-handling procedure. The Hashvps service terms can help you review service conditions, but you should still verify your own workflow’s credential lifetime, access scope, and cleanup behavior. Keep responsibility clear: a service description cannot establish that your pipeline revokes or removes secrets correctly.

Choose the next action from the evidence

Use these branches before you provision another machine:

• If the job’s requested labels do not match an eligible Runner, fix the workflow labels or Runner labels, then rerun the minimal assignment test.
• If the Runner is offline or cannot recover, restore the service and network path, add an alert, and prove recovery with a test job.
• If the Runner is online but the job is not eligible to use it, correct the Runner group or repository access policy before adding capacity.
• If the job starts and then fails, diagnose the toolchain, dependencies, signing, or workflow command; don’t treat it as a queue problem.
• If the current supply is demonstrably insufficient for eligible jobs, or you need a stable macOS maintenance environment, assess a self-hosted Runner and complete the acceptance checks below.
• If your team cannot own host monitoring, patching, access control, and cleanup, compare a managed Mac environment with the operational effort of running your own host.

The key is to match the remedy to the failure stage. A label or permission repair may unblock the job without another machine. A genuine capacity issue may justify additional Runner supply. A build error calls for a reproducible environment, not indiscriminate expansion.

Use this acceptance checklist before routing production work

Treat acceptance as a set of observable results, not a statement that the host has been configured. Tick each item only after testing it with a workflow that uses the intended labels and access scope.

• [ ] Can accept work: A minimal workflow is assigned to the intended Runner and completes.
• [ ] Can build: The real project workflow uses the expected Xcode and macOS environment, resolves dependencies, and reaches its expected build and test steps.
• [ ] Failure can be detected: A controlled interruption or failed test produces an alert with a clear owner and diagnostic evidence.
• [ ] Can recover: After a network interruption or host restart, the Runner returns to an assignable state and completes a new test job.
• [ ] Can clean up: Workspace files and temporary credentials are removed or invalidated after both successful and failed jobs.
• [ ] Access is bounded: Only the intended repositories and workflows can use the Runner, and shared files cannot expose another job’s data.
• [ ] Logs are usable: The run record preserves enough information to separate dispatch, host, and build failures without exposing secrets.

If any box remains unchecked, keep the Runner out of production routing or limit it to a low-risk test workflow until you close the gap. When the root cause is a workflow rule or access setting, fix that configuration first. Buying or renting another Mac will not correct an ineligible job.

The tables below help distinguish the failure stage from the acceptance evidence. They are diagnostic aids, not claims about queue duration or Runner performance.

When a rented Mac is a better fit

Compare your current approach with a Mac environment suited to the job you actually need to run. A GitHub-hosted workflow can be convenient, but it may not give your team the persistent maintenance environment or control over Runner setup that a particular workflow requires. Running your own Mac gives you direct control, but your team also owns host availability, updates, network access, security boundaries, and cleanup.

A rented Mac can be a better experience for a temporary test environment, a migration, or a workload that needs macOS without adding a Mac to your permanent hardware fleet. It is not the right answer for every team: if you need long-running, predictable heavy workloads or physical devices and interfaces, compare those requirements against a dedicated local setup. Before choosing Hashvps, review the Hashvps plan details and confirm that the available environment, access method, lifecycle, and support fit your Runner and workflow. If the mismatch is only a label or permission rule, fix that first; if you need a temporary Mac environment after passing the checklist, evaluate a Hashvps rental against the operational work your current setup requires.