# Github Integration

Think of GitHub as your project’s source of truth for code, history, and collaboration. Each repository stores your files and every code change over time, so your team can review, ship, and maintain your app more easily.

### Overview

If you want your app code in your own GitHub account, ask Cody to move it from your CodeWords project to a repository you control.

You can do this in two ways:

| Method                                 | Setup needed                       | Best for                                   |
| -------------------------------------- | ---------------------------------- | ------------------------------------------ |
| Connected GitHub account (recommended) | Connect GitHub in chat (no token)  | Most users                                 |
| Personal access token (PAT)            | Create token with repo permissions | OAuth unavailable or blocked by org policy |

\
Method one: connected GitHub account (recommended)

This is the simplest setup. Cody uses your connected GitHub account to create a repository and push your project code directly.

#### What to tell Cody

Move this project code to a private repo on my GitHub account.

#### What happens

1. Cody asks you to connect GitHub (one-time OAuth).
2. Cody creates a private repository on your account.
3. Cody pushes all project files in one initial commit.
4. Cody shares the repository link.

#### How it works

Cody uses the GitHub API through your connected account to:

* Create a private repository.
* Read files from your CodeWords-managed project.
* Commit and push everything in one atomic operation.

No PAT, terminal setup, or git credentials are required.

#### Limitations

* Commit history is not preserved. Your new repository starts with a single initial commit.
* Large binary files may hit GitHub API size limits.

### Method two: personal access token (PAT)

Use this if you need full commit history, or if your organization blocks OAuth connections.

#### Before you start

Make sure you have:

* A destination GitHub repository.
* Its URL, for example `https://github.com/OWNER/REPO.git`.
* Permission to push.

#### Create a PAT

Recommended: fine-grained PAT.

Set:

* Repository access: `Only select repositories` and choose your destination repo.
* Repository permission: `Contents: Read and write`.

If you also migrate workflow files in `.github/workflows/*`, set:

* `Workflows: Read and write`.

Alternative: classic PAT.

* Private repos: `repo` scope.
* Public-only repos: `public_repo` scope.

#### What to tell Cody

Move this project code to my GitHub repository:<https://github.com/OWNER/REPO.gitI> have a PAT ready with the correct scopes.

When asked, paste the token in chat. Cody stores it securely and uses it for push operations.

#### After push

* Revoke or rotate one-time tokens.
* Ask Cody to delete stored PAT secrets if no longer needed.

### Keep both repositories in sync

After migration, Cody can push updates to both your CodeWords-managed repository and your personal GitHub repository.  We do not support abaility to connect your personal github as the main branch.

#### What to tell Cody

When you make changes, also push them to my personal GitHub repo.

#### Typical flow

* Cody applies changes in CodeWords.
* Cody pushes the same changes to your GitHub repository.
* Cody deploys to `*.codewords.run`.
* If Vercel is connected, your GitHub-based deployment auto-deploys.

### Optional: deploy from your own Vercel project

If you deploy from your personal repository in Vercel, add these environment variables:

| Key                     | Value                          |
| ----------------------- | ------------------------------ |
| `CODEWORDS_API_KEY`     | Your CodeWords API key         |
| `CODEWORDS_RUNTIME_URI` | `https://runtime.codewords.ai` |

These are required for backend API calls from your deployed app.

### Security best practices

* Prefer connected GitHub account when possible.
* Treat PATs like passwords.
* Use fine-grained PATs scoped to one repository.
* Set token expiration dates.
* Never commit or share tokens in code, logs, or screenshots.
* Revoke tokens after one-time migrations.

### Troubleshooting

| Issue                                          | Solution                                                           |
| ---------------------------------------------- | ------------------------------------------------------------------ |
| GitHub connection popup fails                  | Use PAT method                                                     |
| Push fails with `403 Write access not granted` | Token permissions are insufficient; regenerate with correct scopes |
| Push fails when workflow files change          | Add `Workflows: Read and write` permission                         |
| Organization repo requires SSO                 | Authorize token for SSO in org settings                            |
| Vercel deploy shows server configuration error | Add `CODEWORDS_API_KEY` and `CODEWORDS_RUNTIME_URI`                |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.codewords.ai/website-builder/github-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.