.github/workflows: purge Cloudflare cache on deployment

[ttaylorr]

We use Cloudflare in front of the git-scm.com website in order to cache traffic that would otherwise be going directly to GitHub Pages. However, this cache needs to be purged whenever the actual site is updated, otherwise clients will have to wait out Cloudflare's and their own browser's cache TTL until they see the new content.

Usually this is just fine: for high priority deployments where the new content should be reflected immediately, someone can manually purge the cache by logging into Cloudflare and clicking on the "Purge everything" button.

But sometimes folks aren't around to log into Cloudflare, don't have permissions to, etc. Let's remove the need to have anyone log into Cloudflare and instead purge the cache on deployment so that the site is more up-to-date more quickly upon deployment.

(Note that this only purges the cache for git-scm.com, not git-scm.org. The former receives the vast majority of traffic, and when purging manually I almost always skipped git-scm.org without complaints. Let's avoid having two API keys and instead let git-scm.org lag slightly behind git-scm.com after a deployment).

To generate the API key, I logged into Cloudflare and created an API token1 that has permissions limited to "Zone.Cache Purge" for all zones in the Git project's Cloudflare account. The token is stored as a repository secret2.

/cc @pedrorijo91 @dscho

[dscho]

Sorry, couldn't review this earlier: can we also add an if: secrest.CLOUDFLARE_TOKEN != '' so that deployments in forks don't fail?

[ttaylorr]

Great idea, I pushed this out here: #1895.

[dscho]

Hmm. I just noticed that this adds quite a hefty time penalty to the deploy workflow. In this run, it had to build a Docker container, which took 31 seconds, and these 31 seconds blocked the start of even the first step (checking out the repository).

Compare that to the time it took to actually check out, build and deploy the site. I would have loved to link to the corresponding locations in the log, but GitHub Actions' web UI is not responding here after loading but the first page of the log, so I have to give you timestamps:

• 2024-10-03T06:28:18.5603980Z Syncing repository: git/git-scm.com (10 seconds)
• 2024-10-03T06:28:28.0731391Z ##[group]Run ./.github/actions/deploy-to-github-pages (total: 5 minutes and 8 seconds)
  • 2024-10-03T06:29:09.9429502Z ##[group]Run hugo config && hugo --baseURL "http://git-scm.com/" (33 seconds)
  • 2024-10-03T06:29:43.2388513Z ##[group]Run npx -y pagefind@1.1.1 --site public (2 minutes and 48 seconds)
  • 2024-10-03T06:32:31.0520083Z [work-around for transitioning from Rails to Hugo, could be dropped now] (<1 second)
  • 2024-10-03T06:32:31.3970176Z ##[group]Run echo ::group::Archive artifact (3 seconds, but tons of log output)
  • 2024-10-03T06:32:34.9699271Z ##[group]Run actions/upload-artifact@v4 (20 seconds)
  • 2024-10-03T06:32:55.0582356Z Fetching artifact metadata for "github-pages" in this workflow run (this is basically waiting for the remote site to become active, 41 seconds)
  • 2024-10-03T06:33:36.5116198Z Reported success!

In total, the deploy to GitHub Pages Composite Action took 6 minutes and 29 seconds. Note that this is an atypically long time, typically it takes around 4½ minutes (e.g. here). So adding half a minute does make a bit of a difference.

You will note that I tried to be conscious about the need for speed when e.g. a new Git version comes out, and therefore the deployment is performed before the checks are done for broken links, search results etc. The intention is to keep the time window small between the start of the workflow run (which might have been triggered manually) and the time when things are available on the site. That makes the difference between above-mentioned two deployment runs even more stark: in the fast case, the site was deployed within 4 minutes and 6 seconds including the checkout, quite a bit faster than 5 minutes and 8 seconds that exclude the checkout and the Docker container building.

Now, this here PR only targets the deploy workflow run, which is typically only run when merging a PR, not when the (typically scheduled) workflow runs check for a new Git version, for updates of the ProGit book or its translations, or the newest pre-built Git version for Windows/macOS.

That half minute may be acceptable in the scenarios where we merge PRs, but I don't think I'd like to pay that penalty for deployments in general.

At the same time I have to wonder about two things:

1. do we not want the same cache-flushing actually in the deploy to GitHub Pages Composite Action, so that the caches are flushed also when the site is deployed in response to, say, a new Git version?
2. could we avoid building a Docker container at all and then spinning it up later on, when we could run a curl command instead?

[ttaylorr]

In this run, it had to build a Docker container, which took 31 seconds, and these 31 seconds blocked the start of even the first step (checking out the repository).

Yuck, this is definitely sub-optimal. I think that even if we're 31 seconds slower than otherwise, users are probably still seeing the content faster than the would without this patch, since Cloudflare's own caches likely have a TTL which is longer than 31 seconds.

But I dislike the idea that we're spending that much CPU time to build a Docker container which could be replaced with a simple cURL invocation. So I opened up #1896, which should implement your helpful suggestion. Thank you! 🙇‍♂️