39 lines
2.8 KiB
Markdown
39 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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.
|