Docs / Integrations & settings

Updated July 29, 2026 · ~8 min read

GitHub integration

Connecting GitHub turns repositories into projects, gives Heygents' AI a real checkout to work in, and - through the GitHub App - lets an agent open a pull request on a single repo using a token that cannot reach anything else. This page covers both paths, what they do, and exactly what data is used.

Two ways to connect

Heygents supports two GitHub connection models that run side by side:

• Sign in with GitHub (OAuth) - one linked account for the whole Heygents. Best for browsing your repositories, creating projects from them, and letting Heygents clone private repos it needs to work in.
• The GitHub App - installed on exactly the repositories you pick, with short-lived tokens scoped to one repo at a time. This is the model built for shared and multi-user deployments, and the one used for the branch-to-pull-request flow.

In both cases GitHub is an integration, not the login. Heygents' own passphrase gate still protects the dashboard, and the GitHub connection is stored server-side for Heygents as a whole rather than per browser.

Connecting your GitHub account

Open Settings → GitHub from the sidebar and press Sign in with GitHub. You are sent to GitHub's own authorization page, approve the access, and are returned to Heygents' GitHub panel with your account shown.

The access token is stored on the server, never sent to the browser, and never displayed anywhere in the UI. The panel only tells you whether the integration is configured, whether an account is connected, and which login and avatar it belongs to. Disconnect deletes the stored token immediately. If GitHub ever rejects the token - for example after you revoke access on GitHub's side - Heygents clears it and asks you to reconnect.

One-time setup on the GitHub side is required before the button appears: an OAuth App with Heygents' homepage and callback URLs, whose client ID and secret are placed in the server's environment file. That is a hosting step rather than a per-user one; on a hosted Heygents it is already done.

Turning repositories into projects

Once connected, the GitHub panel lists the repositories the account can reach - repos you own, repos you collaborate on, and organisation repos - with the most recently pushed first. Each entry shows its name, description, default branch, primary language, and whether it is private.

Tick the repositories you want and press Create projects from selected. Heygents creates one project per repo and fills in what it can from GitHub: the repository URL, the default branch, the description, and the primary language as a stack tag, plus a unique slug. Repositories already linked to an existing project are marked in the list and skipped, so re-importing never produces duplicates.

The result is a normal Heygents project - it gets tasks, chat, automations, and everything else - that happens to know where its code lives.

Linking an existing project to its repo

If a project already exists, you do not need to recreate it. Open the project's editor and use the From GitHub button, next to Detect, to pick a repository and link it. Detect does the reverse: for a project that already has a working directory, it reads the git remote and current branch straight from disk and auto-fills the repository URL and branch fields, normalising SSH remotes to their https form.

Working directories and auto-cloning

A repo-linked project does not need a manual working directory. The first time you run the AI or the terminal against it, Heygents clones the repository automatically into a folder named after the project's slug and saves that path as the project's directory. Every later run reuses the same clone.

Private repos are cloned using the stored GitHub token, and then the clone's remote is immediately reset to the tokenless URL, so no credential is left sitting on disk. Clones live outside Heygents' own folder, in a sibling clones directory, so cloned code never lands inside Heygents' working tree. If you prefer to manage the checkout yourself, set a working directory explicitly and Heygents will skip cloning entirely.

The GitHub App: per-repo scoped auth

The OAuth path stores a single long-lived token that can reach every repository the account can see. That is acceptable for a personal, single-operator Heygents, but it is the wrong trust model when Heygents is shared or hosted for others. The GitHub App path fixes that:

• You install, you do not paste tokens. You install the app from GitHub's own UI on exactly the repositories you choose, and you can revoke or change that selection there at any time. Heygents never holds a credential broad enough to be dangerous if it leaked.
• Short-lived, least-privilege tokens. Heygents signs a short app assertion and exchanges it for an installation token that lasts about an hour and is scoped to a single repository. Tokens are minted on demand, held only in memory, and never written to disk. An agent working on repo A gets a token that cannot touch repo B, even inside the same installation.
• Minimal permissions. The app only asks for write access to repository contents and pull requests - enough to push a branch and open a PR, and nothing more.
• It stays in sync. A webhook keeps Heygents' record of installations current when you install, uninstall, suspend, or change which repositories are granted.

Start the installation from a Heygents browser where you are already signed in: the setup return URL is protected by the same session gate as the rest of Heygents, and an anonymous setup request is rejected before Heygents talks to GitHub or records anything. The GitHub panel shows which installations exist, which account each belongs to, whether it covers all repositories or a selected set, and how many repositories it reaches - never a token.

Task workspaces and pull requests

The shared clone described above is convenient for chatting about a project, but it is a single checkout - two agents working on the same repo at once would collide. For work that should end in a pull request, Heygents uses an ephemeral per-task workspace instead. Every task gets its own throwaway checkout in a separate task-workspaces directory, so concurrent tasks on the same repository never interfere with each other.

The flow is deliberately narrow:

• 1. Isolate. Heygents mints a repo-scoped token, shallow-clones the base branch into a fresh workspace, and checks out a new branch named for the task. The token is stripped from the clone's git config right after cloning, so the tree the agent edits holds no credential.
• 2. Work and commit. The agent writes its changes in that directory, and Heygents stages and commits them under a dedicated bot identity, so agent commits are always distinguishable from yours.
• 3. Push and open a PR. The branch is pushed with the token supplied only transiently through a credential helper, so it never appears in a command line or on disk, and a pull request is opened against the base branch.
• 4. Clean up. The workspace is destroyed once the run finishes, unless it is explicitly kept for debugging.

Human review is always required. Heygents never merges. The end product of an agent task is a pull request you read, question, and merge yourself. Note also that this is filesystem and branch isolation between tasks, not a full security sandbox - treat repositories you do not trust accordingly.

What data is used

It is worth being precise about what crosses the line and what does not:

• Read from GitHub: your account login and avatar, and repository metadata - full name, description, default branch, primary language, visibility, and last push time - used to populate the repo picker and fill new projects. Repository contents are read by cloning, on the machine, when a run needs them.
• Written to GitHub: only what a task workspace produces - a branch, its commits, and a pull request. Nothing else is pushed, and nothing is merged.
• Stored by Heygents: the OAuth token, server-side and git-ignored, plus a record of GitHub App installations that contains no secret. Installation tokens are never persisted at all.
• Never stored or shown: any token in the browser, in the UI, in logs, or in a project's checkout.

Frequently asked questions

Do I need both OAuth and the GitHub App?

No, they run alongside each other. OAuth is the simplest way to import repositories and let Heygents clone them, and it stores one long-lived token for the whole Heygents. The GitHub App is what you want for scoped access and the pull request flow, because its installation tokens last about an hour and reach a single repository at a time.

Can the AI push to my main branch?

No. Agent work lands on a fresh branch created in an ephemeral per-task workspace and arrives as a pull request against the base branch, and automation prompts forbid pushing outright. Heygents never merges: the end product of an agent task is a pull request you read, question and merge yourself, so human review is always required.

What happens if I revoke access on GitHub?

Heygents notices the rejected token, clears it, and asks you to reconnect. Existing local clones stay where they are but can no longer be refreshed from a private repo until you reconnect. The Disconnect button in the GitHub panel does the same thing deliberately, deleting the stored token immediately rather than leaving it on the server.

Where do cloned repositories live?

In a clones directory that sits beside Heygents' own folder, never inside it, with one folder per project slug. Private repos are cloned using the stored GitHub token, and the clone's remote is immediately reset to the tokenless URL so no credential is left on disk. The location is configurable by whoever hosts Heygents.