How to Deploy Your Ghost Theme with GitHub Actions

How to deploy your Ghost Theme using Github Actions. Guide to setup and configure automatic Ghost Theme deployment whenever theme files are changed.

Norbert
Norbert2 min read

The Deploy Ghost Theme GitHub action is a great tool to improve the usual workflow when it comes to updating Ghost Themes. The most common way until now was changing the theme files locally and then uploading the zip manually using the Ghost Admin.

But this tool is a much better way of doing theme deployment. We have been using the Deploy Ghost Theme GitHub Action for the last couple of months and not only it is easy to setup, but this can save you a lot of time and performing repetitive tasks.

Let's see how you can setup this tool to automatically deploy your Ghost Theme whenever you are pushing changes to your theme repository on GitHub.

Add Custom Ghost Integration

First step is creating a new Custom Integration in Ghost Admin > Integrations. Name your integration, then press Create.

Ghost Admin Custom Integration
Ghost Admin Custom Integration

This will generate the Admin API Key and Api URL that will be next step.

Add GitHub Repo Secrets

Now, go to your theme repo on Github and go to Settings > Secrets Create two new secrets:

  • GHOST_ADMIN_API_KEY - use the Custom Integration value Admin API Key
  • GHOST_ADMIN_API_URL - use the Custom Integration value Api URL
Github Secrets Ghost CMS
Github Secrets Ghost CMS

Add GitHub Deploy Config

Once the Custom Integration and the GitHub Secrets are in place you have to add the config file which contains the basic configuration.

Copy and paste the following code into .github/workflows/deploy-theme.yml

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

This configuration will trigger a deployment for every commit that is pushed to the master branch. You have the possibility to customize the "on" trigger to different branches, pull requests or more. To find out more, check out the official GitHub Action Documentation.

Besides the api-url and api-key there are additional config options available:

  • exclude - list files & folder you would like to exclude (defaults: gulpfile.js and dist/* )
  • theme-name - use this to override the theme-name set in package.json
  • file - specify path to a built zip file (exclude and theme-name will be ignored)

That is it, now when you push a new commit to your repository, the deploy should be triggered, updating your theme.

More in Tips & Tricks

All tips

How to use Code Injection in Ghost

Enhance your Ghost CMS with Code Injection. Easily add custom scripts and styles, integrate tools, and new features site-wide or per post for seamless customization.

Ghost Pro Hosting

Get the best managed Ghost CMS hosting and focus on bringing value to your audience.