Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
github
What it is
Backs the GitHub integration used by agent sessions and document storage: GitHub account linking, the GitHub App install/webhook sync, and the OAuth link flow, following the hexagonal architecture pattern.
Start here
src/domain/models.rs: re-exports pull request domain types fromgithub_pull_requestsalongside this crate's own link/installation/sync models — most "GitHub" domain types actually live in that crate.src/inbound/github_sync_router.rs: GitHub App install redirect, OAuth callback, and the webhook handler.src/inbound/pull_request_index_router.rs: the HTTP surface for indexed PRs.src/broker.rs+src/domain/models/webhook_delivery.rs: every verified delivery, whatever its event, published tomacro.github_webhooksfor subscribers such as routines.src/outbound/github_sync_client.rs,src/outbound/github_auth_client.rs: GitHub's own REST/App API clients.src/outbound/pg_github_repo.rs,src/outbound/pg_github_sync_repo.rs: the Postgres adapters for links and sync state.
Scope
- Owns: account linking (
linkfeature), the App installation/webhook sync (syncfeature), and the Axum router/webhook verification for both. Theinstallation_claimsfeature exposes whether a user has linked GitHub and who may see an installation's deliveries, without the rest of the sync stack. A personal installation counts only while the account that installed it is the one linked. - Not here: the pull request model, merge rules, and PR listing/service →
crates/github_pull_requests, which this crate re-exports and calls into.
Boundaries
- Depends on:
github_pull_requests(ports/schema),foreign_entity,documents,fusionauth,connection_gateway_client,macro_service_urls,notification/model_notifications. - Used by:
agent_harness_service,agent_harness,agent_egress,document_storage_service,authentication_service,scheduled_action.
Recipes
- Add a webhook event:
src/inbound/github_sync_router.rs(dispatch) →src/domain/models.rs(sync model) →src/outbound/pg_github_sync_repo.rs. - Add a new GitHub API call:
src/outbound/github_sync_client.rsorgithub_auth_client.rs→ the domain service that needs it.
Checks
cargo test -p github --all-features(SQLX_OFFLINEunset).- Start local PostgreSQL and Redis first (
docs/development/database.md);REDIS_URLoverrides the Redis test endpoint. Keep the token-cache race test enabled in CI, which provisions Redis. just check(from this directory) runscargo check --all-features.
Gotchas
Missing FusionAuth identities/grants require reauthentication; infrastructure errors remain errors (outages as
GithubError::Upstream, below). After OAuth proves GitHub identity, refresh the grant before returning an existing link. Reassign every sharer when its grant owner is gone, using the old owner as a compare-and-swap condition. Hold the user guard then the GitHub account guard through OAuth grant writes and DB changes; disconnect follows the same order. Cache tokens by identity and GitHub account.Keep lock-pool acquisition and advisory waits bounded at five seconds; only the dedicated lock connections use the five-second lock and ten-second statement timeouts. Never expire idle transactions while grant writes run.
Grant replacement is unlink/relink with best-effort restoration. A timeout leaves the remote result uncertain; a crash can leave no grant. Preserve Macro links so a later verified OAuth attempt can recreate it.
Webhook signature verification uses
hmac/subtlefor constant-time comparison — don't swap in a plain==when touchinggithub_sync_router.rs.A GitHub or sign-in outage is
GithubError::Upstream, answered 502/503 byinbound.rs. Outbound adapters classify it (github_oauth_client.rsthrottling/unexpected_response,github_auth_client.rsfusionauth_error); everything else they cannot explain staysInternal. Port errors reach the service asGithubError, so map them with.map_err(Into::into), neverGithubError::Internal(e.into()), which turns an outage back into a 500. A GitHub 403 is a refusal only afterthrottlingrules out a rate limit.GithubError::Forbidden,SetupUserNotLinked, andRepositoryUnavailableall map to the same 403 deliberately — don't let a response distinguish "app not installed" from "installed somewhere you have no claim to".
Related
- Rules:
.agents/rules/rust/architecture.md,.agents/rules/rust/security.md