Git, GitHub, and pull requests

Every workspace is a Git repository. Commit from the workspace, then push branches and open pull requests on GitHub, as you, without your GitHub token ever entering the workspace.

#Connect GitHub

1. Link your GitHub account: choose Connect GitHub on your workspace home, or Connect next to GitHub under Settings → Security. Signing up with GitHub links it too.
2. Give CoDev access to your repositories. Right after you connect, CoDev asks for this under Choose your repositories: choose Choose repositories on GitHub, install CoDev's app on your account and keep All repositories selected, so any of them opens in a workspace. Add any organization whose repositories you work on too (an admin may need to approve it), then come back to CoDev, which carries on by itself. To change it later, use Settings → Integrations → Manage repository access.

When you create a workspace from GitHub, the GitHub account menu lists you and your organizations. If you see Give CoDev access to some, CoDev can't open any of that account's repositories yet.

The CoDev GitHub App asks to read and write repository contents and pull requests, and to read issues and metadata.

#Commit

Open the Changes tab:

1. Every changed file has a checkbox, all checked by default. Uncheck anything you don't want in this commit.
2. Write a Commit message.
3. Choose Commit (the button shows how many files are checked), or press ⌘ Enter.

Commits you make here use your name and email. Agents commit with Git as they work, too, but they never push: pushing always goes through CoDev, as you.

#Push and open a pull request

In a workspace with live main (the default), work reaches GitHub when it ships: commit in your own worktree, mark it ready and choose Ship at the top of the right-hand panel. Changes then shows that instead of Push and Open pull request, and /push, /pr and agents' push requests are refused. See Live main and shipping. The rest of this section is for workspaces with live main off.

In the Changes tab, after committing:

• Publish branch pushes a new branch to GitHub. After that, the button shows Push and how many commits are waiting.
• Open pull request appears once the branch is on GitHub, and opens a pull request against your default branch, titled and described from the branch's commits. If the branch already has an open pull request, CoDev shows that one instead.

You can also type /push or /pr <title> in the chat, or let an agent ask to push (see permission levels).

Rules CoDev follows when pushing:

• Pushes are fast-forward only, so they never overwrite commits on GitHub.
• CoDev never pushes your default branch directly; changes to it go through a pull request.
• If GitHub's branch protection refuses a push, CoDev tells you.

#Branches and worktrees

The branch menu in the top bar lists the branches open in the workspace and your GitHub branches. Open on a GitHub branch opens it in its own worktree; New branch… creates one; Find a branch filters the list.

To merge a finished worktree into main inside the workspace, use Merge into main in the Review tab, in a workspace with live main off or without a GitHub repository. See Parallel worktrees.

#Pull from GitHub

CoDev brings your repository's default branch from GitHub into main on its own: while the workspace is running, it checks every few minutes and merges what's new, then brings idle worktrees up to date with main. It waits while an agent is working in main, or when GitHub's changes would touch uncommitted changes in main or conflict with commits made there; other uncommitted changes stay as they are. If GitHub's changes conflict with main, an agent resolves them in main for you to review, unless the owner turned that off in the workspace's settings.

#Private repositories

On Pro and higher plans, including Teams, CoDev clones a private repository whole, with its Git history, whatever its size. Opening one of its GitHub branches downloads that branch's latest files with your GitHub account. Older versions of files aren't downloaded, so Git commands that read them, such as git show of an earlier commit, fail.

On Pay as you go, private repositories arrive as a snapshot of the default branch, without its Git history or other branches (up to 500 files and 3 MiB).

A snapshot can still commit, push, open pull requests and pull from GitHub. A push replays its commits onto the repository's history on GitHub (up to 1,000 commits).

#How pushing stays safe

Anyone who can edit a workspace, and any agent, can change its Git config and hooks. So CoDev never puts your GitHub token in the workspace. When you push, CoDev runs the push from a separate, isolated account using a throwaway copy of your repository, with your token, and then discards it. See Security and privacy.

For the same reason, Git commands an agent runs skip the repository's Git hooks, such as a pre-commit check; your own terminal still runs them.