Deploy Ghost Theme with Github Actions

In this tutorial I will show you how to manage Ghost theme versioning with Github and setup auto-deploy with Github Actions. With this workflow you can easily develop your theme locally, push code changes to your Github and auto-deploy new versions on your Ghost server once ready and without manual copy paste, download and upload.

Preparation

Prerequisites

First we need a local development environment with a Ghost installation. If you have not setup this yet you can check out my Ghost Starter Theme in my Github repo.

In addition we need a fresh Github repository that we use for our theme and a production ready server running our Ghost installation including a DNS entry for our hosted domain. If you don’t have a server yet you can easily spin-up a server using e.g. Hetzner cloud. Using my ref link will earn you 20 Euro for free. [Link](https://hetzner.cloud/?ref=ir0WnxeEHrmU)

Get API Keys

First we need to get our API keys that we will use to publish our theme on the production server. Login to your installation on your Webserver and navigate to Settingsand Integrations. Here you select Add Custom Integration

After choosing a name (select anything you like) the integration it will display the Admin API Key. The API URLshould be the same as your installation URL (basically your domain).

We will now head over to Github and open the fresh repository we just created for our project. On the repo go to Settings and scroll down until Secrets. Select Actions to define new Action Secrets. Create two new Secrets GHOST_ADMIN_API_KEY and GHOST_ADMIN_API_URL by passing the previous API strings from your Ghost installation.

Github Action

In your local theme folder add another folder structure .github/workflows (attention: The dot is mandatory here) and add a new file deploy-theme.ymlinto that folder.

The .github folder is a special folder used by Github repositories and makes it easy to manage workflows and other repo specific files via IDE.

In the deploy-theme.ymlfile we add the following lines:

name: Deploy Theme
on: workflow_dispatch

With the on: workflow_disptach we define that the workflow will only run on manual trigger. Basically it would also be possible to create automatic deployment triggers like „with every release“ or „with every push“ but for the start I recommend using the manual trigger only. With this you can always control when a theme change would be deployed on your production server and be live for your visitors.

Next we will define our so called jobs. The first job we will create is a test. This would be used to check if our theme has any errors or is basically not working on the latest ghost version. This will prevent a theme to be deployed on the server and crashing our website.

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 16
      - name: Run gscan
        run: |
          npm install --global gscan@latest
          gscan --fatal --verbose $GITHUB_WORKSPACE

The main steps are: checkout the main branch on the repo, spin-up a node server, install and run gscan against our code. Here it is important to run gscan with the --fatal and --verbose flags as we only want to abort if fatal errors occur.

If the test succeed the Action will continue to the deploy job:

deploy:
    name: Deploy
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Deploy Ghost Theme
        uses: TryGhost/action-deploy-theme@v1.5.0
        with:
          api-url: ${{ secrets.GHOST_ADMIN_API_URL }}
          api-key: ${{ secrets.GHOST_ADMIN_API_KEY }}

Here we will again checkout the main branch and push it into our Ghost server with the API Key and URL we defined in the repo secrets.

A complete example of the Action file could also be found within my Ghost Starter Template on Github.

Next Steps

As we have setup a Github Action with a connection to your Ghost server we could now start developing our theme and using this CI (Continuous Integration) process. Just remember every time you change your theme you should update the version number in the package.json file of your theme.