Aurelis

GitHub Integration API

Overview

The GitHub Integration API provides seamless integration with GitHub repositories for code analysis, pull request automation, issue management, and CI/CD workflows within the Aurelis platform.

Endpoints

Repository Connection

POST /api/v1/github/connect

Connects a GitHub repository to Aurelis for analysis and automation.

Request Body

{
  "repository_url": "https://github.com/owner/repo",
  "access_token": "github_personal_access_token",
  "webhook_secret": "optional_webhook_secret",
  "sync_settings": {
    "auto_analyze": true,
    "pr_automation": true,
    "issue_tracking": true,
    "branch_protection": false
  }
}

Response

{
  "success": true,
  "repository_id": "repo_12345",
  "connection_status": "connected",
  "webhook_url": "https://api.aurelis.dev/webhooks/github/repo_12345",
  "permissions": [
    "read_repository",
    "write_pull_requests",
    "read_issues"
  ],
  "last_sync": null
}

Repository Analysis

POST /api/v1/github/analyze/{repository_id}

Triggers comprehensive analysis of a connected GitHub repository.

Request Body

{
  "branch": "main",
  "analysis_types": [
    "code_quality",
    "security_scan",
    "dependencies",
    "performance",
    "documentation"
  ],
  "include_history": false,
  "depth_limit": 100
}

Response

{
  "success": true,
  "analysis_id": "analysis_67890",
  "repository_id": "repo_12345",
  "branch": "main",
  "status": "queued",
  "estimated_completion": "2025-06-17T10:45:00Z",
  "progress_url": "/api/v1/github/analysis/67890/status"
}

Pull Request Automation

POST /api/v1/github/pr/create

Creates a pull request with AI-generated improvements or fixes.

Request Body

{
  "repository_id": "repo_12345",
  "base_branch": "main",
  "head_branch": "aurelis/improvements-20250617",
  "title": "AI-Generated Code Improvements",
  "description": "Automated improvements generated by Aurelis AI",
  "changes": [
    {
      "file_path": "src/main.py",
      "operation": "modify",
      "content": "# Updated code content here",
      "description": "Improved error handling and performance"
    }
  ],
  "auto_merge": false,
  "reviewers": ["developer1", "developer2"],
  "labels": ["ai-generated", "improvement"]
}

Response

{
  "success": true,
  "pull_request": {
    "id": "pr_98765",
    "number": 42,
    "url": "https://github.com/owner/repo/pull/42",
    "status": "open",
    "branch": "aurelis/improvements-20250617",
    "files_changed": 3,
    "additions": 45,
    "deletions": 12
  }
}

Issue Management

GET /api/v1/github/issues/{repository_id}

Retrieves issues from a connected repository.

Query Parameters

Response

{
  "success": true,
  "repository_id": "repo_12345",
  "issues": [
    {
      "id": "issue_11111",
      "number": 123,
      "title": "Bug in authentication module",
      "body": "Description of the issue...",
      "state": "open",
      "labels": ["bug", "priority-high"],
      "assignee": "developer1",
      "milestone": "v1.2.0",
      "created_at": "2025-06-15T09:30:00Z",
      "updated_at": "2025-06-17T10:15:00Z",
      "url": "https://github.com/owner/repo/issues/123",
      "ai_analysis": {
        "severity": "high",
        "category": "security",
        "suggested_fix": "Update authentication token validation logic"
      }
    }
  ],
  "total_count": 1,
  "page": 1,
  "per_page": 30
}

Create Issue

POST /api/v1/github/issues/{repository_id}

Creates a new issue based on code analysis findings.

Request Body

{
  "title": "Security vulnerability detected in auth module",
  "body": "Aurelis AI has detected a potential security vulnerability...",
  "labels": ["security", "ai-detected"],
  "assignees": ["security-team"],
  "milestone": "security-fixes",
  "priority": "high"
}

Response

{
  "success": true,
  "issue": {
    "id": "issue_22222",
    "number": 124,
    "url": "https://github.com/owner/repo/issues/124",
    "state": "open",
    "created_at": "2025-06-17T10:30:00Z"
  }
}

Branch Management

GET /api/v1/github/branches/{repository_id}

Lists branches in the connected repository.

Response

{
  "success": true,
  "repository_id": "repo_12345",
  "branches": [
    {
      "name": "main",
      "protected": true,
      "commit_sha": "abc123def456",
      "last_commit": {
        "message": "Fix authentication bug",
        "author": "developer1",
        "date": "2025-06-17T09:45:00Z"
      },
      "analysis_status": "completed",
      "quality_score": 8.5
    },
    {
      "name": "feature/new-api",
      "protected": false,
      "commit_sha": "def456ghi789",
      "last_commit": {
        "message": "Add new API endpoints",
        "author": "developer2",
        "date": "2025-06-17T10:20:00Z"
      },
      "analysis_status": "pending",
      "quality_score": null
    }
  ]
}

Webhook Management

GET /api/v1/github/webhooks/{repository_id}

Retrieves webhook configuration for a repository.

Response

{
  "success": true,
  "repository_id": "repo_12345",
  "webhook": {
    "id": "webhook_33333",
    "url": "https://api.aurelis.dev/webhooks/github/repo_12345",
    "events": [
      "push",
      "pull_request",
      "issues",
      "issue_comment"
    ],
    "active": true,
    "created_at": "2025-06-15T14:30:00Z",
    "last_triggered": "2025-06-17T10:15:00Z"
  }
}

CI/CD Integration

POST /api/v1/github/workflow/create

Creates GitHub Actions workflow for Aurelis integration.

Request Body

