Overview
Forge integrates with GitHub for authentication, pull request creation, and repository operations.
Base URL: http://localhost:8887/api/github
Authentication
GitHub OAuth Device Flow
Forge uses GitHub’s device flow for authentication.
Step 1: Initiate Device Flow
POST /api/auth/github/device
{
"success": true,
"data": {
"device_code": "abc123...",
"user_code": "ABCD-1234",
"verification_uri": "https://github.com/login/device",
"expires_in": 900,
"interval": 5
}
}
Step 2: Poll for Token
POST /api/auth/github/device/poll
{
"device_code": "abc123..."
}
{
"success": false,
"error": "authorization_pending"
}
{
"success": true,
"data": {
"access_token": "gho_...",
"token_type": "bearer",
"scope": "repo,read:user"
}
}
Pull Requests
Create Pull Request
Create a GitHub PR from task attempt branch (covered in Attempts API).
POST /api/task-attempts/:id/create-pr
curl -X POST http://localhost:8887/api/task-attempts/attempt_abc123/create-pr \
-H "Content-Type: application/json" \
-d '{
"title": "Add authentication system",
"body": "Implements JWT authentication for the application",
"baseBranch": "main",
"draft": false
}'
{
"success": true,
"data": {
"number": 42,
"title": "Add authentication system",
"body": "Implements JWT authentication for the application",
"state": "open",
"author": "forge-bot",
"createdAt": "2024-01-15T10:00:00Z",
"htmlUrl": "https://github.com/owner/repo/pull/42",
"head": "forge/task-abc123-attempt-1",
"base": "main",
"url": "https://api.github.com/repos/owner/repo/pulls/42"
}
}
Attach Existing PR
Link an existing GitHub PR to a task attempt.
POST /api/task-attempts/:id/attach-pr
curl -X POST http://localhost:8887/api/task-attempts/attempt_abc123/attach-pr \
-H "Content-Type: application/json" \
-d '{
"owner": "namastexlabs",
"repo": "automagik-forge",
"prNumber": 42
}'
{
"success": true,
"data": {
"attemptId": "attempt_abc123",
"prUrl": "https://github.com/namastexlabs/automagik-forge/pull/42",
"prNumber": 42,
"attachedAt": "2024-01-15T10:00:00Z"
}
}
Repository Operations
Get Repository Info
Get information about the project’s GitHub repository.
GET /api/projects/:id/github/repository
curl -X GET http://localhost:8887/api/projects/proj_abc123/github/repository
{
"success": true,
"data": {
"owner": "namastexlabs",
"repo": "automagik-forge",
"fullName": "namastexlabs/automagik-forge",
"defaultBranch": "main",
"private": false,
"htmlUrl": "https://github.com/namastexlabs/automagik-forge",
"cloneUrl": "https://github.com/namastexlabs/automagik-forge.git"
}
}
List Pull Requests
List pull requests for a project.
Filter by PR state: open, closed, or all
Page number for pagination
GET /api/projects/:id/github/pulls
curl -X GET "http://localhost:8887/api/projects/proj_abc123/github/pulls?state=open&limit=10"
{
"success": true,
"data": [
{
"number": 42,
"title": "Add authentication system",
"state": "open",
"author": "user",
"createdAt": "2024-01-15T10:00:00Z",
"htmlUrl": "https://github.com/owner/repo/pull/42",
"head": "forge/task-abc123-attempt-1",
"base": "main"
},
{
"number": 41,
"title": "Fix database connection",
"state": "open",
"author": "bot",
"createdAt": "2024-01-14T15:30:00Z",
"htmlUrl": "https://github.com/owner/repo/pull/41",
"head": "forge/task-xyz789-attempt-2",
"base": "main"
}
]
}
Webhooks
Set up GitHub webhook to receive events.
Array of events to subscribe to: pull_request, push, issue_comment, pull_request_review
The webhook endpoint URL to receive GitHub events
POST /api/projects/:id/github/webhook
curl -X POST http://localhost:8887/api/projects/proj_abc123/github/webhook \
-H "Content-Type: application/json" \
-d '{
"events": ["pull_request", "push", "issue_comment"],
"url": "https://forge.yourdomain.com/webhooks/github"
}'
{
"success": true,
"data": {
"webhookId": "webhook_abc123",
"url": "https://forge.yourdomain.com/webhooks/github",
"events": ["pull_request", "push", "issue_comment"],
"active": true,
"createdAt": "2024-01-15T10:00:00Z"
}
}
pull_request - PR opened, closed, mergedpush - Commits pushedissue_comment - Comments on issues/PRspull_request_review - PR reviews
SDK Examples
import { ForgeClient } from '@automagik/forge-sdk';
const forge = new ForgeClient();
// Authenticate with GitHub
const deviceFlow = await forge.auth.github.initiateDeviceFlow();
console.log(`Visit: ${deviceFlow.verification_uri}`);
console.log(`Enter code: ${deviceFlow.user_code}`);
// Poll for token
const token = await forge.auth.github.pollForToken(deviceFlow.device_code);
// Create PR from attempt
const pr = await forge.attempts.createPR('attempt_123', {
title: 'Add authentication',
body: 'Implements JWT auth',
baseBranch: 'main',
draft: false
});
console.log(`PR created: ${pr.url}`);
// List PRs
const prs = await forge.projects.listPRs('proj_123', {
state: 'open'
});
Next Steps
