Routines: GitHub App install gap — OAuth authorize flow doesn't trigger install, errors are opaque

Summary

Setting up a Claude Code Routine that needs to clone+push a private GitHub repo failed silently in three connected ways tonight. After ~90 minutes of debugging we found the root cause: the Claude GitHub App must be installed on the repo, separately from the OAuth grant. The path to install isn't surfaced in the claude.ai connector flow.

Three UX gaps

1. Connectors page authorizes OAuth but doesn't trigger GitHub App install

Path: https://claude.ai/customize/connectors → GitHub Integration → Connect.

This flow grants OAuth (visible at https://github.com/settings/apps/authorizations as "Claude · authorized · last used within last week") but does not install the Claude GitHub App on any repo. Result: https://github.com/settings/installations shows "No installed GitHub Apps."

Disconnecting and reconnecting on the Connectors page repeats only the OAuth step, not the install.

2. \"Run now\" returns generic \"Failed to start run\" with no diagnostic

When a routine has a private-repo source and the Claude GitHub App isn't installed, clicking \"Run now\" on the dashboard returns:

Failed to start run. You can try again.

The actual cause (missing GitHub App install) isn't surfaced. The user has no way to know what's wrong.

For one-time run_once_at routines, the failure is recorded as ended_reason: \"auto_disabled_repo_access\" in the API — that's a useful string but it's API-only, not in the dashboard UI.

3. The install URL isn't documented in the claude.ai flow

The canonical install URL for the Claude GitHub App is:

https://github.com/apps/claude/installations/new

This URL is not linked from:

• The Connectors page on claude.ai
• The Routines dashboard
• Any error message
• (As far as I can find) the Claude Code public docs

I had to discover it by curl-ing candidate slugs (/apps/claude returned a real GitHub App page; the rest 404'd). After installing via that URL with \"Only select repositories\" → my repo, the routine ran cleanly.

Reproduction

1. Have a Claude.ai account with GitHub Integration connected via OAuth (Connectors page)
2. Do not install the Claude GitHub App on any repo (skip /settings/installations)
3. Create a routine via web dashboard pointing at a private repo
4. Click \"Run now\" → fails with generic error
5. Or wait for run_once_at to fire → routine auto-disables with ended_reason: auto_disabled_repo_access

Suggested fixes (any one would close the gap)

• Best: Make the OAuth flow on the Connectors page also walk through the App install step (\"Now choose which repos Claude can access\")
• Good: When creating a routine with a git_repository source, validate that the Claude GitHub App is installed on that repo. If not, show \"Install Claude on this repo\" link directly to the install URL
• Minimum: Surface auto_disabled_repo_access (or the equivalent failure) as an actionable error message in the dashboard with a \"Fix: install Claude GitHub App\" link

Environment

• Claude Code Web (browser) and Routines dashboard
• Environment: \"Claude code on iPhone\" (env_01GDt8rTs6kNr6tjKaoTjFbW), but issue is account-level not env-level
• Private repo
• Tested 2026-05-03 evening Asia/Jerusalem

Ref

Full debug trail (in our private repo for context): commit message and handoff 2026-05-03-routine-debug-trail.md. Happy to share specifics if useful.