Symptom: macOS-26 jobs stay queued, and you cannot tell whether releases are at risk or Mac capacity is short.
Fastest fix: Check GitHub-hosted concurrency, workflow concurrency rules, and self-hosted runner status and routing before you add capacity.
Who should use this runbook: Enterprise IT leads assessing release risk and Mac procurement. CI platform engineers separating platform limits from workflow rules and runner routing. Technical and FinOps leaders deciding whether to optimize, divert, or expand iOS CI capacity.
Last updated November 20, 2026. Current platform behavior and runner details were checked against GitHub’s Actions limits, its current jobs view, and the linked workflow, runner, and image documentation. Confirm the limits shown for your organization when you investigate; do not assume a plan allowance from an older runbook.
Start by locating where the job is waiting
“Queued” is a symptom, not a root cause. First determine which part of the path has stopped:
- The workflow has not started. Check whether the event triggered the workflow and whether branch, path, or other workflow conditions excluded it.
- The job is waiting for a runner. Check the job status, runner type, organization activity, and—if self-hosted—the matching runner pool.
- A runner has accepted the job, but execution has not begun. Investigate runner startup and host health rather than treating this as proof of a concurrency cap.
- Another run in the same concurrency group is active. The workflow may be intentionally serializing work or replacing an older pending run.
runs-on values, and the time the job starts or is cancelled. Compare runs across dates and workflows instead of treating one delayed dispatch as a platform incident.
This separates at least three costs that are often mixed together: release time lost to real queueing, developer time spent investigating a routing issue, and Mac capacity paid for but not needed once a workflow rule is corrected. It also shows whether the delay affects every build or only a specific release path.
To inspect organization or enterprise activity, use GitHub’s current jobs view. Compare it with individual job records. A screenshot of one queued job is less useful than a record that identifies which jobs were active, which were pending, and what runner each job could use.
Check GitHub-hosted capacity before blaming the Mac image
GitHub-hosted concurrency is governed by limits that depend on the account and runner configuration. Check the current GitHub Actions limits documentation and your organization’s settings; do not hard-code a remembered allowance into an expansion proposal. Verify whether other workflows are consuming available concurrent jobs and whether your macOS jobs share the relevant pool.
GitHub’s documentation also notes that macOS jobs can take longer to start during periods of high demand. That is an explanation to test against repeated records, not evidence that every slow macOS-26 job is caused by a platform-wide shortage. Compare different trigger times, workflows, and runner types. If only one workflow is delayed, inspect its configuration and routing before generalizing from it.
The macOS-26 runner image is listed in the official runner-images repository. Check the current image and label information in the runner image documentation when reviewing runs-on. Image availability does not guarantee an immediate runner assignment, nor does it show that your organization has exhausted its concurrency allowance.
Treat the queue as evidence with a scope. If unrelated jobs also wait and the organization’s available concurrency is occupied, platform capacity becomes a stronger hypothesis. If only a particular workflow waits, look for a workflow-level concurrency group, runner label mismatch, or a trigger that starts more jobs than the workflow is designed to serve.
Inspect workflow concurrency and self-hosted routing
A concurrency rule can create a queue by design. GitHub documents that a concurrency group allows at most one running job or workflow and one pending member of that group at a time; a new pending run can replace an existing pending run. The group key and cancel-in-progress behavior therefore affect which commit gets built and whether an older run survives. Verify the exact behavior in GitHub’s workflow concurrency guide.
For release workflows, serialization may protect ordering or shared resources. Do not remove it simply to make the queue look shorter. Instead, ask whether the group is broader than necessary. For example, a group shared by independent branches can block work that does not actually need ordering. Separate groups only when the release process permits those jobs to run independently.
For pull-request validation, an older run may be safe to cancel when a newer commit makes it obsolete. That choice is not appropriate for every release, signing, or deployment stage. Identify which runs can be superseded, and retain queued work where dropping it would violate your release policy.
If the job targets a self-hosted Mac, check that the runner is online, available, and eligible for the job’s runs-on labels and runner group. GitHub’s self-hosted runner workflow instructions describe the label and group routing requirements. Its self-hosted runner reference explains runner status and assignment behavior.
A runner can be installed on a healthy host yet fail to receive a job because its labels or group do not match. Conversely, a matching label does not make an offline or busy runner available. Check the runner list, host logs, job routing details, and runs-on expression together. Enable GitHub Actions debug logging when normal job records do not show enough detail to locate the handoff failure.
Compare the likely causes before changing capacity
Use this table to keep the diagnosis tied to observable evidence. “High,” “medium,” and “low” describe the strength of the diagnostic signal, not a measured probability or service guarantee.
| Evidence in the records | Likely cause | First response | Capacity signal |
|---|---|---|---|
| Several GitHub-hosted jobs wait while the organization is using its available concurrency | Hosted concurrency pressure | Check current limits and competing workflows | Medium to high if release-critical jobs repeatedly wait |
| Runs sharing a concurrency group wait or replace earlier pending runs | Workflow serialization | Review the group key and cancellation behavior | Low until the rule is shown to be necessary and correctly scoped |
| A self-hosted job has no eligible online runner | Runner offline, busy, or misrouted | Check host status, labels, and runner group | Low until routing and host availability are corrected |
| A GitHub-hosted macOS job starts slowly, with no matching workflow or routing issue | Possible high-demand startup delay | Compare repeated records across workflows and trigger times | Low from a single event; stronger only with a persistent pattern |
| Important jobs keep waiting after the configuration and routing checks pass | Possible sustained capacity constraint | Pilot task diversion or added Mac capacity | High enough to test an expansion, not to skip validation |
Use a conditional decision path
- If the job never triggered, fix the event or workflow condition; do not add a Mac.
- If the job waits behind a concurrency group, retain serialization when order matters. Otherwise, narrow the group or allow cancellation only for safely superseded work.
- If the job targets a self-hosted runner that is offline or has mismatched labels or group, repair availability and routing before increasing the fleet.
- If GitHub-hosted jobs wait while available concurrency is occupied, review the organization’s limits and workflow demand. Test a change in scheduling or task distribution before committing to permanent capacity.
- If release-critical macOS jobs repeatedly wait after those checks, evaluate a dedicated or remote Mac pilot. Expand only after the pilot passes build, test, signing, and operational acceptance.
Answer common queue and scaling questions
How do you distinguish a concurrency limit from an offline runner?
For GitHub-hosted jobs, review current organization activity and the applicable limits. For self-hosted jobs, verify that a matching runner is online and eligible for the job. These checks answer different questions: one concerns available GitHub-hosted concurrency, while the other concerns whether a particular host can accept the routed job. Record both before deciding that the queue needs more Macs.
When is changing concurrency safer than adding a runner?
Change concurrency when the group is broader than the work’s real ordering requirement, or when obsolete validation runs can safely be cancelled. Keep serialization when jobs share a release state or resource that must not run concurrently. Adding a runner will not fix a workflow rule that intentionally allows only one active run in a group.
What should you measure during an iOS CI capacity review?
For each important workflow, retain trigger time, queued status, runner type, assignment or start time, completion or cancellation, and whether the job was blocked by concurrency or routing. Mark release-critical jobs separately from disposable validation runs. Compare recurring patterns across multiple runs; use actual records to estimate impact instead of inventing a universal wait threshold.
Does a slow macOS-26 start mean GitHub has a platform fault?
No. GitHub documents that macOS jobs can take longer to start during high-demand periods, but one slow job does not establish a platform fault or prove that your team needs dedicated capacity. Compare the same workflow across different times, and check concurrency, runner routing, and job status. Escalate only with a repeatable pattern and the relevant job records.
Run a controlled investigation before expanding
Follow this sequence for a repeatable diagnosis:
- Capture the baseline. Select representative macOS-26 workflows, including release-critical jobs and routine validation. Record job links, trigger times, statuses, runner types, and start outcomes. Avoid estimating a queue from memory.
- Check the current hosted limits and usage. Compare your organization’s observed active jobs with the current GitHub documentation and settings. Note which workflows consume concurrency during the same period.
- Inspect concurrency groups. Search workflow and job definitions for
concurrency, group expressions, and cancellation settings. Map each rule to the release policy: what must run in order, and what can be superseded? - Verify runner assignment. For self-hosted Mac jobs, compare
runs-onvalues with online runner labels and group membership. Review host logs and job routing details for unassigned work or a runner that accepts a job but does not progress. - Compare repeated observations. Separate workflows, runner types, and trigger periods. Look for repeatable wait patterns rather than treating one delay as proof. Enable debug logging when the job record does not expose the relevant handoff.
- Test the smallest safe change. Narrow a concurrency group, change cancellation only for disposable runs, or divert one suitable job to a pilot runner. Change one cause at a time so you can tell whether queue behavior improved.
- Validate the full release boundary. Confirm that the pilot can perform the required build and tests, access signing material under the team’s controls, produce usable artifacts, and support the team’s failure and recovery process. Do not infer production readiness from a job merely reaching “completed.”
- Review the decision with engineering and FinOps. Compare the measured release impact and operational ownership of the current setup against the proposed capacity. Keep the change reversible until the pilot reflects the real workflow and access requirements.
Decide whether remote Mac CI is justified
Use the records to classify the next action:
- Optimize: the main cause is a broad concurrency group, unnecessary serialization, or safely superseded work left running.
- Repair: the main cause is an offline self-hosted host, a busy runner, or labels and groups that do not match the workflow.
- Observe: the cause may be a high-demand hosted startup delay, but the evidence is limited to isolated or inconsistent runs.
- Divert or expand: important macOS jobs repeatedly wait after workflow rules, hosted concurrency, and self-hosted routing have been checked.
MACGPU offers an option to review remote Mac access for a CI workload, but a rented Mac is not automatically the right answer. If your team runs steady, predictable heavy workloads and needs direct physical peripherals or local lab access, purchasing and operating an on-premises Mac may fit better. If the queue comes from workflow serialization or a misrouted runner, neither purchase nor rental addresses the cause.
When the evidence does show sustained capacity pressure and the workload genuinely requires macOS, remote Mac capacity can avoid tying every developer’s work to a newly purchased individual machine. You still need to account for the existing hosted-runner limits, access controls, signing requirements, and who owns day-to-day operations. Check MACGPU’s available Mac options against the pilot’s actual requirements before you commit; this runbook does not assume a configuration, price, location, or delivery time.
Make the expansion decision from repeated job records and a successful isolated pilot. If those records instead point to concurrency rules, routing, or a single slow startup, fix or monitor that cause first.