mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-09-05 23:26:06 +00:00
Anso
0928765232
* fix(git): make gitSourceStatus exhaustive over GitSourceErrorCode GIT_ERROR was the only code falling through the implicit default branch. Give it an explicit case and add the same never-guard webhookPullStatus already uses, so a future code with no mapping is a compile error instead of a silent 400. * fix(git): fail loudly under CI when git or sshd is missing Every real-git and real-sshd integration suite carried its own local gitAvailable()/sshdAvailable() probe and skipped silently when the dependency was absent, in CI as well as locally. A cell in the upcoming support matrix could then advertise automated proof while the test that proves it never ran. Consolidate into shared requireGitBinary()/requireSshd() helpers (one for backend vitest, one for Playwright, since backend's rootDir pin blocks a cross-directory import) that take an injectable probe. Locally a missing dependency still skips; under CI it throws with an actionable message naming what's missing. * feat(docs): publish a versioned Git transport support matrix Adds docs/git-transport-support.yaml as the canonical claim set for every transport/ref/auth/host/CA combination Git Sources supports, each claim naming its own reproducible evidence rather than generalizing from a related test. A claim is supported only when a real end-to-end test (or a dated live attestation) proves that exact combination; everything else is marked unverified, never assumed. The published page (docs/features/git-transport-support.mdx) is generated from the YAML by backend/scripts/git-support-matrix, so it cannot silently drift from what the tests actually prove. A new backend test (git-support-matrix.test.ts) enforces this: schema validity, evidence semantics (supported needs success evidence, unsupported needs a reproducible rejection, unverified forbids evidence entirely), byte-identical page generation, and that every referenced test title resolves via the TypeScript AST rather than a string search that a skipped or commented-out test would pass. The error-model section is cross-checked against the real GitSourceErrorCode and TransportFacingCode unions and against gitSourceStatus's actual HTTP mapping, so the matrix and the runtime behavior cannot diverge either. Named Git hosts (GitHub, GitLab, Gitea, Forgejo, Bitbucket) and the direct-proxy/Pilot execution paths are seeded as unverified pending a live attestation pass; only the generic local-fixture combinations already proven by the real-git integration suites are marked supported today. * docs(git): scope GitHub claims to what this pass can actually attest Splits the GitHub row into a public no-auth claim (attestable with a real public repository) and separate PAT/SSH deploy-key claims marked unverified with an explicit reason: this pass holds no real GitHub credential to exercise them with, and none is assumed or fabricated. * feat(docs): attest the Git transport matrix live against real hosts Runs the QA fleet's live Sencho instance through the transport combinations that automated fixtures cannot exercise, then records each result in docs/git-transport-attestations.yaml so it can be re-run and compared later. GitHub, GitLab, and Bitbucket are attested over public HTTPS against real, stable, publicly-owned demo repositories (branch and pinned SHA; GitLab additionally has a tagged fixture). Gitea and Forgejo get full coverage (branch, tag, and SHA, over both HTTPS with a per-source CA and SSH with a deploy key) against disposable self-hosted instances stood up for this pass, including a private repository so the authentication and host-key failure classifiers were exercised against a real wrong credential and a real wrong host key, not just the mocked corpus. The direct-proxy and Pilot execution paths are each confirmed once against a real public host, proving the distributed dispatch itself rather than assuming it from the local-path evidence. Left honestly unverified: GitHub PAT and SSH deploy-key auth (this pass holds no real GitHub credential), a GitHub tag combination (no small stable tagged fixture found), and a Bitbucket tag combination (the fixture repository carries none). Every claim's evidence records its exact transport, ref, auth, host, CA, and node path so nothing here is extrapolated from a neighboring result. All infrastructure created for this pass (two throwaway Git server containers, one probe stack) was torn down afterward and the fleet's container list was confirmed to match its state before the pass. * style(git): replace em dashes and fix a stale .mjs reference Directive 18 applies to code comments and build markers too, not just prose. Also corrects the claim set's header comment, which still named render.mjs after the renderer was moved to render.js to match the house convention for backend scripts.
83 lines
6.2 KiB
Plaintext
83 lines
6.2 KiB
Plaintext
---
|
|
title: Git Transport Support
|
|
sidebarTitle: Transport Support
|
|
description: Which transports, reference types, authentication methods, and Git hosts Git Sources supports, with the evidence behind each claim.
|
|
---
|
|
|
|
<Note>
|
|
Git Sources, and everything on this page, is available on every tier, including Community.
|
|
</Note>
|
|
|
|
This page states exactly what Git Sources supports today: which transports, reference types, authentication methods, TLS trust modes, and Git hosts, and what happens where a combination is not supported or not yet verified. For how to configure a Git source, see [Git Sources](/features/git-sources).
|
|
|
|
Every "Supported" row here is backed by a test that runs on every change to Sencho, or by a dated pass against a real instance of that host. A row marked "Not yet verified" is not a claim of failure: it means that specific combination has not been exercised yet, so it is not advertised as working. Nothing on this page is inferred from a related combination that behaved correctly.
|
|
|
|
<!-- GENERATED:BEGIN (run `npm run matrix:render` in backend/ to regenerate, do not edit by hand) -->
|
|
|
|
## Transports
|
|
|
|
| Transport | Status | Notes |
|
|
| --- | --- | --- |
|
|
| HTTPS | Supported | Personal Access Token for private repositories, or no credential at all for public ones. TLS verification uses the system trust store by default, or a per-source custom CA when configured. |
|
|
| SSH | Supported | A read-only deploy key with strict host-key verification. Standard (22) and nonstandard ports are both supported. |
|
|
|
|
## Reference types
|
|
|
|
| Reference type | Status | Notes |
|
|
| --- | --- | --- |
|
|
| Branch | Supported | Tracks the head of a branch; each pull resolves and pins the exact commit. |
|
|
| Tag | Supported | Both annotated and lightweight tags resolve to their target commit. |
|
|
| Commit SHA | Supported | A full commit SHA is pinned directly; the Git host must advertise the commit on some branch or tag. |
|
|
|
|
## Authentication
|
|
|
|
| Method | Status | Notes |
|
|
| --- | --- | --- |
|
|
| Public (no auth) | Supported | For public repositories. |
|
|
| Personal Access Token | Supported | Stored encrypted at rest, never returned after save. |
|
|
| SSH deploy key | Supported | Stored encrypted at rest; the server host key is verified on every fetch. |
|
|
|
|
## Git hosts
|
|
|
|
| Host | HTTPS | SSH | Branch | Tag | Commit SHA | Evidence |
|
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
| Generic (self-hosted or any Git server) | Supported | Supported | Supported | Supported | Supported | Automated, every change |
|
|
| GitHub | Supported | Not yet verified | Supported | Not yet verified | Supported | Live, 2026-09-01 |
|
|
| GitLab | Supported | Not yet verified | Supported | Supported | Supported | Live, 2026-09-01 |
|
|
| Gitea | Supported | Supported | Supported | Supported | Supported | Live, 2026-09-01 |
|
|
| Forgejo | Supported | Supported | Supported | Supported | Supported | Live, 2026-09-01 |
|
|
| Bitbucket | Supported | Not yet verified | Supported | Not yet verified | Supported | Live, 2026-09-01 |
|
|
|
|
## TLS and certificate authorities
|
|
|
|
| Mode | Status | Notes |
|
|
| --- | --- | --- |
|
|
| System trust (default) | Supported | The host running the fetch trusts its system certificate store. |
|
|
| Per-source custom CA | Supported | Combined with the system trust anchors, so public hosts keep validating normally. Redirects are re-resolved and only followed when they stay on the source's own host. |
|
|
|
|
## Not supported
|
|
|
|
- **No rate-limit classification.** A Git host rate-limit response (for example GitHub's secondary rate limits) is not classified as its own error state. It surfaces as an authentication failure or a generic transport error depending on the host's exact response. Wait and retry; there is no dedicated rate-limit message or backoff guidance yet.
|
|
- **No Git LFS.** Compose and env files tracked via Git LFS are rejected rather than silently fetched as pointer stubs. Commit plain files instead.
|
|
- **No submodules.** Submodule contents are not fetched. Inputs and build contexts that reference submodule contents are refused with an actionable message; a warning is shown when .gitmodules is present.
|
|
- **No sparse or partial clone.** Every fetch materializes the complete repository at the resolved commit (shallow, single-branch); there is no sparse or partial clone for large monorepos.
|
|
- **No GitHub App authentication.** Authentication is Personal Access Token or SSH deploy key only. GitHub App installation tokens are not supported.
|
|
- **No provider pull/merge request revisions.** Sources track a branch, a tag, or a pinned commit SHA. A provider-specific pull request or merge request revision (for example GitHub's refs/pull/N/head) is not a supported ref shape.
|
|
- **Outbound target restrictions.** Repository targets that resolve to loopback, link-local, multicast, or selected special-use addresses are refused before any request is sent. Private hosts on an operator's own LAN or VPN are not affected by this restriction.
|
|
- **Branch/tag name collisions.** A bare ref name resolves as a branch first, then as a tag. If an operator renames a branch and a tag of the same name later appears, the source silently starts resolving the tag instead. A ref name that is also a valid 40 or 64 character hex string resolves as a commit SHA before either lookup.
|
|
|
|
<!-- GENERATED:END -->
|
|
|
|
## How these claims are verified
|
|
|
|
Two kinds of evidence back the rows above:
|
|
|
|
- **Automated.** A real `git` client, talking to a real local test server over HTTPS or SSH, drives the exact same code path Sencho uses in production. These tests run on every change, so a regression here fails the build before it reaches a release.
|
|
- **Live.** A dated pass against a real instance of the named host (a public GitHub, GitLab, Gitea, Forgejo, or Bitbucket repository, or a self-hosted instance under Sencho's control). This is repeated periodically, not on every change, so its date tells you how current the result is.
|
|
|
|
A host that is not listed, or a combination marked "Not yet verified," most likely still works: Git Sources speaks the standard Git smart-HTTP and SSH protocols, not anything host-specific. It simply has not been exercised as its own row yet.
|
|
|
|
<Card title="Git Sources" icon="code-branch" href="/features/git-sources">
|
|
Configure a repository, review pull previews, and read the field-by-field reference for every setting mentioned above.
|
|
</Card>
|