[Ghost CMS | en] Deploy your Ghost theme from Github

If you're new to Ghost, it's a headless CMS powered by a REST API. It's a fantastic platform that lets you build whatever integrations your developer heart desires. Today we'll use that API to automatically integrate theme changes using GitHub Actions.

Step 1: Put your theme in a GitHub repo

Naturally, to use GitHub Actions, your theme needs to go in a repository on GitHub.

Step 2: Make an API key

We need to generate a set of credentials for GitHub to use to deploy changes to your repository.

Head over to the Integrations section of your Ghost site.

Under Custom Integrations, create a new one. I called mine Theme Deployment but the name does't matter; just give it something sensible.

We'll get a Content API key and an Admin API key. Copy the Admin API key.

Step 3: Add the API Key as a Secret

Great - we've now created some admin credentials. Now we need to give them to GitHub.

In your repository's settings on GitHub, go to Secrets.

Make two secrets:

GHOST_ADMIN_API_KEY

^ with the value as the API key you copied earlier

and

GHOST_ADMIN_API_URL

^ with your site's admin URL. If your site is self-hosted, this is probably https://yoursite.tld (take care to omit any trailing slashes). Otherwise, if you're using the official SaaS, it should be https://yoursite.ghost.io.

There we go ✅

4. Turn on the Action

We've now got to tell GitHub how to deploy our theme.

Create a .github folder in your theme repo, and a workflows folder within that. Now create a yaml file within this folder named something like deploy-theme.yml

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

This sample config uses the Action prebuilt by the Ghost team.

It amounts to running a Linux container that POSTs to https://yoursite.tld/ghost/api/{version}/admin/themes every time you push to master.

5. Watch it work!

Head on over to...

https://github.com/your-username/your-repository/actions

...to watch it work in real time!