GitHub adapter

Use GitHub when promoted changes should land in a GitHub repository.

Package:

@gittrix/[email protected]

Import:

import { GitHubDurableAdapter } from '@gittrix/adapter-github'

Options

interface GitHubDurableAdapterOptions {
  owner: string
  repo: string
  branch?: string
  token?: string
  tokenProvider?: () => Promise<string> | string
  mirrorRoot?: string
  remoteUrl?: string
  apiBaseUrl?: string
  gitUserName?: string
  gitUserEmail?: string
}

Capabilities

{ git: true, push: true, fetch: true, history: true, ttl: false, latencyClass: 'regional' }

How it works

• Maintains a local mirror under ~/.gittrix/github-mirrors by default.
• Clones/fetches the GitHub repo.
• Reads files and lists trees from local git objects.
• Applies promoted files as a commit in the mirror.
• Pushes HEAD to refs/heads/<branch>.
• Can open a GitHub PR via openPullRequest() as a direct adapter method.

Usage with local ephemeral workspaces

import { GitTrix } from '@gittrix/core'
import { GitHubDurableAdapter } from '@gittrix/adapter-github'
import { LocalEphemeralAdapter } from '@gittrix/adapter-local'

const durable = new GitHubDurableAdapter({
  owner: 'acme',
  repo: 'app',
  branch: 'main',
  token: process.env.GITHUB_TOKEN,
})

const gittrix = new GitTrix({
  durable,
  ephemeral: new LocalEphemeralAdapter({ sessionsRootDir: '/tmp/gittrix-sessions' }),
})

Token notes

• Token is optional for public clone/read if the remote allows it.
• Token is required for authenticated push and PR creation.
• Required GitHub permissions for full behavior: contents read/write; pull requests read/write for openPullRequest().

Direct PR API

UserSession.promote({ strategy: 'pr' }) does not currently open a PR. PR creation exists as a direct adapter method.

const result = await durable.applyCommit({
  branch: 'gittrix/update-docs',
  message: 'docs: update readme',
  files: {
    'README.md': new TextEncoder().encode('# Updated\n'),
  },
})

const pr = await durable.openPullRequest({
  title: 'Update docs',
  head: result.branch,
  base: 'main',
  body: 'Promoted from a Gittrix session.',
})

console.log(pr.url)