Borealis-Github-Replica/Docs/integrations.md

Integrations

Back to Docs Index | Index (HTML)

Purpose

Document external integrations used by Borealis, primarily the GitHub repository hash service.

GitHub Integration (Repository Hash)

• The Engine can query GitHub for the latest commit hash of a repository/branch.
• Results are cached locally to reduce API usage.
• Admins can store a GitHub API token via the WebUI.

API Endpoints

• GET /api/github/token (Admin) - GitHub token status.
• POST /api/github/token (Admin) - update GitHub token.
• GET /api/repo/current_hash (Device or Token Authenticated) - current repo hash.

Related Documentation

• Engine Runtime
• API Reference
• Logging and Operations

Codex Agent (Detailed)

Integration implementation

• Data/Engine/integrations/github.py implements GitHubIntegration.
• The integration uses:
  • Cached results stored in repo_hash_cache.json (under the Engine cache directory).
  • Token storage in the github_token SQLite table.

Defaults and overrides

• Default repo: bunny-lab-io/Borealis.
• Default branch: main.
• Environment overrides:
  • BOREALIS_REPO
  • BOREALIS_REPO_BRANCH
• Cache TTL can be overridden via Engine config (repo_hash_refresh).

Token management

• Admins manage tokens via /api/github/token.
• The token is stored in the Engine database (github_token table).
• GitHubIntegration.verify_token() reports validity and rate-limit status.

GET /api/repo/current_hash

• This endpoint uses the cached GitHub integration to return a hash.
• It supports device-auth and operator-auth contexts.
• Useful for agent update checks and diagnostics.

Debug checklist

• Token missing: call /api/github/token as Admin and confirm has_token.
• API rate limit errors: inspect the response payload for rate_limit fields.
• Cache stale: use the force_refresh behavior in GitHubIntegration (via config or code).