GitHub Integration

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

const response = await fetch('http://localhost:8887/api/task-attempts/attempt_abc123/create-pr', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Add authentication system',
    body: 'Implements JWT authentication for the application',
    baseBranch: 'main',
    draft: false
  })
});

const data = await response.json();
console.log(`PR created: ${data.data.htmlUrl}`);

import requests

response = requests.post(
    'http://localhost:8887/api/task-attempts/attempt_abc123/create-pr',
    json={
        'title': 'Add authentication system',
        'body': 'Implements JWT authentication for the application',
        'baseBranch': 'main',
        'draft': False
    }
)

data = response.json()
print(f"PR created: {data['data']['htmlUrl']}")

{
  "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"
  }
}

{
  "success": false,
  "error": "github_auth_required",
  "message": "GitHub authentication is required. Please authenticate first."
}

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

Response:

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

Request:

{
  "device_code": "abc123..."
}

Response (pending):

{
  "success": false,
  "error": "authorization_pending"
}

Response (success):

{
  "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).

string

required

The task attempt ID

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

const response = await fetch('http://localhost:8887/api/task-attempts/attempt_abc123/create-pr', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Add authentication system',
    body: 'Implements JWT authentication for the application',
    baseBranch: 'main',
    draft: false
  })
});

const data = await response.json();
console.log(`PR created: ${data.data.htmlUrl}`);

import requests

response = requests.post(
    'http://localhost:8887/api/task-attempts/attempt_abc123/create-pr',
    json={
        'title': 'Add authentication system',
        'body': 'Implements JWT authentication for the application',
        'baseBranch': 'main',
        'draft': False
    }
)

data = response.json()
print(f"PR created: {data['data']['htmlUrl']}")

{
  "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"
  }
}

{
  "success": false,
  "error": "github_auth_required",
  "message": "GitHub authentication is required. Please authenticate first."
}

See Attempts API - Create GitHub PR for details.

Attach Existing PR

Link an existing GitHub PR to a task attempt.

string

required

The task attempt ID

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

const response = await fetch('http://localhost:8887/api/task-attempts/attempt_abc123/attach-pr', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    owner: 'namastexlabs',
    repo: 'automagik-forge',
    prNumber: 42
  })
});

const data = await response.json();
console.log('PR attached successfully');

import requests

response = requests.post(
    'http://localhost:8887/api/task-attempts/attempt_abc123/attach-pr',
    json={
        'owner': 'namastexlabs',
        'repo': 'automagik-forge',
        'prNumber': 42
    }
)

print('PR attached successfully')

{
  "success": true,
  "data": {
    "attemptId": "attempt_abc123",
    "prUrl": "https://github.com/namastexlabs/automagik-forge/pull/42",
    "prNumber": 42,
    "attachedAt": "2024-01-15T10:00:00Z"
  }
}

{
  "success": false,
  "error": "pr_not_found",
  "message": "Pull request #42 not found in namastexlabs/automagik-forge"
}

See Attempts API - Attach Existing PR for details.

Repository Operations

Get Repository Info

Get information about the project’s GitHub repository.

string

required

The project ID

GET /api/projects/:id/github/repository

curl -X GET http://localhost:8887/api/projects/proj_abc123/github/repository

const response = await fetch('http://localhost:8887/api/projects/proj_abc123/github/repository');
const data = await response.json();
console.log(`Repository: ${data.data.fullName}`);
console.log(`Default branch: ${data.data.defaultBranch}`);

import requests

response = requests.get('http://localhost:8887/api/projects/proj_abc123/github/repository')
data = response.json()

print(f"Repository: {data['data']['fullName']}")
print(f"Default branch: {data['data']['defaultBranch']}")

{
  "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"
  }
}

{
  "success": false,
  "error": "project_not_found",
  "message": "Project proj_abc123 not found"
}

List Pull Requests

List pull requests for a project.

string

required

The project ID

string

default:"open"

Filter by PR state: open, closed, or all

integer

default:"1"

Page number for pagination

integer

default:"20"

Items per page (max 100)

GET /api/projects/:id/github/pulls

curl -X GET "http://localhost:8887/api/projects/proj_abc123/github/pulls?state=open&limit=10"

const response = await fetch(
  'http://localhost:8887/api/projects/proj_abc123/github/pulls?state=open&limit=10'
);
const data = await response.json();

data.data.forEach(pr => {
  console.log(`PR #${pr.number}: ${pr.title} (${pr.state})`);
  console.log(`  Author: ${pr.author}`);
  console.log(`  Created: ${pr.createdAt}`);
});

import requests

response = requests.get(
    'http://localhost:8887/api/projects/proj_abc123/github/pulls',
    params={
        'state': 'open',
        'limit': 10
    }
)

data = response.json()
for pr in data['data']:
    print(f"PR #{pr['number']}: {pr['title']} ({pr['state']})")
    print(f"  Author: {pr['author']}")
    print(f"  Created: {pr['createdAt']}")

{
  "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"
    }
  ]
}

{
  "success": false,
  "error": "project_not_found",
  "message": "Project proj_abc123 not found"
}

Webhooks

Configure Webhook

Set up GitHub webhook to receive events.

string

required

The project ID

array

required

Array of events to subscribe to: pull_request, push, issue_comment, pull_request_review

string

required

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"
  }'

const response = await fetch('http://localhost:8887/api/projects/proj_abc123/github/webhook', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: ['pull_request', 'push', 'issue_comment'],
    url: 'https://forge.yourdomain.com/webhooks/github'
  })
});

const data = await response.json();
if (data.success) {
  console.log('Webhook configured successfully');
}

import requests

response = requests.post(
    'http://localhost:8887/api/projects/proj_abc123/github/webhook',
    json={
        'events': ['pull_request', 'push', 'issue_comment'],
        'url': 'https://forge.yourdomain.com/webhooks/github'
    }
)

data = response.json()
if data['success']:
    print('Webhook configured successfully')

{
  "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"
  }
}

{
  "success": false,
  "error": "invalid_webhook_url",
  "message": "Webhook URL is not accessible or invalid"
}

Supported Events:

pull_request - PR opened, closed, merged
push - Commits pushed
issue_comment - Comments on issues/PRs
pull_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'
});

Getting Started

Learn

Configuration

Reference

Troubleshooting

Overview

Authentication

GitHub OAuth Device Flow

Step 1: Initiate Device Flow

Step 2: Poll for Token

Pull Requests

Create Pull Request

Attach Existing PR

Repository Operations

Get Repository Info

List Pull Requests

Webhooks

Configure Webhook

SDK Examples

Next Steps

Attempts API

Authentication

​Overview

​Authentication

​GitHub OAuth Device Flow

​Step 1: Initiate Device Flow

​Step 2: Poll for Token

​Pull Requests

​Create Pull Request

​Attach Existing PR

​Repository Operations

​Get Repository Info

​List Pull Requests

​Webhooks

​Configure Webhook

​SDK Examples

​Next Steps

Attempts API

Authentication

Overview

Authentication

GitHub OAuth Device Flow

Step 1: Initiate Device Flow

Step 2: Poll for Token

Pull Requests

Create Pull Request

Attach Existing PR

Repository Operations

Get Repository Info

List Pull Requests

Webhooks

Configure Webhook

SDK Examples

Next Steps