Troubleshooting Morph Actions onboarding

Start by preserving GitHub state. If the App installation succeeded but Morph linking did not, do not uninstall it by default. Return to Morph Actions or rerun headless status/setup so Morph can observe current App access and resume.

Installation and handoff outcomes

Outcome	Meaning	Safe next step
linked	The exact authorized handoff linked the installation/repository.	Continue with migration for the selected repository.
resume_agent	GitHub installed the App, but this browser callback could not identify an authorized Morph handoff.	Return to the agent/UI and rerun status/setup. Preserve the installation.
restart_install	The prior authorized handoff is no longer active.	Start setup again from the same Morph org/repository to obtain a fresh handoff.
expired	The short-lived handoff expired.	Obtain a fresh setup action; do not replay the URL.
already_completed	The single-use handoff was already consumed.	Refresh status and continue from observed repository state.
cancelled	GitHub setup was cancelled.	When the GitHub admin is ready, start a fresh handoff.
correlation_mismatch	Browser cookie/state did not exactly match the authorized handoff.	Restart setup from the intended Morph org; do not try alternate state values.
installation_conflict	The installation is already bound to another Morph tenant.	Stop and contact Morph support; the other tenant is intentionally not disclosed.
repository_conflict	The repository is already bound to another Morph tenant.	Stop and contact Morph support; do not remove access speculatively.

Browser callbacks return to a Morph-owned recovery page. Machine clients receive the same stable outcome taxonomy through structured responses. In both cases, invalid correlation must produce zero tenant mutation.

Repository is not selected

The Morph App may be installed for the GitHub organization but not allowed to access the requested repository. Ask the correct GitHub organization owner or repository administrator to open the App's installation settings, add the exact repository under Repository access, and save. Then rerun Morph status/setup.

The public flow does not silently add a repository with a user token. Do not send a GitHub token to Morph or substitute a bare GitHub App installation URL.

Public repository is blocked

Morph Actions onboarding supports private repositories with trusted workflow authors. The backend blocks migration, readiness, dispatch, and link/setup mutations for a public repository, so bypassing the UI does not enable it. Move the first smoke to an eligible private repository. A public/fork mode requires a separately reviewed opt-in and security design.

Migration cannot proceed

• Read every security_warnings and unsupported-job result.
• Confirm the repository and analyzed source commit are still current.
• Review dynamic/reusable jobs manually; Morph preserves unsupported jobs.
• If morph-actions-migration exists with different source/labels/base/head, resolve the typed conflict in GitHub. Morph will not force-reset unrelated branch work.
• Treat the output as supported runner-label rewriting, not a workflow safety certification.

Dispatch response was lost

Look up the durable dispatch receipt returned by the service. Reuse an idempotency key only for the identical canonical repository, workflow, ref, and inputs. A changed, failed, or indeterminate receipt conflicts rather than risking a second GitHub dispatch. Do not create a new key until you have resolved whether the original receipt dispatched.

Verification is not complete

• Pending: continue bounded polling; do not dispatch another run merely because assignment reconciliation is still in progress.
• Mismatch: compare the selected repository, run attempt, expected GitHub job id, actual job id, and runner identity.
• Orphaned: retain the run/job/request ids and escalate; another run cannot repair this one.
• Failed: inspect the selected Morph/GitHub job failure. A successful run in another repository is irrelevant.
• No Morph-labelled job: confirm the migration was merged into the exact dispatched ref and the intended job resolved to the full Morph label set.

Success requires the selected repository, Morph status succeeded, assignment verified, matching non-null expected/actual GitHub job ids, and GitHub job completion success. See Security and exact verification.

What to send support

Send only:

• the response/request id;
• Morph organization id;
• repository full name; and
• approximate UTC time.

Never send a Morph API key, GitHub token, cookie, raw state, request body with secrets, or installation handoff URL. Preserve the successful GitHub App installation while support reconciles it; uninstall/reinstall is a last resort for an explicit security or ownership reason.