Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.


The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Migration Guide

Welcome to your migrating journey onto Federalist! This process may be difficult. 18F generally cannot provide support for migration work beyond general guidance under a standard Federalist agreement, but if you are in a situation where you need a lot of help, please contact us for a path analysis from our Custom Partner Solutions team.

Before you start

Get a sense of how big your migration is before you start. How many pages does your site have? This will help you estimate how long it will reasonably take to migrate your content.

Federalist’s role

Federalist is a backend hosting service that enables lots of flexibility with the look and feel of a hosted website. Federalist is opinionated about the back end hosting of a site, so your code needs to be in a form that Federalist can host, this can be static HTML/CSS/JS files or supported site engines.

In general, we expect getting your site up as static files to be the quickest option, but static html can be very difficult to edit and maintain. Even though it takes more effort to initially convert your site content to a new format, using a site generator, such as Jekyll or Hugo, can ease the long-term maintenance burden of your site. For example, Jekyll and Hugo use templates to manage common content, so adding an item to a global menu can be done in one file instead of many.

Planning the move

You should plan to move everything from your existing site into a format that Federalist can publish, though. For larger sites, getting an export of the source of your old site might be essential.

Working with your current hosting provider, list out your options for exporting, which could include:

Ideally, to align with how most site generators work, the export will have your content in one set of files and the frontend html/css look/feel in another set of files.

Building a Timeline

You should create a timeline for the site migration. This may be an opportunity to restructure how your content is organized or redesign the look and feel of the site. Think about how much time/work these additional tasks require.

You should plan a stopgap measure into your migration timeline. This could be a basic Federalist setup with a landing page that provides information to key stakeholders or notifies visitors that work is in progress.

For these pages you can simply fork them on Github and reword the content in order to have it based on your website, or create your own static page to note the work in process. 18F can help you with your stopgap measure if you have a signed IAA.

Testing the plan

Test your migration concept by first making one page and learning how to work with Federalist. Try using setting up layouts and content separately. Once the first page is live on a prototype site, you can migrate other pages, but focus on completing one first so that you have a good sense of the effort required.

You should create a staging branch in your Github repo and create a pull request from that branch to your main branch. Then, migrate to the staging branch and push to main once you’ve confirmed everything is working correctly in staging. This will help you keep track of changes and provide and easy way to identify what is causing issues. You should push to main everyday.

Reserve time for the go live process. Plan few days before live launch to do a soft launch for stakeholders at a different URL.

The migration team

Who you need in your migration team is based on the work involved in your specific migration. Generally, a migration PM is probably not necessary unless you are managing against a timeline.

Your team will need the following access to get started:

You are able to start working while IAA is being signed.

Additional info

If your site has over 1 GB of images to serve you should look into another way to store those files. Github is not intended to store large amounts of files.