# GitHub Integration

Source: https://docs.ops0.com/docs/settings/integrations/github

ops0 integrates with GitHub for version control of IaC projects, configurations, and discovery-generated code. Two authentication methods are available.

---

## Authentication Methods

| Method | Best for |
|--------|----------|
| **GitHub App** | Teams — fine-grained permissions, no personal token dependency, survives token rotation |
| **Personal Access Token (PAT)** | Individual developers or quick setup |

---

## GitHub App (Recommended)

The GitHub App installation grants ops0 access to specific repositories in your GitHub organization without tying access to a personal account.

### Navigate to Integrations
Go to **Settings** → **Integrations** → **Add Integration** → **GitHub**.

### Click Install GitHub App
Click the **Install GitHub App** button.

### Select your GitHub organization
Choose the GitHub organization or personal account where you want to install the app.

### Choose repository access
Select **All repositories** or choose specific repositories ops0 should access.

### Complete installation
GitHub redirects back to ops0. The integration is created automatically.

### What the GitHub App Can Do

| Permission | Level | Purpose |
|------------|-------|---------|
| **Contents** | Read & Write | Read and push files to repositories |
| **Pull requests** | Read & Write | Create pull requests from ops0 |
| **Metadata** | Read | List repositories and branches |

### Revoking Access

If the GitHub App is uninstalled from your GitHub organization, ops0 detects the revocation via webhook and marks the integration as **Revoked**. A banner appears in the integrations page. Re-install the app to restore access.

---

## Personal Access Token (PAT)

### Create a GitHub token
Go to GitHub → **Settings** → **Developer settings** → **Personal access tokens** → **Fine-grained tokens** (or classic).

For classic tokens, select scopes: `repo`, `read:org`.

### Navigate to Integrations
Go to **Settings** → **Integrations** → **Add Integration** → **GitHub**.

### Choose PAT authentication
Select **Personal Access Token**.

### Enter the token
Paste the token and click **Connect**.

**PAT tokens expire**

GitHub fine-grained tokens have a maximum expiry of one year. When your token expires, all GitHub operations in ops0 will fail. Update the token in the integration settings before it expires.

---

## Integration Purpose

When connecting a GitHub repository to an ops0 project, you select the **purpose** of the connection. This controls how the repository is used:

| Purpose | Description |
|---------|-------------|
| **General** | Default — repository is used for any ops0 project type |
| **IaC** | Repository hosts Terraform/OpenTofu/CloudFormation code |
| **Configurations** | Repository hosts Ansible playbooks or Kubernetes manifests |
| **Discovery** | Repository is the destination for discovery-generated code |
| **Assets** | Repository hosts non-code assets (templates, blueprints, etc.) |

Setting the correct purpose helps ops0 filter and surface the right repositories in each context.

---

## What You Can Do With the Integration

### IaC Project Sync

Link an IaC project to a GitHub repository to push and pull Terraform code:

- **Push** — commit the current project files to a branch
- **Pull** — fetch and apply the latest code from a branch
- **Create PR** — open a pull request with the current project's changes

See [GitHub Sync](https://docs.ops0.com/docs/iac/github-sync) for the full workflow.

### Push Discovery Code

After generating Terraform code from a discovery session, push the generated files directly to a GitHub repository:

1. In the Discovery Wizard code view, click **Push to GitHub**
2. Select the integration, repository, and target branch
3. Optionally check **Create Pull Request** to open a PR instead of a direct push

### Sync Asset Inventory

Push a structured inventory of your discovered cloud resources to a GitHub repository for audit, compliance, or documentation purposes. Trigger from the discovery session actions menu.

### Sync Workflow Files

Push ops0 workflow definitions to a GitHub repository for version control and peer review.

### Sync Configuration Projects

Push Ansible playbook files and Kubernetes manifests to GitHub as part of your GitOps workflow.

---

## Managing the Integration

| Action | How |
|--------|-----|
| **Refresh repositories** | Click **Refresh** in the integration settings to re-sync the repository list |
| **Update repository access** | For GitHub App: re-configure the installation in your GitHub org settings |
| **Delete integration** | Click **Delete** — removes the integration from ops0. Does not uninstall the GitHub App from GitHub. |

---

## Troubleshooting

- **Integration shows Revoked**: The GitHub App was uninstalled. Re-install the app via the Install GitHub App button.

- **Repository not listed**: For GitHub App: check the app's repository access in your GitHub org settings. For PAT: ensure the token has repo scope.

- **PR creation failed**: Verify the target repository allows PR creation and the integration has write access to contents and pull requests.

- **Token expired**: Generate a new PAT in GitHub and update it in Settings → Integrations → (your GitHub integration) → Edit.

---

## Related

- [IaC GitHub Sync](https://docs.ops0.com/docs/iac/github-sync): Two-way sync between IaC projects and GitHub repositories.

- [GitLab Integration](https://docs.ops0.com/docs/settings/integrations/gitlab): Connect GitLab for token-based repository sync.

- [Integrations Overview](https://docs.ops0.com/docs/settings/integrations): Return to the shared integrations overview.