Ghost blog automated theme deployment with Github Actions

Learn how to automate the deployment of changes and tweaks to your Ghost blog theme, using Github Actions.

( Photo by Patrick Hendry )

When I started setting up my Ghost blog (see part one of the setup series here) I decided to use the standard Casper theme provided by the Ghost team. I then started doing some minor ad-hoc modifications, such as adding a Creative Commons notice in the footer and including the template for the Commento commenting system.

As I have an auto-update script that pulls the most recent Ghost blog software version and installs it straight away, I then ended up hacking that script to preserve my template modifications. In other words, I started doing ugly things!

With a little more time at my disposal, I have now decided to set up a proper development and deployment pipeline for my theme. As a part of that, I will automate deploying changes from my code repository to my live blog.

I will explain below how to achieve this in a straightforward process.

Step 1 - Fork out Casper

If you are using Casper, then the first thing to do is to fork out the Casper theme repository on Github. This will allow you to start adding your customisations and other niceties to your template.

Most importantly, you will want to ensure that you stay up to date with the other Casper development changes, especially if you are planning to implement only minor tweaks and not a complete overhaul of the theme.

I recommend changing the name of your repository to something different than Casper: for example, I called mine Casper-pt - lacking any creativity in the process! This allows you to keep the default Casper theme unaltered if everything goes south and you need to roll back to that. But nothing goes south here because we are doing version control already, in a team of one...

Step 2 - Modify your theme in your editor

It's up to you to use your favourite editor, in my case Visual Studio Code. Clone your fork locally, then you can implement the changes you need. Don't commit and push yet as we need to set up the automated deployment first.

Step 3 - Github Action setup

If you are not already familiar with them, Github Actions are very popular and easy to use automation and augmentations that you can initiate and control based on specific events happening on your Github repositories.

Now, in our case, let's say we have done a change and we want to deploy it. We could  zip the folder of our theme, upload it using the Ghost Admin interface, and then activate the new theme. Same goes for changes: zip and upload. This gets boring and repetitive quickly.

Instead of doing this, we can set up a Github action. This will look for new pushes on our master theme branch and will automatically deploy these changes to our blog using an integration. Keep in mind that you can customise the event that triggers this deployment, but let's start from this simple approach.

To accomplish this, we need to set up the Deploy Ghost Theme action and hook it to your existing Ghost installation. The steps are explained in the page itself which I will recap quickly:

1. You will need to add a custom integration to your Ghost Admin > Integration module. This will generate API keys and an API URL that is needed to set up the action on Github later. See above picture for what I mean.
2. Configure the above Admin API Key and API URL as secrets in your Github Repository. Call these secrets GHOST_ADMIN_API_URL and GHOST_ADMIN_API_KEY. These are referenced in the automation configuration below.
3. Add a config file to your repository: .github/workflows/deploy-theme.yml

name: Deploy Theme
on:
  push:
    branches:
      - master
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@master
      - name: Deploy Ghost Theme
        uses: TryGhost/action-deploy-theme@v1.3.1
        with:
          api-url: ${{ secrets.GHOST_ADMIN_API_URL }}
          api-key: ${{ secrets.GHOST_ADMIN_API_KEY }}
          theme-name: "<YOUR_THEME_NAME>"

As mentioned before, the configuration of the event triggering this action can be tweaked. Here we configure it to trigger on all push actions on the master branch. We also see how the Github secret is passed securely from the ones configured for our repository, meaning we avoid committing any API keys in the code of course.

Please also ensure to update theme-name with your actual theme name, replacing the<YOUR_THEME_NAME> placeholder.

Step 4 - Commit and Deploy

Once you are ready with all the above, you can commit and observe the magic. As soon as you push your code, the Action will trigger and will take care of deploying your changes to your blog automatically via the Ghost integration. No more manual uploads, no more hacked scripts, feel much better!

You can monitor the outcome of your Action in the appropriate tab on Github, see the below example for my theme.

Keeping your theme up to date

Keeping your fork up to date is really easy and can be done directly on Github. All you need to do is to regularly perform a compare operation between your repository (in my case Vortexmind/Casper-PT) and the forked one ( TryGhost/Casper ) and then merge the updates that are published by the Ghost team. In most cases, unless you have done very extensive modifications, this should be a seamless operation.

It is critical to do this regularly as it will allow you to obtain all the updates, security fixes and changes that the Ghost team is working on. It's a manual step as you will want to review the changes, but worth doing it regularly.

Enable Security Alerts on your repository

Adding such alerts is somewhat redundant given that most of this work will be undertaken already by the Ghost team, but only on the parts that you do not modify. Either way, it doesn't hurt to be on the safe side, and you never know what you may end up introducing yourself in your customisations!

I highly recommend to enable the security scans and alerts on your repository, helping you to keep your theme safe and avoid vulnerabilities or problems: below is what it should look once you have enabled these features.

Conclusions

I hope you enjoyed this brief article: happy blogging with Ghost and enjoy your automated theme updates going forward! Let me know if you have set up other useful Github actions in the comments.