Setting up continuous integration with a GitHub repository using GitHub Actions

If you work as part of a web development team, you may wish to have your entire production codebase source of truth in version control. This way, your team of developers can use your favorite version control system to collaborate, track and easily roll-back changes. Learn more about developer workflows on the HubSpot CMS by following the Creating an efficient developer workflow guide. 

This guide walks through setting up continuous integration with a GitHub repository utilizing GitHub Actions. This guide assumes you are familiar with git and GitHub, as well as building websites using the CMS CLI. If you don’t have that set up yet, follow the Local Development Tooling: Getting Started guide.

Utilizing the CMS CLI, you can fetch your entire developer file system. Running hs fetch project root to copy your Design Manager project to your local environment. 

If you are starting a new project, you can clone, or fork, the CMS Theme Boilerplate, which is designed to give developers a head start on new HubSpot CMS projects. This project has Actions set up to deploy merges to master of https://github.com/HubSpot/cms-theme-boilerplate to https://boilerplate.hubspotcms.com. 

Follow this GitHub help article on adding your project to a GitHub repository.

If you do not already have one, create a package.json file at your project root. Add the @hubspot/cli and js-yaml as devDependencies. This should look something like:

At your project’s root, create a bin directory (refer to the CMS Theme Boilerplate’s implementation). In this directory, create two files:

1. deploy.sh - a shell command which will run the deploy script

Enter the following in this file:

Notice line two is the CMS CLI upload command. Replace src (the location of your projects source files to be uploaded to HubSpot) and cms-theme-boilerplate (the destination name of your project in your HubSpot CMS account.

Note: if files are removed from your project, they will need to be manually deleted within the HubSpot Design Manager. 

1. generate-config.js - a node script to generate an authentication file to deploy to your production HubSpot CMS account.

Enter the following in this file:

No edits to this file are required.

GitHub Actions allows you to run a workflow on any GitHub event. In your project root, create a file at .github/workflows/deploy.yml

Our deploy workflow is going to occur on pushes to the master branch. Paste the following in your deploy.yml file:

 ${{ secrets.HubSpotApiKey }} and ${{ secrets.HubSpotPortalId }} will add your API key and HubSpot account ID secrets as environmental variables in the deploy process, without having to store your API key visibly in source control. Follow the next step to create the HubSpotApiKey secret.

You can refer to the GitHub Actions documentation to learn more about various events you can use to trigger workflows.

To ensure your HubSpot account’s API key is not visible and stored in source control, we will create a secret for it, that will be passed into the deploy script as an environmental variable. In your GitHub repository, navigate to Settings > Secrets and select “Add a new secret”. Name your new secret HubSpotApiKey, and then enter your HubSpot account’s API key as the value. You can get the API key for your account by navigating to Settings > Integrations > API key, selecting "Create key," and then copying the key. Select “Add secret” to save your secret.

This key will be passed into ${{ secrets.HubSpotApiKey }} from your .github/workflows/deploy.yml file. If you name your secret something other than HubSpotApiKey, make sure to update the ${{ secrets.HubSpotApiKey }} variable with the secret name you set.

While your HubSpot account id is not a true secret, it is useful to repeat this process to add your account id(sometimes referred to as a portal id) as a GitHub Secret.  Create a new secret with the name HubSpotPortalId.  Here's how to get your account id. After doing this you will now be able to reference your account id anywhere in this project using  ${{secrets.HubSpotPortalId}}.

If you have not already committed your new .github/workflows/deploy.yml, bin/deploy.sh and bin/generate-config.js files to your main branch. 

Now that your secrets, workflows, and scripts are in your GitHub repository, create a pull request, and merge it into main. Once you merge the pull request, navigate to Actions, and you should see your deploy action kick-off and your project deploy to your HubSpot CMS account.

Because the source of truth for your project now lives in GitHub, and master represents your live website, it is important to prevent edits made directly in the Design Manager. Changes to your live developer file system should only come through your deploy action. You can lock projects within the Design Manager by right-clicking on a folder and selecting “Lock folder” to prevent anyone from editing files in the Design Manager.