GitHub
Connect repositories, browse docs, manage PRs on tickets, and maintain the connection.
GitHub integration
Per-project GitHub settings link a repository to tickets, agents, documentation browse, MCP tools, skill injection, and optional CI-gated PR merge automations.
Why connect a repo
With a linked repository:
- Cursor Cloud agents start from a configured base ref and sync branches and pull requests to tickets
- MCP
list_docs,get_docs, andcreate_properate on repo contents - The dashboard Docs page renders markdown from the configured docs root
- Publish validates and deploys from the agent starting ref (not the docs branch)
- Project skills can be injected into
.claude/skills/on the agent starting ref
Authentication model
ArxDeck uses a GitHub App with project-scoped repository bindings.
| Binding mode | When it applies | What you do |
|---|---|---|
| Platform-managed | Repository created via Create repository under the operator GitHub org | Nothing after create |
| Customer-managed | Your own GitHub repository | Connect repository wizard with repo owner or admin access |
An ArxDeck organization can link multiple projects to different repositories. Each project has at most one active binding.
Short-lived installation tokens (~1 hour) power server API calls. Automated git operations appear as arxdeck[bot]. Fresh Cursor Cloud agent creates receive envVars.GITHUB_TOKEN with the same minted token.
Setup & configuration
Project
Project admins open Settings → GitHub:
- Use Connect repository and paste a repository URL (
https://github.com/{owner}/{repo}), or use Create repository when the platform GitHub App is configured for managed repos. - Complete GitHub user OAuth. You must be the repository owner (personal repos) or have admin access (collaborators) or be an organization owner/admin (org repos). Personal repo owners are not listed as collaborators on GitHub — that is expected.
- If the ArxDeck GitHub App is not yet installed on the repository owner account, you are redirected to install it first (even when you own the repo — GitHub App user tokens cannot read private repos until the app is installed). After install and granting repository access, connect runs a scoped post-install OAuth pass. If your user token still cannot read the repository (common with GitHub App
ghu_tokens), ArxDeck completes binding using app credentials when the installation covers the repo, then confirms the repository appears in your installation repository list. - Configure Docs branch (default
main), docs root (defaultdocs/), and default entry file (defaultPROJECT.md). - Set Agent starting ref — branch or commit used when agents start work and when skills are injected (may differ from the docs branch).
- Optionally enable Force PR base to agent starting ref so MCP
create_pralways targets that ref. - Optionally enable CI before merge for automation merge actions — pick a
workflow_dispatchworkflow on the repo default branch and click Validate workflow.
After connect, the page shows inline status for callback results (for example success, insufficient permission, repository not found, or temporary GitHub API errors).
Use Collaborators on the same page to add or remove direct collaborators and pending invitations. Suggested logins come from project members who saved a GitHub username in account settings.
Connection maintenance
When a binding needs attention, the GitHub settings page shows actionable status:
- Check connection — verify the installation token and repository access
- Reauthenticate — refresh OAuth when permissions or tokens expire
- Disconnect — remove the project binding (does not delete the GitHub repository)
GitHub settings revisions (update_settings, set_ci_workflow) appear in History with diffs and restore. Binding and OAuth operations themselves are not revision-tracked — see Configuration revision history.
ArxDeck Helper can propose GitHub settings changes (including connect and reauthenticate flows that redirect through OAuth). Approve proposals in Project → Proposals.
Connect callback messages
| Code | Meaning | Action |
|---|---|---|
connected | Binding succeeded | Continue configuring docs and CI settings |
insufficient_permission | Signed-in GitHub user lacks owner/admin rights | Sign in with the repo owner or an admin account |
repo_not_found | Repository missing or not visible to the OAuth account | Check the URL and GitHub account |
installation_not_found | App not installed on repository owner | Complete GitHub App install during connect |
installation_repo_access_required | App installed but repo not in installation scope | Grant repository access in GitHub app settings |
user_installation_access_required | Repository not in your installation list or app not authorized for your account | Re-authorize during connect; grant repository access in GitHub app settings |
github_api_error | Temporary GitHub API failure | Retry connect in a few minutes |
Pull requests on tickets
Pull requests appear on ticket detail from agent run sync and MCP create_pr. Members with ticket edit access can open PRs in GitHub and merge open PRs from the ticket page (manual merge is not CI-gated; automation merge may be).
Technical details
| Topic | Detail |
|---|---|
| Authentication | GitHub App installation tokens (~1 hour); project-scoped bindings |
| Attribution | Server and Cursor agent git operations as arxdeck[bot] |
| Cursor Cloud | Fresh agent create receives envVars.GITHUB_TOKEN with minted installation token |
| Repo create | Platform-managed repos under the operator GitHub org |
| Docs paths | Browse and MCP accept docs-root-relative or repo-relative paths under the configured docs root |
| PR base branch | MCP create_pr defaults to Agent starting ref; invalid refs fall back to the repository default branch |
| Live reads | GitHub REST API — no cached doc tree in v1 |
| CI before merge | One workflow_dispatch workflow per project; webhook-triggered reconciliation when the platform GitHub App webhook is configured, with automation-worker polling as fallback |
| Auto-deploy (Publish) | Uses the platform GitHub App push webhook; no extra GitHub permissions beyond repository access |
Platform operators configure the GitHub App and deployment secrets — that is not part of the tenant dashboard.