Use GitHub deployments on WordPress.com

GitHub Deployments integrates your GitHub repositories directly with your WordPress.com site, giving you a version-controlled, automated workflow for deploying plugins, themes, or complete site changes. This guide covers the setup process and how to manage your connected repositories.

This feature is available on sites with the WordPress.com Business and Commerce plans, and the legacy Pro plan. If you have a Business plan, make sure to activate it. For sites on the Free, Personal, and Premium plans, upgrade your plan to access this feature.

Before you can deploy a GitHub repository to your WordPress.com site, you’ll first need to set up the connection between the two using the following steps:

1. Visit your Sites page: https://wordpress.com/sites/
2. Click the name of your site to view the site overview.
3. Click on the Deployments tab.
4. Click the “Connect repository” button. Then, if you see repositories listed, you have already connected your GitHub account. Continue to step 11.
5. Click the “Install the WordPress.com app” button.
6. A new window will open, and you will be prompted to log into your GitHub account if you haven’t already done so. Then you’ll see this screen:

7. Click the “Authorize WordPress.com for Developers” button.
8. Select the GitHub organization or account where your repository is located.
9. Select which repository/repositories you’d like to connect:
   • All repositories: Selecting this option will grant WordPress.com access to all current and future repositories owned by the selected GitHub account. This includes public repositories that are read-only.
   • Only select repositories: Selecting this option will allow you to choose which repositories WordPress.com can access on the selected GitHub account. 
10. Once you’ve selected an option, click the Install button.
11. The new window will close, and you will be taken back to WordPress.com. Your selected repository/repositories should be listed along with the GitHub account associated with that repository:

12. Click Select next to the repository you wish to connect.

At this point, you should see WordPress.com for Developers under your Authorized GitHub Apps and Installed GitHub Apps.

Once you select a repository, you will need to adjust the deployment settings:

• Deployment branch: Defaults to the default branch of the repository (typically main) but can be changed to the branch you wish to use.
• Destination directory: The server folder where you want to deploy the files. For plugins, it will be /wp-content/plugins/my-plugin-name. For themes, it will be /wp-content/themes/my-theme-name. For a partial site deployment (i.e., multiple plugins or themes), you can use /wp-content. The contents of a repository will be merged with the existing contents of the WordPress site in the specified directory.
• Automatic deployments: There are two ways you can deploy to WordPress.com:
  • Automatic: Once the code is committed, it will be deployed to your WordPress.com site. Automatic deployments are recommended for staging sites.
  • Manual: The code will be deployed once you request a deployment. Manual deployments are recommended for production sites.
• Deployment mode: There are two types of deployments:
  • Simple: This mode will copy all files from a branch of the repository to the site and deploy them with no post-processing.
  • Advanced: With this mode, you can use a workflow script, enabling custom build steps such as installing Composer dependencies, conducting pre-deployment code testing, and controlling file deployment. Ideal for repositories that need Composer or Node software. See Advanced Deployment below for more information.

Once all settings have been configured, click the Connect button. Your repository will be added:

Note that you must trigger the first deployment, either automatically or manually. You can then connect another repository at any time by clicking the “Connect repository” button.

With Advanced Deployment, you can provide a workflow script to process files in your repository before deployment. This opens up many possibilities, such as checking your code to ensure it meets your team’s coding standards, running unit tests, excluding files from the deployment, installing dependencies, and much more. To get started, check out our workflow recipes.

To set up Advanced Deployment:

1. A form will appear where you can configure the deployment.
2. Click the repository’s name to manage the connection.
3. On the right side, under “Pick your deployment mode“, choose Advanced.

4. If the repository already contains a workflow file, you can select it here. The system will check the file for any errors. If no errors are found, proceed to step 7.
5. You can also select the “Create new workflow” option to add a preconfigured workflow file. Choosing this option will overwrite the wpcom.yml workflow file if it already exists in your repository.
6. Click the “Install workflow for me” button to commit the workflow file to the repository.
7. Once a workflow has been added and verified, click Update. Your repository will now use advanced deployment.

After connecting your GitHub repository to a site, the next step is actually deploying your code. There are two deployment methods available: Automatic and Manual.

