TryGhost/action-deploy-theme

Deploy your Ghost Theme from GitHub

This GitHub Action packages and deploys your Ghost theme
from GitHub to a Ghost site through the Ghost Admin API.

Getting Started

1. Generate a set of Ghost Admin API credentials, by configuring a new Custom Integration in Ghost Admin → Integrations.

2. On GitHub, navigate to your theme repository → Settings → Secrets and variables → Actions. Create a secret called GHOST_ADMIN_API_URL containing the API URL and another one called GHOST_ADMIN_API_KEY containing the Admin API Key. Both must be copied exactly from Ghost Admin → Integrations.

3. Once your secrets are in place, copy this example config into .github/workflows/deploy-theme.yml. Then commit and push your changes:

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

This workflow deploys the theme after every push to master or main. To use a different trigger, see GitHub's workflow trigger documentation.

Configuration

The with section must provide the API URL and key. Store both values under the repository's Settings → Secrets and variables → Actions, then reference them with the secrets context as shown above. See GitHub's guide to using secrets in GitHub Actions.

:bulb: Use exclude to reduce the size of the zip file & keep deployment times minimal.

Generated archives reject symbolic links in the theme source so files outside the workspace cannot be packaged accidentally. This applies even when a symlink matches a custom exclude pattern; paths covered by the action's built-in exclusions are ignored. Prebuilt archives supplied with file are uploaded as-is and should come from a trusted build step.

Don't forget to 🌟 Star 🌟 the repo if you like this GitHub Action!

Contributing

See CONTRIBUTING.md for the development, validation, and release commands.

Copyright & License

Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license.