GitHub Actions Workflows

When using the GitHub Actions deployment method, your repository needs a workflow file that builds your theme or plugin and uploads the result as an artifact.

Requirements

For a workflow to work with Deploy Forge, it should 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. Deploy Forge validates this during setup and will flag workflows without it.

on:
  workflow_dispatch: # Required: allows Deploy Forge to trigger on demand

You can also include other triggers alongside workflow_dispatch:

on:
  workflow_dispatch: # Required: allows Deploy Forge to trigger on demand
  push:
    branches: [main] # Also run on push

Note: Without workflow_dispatch, Deploy Forge cannot trigger your workflow on demand. Push-based automatic deployments may still work if your workflow has a push trigger, but Deploy Forge's setup validator will flag this as an issue.

2. Artifact Upload (Required)

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

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

Note: When multiple artifacts are uploaded, Deploy Forge selects the largest one. The artifact name is stored for reference but is not used for selection.

3. ZIP File Format (Recommended)

For best results, create a ZIP file of your built theme and upload that. Deploy Forge's setup validator recommends .zip artifact paths for optimal deployment performance.

# Create a ZIP, then upload it
- name: Create theme package
  run: cd dist && zip -r ../theme-build.zip .

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

Note: GitHub Actions wraps all artifacts in a ZIP container when downloaded via the API. If you upload a directory instead of a ZIP file, it will still work, but the setup validator will show a recommendation to use a .zip path.

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:
  push:
    branches: [main]

jobs:
  build-theme:
    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: "pnpm"

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Install dependencies
        run: pnpm install

      - name: Build production assets
        run: pnpm prod

      - 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:

# Missing workflow_dispatch trigger
name: Build Theme

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

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

      - run: npm run build

      # Missing artifact upload
      # The WordPress plugin has nothing to download

Issues with this workflow:

• No workflow_dispatch trigger — Deploy Forge cannot trigger deployments on demand from WordPress
• No actions/upload-artifact step — No build output for the WordPress plugin to download

Troubleshooting

Workflow trigger issues

If Deploy Forge can't trigger your workflow, ensure workflow_dispatch is in your on: section:

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

No artifact available after build

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

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

Workflow runs but deployment fails

1. Check that your directory structure matches what WordPress expects
2. Ensure the theme folder name inside the artifact matches your theme slug
3. Check the workflow run logs in GitHub Actions for errors

Need Help?

If you're having trouble setting up your workflow:

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