Troubleshooting
GitHub Module Says “I Can’t Clone Repos”?
Fix the common security-restriction loop and get your agent working with GitHub the right way.
If your agent says “I can’t directly clone repositories or use tokens due to security restrictions”, that usually means the GitHub integration path is incomplete or being attempted from the wrong context.
Important: this is rarely a GitHub outage. It is usually a permissions, workspace, or expectation mismatch between your prompt and the runtime.
What this error actually means
- Your agent is in a context where direct git access is not available.
- The token isn’t configured where the agent can use it.
- You asked for a direct clone when the safer flow is: connect integration → verify access → run a tiny test.
5-minute recovery flow
1) Confirm where you are running the task
Dashboard chat, Discord DM, server channel, and isolated runs can have different capabilities. Keep setup + first test in one surface.
2) Re-check GitHub auth state
Reconnect GitHub if needed and ensure the repository is accessible to the connected account. Private repo + wrong account = silent failure loops.
3) Run a tiny “read-only” canary task
Before cloning, ask for a simple repo metadata read (default branch + last commit message). This verifies scope without doing writes.
4) Ask for explicit fallback behavior
If clone is blocked, require the agent to say exactly what it can do instead (e.g., fetch via API, inspect selected files, or provide manual steps).
5) Use a strict output contract
Prevent vague replies by requesting: status, blocker, evidence, next action in that exact order.
Copy/paste prompt that works better
Help me diagnose GitHub access in this environment.
1) First, tell me whether direct clone is available here (yes/no).
2) If no, explain the exact blocker in one sentence.
3) Run a read-only canary check on this repo: OWNER/REPO
4) Return only:
- Status
- Evidence
- Safe next step
Do not claim success without evidence.
Common misconfigurations
- Wrong account connected: token/user has no access to the target private repo.
- Context drift: setup done in one surface, task run in another with different permissions.
- Over-scoped prompt: asking to clone + refactor + push in one step before proving access.
- No evidence requirement: agent says “done” but provides no commit/branch/file proof.
Trust rule: never treat “I did it” as complete unless you see concrete evidence (repo, branch, commit, or file output).
Advanced edge cases (when basics pass but it still fails)
- Connected in browser, not in runtime: OAuth looks successful in UI, but the active runtime/session still has stale auth state. Start a fresh session and run the read-only canary again.
- Public repo works, private repo fails: this usually means scope/account mismatch, not a broken module. Verify the exact GitHub account linked to the current workspace.
- Fallback claims hide real blocker: agent says it can “still help” with generic advice, but gives no repo evidence. Force yes/no on clone capability first, then require canary evidence before planning.
- Wrong workspace assumption: users compare GitHub repo files to a different local workspace and think clone failed. Require absolute path + branch + latest commit hash in the response.
New high-friction case: model-level security refusal
Recent community reports show this exact loop:
"I cannot proceed if it involves directly handling sensitive information like access tokens. My security protocols prevent me from using tokens exposed in plain text."
- This is often model behavior, not your GitHub setup. One model may refuse token-based clone syntax while another model in the same workspace works.
- Do not paste long-lived tokens repeatedly in chat. Repeated retries increase exposure risk and still may not fix the refusal.
- Use capability-first testing: run a read-only canary first, then ask for the safest next action supported by that model/context.
- If the task requires direct token handling and keeps refusing, switch to a model/runtime that supports the flow or use an approved integration path instead of forcing plain-text token prompts.
Known-good verification prompt
Diagnose GitHub repo access in this exact session.
Do this in order and stop on first blocker:
1) Confirm active model and active GitHub identity.
2) Check access to OWNER/REPO with a read-only canary (default branch + latest commit hash).
3) If clone is not allowed, say "clone blocked" and give the exact reason in one sentence.
4) If blocked due to token/security refusal, provide one safer alternative path (no token pasted in chat).
5) Return only:
- Capability: [clone available yes/no]
- Evidence: [model + repo visibility + branch + commit hash OR exact blocker]
- Safe next step: [single best next action]
Do not claim success without concrete evidence.
Escalation packet for #help
I’m getting: "I can't clone repositories due to security restrictions"
Surface: [dashboard / discord dm / server channel]
Repo type: [public/private]
Canary test result: [paste exact output]
What I expected: [one sentence]
What happened: [one sentence]
Bottom line: treat GitHub setup like a pipeline — auth, context, read-only canary, then real work. That sequence fixes most “can’t clone” loops fast.