Deploy ForgeDeployForge
Deploy ForgeDeployForge
Back to Home

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 authorize the Deploy Forge 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 with this structure:

your-theme-repo/
├── style.css           # Required: Theme stylesheet with header
├── functions.php       # Theme functions
├── index.php           # Main template
├── .github/
│   └── workflows/
│       └── build.yml   # GitHub Actions workflow (if using Actions method)
└── ... other theme files

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)
  • Upload a build artifact (so Deploy Forge can download it)

For Direct Clone Method

No workflow file needed. Deploy Forge downloads your repository directly.

How Automatic Deployments Work

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

  1. GitHub notifies Deploy Forge - Your repository sends push events to Deploy Forge servers
  2. Deploy Forge notifies your site - The event is forwarded to your WordPress site
  3. Your site processes the deployment - The plugin downloads and deploys the new code

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

To switch to a different repository or branch:

  1. Go to your Deploy Forge dashboard
  2. Select your site
  3. Update the repository or branch settings
  4. The next push will deploy from the new location

Security Notes

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