Configuring your repo for publishing on pages.nist.gov

Prerequisites

• Set up a GitHub account (NIST allows use of your personal account; no need for a separate one; just be sure you have your NIST email address registered as an additional email address on your account, and enable Two-factor Authentication (2FA))
• Join the USNISTGOV organization (see http://github.nist.gov)
• Create a public GitHub repository within the USNISTGOV organization
• Create a branch within that repository named nist-pages containing your Jekyll and other site content
  • You probably do not want nist-pages to inherit the history of your existing branches. To create a new empty branch:

    git switch --orphan nist-pages
    git commit --allow-empty -m "Initial commit on orphan branch"
    git push --set-upstream origin nist-pages

  • Make sure you’ve added NIST required headers/footers and Google Analytics to every page of your site as described Here

Configure your repository

(NOTE: we've had to revoke most users' admin access to the repos, so you may not be able to do this part yourself. If you don't see the Webhooks option in settings then you'll need to submit a request to [email protected] to have the webhook enabled for you.)

For the rest of these instructions replace REPO with the name of your GitHub repository.

1. Log in to your repostory on GitHub: https://github.com/usnistgov/REPO
2. Click on the Settings tab (near the top of the page, with a gear icon)
3. Click on Webhooks (in the left side nav bar)
4. Click the "Add webhook" button (top right corner)
5. Supply a Payload URL of: https://pages.nist.gov/deploy
6. Set the Content type to: application/json
7. Ensure that Secret is blank
8. Ensure that "Just the push event" is selected
9. Ensure that Active is checked
10. Click the green "Add webhook" button

If your repo is entirely to support use of pages.nist.gov and does not contain any other branches or code, you may also want to make nist-pages the default branch for your repo. (You must first have created the branch.)

1. While still in the Settings tab, click on Branches in the left nav bar
2. In the "Default branch" section select nist-pages in the pulldown menu, and click the Update button

At this point you will probably have to push an update to your repo's nist-pages branch, to cause a push operation that will trigger the webhook and result in the publishing of your site.

Your site will be published as: https://pages.nist.gov/REPO

If there are errors building your site, you should receive a copy of those errors in your email.

NEW: Protect the nist-pages branch

Please note that the pages server operates by cloning your repo from github, therefore in order to avoid problems you must avoid actions such as git push --force or any other sort of action that will force the server into a situation where manual merging is required. (It can't!) Commits you make to the nist-pages branch must be fast-forwardable.

Therefore it is strongly recommended to go into the branch settings for your repo and make nist-pages a protected branch. This will cause github to refuse force-pushes and a number of other similarly destructive operations and prevent problems with the Pages server. Note that it appears that this will prevent editing your files directly on github.com; but I have not tested this.

Instructions for doing this can be found here but basically:

1. Go into your repo settings
2. Click Branches in the left menu
3. Under Protected Branches select the nist-pages branch
4. Select "Protect this branch"
5. Click "Save changes"