GitHub Pages is an easy, powerful way to get static websites built using Jekyll, published directly from a source repository. As 18F is a heavy user of Jekyll, we have a need for exactly this kind of functionality, particularly for public-facing artifacts that aren’t projects for customers or that should be managed independently of https://18f.gsa.gov/.

However, there is a wrinkle: In order for a government system to be launched into production, it must first acquire an approval known as an “authority to operate,” or ATO. This represents formal acceptance, by a government official, of the security and privacy risk posed by the system. It also documents the level of the risk and any mitigating controls.

Two of our standard controls, implementing HTTPS Everywhere and using the .gov and 18F DNS infrastructure, are not available with GitHub Pages. Increasingly, we found ourselves putting important and canonical content on GitHub Pages, information that couldn't be found on an official government system. Implementing these controls also ensures that any attack to prevent the public from accessing public information is considered an attack on the U.S. government itself, and therefore serves as an additional deterrent.

This risk threatened to stall a number of public-facing documentation efforts currently underway; however, we figured out a hack. The solution, based on GitHub webhooks and an existing ATO for our 18f.gsa.gov technical stack, proved surprisingly straightforward, and now we’re happy to announce https://pages.18f.gov/, aka “18F Pages.”

Screenshot of 18F Pages site

While the site is still in its earliest stages, we will be adding more content to it over time, as our team generates documentation that we feel is of benefit not just to 18F, but potentially to other government digital service teams. The basic publishing flow amounts to:

  • An 18F staff member creates a new Jekyll site repository on GitHub, e.g., https://github.com/18F/wonderful-website.
  • The staff member adds some content, and pushes to an 18f-pages branch.
  • The website appears at https://pages.18f.gov/wonderful-website/.

You can see the webhook listener implementation in our 18F/pages GitHub repository and read through the 18F Guides Template to understand the details of how our 18F Pages sites are organized and published.