GitHub Setup

Deploy Forge connects to GitHub to access your repository and receive push notifications. This guide covers the complete GitHub configuration.

GitHub App Authorization

Deploy Forge uses a GitHub App for secure access to your repositories. When you click Connect in the WordPress plugin, you're redirected to the Deploy Forge app where you'll:

1. Click Connect GitHub
2. Be redirected to GitHub to install the Deploy Forge GitHub App
3. Select which repositories Deploy Forge can access
4. Be returned to continue setup

The GitHub App provides:

• Read access to your repository code
• Ability to trigger GitHub Actions workflows
• No need to manage personal access tokens

Repository Requirements

Your repository should contain your WordPress theme. Typical structure:

• style.css - Theme stylesheet with header
• functions.php - Theme functions
• index.php - Main template

For GitHub Actions method, you also need:

• A workflow file in .github/workflows/ (e.g., build.yml, deploy.yml, or any .yml/.yaml filename)

Plus any other theme files (templates, assets, etc.)

Note: Deploy Forge does not validate your repository structure. These are standard WordPress theme requirements, not Deploy Forge requirements.

For GitHub Actions Method

If your theme needs building, you need a workflow file. See Workflows for complete examples.

Your workflow must:

• Include workflow_dispatch trigger (so Deploy Forge can trigger it on demand)
• Upload a build artifact (so the WordPress plugin can download the result)

Deploy Forge validates your selected workflow for these requirements during setup.

For Direct Clone Method

No workflow file needed. The WordPress plugin clones your repository directly using temporary credentials provided by Deploy Forge.

How Automatic Deployments Work

When you push code to GitHub, Deploy Forge automatically detects the change and coordinates a deployment. Here's what happens behind the scenes:

1. GitHub notifies Deploy Forge - Your repository sends push events to Deploy Forge servers via the GitHub App webhook
2. Deploy Forge creates a deployment - A deployment record is created and a custom event is forwarded to your WordPress site
3. Your WordPress plugin processes it - The plugin acknowledges the deployment and either requests a workflow trigger (GitHub Actions) or clone credentials (Direct Clone)
4. Files are deployed - The plugin downloads the artifact or clones the repo, then deploys the files to your theme directory

This is all configured automatically when you connect your site. You don't need to manually set up any webhooks.

Troubleshooting Automatic Deployments

Push not triggering deployment

1. Check your branch - Ensure you pushed to the branch configured in Deploy Forge (usually main)
2. Verify connection - In WordPress admin, go to Deploy Forge and confirm your site shows as Connected
3. Check deployment history - Look in Deploy Forge → History to see if a deployment was created

Deployment created but not running

• For GitHub Actions method: Check your workflow completed successfully on GitHub
• For Direct Clone method: Check the deployment logs for download errors

Site shows "Not Connected"

Your connection may have expired or been revoked. In WordPress admin, go to Deploy Forge and click Connect to re-establish the connection (you'll be redirected to the Deploy Forge app to complete setup).

Changing Your Repository

You can update your repository, branch, or deployment method directly through the WordPress plugin settings. Alternatively, you can disconnect and reconnect your site to go through the full setup wizard again.

Security Notes

• Deploy Forge never stores your GitHub password
• Authorization uses the GitHub App model with limited, revocable permissions
• Webhook secrets use HMAC-SHA256 for signature verification
• You can revoke access anytime from GitHub Settings → Applications