{
  "repository_id": "repo_12345",
  "workflow_name": "aurelis-analysis",
  "triggers": ["push", "pull_request"],
  "branches": ["main", "develop"],
  "analysis_types": ["code_quality", "security_scan"],
  "auto_comment": true,
  "fail_on_critical": true
}

Response

{
  "success": true,
  "workflow": {
    "id": "workflow_44444",
    "name": "aurelis-analysis",
    "file_path": ".github/workflows/aurelis-analysis.yml",
    "status": "created",
    "first_run": null
  }
}

Code Review Automation

POST /api/v1/github/review/{pull_request_id}

Triggers AI-powered code review for a pull request.

Request Body

{
  "review_types": [
    "code_quality",
    "security",
    "performance",
    "best_practices",
    "documentation"
  ],
  "auto_approve": false,
  "comment_style": "constructive",
  "include_suggestions": true
}

Response

{
  "success": true,
  "review": {
    "id": "review_55555",
    "pull_request_id": "pr_98765",
    "status": "completed",
    "overall_score": 8.2,
    "comments_added": 5,
    "suggestions_made": 3,
    "critical_issues": 0,
    "approval_status": "changes_requested"
  }
}

Repository Statistics

GET /api/v1/github/stats/{repository_id}

Retrieves comprehensive statistics for a repository.

Response

{
  "success": true,
  "repository_id": "repo_12345",
  "statistics": {
    "general": {
      "total_commits": 1250,
      "total_contributors": 8,
      "total_branches": 15,
      "total_releases": 12,
      "last_activity": "2025-06-17T10:30:00Z"
    },
    "code_quality": {
      "average_score": 8.5,
      "trend": "improving",
      "issues_found": 23,
      "issues_resolved": 45,
      "test_coverage": 87.5
    },
    "security": {
      "vulnerabilities": 2,
      "severity_breakdown": {
        "critical": 0,
        "high": 1,
        "medium": 1,
        "low": 0
      },
      "last_scan": "2025-06-17T08:00:00Z"
    },
    "activity": {
      "commits_last_30_days": 156,
      "prs_opened": 23,
      "prs_merged": 19,
      "issues_opened": 12,
      "issues_closed": 15
    }
  }
}

Authentication

GitHub App Installation

Aurelis provides a GitHub App for seamless integration:

  1. Install the Aurelis GitHub App from the GitHub Marketplace
  2. Grant necessary permissions to your repositories
  3. Use the installation token for API authentication

Personal Access Token

Alternatively, use a GitHub Personal Access Token with these scopes:

Webhook Events

Aurelis processes these GitHub webhook events:

Push Events

{
  "event": "push",
  "repository_id": "repo_12345",
  "branch": "main",
  "commits": [
    {
      "sha": "abc123def456",
      "message": "Fix authentication bug",
      "author": "developer1",
      "files_changed": ["src/auth.py", "tests/test_auth.py"]
    }
  ],
  "analysis_triggered": true
}

Pull Request Events

{
  "event": "pull_request",
  "action": "opened",
  "repository_id": "repo_12345",
  "pull_request": {
    "number": 42,
    "title": "Add new feature",
    "branch": "feature/new-api",
    "files_changed": 5,
    "review_requested": true
  }
}

Error Handling

Common Error Codes

Error Response Format

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "GitHub token lacks required permissions",
    "details": {
      "required_scopes": ["repo", "write:repo_hook"],
      "current_scopes": ["repo"],
      "suggestion": "Update token permissions in GitHub settings"
    }
  }
}

Rate Limiting

GitHub API rate limits also apply and are automatically handled.

Examples

Connect Repository

curl -X POST "https://api.aurelis.dev/v1/github/connect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_url": "https://github.com/myorg/myrepo",
    "access_token": "github_token_here",
    "sync_settings": {
      "auto_analyze": true,
      "pr_automation": true
    }
  }'

Trigger Analysis

curl -X POST "https://api.aurelis.dev/v1/github/analyze/repo_12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "analysis_types": ["code_quality", "security_scan"]
  }'

Create Pull Request

curl -X POST "https://api.aurelis.dev/v1/github/pr/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_id": "repo_12345",
    "base_branch": "main",
    "head_branch": "aurelis/fixes",
    "title": "AI-Generated Improvements",
    "changes": [
      {
        "file_path": "src/main.py",
        "operation": "modify",
        "content": "improved_code_here"
      }
    ]
  }'

Integration

Python SDK

from aurelis import GitHubIntegration

github = GitHubIntegration(api_key="your_api_key")

# Connect repository
repo = github.connect_repository(
    url="https://github.com/myorg/myrepo",
    token="github_token"
)

# Trigger analysis
analysis = github.analyze_repository(
    repo.id,
    branch="main",
    types=["code_quality", "security_scan"]
)

# Create pull request
pr = github.create_pull_request(
    repo.id,
    title="AI Improvements",
    base="main",
    head="aurelius/improvements",
    changes=[...]
)

CLI Integration

# Connect repository
aurelis github connect https://github.com/myorg/myrepo --token YOUR_GITHUB_TOKEN

# Analyze repository
aurelis github analyze repo_12345 --branch main --types code_quality,security

# Create pull request
aurelis github pr create repo_12345 --title "AI Improvements" --base main

Best Practices

  1. Token Security: Store GitHub tokens securely and rotate regularly
  2. Webhook Validation: Always validate webhook signatures
  3. Rate Limiting: Implement proper rate limiting for GitHub API calls
  4. Branch Protection: Enable branch protection for critical branches
  5. Review Automation: Use AI reviews to supplement, not replace, human reviews
  6. Monitoring: Monitor webhook delivery and API usage

GitHub App Permissions

The Aurelis GitHub App requires these permissions:

Limitations

Support

For GitHub integration issues: