Triggered site builds

When the site repository is separate from the data repository, making a change to the data will not cause those changes to appear on the site. This is because the change to the data only triggers a data rebuild, but the site will not change until it is rebuilt. Out of the box, the only way to rebuild the site is to change a file in the site repository.

This means that, in order to see their updated data on the site, data managers must change a site file to trigger a site build. To avoid this hassle, we recommend that you automate this process. There are two ways to automated the process:

  1. Automatically trigger a site build when data changes
  2. Perform scheduled builds on a nightly basis

We recommend the first option. Both are detailed below.

1. Automatically trigger a site build when data changes

Creating an access token

  1. Create an access token described in this official GitHub documentation. Notes:
    • Select the repo permission, as indicated in those instructions.
    • Save the token somewhere private.
  2. Copy the access token so that you can paste in the next steps.

Adding the access token as a "secret"

  1. Go to the site repository.
  2. Under the repository name, click "Settings".
  3. In the left sidebar, click "Secrets".
  4. Click "New repository secret".
  5. Under "Name", type the following (case-sensitive): token
  6. Under "Value", paste in the access token you copied earlier.
  7. Click the green "Add secret" button.

Then repeat this for the data repository, as follows:

  1. Go to the data repository.
  2. Under the repository name, click "Settings".
  3. In the left sidebar, click "Secrets".
  4. Click "New repository secret".
  5. Under "Name", type the following (case-sensitive): token
  6. Under "Value", paste in the access token you copied earlier.
  7. Click the green "Add secret" button.

Configuring the automatic rebuild

  1. In the list of files in the data repository, click on .github/workflows.
  2. Click on deploy-to-staging.yml.
  3. Click the pencil to edit the file.
  4. Make changes to the file by following the instructions in the notes.
  5. Towards the right, click "Start commit"
  6. Select "Create a new branch for this commit and start a pull request."
  7. Beneath this, click "Propose changes".
  8. Click on the green "Create pull request" button.
  9. Wait a moment to see the message that says "Test PRs / test (pull_request) - in progress"
  10. Wait until you see "All checks have passed". This takes about 5 minutes.
  11. Click on the green "Merge pull request" button.

2. Perform scheduled builds on a nightly basis

Alternatively, you can instead set up scheduled nightly builds. This is easier to setup, but is not preferred, because of the 24 hour delay before changes become visible on the site.

Configuring the scheduled build

  1. In the list of files in the site repository, click on .github/workflows.
  2. Click on deploy-to-staging.yml.
  3. Click the pencil to edit the file.
  4. Uncomment the line that says schedule: and also uncomment the cron line below it. To "uncomment" a line simply remove the # character, making no other changes.
  5. Towards the right, click "Start commit"
  6. Select "Create a new branch for this commit and start a pull request."
  7. Beneath this, click "Propose changes".
  8. Click on the green "Create pull request" button.
  9. Wait a moment to see the message that says "Test PRs / test (pull_request) - in progress"
  10. Wait until you see "All checks have passed". This takes about 5 minutes.
  11. Click on the green "Merge pull request" button.