Deploy ForgeDeployForge
Deploy ForgeDeployForge
Back to Home

Deployment Methods

Deploy Forge offers two ways to deploy your theme: GitHub Actions and Direct Clone. This guide helps you choose the right method for your workflow.

GitHub Actions (Build + Deploy)

Use this method if your theme requires a build step—compiling SCSS, bundling JavaScript, or any npm/webpack/vite process.

How It Works

  1. You push code to your configured branch
  2. Deploy Forge triggers your GitHub Actions workflow
  3. Your workflow builds the theme and uploads an artifact
  4. Deploy Forge downloads the artifact
  5. Theme files are deployed to WordPress

When to Use

  • Your theme uses npm, webpack, vite, or similar build tools
  • You compile SCSS/SASS to CSS
  • You bundle or transpile JavaScript/TypeScript
  • You need to run any pre-deployment scripts
  • Your node_modules folder shouldn't be deployed

Workflow Requirements

Your workflow must include:

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

And upload an artifact:

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

See Workflows for complete examples.

Pros

  • Full control over build process
  • Can run tests, linting, optimization
  • Only deploy built/production files
  • Works with any build toolchain

Cons

  • Slower deployments (build time + download)
  • Uses GitHub Actions minutes
  • Requires workflow configuration
  • More complex setup

Direct Clone (No Build)

Use this method for simple themes that don't need any build process. Deploy Forge downloads your repository directly.

How It Works

  1. You push code to your configured branch
  2. Deploy Forge downloads your repository as a ZIP
  3. Theme files are deployed to WordPress immediately

That's it—no workflow, no build step, no waiting.

When to Use

  • Your theme uses plain CSS (no SCSS/SASS)
  • Your JavaScript doesn't need bundling or transpilation
  • All files in your repo are production-ready
  • You want the fastest possible deployments
  • You're deploying to a development/staging environment

Pros

  • Extremely fast (seconds, not minutes)
  • No workflow file needed
  • No GitHub Actions minutes used
  • Simplest possible setup

Cons

  • No build step available
  • Deploys entire repository (use .distignore to exclude files)
  • Not suitable for themes requiring compilation

Excluding Files

Create a .distignore file in your repository root to exclude files from deployment:

# .distignore - files to exclude from Direct Clone deployments
.git
.github
node_modules
.gitignore
.distignore
README.md
package.json
package-lock.json
*.log

Switching Methods

You can change deployment methods anytime:

  1. Go to Deploy Forge → Settings
  2. Find Deployment Method
  3. Select GitHub Actions or Direct Clone
  4. If switching to GitHub Actions, select your workflow file
  5. Save settings

Your next deployment will use the new method.

Recommendations

Use GitHub Actions if:

  • You have package.json with build scripts
  • Your repo has a src/ or assets/ folder that compiles to dist/
  • You see node_modules in your project
  • You run npm run build or similar before deploying manually

Use Direct Clone if:

  • Your theme works exactly as it exists in the repository
  • You write plain CSS and JavaScript
  • You're deploying to development or staging
  • Speed is your top priority

Hybrid Approach

Some teams use both methods:

  • Production: GitHub Actions for optimized, built assets
  • Staging: Direct Clone for quick iteration during development

You can configure different Deploy Forge installations on different WordPress sites to achieve this.