Skip to content
ContractSpec
Start here

Package manual · integrations

·Integrations and provider selection

integration.provider-github

GitHub provider implementation for ContractSpec with repository, issue, and pull request management.

integrationsintegrationv2.1.4experimentalservernode
@lssm-tech/integration.provider-github
bun add @lssm-tech/integration.provider-github
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

GitHub provider implementation for repository, issue, pull-request, check-run, installation, and self-maintaining API workflows.

Installation

bash
npm install @lssm-tech/integration.provider-github
# or
bun add @lssm-tech/integration.provider-github

GitHub App authentication

Use @lssm-tech/integration.provider-github/github/auth for GitHub App installation authentication. Configuration carries secret references, not raw private keys. The host resolves the key through its secret provider and must authorize the tenant-to-installation and tenant-to-repository relationship.

Self-maintaining API operations

@lssm-tech/integration.provider-github/github/maintenance exposes the bounded provider operations required by @lssm-tech/bundle.workspace/maintenance: exact refs and trees, atomic branch commits, stale-ref detection, check-run observation, draft pull requests, installation discovery, and exact-ref rollback.

The additive native-automation operations mark a draft ready and schedule GitHub auto-merge only when the pull request still matches an exact expected head SHA. They are idempotent, preserve branch protection, and never call the direct merge endpoint. Existing provider implementations may omit these optional capabilities.

The bundle adds signed migration-pack enforcement, webhook verification and durable delivery replay. This package does not grant repository access, resolve tenant authority or bypass branch protection.

Local commands

  • bun run build
  • bun run typecheck
  • bun run test
  • bun run lint:check

./editorial implements the library-owned editorial Git transport using native branch commits, exact refs, comparisons and file reads. Supply current scope/repository authority for every commit or reconciliation. Commit messages bind the immutable publication artifact; recovery requires one matching commit directly after the expected base, no unapproved changed paths, and exact file bytes. Incomplete history or mismatches remain unresolved. Files are bounded to 1 MB each; Git acceptance still requires separate deployment verification.

GitHubEditorialSourceLoader from ./editorial-sources loads authorized Markdown and native publication manifests at an exact source commit. Approval binds tenant/workspace/brand, record, publication claim, content digest, paths, expiry and target Git base. It rejects wrong-ref/non-file responses, unsafe or duplicate paths and oversized data (1,000 compilation sources, 1 MB/file, 5 MB total). The reviewed source commit may differ from the target publication branch base, and its SHA is carried into artifact provenance.

Live isolated-branch qualification passed on tryhirly/hirly: native commit, exact marker/file recovery, pinned Markdown and manifest reads, and guarded branch deletion. Independent reads confirmed the branch absent and main unchanged. Evidence: docs/evidence/marketing-operations/live-github-4ed75a74-8678-4f43-a1ee-492006415adb.json. This qualifies these Git operations, not a deployed marketing publication.

Native branch commits retain a 100-file default. fileLimit: 300 explicitly enables larger reviewed atomic artifacts; the editorial transport opts in when necessary. Source approvals may select up to 299 commitPaths from the complete compilation snapshot, plus the manifest. A 146-file live isolated-branch qualification passed; branch absence and unchanged main were independently verified.

For selective commits, the source loader verifies every omitted source byte-for-byte against the approved target base before returning the snapshot. Baseline comparisons have a separate 5 MB read bound; compilation inputs and commit payloads retain their existing bounds. Identical source/base SHAs require no duplicate reads.

Relationships

THIS PACKAGEintegration.provider-github27 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

3 declarations

Declared capabilities

Integration Provider Github

GitHub provider implementation for ContractSpec with repository, issue, and pull request management.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lint:checknode ../../../scripts/biome.cjs check .
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit