GitHub Integration & Polling
Relevant source files
The following files were used as context for generating this wiki page:
GitHub Integration & Polling provides the mechanism for Opificia AI to interact with GitHub repositories, issues, and pull requests. The system uses a GitHub App to authenticate and perform actions like listing issues, opening pull requests, and generating installation tokens for git operations.
The integration facilitates a loop where AI agents pick up tickets (issues), write changes, and open pull requests for human review. While the system is designed to be model-agnostic and self-hostable, the initial prototype utilizes a harness for Claude Code to execute this loop.
Sources: README.md:9-16, apps/server/src/github/github.service.ts:31-34
GitHub Service Architecture
The GitHubService acts as the central communication hub between the Opificia server and the GitHub API. It leverages the octokit library and @octokit/auth-app to manage authentication via a GitHub App ID and private key.
Authentication and Tokens
The service manages two levels of authentication:
- App-level: Authenticates as the GitHub App to list installations and repositories.
- Installation-level: Generates short-lived installation tokens restricted to specific repositories. These tokens stay within the control plane and can be configured for read-only or read-write access to repository contents.
Sources: apps/server/src/github/github.service.ts:31-41, apps/server/src/github/github.service.ts:109-119
Key GitHub Service Methods
| Method | Description |
|---|---|
listInstallations | Returns a list of installations including ID and account login. |
listRepos | Lists all repositories accessible to a specific installation. |
listLabelledIssues | Retrieves open issues filtered by a specific label; excludes pull requests. |
openPullRequest | Creates a new pull request with a specified title, body, head branch, and base branch. |
repoToken | Generates a scoped installation token for git operations on a single repository. |
Sources: apps/server/src/github/github.service.ts:43-119
Issue and Pull Request Flow
The system identifies work by polling or listing issues with specific labels. AI agents then process these issues to generate code changes and documentation.
The Agent Loop
The following diagram illustrates how the GitHub integration supports the agentic workflow:
The integration ensures that agents can read repository data but requires human intervention for the final merge.
Sources: README.md:9-16, SOVEREIGNTY.md:46-50, plugins/harness-claude/src/prompts.ts:46-54
Automated Sign-off by Approval
Maintainers can sign off on pull requests without using a terminal by providing an approving review containing the /signoff command. A GitHub App-driven workflow then adds the Signed-off-by trailer to the commits. This process requires a GitHub App with "Contents: read and write" permissions and valid credentials stored in repository secrets.
Sources: CONTRIBUTING.md:78-85, CONTRIBUTING.md:104-109
Agent Interactions with GitHub
Agents are provided with specific instructions and constraints when interacting with GitHub resources. These rules prevent agents from altering sensitive configuration or security-related files.
Protection Rules
Agents are explicitly prohibited from changing:
- CI workflows and scripts (
.github/workflows/) CODEOWNERSMAINTAINERS.md,AGENTS.md,CLAUDE.md.mcp.jsonor anything under.claude/
Sources: plugins/harness-claude/src/prompts.ts:46-52
Pull Request Generation
When an agent finishes an implementation, it generates a pull request description. The GitHubService uses this data to call the GitHub API. The description follows a standardized format:
// Example of the expected PR description format enforced by prompts
const DESCRIPTION_FORMAT = `Title: <type>(<optional scope>): <summary>
## What changed
A short list of the changes, by file.
## Tests
The test command you ran and its result.`;
Sources: plugins/harness-claude/src/prompts.ts:86-98, apps/server/src/github/github.service.ts:93-100
Integration Safety and Sovereignty
The GitHub integration adheres to the project's sovereignty commitments by ensuring data and control remain with the operator.
- Human Control: By default, no agent can merge or deploy without recorded human approval on GitHub.
- Scoped Access: Tokens generated via
repoTokenare limited to single repositories and specific permissions (read or write). - Transparency: Commits generated by tools must include an
Assisted-bytrailer naming the tool and model.
Sources: SOVEREIGNTY.md:46-50, apps/server/src/github/github.service.ts:109-119, CONTRIBUTING.md:144-150
Summary
GitHub Integration & Polling enables Opificia to automate the software development lifecycle while maintaining human oversight. By using a GitHub App and scoped installation tokens, the system provides a secure path for AI agents to process issues and propose changes as pull requests. The integration is governed by strict protection rules and a human-in-the-loop requirement for all merges, ensuring the integrity of the target repositories.