2.8 KiB
Step 1 validation evidence: GitHub SCM connector
Intent established
Step 1 is the source-specific implementation of the Step 0 connector contract. It is deliberately scoped to GitHub repositories and paths, supports Markdown/plain-text/source files, and has three invocation paths: full synchronization, cursor-based incremental synchronization, and webhook-triggered synchronization. Its observable output is a KAB-compatible normalized document, not a raw GitHub API response.
Artifact map
| Requirement | Inspectable artifact | Evidence to inspect |
|---|---|---|
| Contract adapter | src/connectors/github.py |
Connector input/output types and normalized-document construction |
| Repository and path scope | src/connectors/github.py |
Repository identity, include/exclude globs, and supported-extension filtering |
| Authenticated retrieval | src/connectors/github.py |
Managed-secret token injection and authenticated GitHub API requests |
| Full and incremental sync | src/connectors/github.py |
Full tree traversal and revision/cursor-based changed-file traversal |
| Webhook and revision metadata | src/connectors/github.py |
Push-event SHA/ref parsing, signature verification, and source revision provenance |
| Regression evidence | tests/test_github_connector.py |
Focused tests for scope, file types, pagination, cursor updates, signatures, and idempotency |
| Deterministic inputs | tests/fixtures/github/ |
API payload and webhook fixtures used by the focused tests |
Platform-compliance checks
- GitHub REST requests are authenticated and paginated; credentials are configuration references rather than document content.
- A webhook is accepted only after HMAC-SHA256 verification with the configured secret.
- Repository/path filters are applied before publication, so an event cannot widen a configured scope.
- Revision SHA, source URL, fetched timestamp, and connector identity are retained as provenance.
- The synchronization cursor is advanced only from the completed source revision, allowing retry-safe incremental runs.
- Unsupported binary formats are excluded; Markdown, text, and configured source extensions are normalized into the shared document shape.
- Tenant and source ACL fields are copied into every emitted document; no cross-tenant fallback is permitted.
Verification evidence
The focused verification was executed against the Step 1 artifact boundary with:
python -m pytest tests/test_github_connector.py -q
python -m compileall src/connectors/github.py
The verification boundary is intentionally narrow: it checks the connector and its fixtures without regenerating or changing Steps 0, 2, 3, 4, 5, or 6. The generation result records the same commands and the contract/platform assertions above so the step has a step-specific, inspectable result rather than relying on a cluster-level result.