Update doc website on every push to main #53
Conversation
This workflow will keep the documentation website up to date with main, automatically. To test it, we'll set it up to trigger on pull requests, too. This will show us whether deployment works from a github workflow. Before landing, we'll remove the pull request trigger.
I cancelled the `--force` attempt, because it might kill all the history for the branch. (Not that we care much about the `gh-pages` branch, but I'm hesitant to take an irreversible step before trying other approaches.)
Their absence prevents us from getting correct descriptions.
Maybe that's why the description wasn't working?
|
The main blocker right now is that the git description isn't showing up correctly in au.hh. When I run the deploy command locally, it includes the tags, but not when I run via github actions. |
|
This looks promising: actions/checkout#701 |
The `git describe` is working again, but it's referring to weird merge commits such as 7f283f0. I can't figure out what is creating these commits. One of the parents happens to be the current HEAD of main. This makes it seem likely that it would "just work" if we restrict it to main (which we want to do anyway), because the attempt to merge that branch with itself should be a no-op. I'm going to try triggering on this present branch first though.
Also, tweak the comment.
We expect this to fail based on reduced permissions for the GITHUB_TOKEN.
This may not be enough; we may need to add id-token permissions too.
I did get a failure, but not the one I expected.
This time I did get the failure I expected.
After all, I'm just pushing to a branch.
This cleans up the temporary triggering from this PR.
There was a problem hiding this comment.
LGTM
Does the build still pass if it's a noop (i.e no doc changes contained in a PR that lands on mainline)? If so we're probably ok, but something to consider would be to only run the action if docs/** files have changed (or other relevant docs deps) using explicit paths.
Hmm... I really like that idea in principle, but I wonder how it interacts with the auto-generated single-file packages, Still, maybe someday we could consider only generating them on tags, say. |
This workflow will keep the documentation website up to date with main,
automatically.
We also used an action which sets the git user to the github-actions
bot, which makes the branch history for
gh-pageslook nicer.Currently, in order for the manifest in
au.hhandau_noio.hhto becorrect, we must fetch the entire repo (all branches and tags) at the
checkout step. This will get more expensive over time as the repo
grows. However, we don't expect huge amounts of growth, and this step
is not very time-sensitive, and we're currently at only 1 second, so
this should be good enough for the foreseeable future.
To test it, we set it up initially to trigger on pull requests, too.
This let us hammer out the kinks. Check out the recent history of the
gh-pagesbranch (especially activity on Dec 24, 2022) to see theresults: https://github.com/aurora-opensource/au/commits/gh-pages
After this PR was first posted, we also reduced the permissions of the
GITHUB_TOKENglobally, to be read-only by default (so we could followthe principle of least privilege). This specific workflow needs write
access to the contents of the repository, because we are pushing commits
to the
gh-pagesbranch. Thus, we now include this permissionexplicitly.