# GitHub

Connect GitHub once and every <Term id="project">project</Term> in your <Term id="workspace">workspace</Term> can link a repository. Each push can then <Term id="deploy">deploy</Term> your app.

<Screenshot src="/docs/_media/github-connector-cover.png" alt="A project deploying from a linked GitHub repository" />

## Before you start [#before-you-start]

<Callout type="warn" title="Owners and admins only">
  Only workspace owners and admins can connect or disconnect GitHub. Everyone else sees **Ask an admin to connect** and uses the repositories an admin connected. See [Members and roles](/docs/workspace/members).
</Callout>

- **GitHub access.** Permission to install apps on the GitHub account or organization that owns the repositories.

## Connect GitHub [#connect-github]

<ForEveryone>
<Steps>
<Step>
### Start the connection [#start-the-connection]
Go to <AppLink to="connectors" />, open **GitHub** and select **Connect**. You can also connect it from <AppLink to="settings.connected-accounts" /> or from **Connect GitHub** on Home.
</Step>
<Step>
### Install the Klarety app on GitHub [#install-the-klarety-app-on-github]
Choose the account or organization, then **only the repositories** behind your apps. Klarety sees only these.
</Step>
<Step>
### Check it worked [#check-it-worked]
Back in Klarety, GitHub shows **Connected**. <Term id="studio">Studios</Term> can now link a repository.
</Step>
</Steps>
</ForEveryone>

<ForDevelopers>
```python title="connect_github.py"
from klarety import Nexus

nx = Nexus.connect("YOUR_API_KEY")

if not nx.github.connected():
    print("Open this in a browser:", nx.github.install_url(return_to="/"))

print(nx.github.repositories())
```

`install_url` returns the GitHub page to open; you return to `return_to`. `repositories()` lists the repositories Klarety can reach.
</ForDevelopers>

## Link a repository to a project [#link-a-repository-to-a-project]

A project saves its code to one repository and deploys from it.

<Steps>
<Step>
### When you create the project [#when-you-create-the-project]
In **Connect GitHub**, choose a repository, or create a **New repository**.
</Step>
<Step>
### Or later, in the project [#or-later-in-the-project]
In the project's **Settings**, under **Deploy**, **Code**, choose a **Repository**. A Studio picks it up when it next opens.
</Step>
<Step>
### Choose the branch that goes live [#choose-the-branch-that-goes-live]
In **Deploys from**, type a branch, or leave it empty for the default branch. Merges to it go live. Select **Save**.
</Step>
</Steps>

<Screenshot src="/docs/_media/github-connector-2.png" alt="Source control in a Studio, with commits on the linked repository" />

### Repository not listed? [#repository-not-listed]

Select **Repository not listed?** to change which repositories Klarety can reach, including a new one. You return straight to the project.

## Work with the repository in the Studio [#work-with-the-repository-in-the-studio]

Commits you or the AI make in the Studio are pushed to the linked repository. You can review changes side by side before they go live.

<Screenshot src="/docs/_media/github-connector-1.png" alt="Comparing two versions of a file in the Studio" />

Pushes to the deploy branch start a deploy. See [Deploy your app](/docs/deploy/deploy-an-app).

## Change the repository [#change-the-repository]

In the project's **Settings**, **Danger zone**, select **Change repository**. The project then saves to and goes live from the new one. The Studio opens it on its next start and keeps the old work in its own branches. For a different app, create a new project.

## Disconnect GitHub [#disconnect-github]

Open GitHub on <AppLink to="connectors" />, open the options next to **Connected** and select **Disconnect**, then **Disconnect GitHub**.

<Callout type="warn" title="What disconnecting stops">
  The Klarety app is removed from your GitHub organization. Until it is reconnected, pushes stop deploying and Studios cannot push to GitHub. Your repositories and code are not touched.
</Callout>

## Troubleshooting [#troubleshooting]

| What you see | What to do |
| --- | --- |
| **Ask an admin to connect** | You are not an owner or admin. Ask one to connect GitHub. |
| **GitHub is not connected** in project settings | A workspace admin connects it once for every project. |
| **GitHub could not be reached.** | Try again in a moment. |
| A push does not deploy | Check the project's **Deploys from** branch and that GitHub is still **Connected**. |

## Next steps [#next-steps]

- [Deploy your app](/docs/deploy/deploy-an-app)
- [How connectors work](/docs/connectors)
- [Create a project](/docs/projects/create-a-project)