Git (Repository Management)

Git is the repository management surface for the Shift Platform and the preferred repository bootstrap path for generated apps:

1. shift-cli create-app scaffolds a project and creates a Stage app
2. The CLI asks the Git service to create or connect a GitHub repo in the authenticated user's personal namespace
3. Git delegates GitHub access to Passport, so generated apps never need to hold GitHub OAuth tokens directly
4. The Stage app and local config store canonical Git provider/repository ids alongside GitHub metadata
5. shift-cli app push and stage-cli push can record Stage deploys as Git sessions/checkpoints for evolution tracking

If Git or Passport is not ready, the CLI falls back to a local-only scaffold and the repo can be connected later.

What It Does

• Provider Registration — Register Git hosting providers (GitHub) with Passport OAuth integration.
• Repository Management — Connect, create, sync, and disconnect repositories.
• Delegated Repo Bootstrap — Create or adopt GitHub repos for Shift apps through Passport-backed user tokens.
• Session Tracking — Store agent sessions, transcript entries, and checkpoints linked to repositories.
• Local Hook Intake — Accept local Claude Code hook events and map them into Git sessions.
• Branch Operations — List, create, and delete branches on connected repositories.
• Commit Operations — Browse commit history and create commits programmatically.
• File Browsing — List directories and read file contents at any ref.
• Diff & Compare — Compare two refs to see commits and changed files.
• Pull Requests — Create, list, show, and merge pull requests.
• Webhooks — Set up and manage repository webhooks with HMAC-SHA256 signature verification.

Key Concepts

Concept	Description
Provider	A Git hosting service configuration (e.g., GitHub) linked to a Passport OAuth provider.
Repository	A connected remote repository with metadata, sync state, and optional webhook.
Agent Session	A tracked Studio, Stage, or local coding session linked to a repository.
Checkpoint	A saved point in a tracked session, optionally linked to a commit SHA.
Webhook Event	An incoming event from a repository's webhook, verified and stored.

Configuration

Setting	Value
Storage Directory	.shift-git/
API Dev Port	4009
Gateway Prefix	/api/v1/git/*

Architecture

Git delegates authentication to the Passport service. When an API request requires GitHub access, Git retrieves an OAuth token from Passport for the specified user and requested scopes.

Shift CLI / Studio / local Claude hooks -> Git API -> Passport (OAuth token) -> GitHub API

Getting Started

Register a GitHub provider:

shift-cli git provider add --name github --type github --passport-provider github

Connect a repository:

shift-cli git repo add --provider github --owner my-org --repo my-app --user me@example.com

Browse the repository:

shift-cli git branches <repo-id> --user me@example.com
shift-cli git commits <repo-id> --user me@example.com --branch main
shift-cli git files <repo-id> --user me@example.com --path src/