GitHub

GitHub Integration

Repos, issues, pull requests, commits, branches, files, Actions, teams — the full dev workflow, auto-exposed as HTTP endpoints and CLI commands.

GitHub Adapter Architecture

GitHubService

service.py

@service_method
~27 methods

OAuth token

PAT

GitHub App JWT

→

calls

GitHubAdapter

adapter.py

httpx client
Link header pagination
X-RateLimit-* handling

→

HTTPS

GitHub REST API

api.github.com

Authorization: Bearer {token}
JSON responses

What & Why

The GitHub integration covers the full dev workflow: repositories, issues, pull requests, commits, branches, file operations, GitHub Actions, teams, search, and user info. All ~27 service methods are auto-exposed via Constellation's code-generation pipeline as:

• HTTP endpoints — POST /github/{method}
• CLI commands — constellation github {method}
• LLM tool calls — available to Sagittarius agents

Three auth strategies are supported:

Strategy	Best For
OAuth 2.0 user token	Interactive user-delegated access
Personal Access Token (PAT)	CI/CD pipelines, scripted automation
GitHub App (JWT + installation token)	Org-wide bot access, fine-grained permissions

---

OAuth 2.0 Flow

User

→

GET /v1/oauth/github/authorize

Constellation

redirects to GitHub

→

redirect

GitHub OAuth

user authorizes

→

POST /v1/oauth/github/callback

Token Stored

ready to use

---

Methods Reference

All methods are available as HTTP endpoints (POST /github/{method-name}) and CLI commands (constellation github {method-name}).

Method	HTTP Verb	Description	Key Parameters
Repositories
list_repositories	GET	List repositories for an owner or the authenticated user	owner, type, sort, per_page
get_repository	GET	Get full metadata for a single repository	owner, repo
create_repository	POST	Create a new repository under the authenticated user or org	name, description, private, auto_init
delete_repository	DELETE	Permanently delete a repository (requires admin permission)	owner, repo
Issues
list_issues	GET	List issues for a repository with optional filters	owner, repo, state, labels, assignee
get_issue	GET	Get a single issue by number	owner, repo, issue_number
create_issue	POST	Create a new issue in a repository	owner, repo, title, body, labels, assignees
update_issue	PATCH	Update title, body, state, labels, or assignees on an issue	owner, repo, issue_number, title, body, state
close_issue	PATCH	Close an issue (sets state to closed)	owner, repo, issue_number
add_issue_comment	POST	Add a comment to an existing issue	owner, repo, issue_number, body
Pull Requests
list_pull_requests	GET	List pull requests with state and base branch filters	owner, repo, state, base, sort
get_pull_request	GET	Get a single pull request by number	owner, repo, pull_number
create_pull_request	POST	Open a new pull request from head to base branch	owner, repo, title, head, base, body, draft
merge_pull_request	POST	Merge a pull request (merge / squash / rebase)	owner, repo, pull_number, merge_method, commit_message
review_pull_request	POST	Submit a review (APPROVE / REQUEST_CHANGES / COMMENT)	owner, repo, pull_number, event, body
Commits
list_commits	GET	List commits on a branch with optional author/path filter	owner, repo, sha, author, path, per_page
get_commit	GET	Get a single commit including diff stats and file changes	owner, repo, ref
compare_commits	GET	Compare two commits or branches (ahead/behind, diff)	owner, repo, base, head
Branches
list_branches	GET	List all branches in a repository	owner, repo, protected, per_page
create_branch	POST	Create a new branch from an existing branch or SHA	owner, repo, branch, sha
delete_branch	DELETE	Delete a branch by name	owner, repo, branch
Files
get_file_content	GET	Retrieve file content (base64-decoded) from a branch or SHA	owner, repo, path, ref
create_or_update_file	PUT	Create or update a file with a commit message	owner, repo, path, message, content, sha, branch
Actions
list_workflows	GET	List all GitHub Actions workflows in a repository	owner, repo
trigger_workflow	POST	Dispatch a workflow run via workflow_dispatch event	owner, repo, workflow_id, ref, inputs
Teams
list_teams	GET	List all teams in a GitHub organization	org
get_team_members	GET	List members of a specific team	org, team_slug, role
Search
search_repositories	GET	Search repositories using GitHub search syntax	q, sort, order, per_page
search_issues	GET	Search issues and pull requests across GitHub	q, sort, order, per_page
search_code	GET	Search code across all accessible repositories	q, sort, order, per_page
Users
get_user	GET	Get a public GitHub user profile by username	username
get_authenticated_user	GET	Get the profile of the currently authenticated user	(none)

---

CLI Examples

# List repositories for an organization
constellation github list-repositories --owner myorg

# Get a specific repository
constellation github get-repository --owner myorg --repo myrepo

# Create a new issue
constellation github create-issue --owner myorg --repo myrepo --title "Bug fix" --body "Steps to reproduce..."

# Update an issue
constellation github update-issue --owner myorg --repo myrepo --issue-number 42 --state closed

# Add a comment to an issue
constellation github add-issue-comment --owner myorg --repo myrepo --issue-number 42 --body "Fixed in PR #45"

# List open pull requests
constellation github list-pull-requests --owner myorg --repo myrepo --state open

# Create a pull request
constellation github create-pull-request --owner myorg --repo myrepo \
  --title "Add feature X" --head feature/x --base main --body "## Changes"

# Merge a pull request (squash)
constellation github merge-pull-request --owner myorg --repo myrepo \
  --pull-number 42 --merge-method squash

# Review a pull request
constellation github review-pull-request --owner myorg --repo myrepo \
  --pull-number 42 --event APPROVE

# List commits on main
constellation github list-commits --owner myorg --repo myrepo --sha main

# Compare two branches
constellation github compare-commits --owner myorg --repo myrepo --base main --head feature/x

# Create a branch
constellation github create-branch --owner myorg --repo myrepo --branch feature/new --sha main

# Get file content
constellation github get-file-content --owner myorg --repo myrepo --path src/main.py --ref main

# Create or update a file
constellation github create-or-update-file --owner myorg --repo myrepo \
  --path docs/API.md --message "docs: update API docs" --content "# API Docs" --branch main

# List workflows
constellation github list-workflows --owner myorg --repo myrepo

# Trigger a workflow
constellation github trigger-workflow --owner myorg --repo myrepo \
  --workflow-id deploy.yml --ref main

# List teams in an org
constellation github list-teams --org myorg

# Search repositories
constellation github search-repositories --q "language:python stars:>100 org:myorg"

# Search code
constellation github search-code --q "repo:myorg/myrepo function authenticate"

# Get authenticated user
constellation github get-authenticated-user

---

Rate Limits & Pagination

The GitHub adapter automatically handles:

• Pagination — follows Link response headers to retrieve subsequent pages when per_page limit is reached
• Rate limit headers — reads X-RateLimit-Remaining and X-RateLimit-Reset from every response; surfaces 429-equivalent errors with reset time when the limit is exhausted
• Secondary rate limits — backs off on 403 responses with Retry-After headers from GitHub's abuse detection

GitHub REST API limits:

Auth type	Requests / hour
Unauthenticated	60
OAuth / PAT	5,000
GitHub App (installation)	5,000 – 15,000