---
title: GitHub & GitLab Setup
description: Connect GitHub and GitLab repositories to TaskView. Import and sync issues as tasks with OAuth authorization, webhook-based real-time updates, and AES-256 encrypted token storage. Supports GitHub Enterprise and self-hosted GitLab.
navigation:
  icon: i-lucide-git-pull-request
---

TaskView integrations allow you to connect GitHub or GitLab repositories to your projects. After connecting, issues from the repository are synced as tasks in TaskView and kept up to date via webhooks.

## Prerequisites

- TaskView API running
- PostgreSQL database with migrations applied
- `.env.taskview` file configured

---

## 1. Database Migration

The migration creates the required tables (`tasks.integrations` and `tasks.integration_task_map`) automatically. The migration container handles this on startup - no manual steps needed. Just make sure you've run `docker compose up` and the migration container completed successfully.

---

## 2. Generate Encryption Key

Tokens are encrypted with AES-256-GCM. You need a 32-byte hex key (64 characters):

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Add it to `.env.taskview`:

```
ENCRYPTION_KEY=<your-64-char-hex-key>
```

---

## 3. Create GitHub OAuth App

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Click **"New OAuth App"**
3. Fill in:
   - **Application name**: `TaskView Integrations` (or any name)
   - **Homepage URL**: `http://localhost:3000` (your frontend URL)
   - **Authorization callback URL**: `http://localhost:1401/module/integrations/oauth/github/callback`
4. Click **"Register application"**
5. Copy **Client ID** and generate a **Client Secret**

Add to `.env.taskview`:

```
GITHUB_INTEGRATION_CLIENT_ID=<your-client-id>
GITHUB_INTEGRATION_CLIENT_SECRET=<your-client-secret>
GITHUB_INTEGRATION_CALLBACK_URL=http://localhost:1401/module/integrations/oauth/github/callback
```

> **Note**: This is a separate OAuth App from the one used for login (`GITHUB_CLIENT_ID`). The integrations app requests `repo` scope, while the login app only requests `user:email`.

---

## 4. Create GitLab OAuth App (optional)

1. Go to [GitLab Applications](https://gitlab.com/-/user_settings/applications)
2. Click **"New application"**
3. Fill in:
   - **Name**: `TaskView Integrations`
   - **Redirect URI**: `http://localhost:1401/module/integrations/oauth/gitlab/callback`
   - **Scopes**: check `api`
4. Click **"Save application"**
5. Copy **Application ID** and **Secret**

Add to `.env.taskview`:

```
GITLAB_INTEGRATION_CLIENT_ID=<your-application-id>
GITLAB_INTEGRATION_CLIENT_SECRET=<your-secret>
GITLAB_INTEGRATION_CALLBACK_URL=http://localhost:1401/module/integrations/oauth/gitlab/callback
```

---

## 5. Full `.env.taskview` Example

```env
# ... existing vars ...

# Encryption (required for integrations)
ENCRYPTION_KEY=a1b2c3d4e5f6...  # 64 hex characters

# GitHub Integration OAuth
GITHUB_INTEGRATION_CLIENT_ID=Iv1.abc123
GITHUB_INTEGRATION_CLIENT_SECRET=secret_abc123
GITHUB_INTEGRATION_CALLBACK_URL=http://localhost:1401/module/integrations/oauth/github/callback

# GitLab Integration OAuth (optional)
GITLAB_INTEGRATION_CLIENT_ID=app_id_123
GITLAB_INTEGRATION_CLIENT_SECRET=secret_123
GITLAB_INTEGRATION_CALLBACK_URL=http://localhost:1401/module/integrations/oauth/gitlab/callback
```

---

## 6. Usage

1. Open a project in TaskView
2. Right-click the project in the sidebar → **"Integrations"**
3. Click **"Add Integration"**
4. Choose **GitHub** or **GitLab** - you'll be redirected to authorize
5. After authorization, select a repository from the list
6. Done - the integration is active

You can toggle integrations on/off or delete them from the integrations page.

---

## Production Notes

- **Callback URLs**: Update to your production domain (e.g., `https://api.yourdomain.com/module/integrations/oauth/github/callback`)
- **ENCRYPTION_KEY**: Store securely, never commit to git. If changed, existing encrypted tokens become unreadable
- **Separate OAuth Apps**: Create new GitHub/GitLab OAuth Apps for production with production callback URLs
- **CORS**: Ensure your production frontend domain is in `CORS_ALLOWED_ORIGINS`

---

## API Endpoints

Watch in the source code.

---

## Troubleshooting

**"GitHub integration OAuth is not configured"**
→ `GITHUB_INTEGRATION_CLIENT_ID` or `GITHUB_INTEGRATION_CALLBACK_URL` is missing in `.env`

**"ENCRYPTION_KEY must be a 64-character hex string"**
→ Generate a key: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`

**OAuth redirects to wrong URL after callback**
→ Check that `APP_URL` in `.env` matches your frontend URL (e.g., `http://localhost:3000`)

**Empty repo list after OAuth**
→ The token may have expired or the integration record wasn't created. Check server logs and re-authorize.