11 Intro to Federalist and managing builds - 18F/federalist-jekyll-netlify-cms-guides GitHub Wiki

Using Federalist for the first time

The Jekyll version of ChildCare.gov is hosted on the Federalist platform. Each time code is pushed to the GitHub repo on any branch, a build is initiated on Federalist scoped to the branch that the changes were made on.

Log in to Federalist to see builds and access other features.

If it’s your first time going to Federalist, you may not see any sites listed when you sign in. To add the ChildCare.gov site to your Federalist UI, please do the following:

• Copy the URL to the project on GitHub; as of April 2022 this would be: https://github.com/HHS/childcare-gov
• After signing into Federalist, click the + Add site button near the top
• On the next screen, paste the URL to the project into the text input field that appears just below the heading Use your own GitHub repository
• Click the Add repository-based site button just below where you pasted the URL in the previous step.

Managing builds on Federalist

After adding ChildCare.gov to your Federalist account, a link to hhs/childcare-gov should appear under the Your sites list, which is the main page that you land on after logging in. Once you click that link, you’ll see the Build history of the site.

Build history page for ChildCare.gov on Federalist

From the Build history page, you can see a list of builds and their different statuses; the build names are the branch names from GitHub. A yellow spinner image indicates that a build is in progress and has not yet completed. A green checkmark indicates that the build is done and you can see a Preview site link directly under the branch name.

As of April 2022, builds typically take about 5-6 minutes to complete. On the Federalist page, you can click the Refresh builds button to see if the build you’re interested in has completed. You can also enable automatic page refreshes by clicking the Auto Refresh: OFF link which will make the build history area refresh automatically approximately every 15 seconds.

Deployment logs

Under the Message column where you can see the build status, there is a View logs link for each build in the build history. Clicking this link will show you the full build and deployment log for the build whose link was clicked. Any error messages can be seen in the logs.

A typical deployment process would go like this:

• Federalist git clones the branch into a temporary directory and determines what buildpak to run
• Federalist runs a buildpak that sets up the build environment
• Federalist begins installing your applications dependencies. Inthe case of Jekyll, it’s reading both the Gemfile.lock and package-lock.json files. Buildpak and dependency installation takes around 3 minutes.
• A Jekyll build is initiated, which generally takes 15-25 seconds. Everything is output to the _site directory.
• All files are published to S3 in an upload process that takes a few minutes. If there’s a file that you don’t want being sent to S3, add it to the exclude key in _config.yml

Environment variables

Anytime you have a need to store sensitive things like API keys that you want to access in a template but you don’t want to commit them to your code repository, you can use environment variables inside of Federalist.

Federalist is a Federal Information Security Management Act (FISMA) low-rated system. Avoid storing information in environment variables that would be considered moderate or high. You can view the FISMA rating levels on page 10 of this PDF.

In the left side navigation menu within Federalist, click Site settings and scroll down until you see the Environment variables section and click the + to expand the environment variables section.

Next, click the + to the right of Add a new environment variable to get to the form that allows new environment variables to be created. You must provide a name and value for your environment variable in order to enable the blue Add button to be clicked.

Once the environment variable has been created, Federalist will add it into your _config.yml file at build time. You can access your environment variable within a Liquid template or file by outputting it like any other site variable, {{ site.yourEnvVariable }}.

Note: This does place the value of your environment variable into an HTML page which will be served to the public. Also, some names are reserved for Federalist use, you should see alerts in the logs if you’re using one of them.

Adding a new environment variable within the Federalist UI