infra: automatically post documentation previews for PRs

[neongreen]

This adds a new workflow that renders docs, publishes them to https://jj-preview.github.io/docs/, and posts a link to the PR thread.

Ignore all commits except for the last one. (uv changes are #4822)

How it looks in action: neongreen#1

TODOs

• Add people to the jj-preview org
• Add the deploy key to martinvonz/jj
• Enable the docs-preview-build workflow for forks

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, demos/)
• I have updated the config schema (cli/src/config-schema.json)
• I have added tests to cover my changes

[martinvonz]

@ilyagr, you know much more about the doc generation than I do. Will you have time to review this?

[ilyagr]

I will take a look, yes.

[ilyagr]

I'm guessing only @martinvonz can do this, right?

Speaking of which, I just invited Martin to the jj-preview org. It's a party now. :)

[neongreen]

Yeah, Martin needs to add a GH secret. Or give someone a "CI/CD admin" role:

https://github.blog/changelog/2024-09-25-introducing-ci-cd-admin-a-new-pre-defined-organization-role-for-github-actions/

With the new CI/CD Admin role, organization owners and teams can now delegate comprehensive CI/CD management to individuals without the need to maintain a custom role

[martinvonz]

I've added a secret called DOCS_DEPLOY_KEY. Its public key is:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH5kNau/89p02CNJy0I+ijuE0qZUp+HjhZgZLtJ64m9y

[ilyagr]

Thank you! I added the public key to https://github.com/jj-preview/docs/settings/keys. I also invited Martin to that org, but there's probably now no immediate need for him to join.

[ilyagr]

Might make sense to add a comment: # Creating this is documented in docs-preview-deploy.yml.

[ilyagr]

I'd add:

This feature is experimental, feel free to open a bug or tell us in a chat if something is not working. We may remove it if it's too flaky.

You can always build and serve the docs on your own machine by following the instructions at https://martinvonz.github.io/jj/prerelease/contributing/#previewing-the-html-documentation

[ilyagr]

(Thinking out loud, we can fiddle with this later if necessary) This might create a lot of empty dirs.

I don't think it matters much, but perhaps a better approach would be:

• Deploy a file called PR_CLOSED to the dir in the docs repo here. No need to delete anything.
• Have an action in the docs repo that deletes all dirs with PR_CLOSED marker if it's over 7 days old.

I'm not sure how well that will work if that action happens to happen while another action is deploying to the docs. But I'm also not sure it'd be worse than with this PR as is; I'm not sure how this PR will do if the cleanup action on one PR is running at the same time as the deploy action acts on another PR.

It is something we can discover experimentally, though.

[neongreen]

This might create a lot of empty dirs.

It actually deletes the dir entirely (I checked).

I'm not sure how well that will work if that action happens to happen while another action is deploying to the docs.

Good catch. In fact, GHA doesn't support a "workflow queue" at all — if you use concurrency:, it will only keep one pending job in the queue.

I will fix that by disabling force and single-commit and switching to per-PR concurrency groups.

[neongreen]

Update: I will also delete the cleanup entirely b/c the extra complexity is not worth it

[ilyagr]

(Thinking out loud) Would just adding the PR_CLOSED file (or something like that) be too complex as well? Then we could occasionally clean up manually.

Unless we nuke the repo history, garbage collection won't save much git storage, but it might save on the amount of traffic needed to deploy the website. OTOH, GitHub seems to take care of that, so maybe it's not a problem (or we could assume that they are smart about it and use rsync).

Ultimately, this is up to you.

[neongreen]

I just spent several hours reading about GHA security and learned (among other things) that all workflows have access to repo secrets.

We can mitigate that by creating a "deployment environment", scoping it to the main branch, and moving the secret there.

• Move the deploy key (can call the environment eg. "preview") — https://github.com/martinvonz/jj/settings/environments/new
• Configure the environment to only allow deploys from the main branch
• I will change the deploy/cleanup workflows to require environment: preview

[martinvonz]

I just spent several hours reading about GHA security and learned (among other things) that all workflows have access to repo secrets.

Thank you! I've moved the private key to the new preview environment now (and removed it from the project's top level).

[neongreen]

GitHub closed this PR b/c I renamed the branch in my fork.

I’ll make a new PR after fixing a few papercuts in the new version.