Automatic deployments are not recommended for live production sites, as any code changes in the repository are automatically deployed from GitHub to the live site. Instead, consider setting up automatic deployment to a staging site and syncing it to production once you’re ready.

Manual deployments give you more control over when your code changes are pushed live, as you will manually need to trigger each deployment. We recommend manual deployments if you don’t want to use a staging site.

To manually trigger a deployment:

1. Visit your Sites page: https://wordpress.com/sites/
2. Click the name of your site to view the site overview.
3. Click on the Deployments tab.
4. Click the ellipsis menu (⋮) on the repository you wish to deploy.
5. Choose “Trigger manual deployment“. You should see a banner notification that says, “Deployment run created,” and the deployment status will change to “Queued.”
6. Wait for the deployment to complete (the status will change to “Deployed”).

7. Click the ellipsis menu (⋮) again and choose “See deployment runs“. 
8. The Deployment run log displays the Author and the deployed commit. If you click the deployment run entry, you can view more information.

To manage your existing GitHub repository connections:

1. Visit your Sites page: https://wordpress.com/sites/
2. Click the name of your site to view the site overview.
3. Click on the Deployments tab.
4. You should then see the connections list. 

The connection list is shown if there is at least one connection between a GitHub repository and your site. The list includes relevant information for each connection, such as the repository name and branch, the last commit that was deployed to a site, when it happened, where the code was placed, how long the deployment run took, and its status.

There are additional actions available after clicking the ellipsis menu (⋮):

• Trigger manual deployment: Starts a deployment run on the latest commit of the configured branch.
• See deployment runs: Opens the deployment run logs view for the connected repository.
• Configure connection: Opens the manage connection view for the repository.
• Disconnect repository: Removes the connection between the repository and the site.

Deployment run logs provide a detailed, step-by-step record of each deployment, whether triggered automatically or manually. These logs help you track changes, monitor deployment status, and troubleshoot any issues that arise. With access to logs from the last 10 runs within 30 days, you can easily review what happened during each deployment and ensure everything is running smoothly.

To check the logs of a deployment:

1. Visit your Sites page: https://wordpress.com/sites/
2. Click the name of your site to view the site overview.
3. Click on the Deployments tab.
4. Click the ellipsis menu (⋮) next to the repository you want to view logs for.
5. Select “See deployment runs“.
6. The Deployment runs list view shows commits that were deployed to the site, the deployment status, the date, and the duration.
7. Click anywhere on a run to expand and view more information about the deployment.

The logs provide a record of all executed commands, from fetching code from GitHub to placing it in the target directory. You can expand log lines to see more information by clicking “show more“.

When you disconnect a GitHub repository from your site, any future changes to the repository will no longer impact your site. By default, the deployed files remain on your site, but you have the option to remove them during the disconnection process.

To remove a repository:

1. Visit your Sites page: https://wordpress.com/sites/
2. Click the name of your site to view the site overview.
3. Click on the Deployments tab.
4. Click the ellipsis menu (⋮) on the repository.
5. Select “Disconnect repository“.
6. A dialog window will appear. Click the switch to remove associated files from the site.
7. Click “Disconnect repository” to close the dialog and disconnect the repository.

Note that WordPress.com for Developers will still appear in your Installed GitHub Apps and your Authorized GitHub Apps. This is because WordPress.com still has access to the repository, but the connection has been deleted.

You may also choose to revoke WordPress.com’s access to your GitHub account. You can do so at any time by visiting your Applications settings on GitHub. 

To revoke authorized app access to your GitHub account:

1. Go to Authorized GitHub Apps.
2. Click Revoke next to WordPress.com for Developers.
3. Click the “I understand, revoke access” button.

Even if you revoke authorized app access, code can still be deployed because the WordPress.com for Developers app remains installed on the selected accounts.

To revoke access to the WordPress.com installation and disable the ability to deploy code to your WordPress.com site:

1. Go to Installed GitHub Apps.
2. Click Configure next to WordPress.com for Developers.
3. In the Danger zone area, click Uninstall, then click OK when prompted.

Removing WordPress.com from the list of authorized apps does not mean that the repositories will be deleted or stop working; your repositories will still exist on GitHub after you revoke WordPress.com’s access, but WordPress.com will no longer be able to deploy code.