How to Deploy a Theme From GitHub to Your Ghost Blog (With Secrets)

Hello programmer!

Today's article will guide you through using GitHub Actions and defining secrets to automate the creation of a Ghost Theme using GitHub Actions.

Before discovering GitHub Actions, I created many zip files on my computer, including my comment plugins. Now that I’m using GitHub actions, I have forked Source —Ghost’s default theme—and made the changes there, too.

Automation makes life easier! And now, with GitHub actions, I can get the latest and greatest from Source directly to all of my sites running it.

This is an updated version of the original article I wrote in 2022 about Casper.

In this article, I’ll showcase the process so you can replicate it. Finally, I’ll show you how to use my theme and save development time if you're using Ghost.

Outside of using this for a Ghost's theme deployment, messing around with GitHub Actions should be a welcome advancement in your knowledge. GitHub Actions can help you in so many ways.

Let’s dive right in!

First, Fork Source (or your theme of choice)

You can find Ghost’s official default theme here.

Fork it as a local repo on your profile, clone the new repo to your computer, and let’s start working on it!

Create a Custom Integration on Your Ghost Site

By going to Settings -> Integrations.

At the bottom of the page, you’ll see a button that says Add Custom Integration.

Create a new integration and name it whatever you like (preferably "GitHub Actions" or "GitHub Integration," so you know what purpose this integration serves a month from now).

You’ll see the Admin API URL and Admin API Key on that page.

Copy them, as you’ll need those next.

It’s Time to Create Secrets

On your Repository on GitHub, you can create secrets to use in GitHub actions. Go to Settings -> Secrets on the left menu -> Add Repository Secret.

Here's a little Loom to explain it better:

Create a secret for the Admin API URL and the Admin API Key you wrote down in the last step.

Do You Have Other Sensitive Information?

I use Hyvor Talk on my websites. It’s for the comments plugin you see below this article. So, since my forked repo is public, I changed my website’s ID to a placeholder so people don’t accidentally use it.

The way to do so is by adding a preceding step in your GitHub Actions to replace text in your repo before deploying it to your website. In my case, I put my Hyvor Website ID in a Secret and used that secret in the workflow to replace the text with the actual ID before deploying the theme to my site.

Create The GitHub Action Workflow

Here’s the actual workflow code:

name: Deploy Theme To Oren Codes
on:
  push:
    branches:
      - master
      - main
jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v4
      - name: Find and Replace
        uses: jacobtomlinson/gha-find-replace@v2
        with:
          find: "HYVOR_TALK_WEBSITE_CODE"
          replace: ${{ secrets.OREN_CODES_HYVOR_WEBSITE_KEY }}
          regex: false
      - uses: TryGhost/action-deploy-theme@v1
        with:
          api-url: ${{ secrets.OREN_CODES_GHOST_ADMIN_API_URL }}
          api-key: ${{ secrets.OREN_CODES_GHOST_ADMIN_API_KEY }}
          theme-name: "source-by-oren"

This code says that this flow will run whenever you commit to the main branch. It will find and replace my Hyvor code in all of the relevant hbs files, and then it will use Ghost’s own GitHub action to deploy the theme to my blog.

One thing to note here is that you must provide the theme-name property when you fork Source, as the action will not override the original theme.

Trigger Deployment With Tags

You can easily make deployment work only using tags. This way, you can make multiple changes and then tag the main branch to create a new version deployed to your site. That's what I'm using now. Here's how:

name: Deploy Theme To Oren Codes

on:
  push:
    tags:
      - '*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Find and Replace
        uses: jacobtomlinson/gha-find-replace@v2
        with:
          find: "HYVOR_TALK_WEBSITE_ID"
          replace: ${{ secrets.OREN_CODES_HYVOR_TALK_ID }}
          regex: false
      - uses: TryGhost/action-deploy-theme@v1
        with:
          api-url: ${{ secrets.OREN_CODES_API_URL }}
          api-key: ${{ secrets.OREN_CODES_ADMIN_API_KEY }}
          theme-name: "oren-codes-source-${{ github.ref_name }}"

Use it for Multiple sites!

I have one yaml file for this very blog you’re reading this on (if you’re not reading it on Medium). I can easily create another yaml file to deploy a different version to a different website.

The only things I need to change between the files are the Secrets to ensure different sites have different themes with different comment configs!

Watch it work

If everything went smoothly, you should see a new theme on your ghost admin's “Design” menu. Before activating it, download it to your computer and check that the find and replace action worked correctly and that your HBS files contain the correct code for your comments.

Want to use mine?

You can fork my repo on GitHub and add the necessary secrets to make it your own. Find my Source fork here.

Then create a workflow file just like mine and only replace the secrets with your generated ones.

Have any questions?

Write a comment below! And I’ll make sure to answer to the best of my ability. Thanks for reading!