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.
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.
We recommend using the deploy action we created as it takes a lot of the setup and configuration out of the equation. If you wish to still manually configure your action or are using a service other than GitHub then follow the instructions below.
If you do not already have one, create a package.json file at your project root. Add the @hubspot/cms-cli and js-yaml as devDependencies. This should look something like:
// package.json
{
"name": "my-website-theme",
"version": "0.0.1",
"devDependencies": {
"@hubspot/cms-cli": "^1.0.2",
"js-yaml": "^3.13.1",
}
}At your project’s root, create a bin directory (refer to the CMS Theme Boilerplate’s implementation). In this directory, create two files:
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-boilerplateNotice 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.
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 apiKey = process.env.HUBSPOT_API_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.
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.shFor Windows users, try this snippet below:
git update-index --chmod=+x path/to/fileGitHub 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_API_KEY: ${{ secrets.HubSpotApiKey }}
run: |
bin/generate-config.js
bin/deploy.shReplace ENTER_YOUR_ACCOUNT_ID with your HubSpot account ID. If you need help finding your HubSpot account ID, see Manage multiple HubSpot accounts. ${{ secrets.HubSpotApiKey }} will add your API key secret as an environmental variable 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 master branch.
Now that your secrets, workflows, and scripts are in your GitHub repository, create a pull request, and merge it into master. 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.
Thank you for your feedback, it means a lot to us.