GitHub & GitLab Setup

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):

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
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
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

# ... 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.