GitHub Integration

LatchLoop’s GitHub integration lets the app read your code, open pull-requests (PRs), and keep tasks up-to-date as your work is merged or deployed.
Below is an overview of what happens at every step, the controls you have, and a few FAQs.

---

1. Installing the LatchLoop GitHub App

1. Open Settings → Integrations → GitHub in LatchLoop.
2. Click “Install GitHub App” – you’ll be redirected to GitHub.
3. Choose which GitHub account or organisation you want to install the app on.
4. Select “All repositories” or pick only the projects you need.
5. Finish the GitHub flow and you’ll land back in LatchLoop with a success message.

---

2. Selecting a repository for a project or task

Whenever LatchLoop asks for a repository (for example while creating a project or enriching a task):

1. Click “Connect GitHub Repository”.
2. A list of repos the app can access appears – including private ones.
   • Use the search box or scroll; it loads up to 50 repos at a time.
3. Pick a branch (default: main) and optionally list folders to ignore
   (e.g. node_modules,.git,dist).
4. Hit “Connect Repository”.

What happens next • LatchLoop downloads a lightweight file-tree (names only, not file contents) and saves it in Supabase.
• That tree is used by the AI to understand your project’s structure when answering questions or generating code.
• If you link the repo to a task, a reference to the same file-tree is stored with the task.

---

3. How LatchLoop works with your code

Reading files on demand

When the AI needs actual code (not just the file list) it asks the GitHub API for the file’s content. Only the file requested is fetched, never the entire repo.

Creating branches & commits

• Each “Build” or “Apply Patch” action creates one branch per task (if it doesn’t already exist).
• Branch names include the task’s short ID so they’re unique and easy to find, e.g.
latchloop/feat-LL9conKjz99-my-feature.
• The AI’s changes are committed to that branch.

Opening pull-requests automatically

When the AI has pushed at least one commit and there is no open PR yet, LatchLoop will:

1. Draft an informative PR title and body
2. Open the PR from the task’s branch into your repo’s default branch.
3. Update the task in LatchLoop with the PR link and mark its status “PR Open”.

---

4. Keeping tasks in sync with GitHub

Pull-request events

When a PR opened by LatchLoop is merged or closed, GitHub sends a webhook that:

• Updates the task’s status to Merged (if merged).
• Leaves a note in the task sidebar so your team sees the event.

Deployment notifications

If your CI/CD pipeline reports a deployment status (e.g. Vercel, Netlify, GitHub Actions), LatchLoop will store a deployment message in the task’s activity feed – useful for quick access to preview links.

---

5. Managing or revoking access

Refreshing tokens

Tokens refresh automatically. If you ever see a “token expired” message, just click “Reconnect GitHub App” in Settings – no code or PRs are lost.

Disconnecting (from inside LatchLoop)

Settings → GitHub → Disconnect instantly stops LatchLoop from making new API calls. The GitHub App remains installed, but unused.

Fully uninstalling (from GitHub)

1. Go to github.com/settings/installations.
2. Find “LatchLoop” and click Uninstall.
3. Tokens are revoked immediately and LatchLoop can no longer reach any repository until you reinstall.

---

6. Frequently-asked questions

Q: Does LatchLoop ever push directly to main?
A: Never. All changes go to a task-specific branch and must be merged via a PR.

Q: Can the AI see private repositories?
A: Yes – but only the repos you granted the GitHub App permission for.

Q: What permissions does the GitHub App request?
A: Contents: Read & write, Pull requests: Read & write, Deployments: Read. No access to Issues, Wikis, or Actions secrets.

Q: How large a repository can I connect?
A: There is no hard size limit, but extremely large repos (50k+ files) may take longer to fetch the initial file-tree.

Q: Can I switch the repository linked to a task?
A: Yes. Open the “Connect repository” dialog again, pick a different repo, and LatchLoop will replace the link.

---

7. Need help?

If anything in this guide isn’t clear or you hit a snag:

• Email us at [email protected]

Happy coding!