# GitHub Integration {#github-integration}


Bi-directional synchronization between GitHub repositories and Gauzy projects/tasks.


## Features {#features}


- **Issue sync** — GitHub issues ↔ Gauzy tasks
- **PR linking** — link pull requests to tasks
- **Status sync** — issue status maps to task status
- **Label sync** — GitHub labels map to task tags
- **Webhook events** — real-time updates via webhooks
- **Multi-repo** — connect multiple repositories


## Setup {#setup}



### 1. Install GitHub App {#1-install-github-app}


Navigate to **Settings → Integrations → GitHub** and install the Gauzy GitHub App on your organization.


### 2. Configure Repository Mapping {#2-configure-repository-mapping}


Map GitHub repositories to Gauzy projects:

| GitHub Repo    | →   | Gauzy Project |
| -------------- | --- | ------------- |
| `org/frontend` | →   | Frontend App  |
| `org/backend`  | →   | Backend API   |


### 3. Entity Sync Settings {#3-entity-sync-settings}


| Entity               | Sync Direction | Default |
| -------------------- | :------------: | :-----: |
| Issues → Tasks       |   ✅ Import    |   On    |
| Tasks → Issues       |   ✅ Export    |   Off   |
| Labels → Tags        |   ✅ Import    |   On    |
| Milestones → Sprints |   ✅ Import    |   Off   |


## Configuration {#configuration}


```bash
GAUZY_GITHUB_APP_ID=123456
GAUZY_GITHUB_APP_NAME=ever-gauzy-dev
GAUZY_GITHUB_APP_PRIVATE_KEY=base64-encoded-private-key
GAUZY_GITHUB_WEBHOOK_SECRET=your-webhook-secret
GAUZY_GITHUB_CALLBACK_URL=https://api.yourdomain.com/api/integration/github/callback
GAUZY_GITHUB_POST_INSTALL_URL=https://app.yourdomain.com/pages/integrations/github/setup
```


## Webhook Events {#webhook-events}


Handled webhook events:

| Event                  | Action               |
| ---------------------- | -------------------- |
| `issues.opened`        | Create task          |
| `issues.edited`        | Update task          |
| `issues.closed`        | Close task           |
| `issues.reopened`      | Reopen task          |
| `issues.labeled`       | Add tag              |
| `issues.unlabeled`     | Remove tag           |
| `pull_request.opened`  | Link PR to task      |
| `pull_request.merged`  | Update task status   |
| `installation.created` | Activate integration |


## Status Mapping {#status-mapping}


| GitHub Issue State | Gauzy Task Status |
| ------------------ | ----------------- |
| `open`             | Open              |
| `closed`           | Done              |


## Related Pages {#related-pages}


- [Integrations Overview](https://sourcey-gauzy.pages.dev/integrations/integrations-overview/index.md)
- [Task Management](https://sourcey-gauzy.pages.dev/features/task-management/index.md)
- [Integration Endpoints](https://sourcey-gauzy.pages.dev/api/integration-endpoints/index.md)