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. GitHub sends a webhook to Deploy Forge
3. Deploy Forge notifies your WordPress site, which requests a workflow trigger
4. Deploy Forge triggers your GitHub Actions workflow via the GitHub API
5. Your workflow builds the theme and uploads an artifact
6. GitHub notifies Deploy Forge when the workflow completes, and Deploy Forge forwards the artifact info to WordPress
7. The WordPress plugin downloads the artifact and deploys the files

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 on demand

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. The WordPress plugin clones your repository directly using temporary credentials from Deploy Forge.

How It Works

1. You push code to your configured branch
2. GitHub sends a webhook to Deploy Forge
3. Deploy Forge notifies your WordPress site
4. The WordPress plugin requests clone credentials from Deploy Forge
5. Deploy Forge generates a temporary access token
6. The WordPress plugin clones the repository and deploys the files

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

• Fast deployments (no build step)
• No workflow file needed
• No GitHub Actions minutes used
• Simplest possible setup

Cons

• No build step available
• Deploys entire repository contents
• Not suitable for themes requiring compilation

Switching Methods

You can change your deployment method through the WordPress plugin settings. Alternatively, disconnect and reconnect your site to go through the full setup wizard again.

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

You can use both methods across different sites:

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

Connect different WordPress sites to the same Deploy Forge account, each configured with its own deployment method.