---
name: git
description: "Git repository connector with clone/pull, session branching, and lifecycle hooks."
version: "0.1.0"
entry: ./driver.ts
fields:
  - key: source
    label: "Git repository URL"
    required: true
    sensitive: false
  - key: auth
    label: "Auth (provider-prefixed; pat:env:NAME, oauth:<provider>/env:VAR, github-app:APP_ID/INSTALLATION_ID)"
    required: false
    sensitive: true
  - key: exposeAccessToken
    label: "Expose access token to agent CLI (advanced; expert-only)"
    required: false
    sensitive: true
  - key: accessTokenTTL
    label: "Override access token TTL in seconds (refresh-capable providers only)"
    required: false
    sensitive: false
  - key: options.branch
    label: "Branch to track"
    required: false
    sensitive: false
  - key: options.session.enabled
    label: "Enable session branching"
    required: false
    sensitive: false
  - key: options.session.slug
    label: "Session branch slug"
    required: false
    sensitive: false
  - key: options.session.branchPrefix
    label: "Session branch prefix"
    required: false
    sensitive: false
  - key: options.sync.fetchIntervalSec
    label: "Periodic fetch interval (seconds, 0 = disabled)"
    required: false
    sensitive: false
  - key: options.sync.autoRebase
    label: "Auto-rebase on fetch"
    required: false
    sensitive: false
  - key: options.lifecycle.commitOnHibernate
    label: "Commit on hibernate"
    required: false
    sensitive: false
  - key: options.lifecycle.pushOnHibernate
    label: "Push on hibernate"
    required: false
    sensitive: false
  - key: options.lifecycle.mergeOnClose
    label: "Merge session branch on close"
    required: false
    sensitive: false
  - key: options.lifecycle.autoCommitIdleMs
    label: "Auto-commit after idle (ms, 0 = disabled)"
    required: false
    sensitive: false
keywords:
  - git
  - repository
  - clone
  - branch
  - session
---

## Git Connector

Connects a git repository by cloning (or pulling) to the session filesystem mount point.
Supports session-aware branching, periodic fetch/rebase, auto-commit on idle,
and lifecycle hooks for hibernate/close.

### Configuration

```yaml
connectors:
  - id: project-repo
    driver: git
    access: read-write
    # Provider-prefixed auth grammar (clean break from the legacy bare `env:`):
    #   pat:env:NAME                       — long-lived PAT (no refresh)
    #   oauth:<provider>/env:VAR           — refresh-capable OAuth (Step 2/3)
    #   github-app:APP_ID/INSTALLATION_ID  — refresh-capable GitHub App (Step 2)
    auth: pat:env:GIT_TOKEN
    mount:
      source: https://github.com/org/repo.git
      # Expert-only. Default `false`. When `true`, the runner writes a
      # short-lived credential into `<workspace>/.skaile/managed-gitconfig`
      # so the agent's interactive `git push` / `git pull` can authenticate.
      # Sensitive: gives prompt-injected agents direct CLI access bounded by
      # the credential's TTL (no refresh on PAT — blast radius = PAT scope).
      # See _devlog/specs/2026-05-05-git-credential-tiers.md.
      exposeAccessToken: false
      # Optional override for the access token TTL (seconds). Capped at the
      # provider's documented maximum.
      accessTokenTTL: 3600
    options:
      branch: main
      session:
        enabled: true
        slug: session-123
        branchPrefix: "session/"
      sync:
        fetchIntervalSec: 60
        autoRebase: true
      lifecycle:
        commitOnHibernate: true
        pushOnHibernate: true
        mergeOnClose: true
        autoCommitIdleMs: 30000
```

### Credential tiers

The git driver supports two credential tiers, gated by the `mount.exposeAccessToken`
field (default off):

| Tier | When | What the agent sees |
|---|---|---|
| Tier 1 (default) | `exposeAccessToken: false` | No credential. Driver-internal pulls/pushes use ephemeral `http.<scope>.extraheader`. Agent native `git push` / `pull` against the remote fails by design. |
| Tier 2 (opt-in) | `exposeAccessToken: true` | Short-lived access token written to `<workspace>/.skaile/managed-gitconfig` + `git-credentials`. Agent native git CLI works for the mount's host. |

`auth:` is **required** to use a provider-prefixed grammar:

| Syntax | Refresh capability |
|---|---|
| `pat:env:NAME` | None — static long-lived PAT. |
| `oauth:<provider>/env:VAR` | Refresh-capable (Step 2/3). |
| `github-app:APP_ID/INSTALLATION_ID` | Refresh-capable (Step 2). |

The legacy bare `env:NAME` form is rejected at session start with a clear
migration error pointing at this doc.

### Behavior

- **mount**: Clones the repo (or pulls if `.git` exists). Creates a session branch if configured.
- **unmount**: Stops periodic fetch and auto-commit timers.
- **sync**: Pulls from origin on the active branch.
- **watch**: Uses chokidar with `.git/**` ignored. Resets the auto-commit idle timer on changes.
- **onHibernate**: Commits and optionally pushes all changes.
- **onSessionClose**: Commits, pushes, and optionally merges the session branch into the base branch. Handles merge conflicts by keeping "ours" and saving "theirs" as `.conflict` files.

### Operations (tool face)

| Operation | Access | Description |
|---|---|---|
| `sync_status` | read | Returns a JSON snapshot of the mount's git sync status: `{ branch, dirty, ahead, behind, mainAhead, mainBehind, commitSha }`. `ahead`/`behind` are measured against the upstream tracking ref; `mainAhead`/`mainBehind` against `origin/<baseBranch>`. Read-only — performs no network fetch, so counts reflect locally-known remote-tracking refs ("since last sync"). |

This op backs the platform's git sync-status badge for **in-container** sources (Git / SharePoint / Empty), whose host workspace dir is empty even while the container is awake — the platform dispatches `sync_status` to the live agent rather than reading the host filesystem.