GitHub Actions Workflows

When using the GitHub Actions deployment method, your repository must contain a workflow file that builds your theme or plugin and creates an artifact for Deploy Forge to download.

Requirements

For a workflow to be compatible with Deploy Forge, it must meet these criteria:

1. Manual Trigger (Required)

Your workflow must include the workflow_dispatch trigger. This allows Deploy Forge to trigger deployments on demand from WordPress.

on:
  workflow_dispatch: # Required for Deploy Forge

You can also include other triggers alongside workflow_dispatch:

on:
  workflow_dispatch: # Required for Deploy Forge
  push:
    branches: [main] # Optional: also run on push

2. Artifact Upload (Required)

Your workflow must upload a build artifact using actions/upload-artifact. This is what Deploy Forge downloads and deploys to your WordPress site.

- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: theme-build
    path: theme-build.zip
    retention-days: 7

3. ZIP File Format (Recommended)

For best performance, your artifact should be a single ZIP file containing your built theme or plugin.

# Create the ZIP file
- name: Create package
  run: zip -r theme-build.zip dist/

# Upload the ZIP
- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: theme-build
    path: theme-build.zip # Upload the ZIP, not a directory

4. Artifact Naming (Recommended)

Always specify a name for your artifact. This helps Deploy Forge identify the correct artifact when your workflow uploads multiple files.

- uses: actions/upload-artifact@v4
  with:
    name: theme-build # Recommended: helps identify the artifact
    path: theme-build.zip

Example Workflows

Below are complete, working examples for common build setups.

Example 1: Webpack Build (Node.js)

A typical WordPress theme using Webpack for asset compilation:

name: Build Theme (Webpack)

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Build production assets
        run: npm run build

      - name: Create theme package
        run: |
          mkdir -p package/my-theme
          cp -r dist/* package/my-theme/
          cp -r theme/* package/my-theme/
          cp style.css package/my-theme/
          cd package && zip -r ../theme-build.zip .

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: theme-build
          path: theme-build.zip
          retention-days: 7

Example 2: SCSS Only (No JavaScript Build)

A simpler theme that only needs SASS compilation:

name: Build Theme (SCSS)

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install Sass
        run: npm install -g sass

      - name: Compile SCSS
        run: sass src/scss:dist/css --style=compressed

      - name: Create theme package
        run: |
          mkdir -p package/my-theme
          cp -r dist/css/* package/my-theme/css/
          cp -r *.php package/my-theme/
          cp style.css package/my-theme/
          cd package && zip -r ../theme-build.zip .

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: theme-build
          path: theme-build.zip
          retention-days: 7

Example 3: Custom Folder Structure (pnpm + Theme Subfolder)

A more complex setup with a theme/ subfolder and pnpm package manager:

name: Deploy WordPress Theme

on:
  workflow_dispatch:

jobs:
  build-theme:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: Cache dependencies
        uses: actions/cache@v3
        id: cache-pnpm
        with:
          path: |
            node_modules
            ~/.pnpm-store
          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-

      - name: Install dependencies
        if: steps.cache-pnpm.outputs.cache-hit != 'true'
        run: pnpm install

      - name: Build production assets
        run: pnpm prod

      - name: Get commit hash
        id: commit
        run: echo "hash=$(git rev-parse --short HEAD)" >> $GITHUB_ENV

      - name: Get repository name
        run: echo "REPO_NAME=$(echo ${{ github.repository }} | cut -d'/' -f2)" >> $GITHUB_ENV

      - name: Create theme package
        run: |
          mkdir -p theme-package/${{ env.REPO_NAME }}/theme
          cp -r theme/* theme-package/${{ env.REPO_NAME }}/theme/
          cd theme-package
          zip -r ../theme-build.zip .

      - name: Upload theme artifact
        uses: actions/upload-artifact@v4
        with:
          name: theme-build
          path: theme-build.zip
          retention-days: 7

Invalid Workflow Example

Here's what NOT to do:

# INVALID - Missing workflow_dispatch trigger
name: Build Theme

on:
  push:
    branches: [main] # Only triggers on push, not manually!

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - run: npm run build

      # INVALID - Missing artifact upload!
      # Deploy Forge has nothing to download

Issues with this workflow:

No workflow_dispatch trigger - Deploy Forge cannot trigger deployments
No actions/upload-artifact step - No artifact for Deploy Forge to download

Troubleshooting

"Workflow must include workflow_dispatch trigger"

Add workflow_dispatch to your on: section:

on:
  workflow_dispatch: # Add this line
  push:
    branches: [main]

"Workflow must upload an artifact"

Add an actions/upload-artifact step to your workflow:

- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: my-build
    path: build.zip

"Artifact path should be a .zip file"

Instead of uploading a directory, create a ZIP file first:

# Instead of this:
- uses: actions/upload-artifact@v4
  with:
    path: dist/

# Do this:
- run: zip -r build.zip dist/
- uses: actions/upload-artifact@v4
  with:
    path: build.zip

Workflow runs but deployment fails

Check that your ZIP file structure matches what WordPress expects
Ensure the theme/plugin folder name inside the ZIP matches your theme slug
Check the workflow run logs in GitHub Actions for errors

Need Help?

If you're having trouble setting up your workflow:

Check the GitHub Actions documentation
Review the example workflows above
Contact support with your workflow file for assistance