Setting up continuous integration with a GitHub repository using GitHub Actions

Last updated:

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.

Get your developer file system in GitHub

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.

Use the HubSpot CMS Deploy GitHub Action (recommended)

We've created a GitHub action you can install to your GitHub project to have it automatically deploy your changes from a branch to your production portal.

Install GitHub Action

Manual configuration

It's recommend using the deploy action, as it takes a lot of the setup and configuration out of the equation. If you still wish to still manually configure your action or are using a service other than GitHub, follow the instructions below.

Add dependencies to your package.json file

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:

// package.json { "name": "my-website-theme", "version": "0.0.1", "devDependencies": { "@hubspot/cli": "^3.0.9", "js-yaml": "^3.13.1", } }

Write your files to be run on deploy

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:

#!/bin/bash npx hs upload src cms-theme-boilerplate

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:

#!/usr/bin/env node const path = require('path'); const fs = require('fs'); const yaml = require('js-yaml'); const portalId = process.env.HUBSPOT_PORTAL_ID; const HubSpotPersonalAccessKey = process.env.HUBSPOT_PERSONAL_ACCESS_KEY; const portalConfig = { name: 'PROD', portalId, apiKey, }; const config = { defaultPortal: 'PROD', portals: [portalConfig], }; fs.writeFileSync( path.join(process.cwd(), 'hubspot.config.yml'), yaml.safeDump(config) );

No edits to this file are required.

Make the scripts executable

To make these scripts executable, run the following command in your terminal from your projects root:

chmod +x bin/generate-config.js;chmod +x bin/deploy.sh

For Windows users, try this snippet below:

git update-index --chmod=+x path/to/file

Create your GitHub action workflow

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:

on: push: branches: - master jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - name: Use Node.js uses: actions/setup-node@v1 with: node-version: 10.x - name: Install NPM deps run: | npm install - name: Generate hubspot.config.yml and deploy env: HUBSPOT_PORTAL_ID: ${{ secrets.HubSpotPortalId }} HUBSPOT_PERSONAL_ACCESS_KEY: ${{ secrets.HubSpotPersonalAccessKey }} run: | bin/generate-config.js bin/deploy.sh

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

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

Create a secret for your personal access key and HubSpot account id

To ensure your personal access key is not visible and stored in source control, 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 HubSpotPersonalAccessKey, and then enter your HubSpot personal access key as the value. Select “Add secret” to save your secret.

This key will be passed into ${{ secrets.HubSpotPersonalAccessKey }} from your .github/workflows/deploy.yml file. If you name your secret something other than HubSpotPersonalAccessKey, make sure to update the ${{ secrets.HubSpotPersonalAccessKey }} 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}}.

Commit your new folders and files to main

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. 

Create, and merge a pull request in main

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.

screenshot of GitHub interface showing GitHub Deploy action

 

Lock your project in the Design Manager

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.

screenshot showing locked folder in Design Manager

 

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.