docs: define workspace evidence registry contract
This commit is contained in:
@@ -39,10 +39,13 @@ Create one private repository such as `thoth-workspaces.git`. It contains canoni
|
||||
definitions and generated artifacts only:
|
||||
|
||||
```text
|
||||
thoth-workspaces.yaml
|
||||
workspaces/<workspace-id>.yaml
|
||||
workspaces/<workspace-id>.env.example
|
||||
workspaces/<workspace-id>.md
|
||||
registry.git/
|
||||
├── workspaces/
|
||||
│ └── <workspace-id>.yaml
|
||||
├── workspace-content/
|
||||
│ └── <workspace-id>/evidence/...
|
||||
└── workspace-docs/
|
||||
└── <workspace-id>/{contract.env.example,README.md}
|
||||
```
|
||||
|
||||
For SSH, use a scoped deploy key, a verified `known_hosts` file, and strict host-key checking. For
|
||||
@@ -66,6 +69,32 @@ THT_WORKSPACE_GIT_CA_FILE=/absolute/path/installation-secrets/git-ca.pem
|
||||
For HTTPS set `THT_WORKSPACE_GIT_CREDENTIALS_FILE` instead of the SSH key/known-hosts pair. Remote
|
||||
and branch are non-secret; every `*_FILE` is a local path whose content never enters Git or logs.
|
||||
|
||||
## Curator flow for shared-registry Evidence
|
||||
|
||||
Follow this order; the [canonical Evidence contract](../contracts/workspace-evidence-v3.md) defines
|
||||
the source shapes and safety boundary.
|
||||
|
||||
1. Clone the one shared registry, or update the review clone with `git pull --ff-only`.
|
||||
2. Add source bytes below `workspace-content/<id>/evidence`, then commit and push.
|
||||
3. Validate and publish the descriptor against that base commit.
|
||||
4. Inspect `workspace-docs/<id>/contract.env.example` and `workspace-docs/<id>/README.md`.
|
||||
5. Provision only the selected Evidence `*_FILE` files outside Git and strictly below a root in `THT_WORKSPACE_SECRET_ROOTS`; add matching host-only `*_SOURCE` paths for the generated connector override.
|
||||
6. Render or acquire the runtime config, then run `tht config check -c <path>`.
|
||||
7. Stop: P2/P6 later performs preprocessing and materialization.
|
||||
|
||||
For example, a signed-HTTP workspace and a different static-S3 workspace can use these host-only
|
||||
connector sources; the values are paths, not file contents:
|
||||
|
||||
```dotenv
|
||||
THT_WS_SIGNED_HTTP_EVIDENCE_SIGNED_URLS_SOURCE=/absolute/path/installation-secrets/signed-http-evidence-urls.json
|
||||
THT_WS_STATIC_S3_EVIDENCE_ACCESS_KEY_SOURCE=/absolute/path/installation-secrets/static-s3-evidence-access-key
|
||||
THT_WS_STATIC_S3_EVIDENCE_SECRET_KEY_SOURCE=/absolute/path/installation-secrets/static-s3-evidence-secret-key
|
||||
THT_WS_STATIC_S3_EVIDENCE_SESSION_TOKEN_SOURCE=/absolute/path/installation-secrets/static-s3-evidence-session-token
|
||||
```
|
||||
|
||||
The descriptor and declared filesystem root are validated at the same registry commit. The
|
||||
browser shows a read-only Evidence summary, while exports omit Evidence bytes.
|
||||
|
||||
## Shared Git values, local bindings, and secret files
|
||||
|
||||
| Location | Contains | Never contains |
|
||||
|
||||
Reference in New Issue
Block a user