Add a workflow to build and deploy docs site

[ashmaroli]

Summary

Implement a workflow to build our documentation site with the current repository state yet served via GitHub Pages.

(Use an in-house module instead of third-party action for greater control over the process)

---

TODO (after the idea is accepted):

• Add JEKYLL_PAT token (preferably get jekyllbot to step in).
• Refactor to trigger on push event and write to gh-pages.

[ashmaroli]

@parkr Will Jekyllbot be able to provide an access token to have GitHub Actions publish our docs site on its behalf..?

[iBug]

GitHub provides a GITHUB_TOKEN for each Actions run. The token has write access to the repository the workflow is running on. Is it unavailable for any reason?

Ref: https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token

[ashmaroli]

@iBug Honestly, I didn't know about GITHUB_TOKEN.
I've updated the workflow now. Lets see if it works...

[parkr]

I think the GITHUB_TOKEN provided by Actions doesn't allow page builds to be triggered, so I'd have to add a PAT to the secrets for this repo.

[iBug]

@parkr This is no longer the case. I couldn't find the exact timestamp for the change but I can assure you about this. I've been building my GitHub Pages website for months without problems.

@ashmaroli Sorry I forgot to mention: The GITHUB_TOKEN secret on workflows triggered by pull requests does not have write access to the base repository (IMO this is intuitive - you don't want an arbitrary PR to be able to alter your content).

Another thing to note is that when being used to push / pull from repositories, the token must be combined with its owner (i.e. $GITHUB_ACTOR) *. Here's a working example from another project that I work on:

Code:

git clone --depth=1 --branch=gh-pages --single-branch --no-checkout \
  "https://${GITHUB_ACTOR}:${{ secrets.GITHUB_TOKEN }}@github.com/${GITHUB_REPOSITORY}.git" test

* I'm unsure if this is still a problem now, but I had problems with this in the past.

[ashmaroli]

have to add a PAT

That's great @parkr! I think you can provide Jekyllbot's Token for security purposes.

[ashmaroli]

you don't want an arbitrary PR to be able to alter your content

That makes sense.

[iBug]

Update: Here's another source stating that secrets.GITHUB_TOKEN failing trigger Pages builds has been fixed some time in February 2020. (cc @parkr)

@ashmaroli: This is a purely preferential setting. Because GITHUB_ACTOR is always set to github-actions in Actions runs, I always set the committer information to "GitHub" in my Actions workflows. For example:

git config user.name "${GIT_USER:-GitHub}"
git config user.email "${GIT_EMAIL:-noreply@github.com}"

BTW, the identity GitHub <noreply@github.com> is also the committer for all web-based Git operations (where you'll see a Verified badge that reads like following).

This commit was created on GitHub.com and signed with a verified signature using GitHub’s key.

[parkr]

I think adding a @jekyllbot PAT might be a bit scary. It's hard to lock down to a given repo. Maybe what I'll do is create a deploy key for this repo – would that work? I agree that the token should not be usable by contributors to overwrite jekyllrb.com 😱

[ashmaroli]

I'll do is create a deploy key for this repo – would that work?

The latest run aborted with the following:

remote: Permission to jekyll/jekyll.git denied to github-actions[bot].

That could be a good sign indicating that PRs can't push to our repo.

[iBug]

@parkr No worries. As I said above:

The GITHUB_TOKEN secret on workflows triggered by pull requests does not have write access to the base repository

I'd say this is the best option unless you have extra requirements (authenticating another repository etc.). This special token is created every time a workflow runs and is valid for only one hour. Confident to say, GitHub has taken all the security considerations you ever need to.

Using a deploy key is definitely OK, but it adds complexity.

[ashmaroli]

Merging this manually to master on a trial basis. Will revert if unsuccessful.

[iBug]

on a trial basis

@ashmaroli You need not. Merging this into another branch is also OK as long as it's in the target repository.

[iBug]

@ashmaroli I just tested in my repository, specifying the user as x-access-token leads to failure.

Use the following URL for the remote repository, however, succeeded used to succeed.

"https://${GITHUB_ACTOR}:${{ secrets.GITHUB_TOKEN }}@github.com/${GITHUB_REPOSITORY}.git"

---

Update

Things are getting nasty now. My repositories are also failing to push with GITHUB_TOKEN, where all of them were working properly (even yesterday). This looks more like an issue on GitHub's side.

Looks like it's related to this issue: https://www.githubstatus.com/incidents/6tcfpztf6j9m

[ashmaroli]

@iBug and was ${GITHUB_ACTOR} your username?

[iBug]

@ashmaroli ${GITHUB_ACTOR} has consistently been github-actions in my Actions runs.

Sorry I was wrong. ${GITHUB_ACTOR} is my username (iBug).

See the update in the above comment. I'm currently waiting for the GitHub problem to resolve. I think it's the cause of the push failure.

---

Anyway, I'm going to sleep now (1:20 AM in UTC+8). Hope things will be settled when I wake up.