Git Data Model

Current status: this model describes the experimental standalone Git service. The default project bootstrap path today stores GitHub repo linkage on Stage apps instead.

Git manages three stored collections (providers, repositories, webhook events) and several read-only types returned from the GitHub API. All stored entities use nanoid(8) identifiers.

GitProviderConfig

A registered Git hosting provider.

interface GitProviderConfig {
  id: string;                  // nanoid(8)
  name: string;                // Unique name
  type: GitProviderType;       // Currently only "github"
  passportProviderId: string;  // Passport OAuth provider for token delegation
  apiBaseUrl?: string;         // Custom API URL (for GitHub Enterprise)
  defaultOrg?: string;         // Default organization
  created: string;             // ISO 8601
  updated: string;             // ISO 8601
}

type GitProviderType = "github";

GitRepository

A connected remote repository.

interface GitRepository {
  id: string;                  // nanoid(8)
  name: string;                // Display name (owner/repo)
  providerId: string;          // Parent provider ID
  owner: string;               // Repository owner (org or user)
  repoName: string;            // Repository name
  fullName: string;            // Full name (owner/repo)
  htmlUrl: string;             // Web URL
  defaultBranch: string;       // Default branch name
  serviceId?: string;          // Linked Yellow Pages service ID
  connectedBy: string;         // User who connected the repo
  status: RepositoryStatus;    // Connection status
  private: boolean;            // Visibility
  description?: string;
  webhookId?: string;          // GitHub webhook ID
  webhookSecret?: string;      // HMAC secret for webhook verification
  lastSyncedAt?: string;       // ISO 8601
  created: string;             // ISO 8601
  updated: string;             // ISO 8601
}

type RepositoryStatus = "active" | "disconnected" | "error";

WebhookEvent

An incoming webhook event from a repository.

interface WebhookEvent {
  id: string;                          // nanoid(8)
  repositoryId: string;                // Repository that received the event
  eventType: string;                   // GitHub event type (push, pull_request, etc.)
  ref?: string;                        // Git ref (for push events)
  sender: string;                      // GitHub login of the sender
  payload: Record<string, unknown>;    // Full webhook payload
  receivedAt: string;                  // ISO 8601
}

Read-Only Types (from GitHub API)

These types are not stored locally but returned by API endpoints.

BranchInfo

interface BranchInfo {
  name: string;
  sha: string;
  protected: boolean;
}

CommitInfo

interface CommitInfo {
  sha: string;
  message: string;
  author: string;
  authorEmail: string;
  date: string;
  url: string;
}

FileContent

interface FileContent {
  path: string;
  name: string;
  type: "file" | "dir";
  size: number;
  sha: string;
  content?: string;    // Base64-encoded for files
  encoding?: string;
}

CompareResult

interface CompareResult {
  status: string;
  aheadBy: number;
  behindBy: number;
  totalCommits: number;
  commits: CommitInfo[];
  files: Array<{
    filename: string;
    status: string;
    additions: number;
    deletions: number;
    patch?: string;
  }>;
}

PullRequestInfo

interface PullRequestInfo {
  number: number;
  title: string;
  body: string;
  state: string;
  head: string;
  base: string;
  author: string;
  htmlUrl: string;
  mergeable?: boolean;
  created: string;
  updated: string;
}

Storage

File-Based (SHIFT_STORAGE=file)

.shift-git/
  config.json                # GitConfig
  providers/<id>.json         # Provider registrations
  repositories/<id>.json      # Connected repositories
  webhookEvents/<id>.json     # Webhook event history

Convex (SHIFT_STORAGE=convex)

Tables use the git_ prefix:

Table	Description
git_providers	Provider configurations
git_repositories	Connected repository records
git_webhookEvents	Webhook event logs

Each record includes a sid field (shift ID) that maps to the application-level id.