Video version:

Version control plays a critical part in ensuring your development workflow remains manageable, and that all code changes can be traced directly to the source.

GitHub is now by far the most used service for version control, and with its additional features such as "Actions", we can not only ensure that our code remains manageable, but we can also set up smooth deployment workflows that brings automation to our fingertips.

In my previous article, I walked you through setting up a Ghost installation on Ubunutu. If you havent installed Ghost on your production server yet, I highly recommend giving it a read.

In this guide, we'll build an automated workflow in which we can deploy any local theme changes to the production server in minutes.

Process overview:

  • Set up a new GitHub repository
  • Create a new theme (we'll duplicate the default Caper theme)
  • Link our GitHub repository with our production server via API Keys
  • Set up a GitHub action to manage automation
  • Deploy

Prerequisites:


1. Create a new GitHub Repository

1.a

Navigate to https://github.com/new and create a new, private repo. Name the repo something appropriate. You don't need to check any of the lower boxes.

1.b

Keep this url somewhere for later:

2. Create the new theme

In this guide we'll duplicate the Casper theme, but feel free to create a fully new theme or use a custom theme at this point (simply skip 2.b and CD into your chosen theme at step 3.c)

2.a

Navigate to your LOCAL themes folder

cd <site directory>content/themes/

2.b

Duplicate the default theme. The command means (cp) COPY (-R)RECURSIVELY the casper theme to NEWFOLDERNAME

# replace <newThemeName> with your new theme name (ie cp -R casper adamTheDevGhostTheme)
cp -R casper <newThemeName>

2.c

Navigate to the new theme folder

cd <newThemeName>

2.d

We now need to open and update the package.json file so that the 'name' property is different. You can also change all the other information if required.

2.e

Let's install the dependencies to ensure everything is working

yarn install
npm run dev

After gulp runs, you can cancel it by doing "Ctrl + C"

3. Push theme files to our new repository

Let's link our new theme files linked up to our newly made repository. We also need to 'ignore' the node_modules files (as they are only needed for development purposes).

## These commands should be run in the same directory as above i.e (/content/themes/adamTheDevGhostTheme)

# Initialise the repository
git init

# Create a new ignore file and insert 'node_modules/' within so that it's not committed to the repo
touch .gitignore && echo "node_modules/" >> .gitignore

# Add all files in the directory to be committed
git add .

# Commit the files with the message 'first commit'
git commit -m "first commit"

# Switch to the main branch
git branch -M main

# Change <gitRepositoryUrl> to the URL in step 1.b)
# This determines where the files are 'pushed' to
git remote add origin <gitRepositoryUrl> 

# Push the files to the repository
git push -u origin main

Refresh your repository and your files should appear:

4. Integrate the GitHub Repository with our PRODUCTION install of Ghost

We now want to be able to 'transfer' our files from our GitHub repository to our LIVE/PRODUCTION site.

We can save tons of time by using an already made GitHub action (if you'd like to read more on the action, visit here).

4.a

Firstly, navigate to your PRODUCTION Ghost dashboard and head to Settings > Integrations (/ghost/#/settings/integrations if you're lazy)

Click 'add custom integrations' and name it something appropriate

Take note of the generated keys

4.b

Head back to your GitHub repo and go to Settings > Secrets

4.c

Click 'new secret' and Create two new secrets named:

GHOST_ADMIN_API_KEY paste the ADMIN API KEY from ghost

GHOST_ADMIN_API_URL paste the API URL from ghost

5. Add the GitHub action to LOCAL and test

We now want to be able to 'transfer' our files from our LOCAL to Git then directly to the PRODUCTION. To do that we need to add the action workflow file.

5.a

Now, in your new theme directory (local)

# within (/content/themes/<newThemeName>

# make a .github directory and change to that folder
mkdir .github && cd .github 

# make a workflows directory and change to that folder
mkdir workflows && cd workflows

# now within (/content/themes/<newThemeName>/.github.workflows)
touch deploy-theme.yml && sudo nano deploy-theme.yml

5.b

Paste the below and save

name: Deploy Theme
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-20.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 }}

5.c

Move back to your theme main directory, run the following commands to add the action to your repository

# in /content/themes/<newThemeName>
git add . && git commit -m "adding actions" && git push

5.d

Now visit your Github actions tab, you should see a green tick next to the 'deploy theme' action if it was succesful. If it failed, click and view the reason.

6. Visit your PRODUCTION Ghost admin panel and activate your new theme

That should be it!

You can now run "npm run dev" in your theme directory, make any changes to the theme (css, templates etc) and then simply push your files to the main branch of your repo, wait a few minutes and the files will automagically appear on the production site.

For more articles like this, remember to hit subscribe and be updated as soon as I post any nee content.

If you have any problems, leave a comment below and I'll try my best to help!