Manually uploading a theme every time you change a template is slow and error-prone. With GitHub Actions you can automate theme deployment so pushes to your repo automatically upload and activate the theme on your Ghost site. This guide shows a reliable, production-ready setup and includes a copy-paste workflow you can use right away.
TL;DR β what to do (one-line)
Create a Ghost custom integration β add two GitHub secrets β add the workflow file using the official TryGhost action β push to main and the theme auto-deploys.
What you need (prerequisites)
- A Ghost site (self-hosted or Ghost(Pro)).
- Your theme in a GitHub repo (or create one).
- Ghost Admin API URL and Admin API Key from a custom integration.
- A repo on GitHub where you can add Actions and Secrets.
Step-by-step: automation setup (exact steps)
Step 1 β Create a Ghost integration (get credentials)
- Log in to Ghost Admin β Settings β Integrations.
- Click Add custom integration and name it (e.g., GitHub Deploy).
- Copy the Admin API Key and the API URL β youβll store these as secrets in GitHub.
Step 2 β Add repo secrets on GitHub
- In your theme repo on GitHub go to Settings β Secrets and variables β Actions.
- Add two secrets:
GHOST_ADMIN_API_URL
β paste the API URL value.GHOST_ADMIN_API_KEY
β paste the Admin API Key value.
Secrets are encrypted and safe for Actions to use; never hardcode keys into code.
The GitHub action automatically deploys ghost theme whenever you push a new update to your repository's main branch, saving you time from manual uploads. To set up this tool for automatic deployment, create a new Custom Integration in your Ghost Admin and check the theme deployment actions list in your GitHub repository's Settings > Actions section.
Add Custom Ghost Integration
First, you must create a new Custom Integration in Ghost Admin β Integrations. You can give the new integration a new name, then press Create.
This will generate the Admin API Key and API URL which will be the next step.
Add GitHub Repo Secrets
Now, go to your theme repo on GitHub and click 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
Add the GitHub Deployment Config File
Once the Custom Integration and GitHub Secrets are in place, the config file with the basic setup must be added. Copy and paste the code below into.github/workflows/deploy-theme.yml.
name: Deploy Ghost Theme
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: TryGhost/action-deploy-theme@v1
with:
api-url: ${{ secrets.GHOST_ADMIN_API_URL }}
api-key: ${{ secrets.GHOST_ADMIN_API_KEY }}
The action zips your theme and uploads via the Ghost Admin API β after a successful run your theme will be available on the site (and the action can also activate it). Use this if you want straightforward automation without extra scripting.
Step 4 β (Optional) Build step for themes that need compiling
If your theme needs npm run build
(for assets, Tailwind, etc.), add a build step before the deploy step:
- name: Install dependencies
run: npm ci
- name: Build theme
run: npm run build
Step 5 β Push and verify
- Commit and push the workflow file to main.
- Open your repo β Actions tab to watch the run logs.
- Check Ghost Admin β Design β Themes to confirm the uploaded theme. (GitHub Actions logs give file & HTTP responses when something fails.)
Note : If you prefer a custom script (not using the action), you can zip and POST to the Admin API. Note: using the Admin API directly typically requires generating a JWT from the Admin API key (the action wraps that complexity for you). Use the official Ghost API docs and community examples if you go this route.
Quick checklist
- Create Ghost custom integration β get API URL + Admin API Key. Ghost
- Add GHOST_ADMIN_API_URL and GHOST_ADMIN_API_KEY to GitHub repo secrets. GitHub Docs
- Add .github/workflows/deploy-theme.yml with the TryGhost action snippet above. GitHub
- Push β check Actions β verify theme in Ghost Admin.
For further details, please visit the official GitHub Action Documentation. To get further information about ghost cms, then you can visit the official blog site here- themeix.com.