mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-10-25 21:20:25 +00:00

Files

T

History

Anso 26f77cac96 docs: v1 docs refresh (batch 9) (#2181 )

* docs(gitops): complete the overview's source states, placement limits, and control locations

List every source state the app can show, with the order in which the most
serious one wins. Add the pin-driven and unreadable-evidence cases to what
the placement policy hands back to an operator, and name the controls where
each policy is set.

* docs(git-sources): document the polling controls, Manual behavior, and pending-update indicators

State the per-node polling interval and its range, that a Manual source is
never polled or retried but still stages a plan when a webhook delivers a
commit, and where the pending-update icon and button lead. Add common setups
and what Git sources do not do, and correct the create form's alt text.

* docs(git-authentication): cover the Git error cases and current Bitbucket credentials

Add the failures a Git source can report that were missing from
troubleshooting (embedded credentials, SSH without a deploy key, blocked
hosts, rate limits, certificate expiry and hostname mismatch, network
errors), state that the token is only given to the repository's host, and
replace the deprecated Bitbucket app password guidance.

* docs(git-webhooks): state the GitHub content type, remote-node failures, and limits

A form-encoded GitHub delivery fails verification and answers 404, so say to
set the content type to JSON. Add the 500 a delivery gets when the owning
node is unreachable, correct how the hub forwards to a remote node, and list
what provider hooks do not cover.

* docs(git-secrets): document linking an encrypted repository and where encrypted values work

A repository that is already encrypted cannot be linked, because the identity
belongs to a linked source. Encrypted values belong in env files and
file-backed secrets, not in image references or published ports, which
Sencho resolves before decrypting.

* docs(blueprints): correct permissions, remote deploys, and roadmap wording

Describe the permissions Blueprint actions need instead of an admin-only
rule, say that a remote node runs the deploy itself with its own policy and
scanner state, and list all three drift notifications. Remove the repeated
marker, policy gate, and snapshot explanations, the raw apply request
format, and statements about future features.

* docs(git-managed-blueprints): add who can take each step and the limits

List the permission each authority step and rollout control needs, say that
webhooks do not fetch a Blueprint's source so Pull source and polling bring in
new commits, and gather the constraints that were scattered through the page.

* docs(gitops-portfolio): name the row menu actions and state what the portfolio does not do

List the exact row menu items for Direct and Blueprint applications, and
add the limits: hub only, navigation from row menus, and how unreachable
nodes appear.

* docs(gitops-drift): describe the drift row as it appears and add a screenshot

The row shows the class, the deriving component, evidence age, reason, and
expected against observed; the resolving action lives on the application's
status. Name the retry-interval setting, drop rollout states Sencho never
reports, and replace a hedge about which classes are reported.

* docs(git-transport): refresh the live attestations against the 0.98.0 release

Re-run all 21 live attestations (hosted public repositories, the direct
proxy and Pilot node paths, and disposable Gitea and Forgejo instances over
HTTPS with a private CA and over SSH with a deploy key) against the 0.98.0
image, record the new date, commit, and image digest, and regenerate the
matrix page. Describe unlisted hosts without claiming more than was tested,
and add the procedure the attestation record refers to.

2026-10-23 12:51:36 -04:00

README.md

docs: v1 docs refresh (batch 9) (#2181 )

2026-10-23 12:51:36 -04:00

README.md

Git transport live attestations

docs/git-transport-attestations.yaml retains the results of the live passes behind the "Live" rows of docs/git-transport-support.yaml. This file is the procedure that produces them, so a later pass can repeat it and compare.

A live pass proves one exact combination (host, transport, ref type, authentication, certificate trust, node path). It never extrapolates to a neighbouring combination.

Before you start

A Sencho instance running the revision that implementation_baseline names, signed in as an admin.
For the node-path attestations, one proxy-mode node and one Pilot-agent node connected to that instance.
Record the running image's digest (docker image inspect <image> --format '{{index .RepoDigests 0}}').

The request

Every attestation is one POST /api/git-sources/browse through the instance, with the node chosen by the x-node-id header:

{ "repo_url": "https://host/owner/repo.git", "branch": "<branch, tag, or full commit SHA>", "auth_type": "none" }

For a Personal Access Token add "auth_type": "token", "token": "<read-only token>" and, for a private certificate authority, "ca_bundle": "<PEM>". For SSH add "auth_type": "deploy_key", "deploy_key": "<private key>", "ssh_known_hosts_entry": "<line>", taking the line from POST /api/git-sources/ssh-host-key with { "repo_url": "ssh://git@host:port/owner/repo.git" }.

A pass succeeds when the response is HTTP 200 and commitSha is the commit the ref resolves to. A branch resolves to its tip, an annotated or lightweight tag to its target commit, and a full SHA to itself.

Hosted hosts, public repositories

These need no account. Run each with "auth_type": "none" on the local node:

Host	Repository	Refs
GitHub	`octocat/Hello-World`	branch `master`; that branch tip's commit SHA
GitLab	`gitlab-org/gitlab-test`	branch `master`; annotated tag `v1.0.0`; that tag's peeled commit SHA
Bitbucket	`atlassian_tutorial/helloworld`	branch `master`; that branch tip's commit SHA

Repeat the GitHub branch request with x-node-id set to the proxy-mode node, then to the Pilot-agent node.

Self-hosted hosts, disposable instances

Run Gitea and Forgejo at the versions named by host_version in the attestation file, each in a throwaway container:

Create a private certificate authority and a server certificate whose subject alternative name is the address Sencho will reach.
Start the forge over HTTPS with the built-in SSH server on its own port.
Create a user and a private repository with a main branch, an annotated tag v1.0, and a lightweight tag v1.0-light.
Create a read-only access token (repository read scope) and register a read-only deploy key.

Run six requests per forge:

Transport	Authentication	Refs
HTTPS	token with the authority as `ca_bundle`	`main`, `v1.0`, the branch tip's commit SHA
SSH	deploy key and the probed host key	`main`, `v1.0-light`, the branch tip's commit SHA

Remove the containers and certificates afterwards.

Recording the result

In docs/git-transport-attestations.yaml, update each attestation's id, date, source_commit (the commit the instance runs), and sencho_image_digest. Record only structured pass or fail data and scrubbed commands: no tokens, keys, hostnames, or addresses beyond generic fixture identities.
Update every attestation reference and implementation_baseline in docs/git-transport-support.yaml to match.
From backend/, run npm run matrix:render, then npx vitest run src/__tests__/git-support-matrix.test.ts. The test fails when a claim's attestation was recorded against a different commit than implementation_baseline.