How did we manage our theme versioning in Ghost

What was the problem?

We found out that when we uploaded our theme to Digital Garden, the previous version was deleted and replaced with the new one. That's not good because we can't manage versions and if for example the new version of the theme is broken or has some bugs, we would not be able to easily revert to a previous version.

How can we solve that?

The way Ghost manages multiple versions of the same theme is by checking their tags. For example, if you have the theme "my-theme-1.0" uploaded to your Ghost website and then upload a new version named "my-theme-1.1", the new one will not replace the previous one. Therefore it's possible to easily switch versions with a simple click.

So we had to find a way of writing tags to our theme file name deployments.

Solving the problem with "release-it" and GitHub Actions

Because our theme source code is in a GitHub repository, we can use features provided by GitHub to help us achieve what we want like in our case: tags and GitHub Actions.

To be able to easily add a new release/tag, we used the "release-it" package which you can find here  👉   Release it!
It provides us a useful CLI to quickly create a new release and a new tag.

Then because we wanted to automate the deployment after a new release we created two GitHub Actions:

• The first one will be triggered when a new release has been published, it will test the code of the theme to make sure everything is ready to be deployed to Digital Garden.

name: test & lint the theme

on:
  pull_request:
    branchs:
      - "main"

jobs:
  test:
    name: testing
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: "14"
      - run: npm install
      # The 2 next lines launch Gscan which validate the theme: https://ghost.org/docs/themes/gscan/
      - run: npm run test
      - run: npm run test:ci

  lint:
    name: linting
    needs: test
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: "14"
      - run: npm install
      - run: npm run lint

• The second one will be triggered when the first GitHub Action will be completed, it will deploy our theme to Digital Garden with the new release tag at the end of the name file, e.g. "mirahi-digital-garden-1.1.0".

name: zip & upload the theme

on:
  push:
    tags:
      - "*"

jobs:
  zip:
    name: zip & upload theme
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: "14"
      - run: npm install
      - run: npm run zip
      - name: Extract version
        id: extract_version
        uses: Saionaro/extract-package-version@v1.0.6
      - name: Deploy Ghost Theme
        uses: TryGhost/action-deploy-theme@v1.4.0
        with:
          api-url: ${{ secrets.GHOST_DOMAIN }}
          api-key: ${{ secrets.GHOST_API_KEY }}
          file: ./dist/mirahi-digital-garden-${{steps.extract_version.outputs.version}}.zip

Now we only need to release a new tag with the "release-it" CLI and the versioning and deployment to Digital Garden will be done automatically.
The only thing left to do is to connect to the Ghost administration panel and activate the new version of the theme with a simple click.

If somehow bugs would occur, it's easy to revert back to the previous version with one simple click.

And voilà! As you can see it was not difficult to implement an automatic versioning deployment with Ghost.