External Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• packages/api/src/services/integrations/githubAdapter.ts
• packages/api/src/test/integrationRepositories.test.ts
• packages/mcp/src/api.ts
• packages/mcp/src/api/interfaces.ts
• CONTEXT.md

External Integrations in Orcy function as a coordination layer that connects the central task board with third-party issue trackers, code repositories, and communication platforms. Orcy acts as an agnostic hub, using specialized adapters to pull work from trackers like GitHub, Linear, and Jira, while pushing notifications and attention to chat tools like Slack and Discord.

The integration system is designed to provide Code Evidence and provenance by linking external artifacts—such as Pull Requests, commits, and CI/CD runs—directly to Orcy missions and tasks. This ensures that work performed across various vendor products is synthesized into a single, visible audit trail within a Habitat.
Sources: README.md:144-156, CONTEXT.md:144-156

Integration Architecture

Orcy utilizes an adapter-based architecture to interface with external providers. This structure allows the core platform to remain agnostic of specific vendor implementations.

Issue Tracker Adapters

Issue trackers serve as "work in" sources. The system pulls external issues into a Habitat's intake, where they can be promoted to missions.

• GitHub Issues: Uses OAuth device flow or PAT fallback. It supports inbound webhooks for real-time synchronization of issue events.
• Linear: Connects via OAuth PKCE from the CLI.
• Jira Cloud: Managed via API tokens or advanced OAuth configurations, requiring site URLs and project keys.
  Sources: README.md:204-219, packages/api/src/services/integrations/githubAdapter.ts:44-77

Data Normalization Flow

When an external issue is retrieved, it is passed through a provider-specific normalization function to match Orcy's internal ExternalIssue schema.

Integration Components

Component	Description
IntegrationConnection	Stores authentication (tokens), repository details, and sync status for a specific provider link in a Habitat.
ExternalIssueLink	A record connecting an Orcy Mission to a specific external entity (e.g., a GitHub Issue ID).
IntegrationSyncRun	Tracks the execution of a synchronization process, including counts for created, updated, or failed items.
IssueProviderAdapter	An interface defining methods like listIssues and getIssue for specific providers.
Sources: packages/api/src/test/integrationRepositories.test.ts:41-55, packages/api/src/test/integrationRepositories.test.ts:133-149, packages/api/src/test/integrationRepositories.test.ts:208-216

Data Models and Persistence

Integrations are backed by several database entities that manage the lifecycle of the connection and the linked work items.

Connection Management

IntegrationConnection records are habitat-scoped. They include fields for authMethod (e.g., 'pat'), accessToken, and repository coordinates. The system implements security measures such as masking token fields in views to prevent sensitive data leakage.
Sources: packages/api/src/test/integrationRepositories.test.ts:41-78

Synchronization Logic

Synchronization can be triggered manually or via webhooks. IntegrationSyncRun objects store the duration and outcome of these events.

Code Evidence & Provenance

Integrations provide "provenance in" by linking code artifacts to tasks. This is primarily handled via GitHub and GitLab integrations.

• Artifacts: Commits, PRs, branches, and CI runs.
• Audit Trail: Webhooks from GitHub, GitLab, and Bitbucket feed the audit trail, creating a chronological record of implementation work.
• Evidence Gaps: If work happens outside of Orcy's observable paths, it is flagged as an "Evidence Gap" rather than assumed that no work occurred.
  Sources: README.md:222-226, CONTEXT.md:144-156

Evidence Link Parameters

Field	Type	Description
targetType	Enum	The type of source primitive (e.g., commit, pull_request, external_issue).
targetId	String	The unique identifier from the external provider.
linkNote	String	Optional context explaining the relationship to the Orcy task.
Sources: packages/mcp/src/api/interfaces.ts:792-796, packages/mcp/src/api.ts:861-870

GitHub Integration Implementation

The githubAdapter demonstrates the standard implementation pattern for external providers.

Normalized Issue Structure

export function normalizeGitHubIssue(
  owner: string,
  repo: string,
  issue: GitHubIssue,
): ExternalIssue {
  return {
    provider: "github",
    externalId: issue.node_id ?? String(issue.id),
    externalKey: `${owner}/${repo}#${issue.number}`,
    title: issue.title,
    body: issue.body ?? "",
    status: issue.state === "closed" ? "closed" : "open",
    labels: issue.labels.map((l) => (typeof l === "string" ? l : l.name)),
    url: issue.html_url,
    updatedAt: issue.updated_at,
    reporter: issue.user?.login ?? undefined,
  };
}

Sources: packages/api/src/services/integrations/githubAdapter.ts:25-42

Webhook Management

Orcy can automatically create webhooks on GitHub to monitor issues events. This requires the admin:repo_hook scope. If permissions are insufficient, the system provides a warning but allows manual synchronization to continue.
Sources: packages/api/src/services/integrations/githubAdapter.ts:108-154

Summary

External Integrations act as the sensory organs for an Orcy Habitat, pulling in requirements from issue trackers and observing implementation via code repositories. By normalizing disparate vendor data into a unified mission-task hierarchy, Orcy maintains a central source of truth for pod coordination while remaining agnostic of specific developer tools. Over time, these integrations build an append-only audit trail and evidence bundle that verifies task completion through hard code artifacts.