Human readable repository state

[jku]

Production root-signing relies on documentation that's manually kept up-to-date to list who the root signers are, what delegations exists, which artifacts the repository contains etc. This has significant downsides and I'd like to avoid this manual work.

It's completely reasonable to expect the tooling to automatically describe important repository details in a way that is always up-to-date and readable in a browser. Some options:

1. javascript solution that dynamically reads metadata and produces html that describes the repo (this requires no build steps but does require someone with js skills)
   • the advantages of this approach are less uploading (since the html+js does not need to change when metadata changes) and ability to make content time-aware ("Next root signing event starts in 2 days")
2. a doc-build step in tuf-on-ci-build-repository where some static docs (markdown or html) are produced and then published alongside the repository
   • as previous (node/svelte) work there is https://github.com/DataDog/tuf-explorer
   • markdown would be fairly easy to produce in tuf-on-ci itself There is a generic issue about this in theupdateframework/tuf-on-ci#39 but it might be more useful to solve the sigstore use case and then see if it's general enough or no...

[jku]

I have a rough POC with markdown in https://github.com/jku/tuf-on-ci/tree/markdown-description. I think I'd prefer HTML but this was so quick to write that I did it. It currently produces the following content for this repository (apologies to signers for unnecessary pings):

Signers

Role	required # of signatures	Signers
root	2	@jku, @kommendorkapten, @joshuagl, @mnm678
timestamp	1	online key
snapshot	1	online key
targets	1	@jku, @kommendorkapten, @joshuagl, @mnm678
registry.npmjs.org	1	@jku

possible downsides:

• this will likely require enabling markdown on GitHub Pages (I think adding a _config.yml file to git is enough)
• There's no builtin markdown rendering on GCS so this is really only useful for https://sigstore.github.io/root-signing-staging/

[jku]

this will likely require enabling markdown on GitHub Pages (I think adding a _config.yml file to git is enough)

I was not able to do this. Maybe it's possible but I can't figure it out

• It's not clear which step actually runs jekyll: maybe it will only happen for data committed to git (I would rather avoid committing redundant files) and not to data I upload to Pages
• it's also possible that I just don't know what the configuration should look like -- there are no example projects

[joshuagl]

I think GH pages requires pushing to git, but it doesn't need to be your main branch or even a branch with similar contents to main. IIRC default configuration is to have a gh-pages branch, or similar, where the contents for the pages are stored.

[jku]

I think GH pages requires pushing to git, but it doesn't need to be your main branch or even a branch with similar contents to main. IIRC default configuration is to have a gh-pages branch, or similar, where the contents for the pages are stored.

tuf-on-ci uses "Github Actions" as source instead of "Deploy from branch" (and I won't change that, the branch method is just insane). Your comment did make me try a fresh project from scratch and the proposed template does this before uploading to pages:

        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site

that looks promising. Would be nice to get this as documentation instead of having to create new projects to find out but this works...

[jku]

That actually pretty much worked: https://jku.github.io/tuf-on-ci-sigstore-test/metadata/

• would be nice to get that at the root level (now it's with metadata) but as v1 that seems decent: Easy to link to from project README
• in general dropping markdown, html and css files in the metadata dir feels a bit dirty

[jku]

The downside of "rendering" on the server is that the description cannot say things like "signing event starts in 2 days" (and guarantee that it stays updated) - a javascript solution could.

See https://jku.github.io/tuf-on-ci-sigstore-test/metadata/ for current example

[jku]

Initial version is in tuf-on-ci now, we should get it in the next release

[jku]

First version of this is now live:

• preprod (GH pages) staging: https://sigstore.github.io/root-signing-staging/
• staging https://tuf-repo-cdn.sigstage.dev/

Two issues remain for the actual sigstage repository:

1. CSS styling is not applied
2. the json links are incorrect

both have the same underlying reason: jekyll writes links as absolute so changing the "root" location from /root-signing-staging/ in staging-preprod to / in staging breaks the links. A workaround for the json links has been merged in tuf-on-ci.

---

I'll modify the README to link to the description and will close this issue.