| title | Connect GitHub |
|---|---|
| description | One control, one label, and no token to paste: how Cortex Code reaches your repositories, and what every failure message means. |
| icon | github |
Cortex Code needs a repository to work on, and it gets one by connecting your GitHub account from inside the product. The connection is what lets Code list your repositories, prepare a session's runtime from one of them, and open a pull request when the work is done. Without it, the composer has nothing to point a session at.
There is exactly one control for this, it has one label per state, and there is no token to paste, anywhere. No personal access token field exists on any Cortex surface, and there is no fallback to one. This page covers the control, the four places it appears, what the connection is and is not, every message the connection can show you, and how to revoke it.
Connecting GitHub gives Code three things: the list of repositories you can choose from, a clone in the runtime a session attaches, and the ability to push a Cortex-owned branch and open a pull request from it. Pushes stay on Cortex-owned branches, so the agent cannot push over your default branch.
It is not a connected app reaching into your session. A Code session is built with no tool servers, no connectors and no plugins of its own, and access you have granted in Chat or in Bot does not carry into Code: a session's own tools list can say as much. GitHub is not an exception dressed up as a connector; it is the repository source and the destination for a pull request. See [Code integrations](/code/integrations).| State | What you see | What it means |
|---|---|---|
| Not connected | Connect GitHub, with the note Connect GitHub to list your repositories and open pull requests. | press it to start |
| Expired | Reconnect GitHub | the connection lapsed; it asks to be reconnected, not connected |
| Connected | no control and no note | there is nothing to do |
| Not available on this deployment | no control at all | the control is absent, not greyed out, because this deployment has no GitHub app to connect to |
The same control, with the same label, appears in every place Cortex might reasonably ask you for it: the Code Integrations page, Settings → Integrations, the repository picker in the composer, and the getting-started row Connect your GitHub account. Whichever one you press, it is the same connection.
A guest who presses it goes to sign-in, not to GitHub. Holding a connection requires an account, so the invitation comes first.
Then open Code. A guest can browse and type, but cannot hold a connection. From the Code **Integrations** page, from **Settings → Integrations**, or straight from the repository picker in the composer, which offers the control instead of an empty list when there is nothing to list. GitHub shows you its own consent screen and you decide there which repositories Cortex may see. Nothing in Cortex asks you for a credential, before or after. You return to a page that reads **Connecting GitHub** and **Finishing the connection…**, with **Cortex is finishing the connection with GitHub. This takes a moment.** It then reads **GitHub is connected. Taking you back…** (or `GitHub is connected as {label}. Taking you back…`, with the account it connected) and returns you where you started. Back in the composer, the first chip is **Choose a repository** and the second is **Branch**. See [Repositories and branches](/code/repositories).Every one of these messages ends the same way: Nothing was changed. Connecting is all or nothing, so a failure leaves you exactly where you were and you can simply try again.
| Message | What happened | What to do |
|---|---|---|
| GitHub was not connected + Nothing was changed. Cortex Code needs a connected GitHub account to list your repositories and open pull requests. | you pressed Cancel on GitHub's consent screen | nothing is wrong; this is a decision, not an error. Press Connect GitHub again when you want to |
| The connection did not finish + Cortex could not finish the connection with GitHub. Nothing was changed. | the round trip broke off | start again from Connect GitHub |
| GitHub did not complete the connection + Try connecting again. Nothing was changed. | GitHub answered with a failure | try again |
| GitHub took too long + The connection was abandoned rather than left hanging. Try connecting again. | GitHub did not answer in time | try again |
| GitHub is not available to connect + GitHub isn't available to connect right now. | GitHub is unreachable for now | wait and try again |
| This connection attempt is no longer valid + Start again from Connect GitHub. Nothing was changed. | the attempt went stale or was already used | begin a fresh attempt rather than reloading the old one |
You may also see the flat label GitHub could not be connected. The callback page carries Back to Code, and on a failure it offers a fresh Connect GitHub that returns you to the Code integrations page.
Cortex does not publish how long a connection lasts. You find out the ordinary way: the control reads Reconnect GitHub, which you press, approving on GitHub once more.
Revoke the connection from GitHub's own settings. Cortex has no disconnect button of its own that we can point you at, and revoking on GitHub always works: afterwards Cortex reports the connection as needing reconnection, or as not connected, and the repository list goes quiet until you connect again.
This is the most common confusion in the area, so it is worth stating plainly. Three separate things install against GitHub, and having one does not give you another.
| Install | What it is for | Where it is documented |
|---|---|---|
| Connect GitHub | lets Code list your repositories and open pull requests | this page |
| The Cortex Security GitHub App | lets Cortex Security read pull requests and post checks | Pull-request review and Cortex Security |
| The Cortex CLI's own install command | wires the CLI to GitHub | Cortex CLI |
- Repositories and branches for choosing what a session works on.
- Code integrations for connected apps, repositories and tool servers.
- Code quickstart for a first session end to end.
- Pull-request review for the separate Security install.
- Code troubleshooting when a repository you expect is not listed.