Integrations / GitHub
GitHub
Value: Link your GitHub account with OAuth, then add repositories by URL, clone them into your CloudyBot workspace, pull updates, and remove them when done. The same stack powers chat and automation that reference repo files—without handing the model raw shell access outside the allowlisted git helpers.
What the product supports
- OAuth:
POST /api/github/connect-init(Bearer session) starts the flow;GET /api/github/callbackcompletes it;GET /api/github/statuschecks token liveness;DELETE /api/github/disconnectunlinks. - Repositories:
GET /api/reposlists configured repos;POST /api/reposadds by URL;POST /api/repos/:name/cloneclones to disk;POST /api/repos/:name/pullpulls;DELETE /api/repos/:nameremoves metadata and workspace files. - Safe git: Server-side git runs through
git-exec.js(argv-onlygitwith a subcommand allowlist andassertRepoPathUnderUserRepos). A mutex serializes intensive git work. - Cross-feature use: Helpers are also used from
tools.js(git_operation) and account deletion paths—see feature README.
Hiring specialists is a different subsystem under features/employees; GitHub OAuth and clones are implemented in features/github, mounted from server.js as githubRouter.
Setup checklist (operator + user)
- Create a GitHub OAuth app; configure
GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET(or separate local vs production pair as documented ingithub-routes.js). - Set
GITHUB_TOKEN_ENCRYPTION_KEYto 64 hex characters in production so tokens are not stored reversibly without encryption. - Set
WORKSPACE_PATHif the default workspace location under the API data directory is not desired. - Optional: tune
GIT_MAX_REPO_SIZE_MBfor pre-clone size checks (default noted in route comments). - Users connect from the dashboard (workspace / GitHub UI), then add and clone repos they are allowed to access with their GitHub token.
Example workflows
- Chat over your codebase: Clone a private repo once, then ask questions that read files through the normal workspace and agent tools.
- Stay current: Use pull after teammates merge to refresh the local clone before analysis.
- Trim disk: Delete repos you no longer need so workspace storage stays within plan limits.
Security notes
Do not log full OAuth tokens or encryption keys. Use a dedicated GitHub OAuth application per environment, rotate credentials if exposed, and rely on path checks so git never escapes the user repo directory.
FAQ
What does the GitHub integration expose?
Express routes under /api/github for OAuth connect-init, callback, status, and disconnect, plus /api/repos to list repositories, add one by URL, clone to your workspace disk, pull latest, and delete (removing disk data). Helpers support tools such as git_operation and account deletion flows. This feature is separate from the employees or hire UI—OAuth and cloned repos live here.
How is my GitHub token stored?
Tokens are encrypted with AES-256-GCM when GITHUB_TOKEN_ENCRYPTION_KEY is set to 64 hex characters; in production that key is required for usable OAuth tokens. Without a valid key in production, decryption fails closed. Non-production can fall back to dev behavior documented in code.
Where do cloned repositories live?
Per-user directories under WORKSPACE_PATH (default under api/data/workspaces relative to the API). Git commands run through git-exec.js with an allowlisted argv-only git subcommand set and assertRepoPathUnderUserRepos so paths stay under the user repo root. Heavy operations use a serialized lock to avoid overlapping clone or pull jobs.
What environment variables should operators set?
Typically GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET with optional separate local vs production OAuth app vars; callback URLs can be set explicitly or derived from PUBLIC_APP_URL or APP_URL. Use GITHUB_TOKEN_ENCRYPTION_KEY in production, WORKSPACE_PATH for workspace root, and optional GIT_MAX_REPO_SIZE_MB before clone (default 100 in code comments). See api/.env.example and the file header in github-routes.js.
Connect GitHub from the dashboard workspace flow, then manage repos there.
Open dashboard