GitHub Deployments

GitHub Deployments allow you to connect GitHub repositories to a WordPress.com site in a reliable, predictable, automated, and streamlined way using version control.

Whenever you make a code change in a repository, WordPress.com will be able to deploy it from GitHub to the site, either automatically or upon request. 

GitHub Deployments also give you the power to process files and run tasks before transferring the files to your WordPress.com site through GitHub workflows.

This feature is available on sites with the WordPress.com Creator or Entrepreneur plan.

This guide assumes you already have a GitHub repository for the deployment you want to perform. If not, head to Creating a GitHub Repository from Existing Source Files so you can create one.

Connect a repository

To deploy a GitHub repository to your WordPress.com site, the first thing you will need to do is to configure a repository connection.

1. Visit your site’s dashboard.
2. Navigate to Tools → GitHub Deployments.
3. Click the Select repository button.
4. Click the Install the WordPress.com app button.
5. A new window will open, and you will be prompted to log into your GitHub account if you aren’t already. Then, you’ll see this screen:

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

11. 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.

Manage Deployment Settings

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. The main branch is normally used as default and has the newest version of the product your customers are using.
• Destination directory: The server folder 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 on the specified directory.
• Automatic deployments: There are two ways to deploy from WordPress.com: automatic or manual.
  • Automatic: Once the code is committed, it will be deployed to your WordPress.com site
  • Manual: The code will be deployed once you request a deployment.
• Deployment mode: There are two types of deployments:
  • Simple: Configured to copy all files from a branch of the repository to the site and are deployed with no post-processing.
  • Advanced: Allow you to 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 below for more information.

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

You can connect another repository at any time by clicking the Connect repository button.

Note that you must trigger the first deployment, either automatically or manually.

Advanced Deployment

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

To set up Advanced Deployment:

1. Click the connected repository’s name to open the Manage connection view.
2. On the right side, under Pick your deployment mode, click Advanced.
3. A form will appear where you can configure the deployment.

4. If the repository already contains a workflow file, you can select it here. You can also select the Create new workflow option to add a new workflow file. Note that it will overwrite the wpcom.yml workflow file if it already exists.

Click the Install workflow for me button to commit the workflow file to the repository.

Deploy

Once the repository is connected, it’s time to deploy your code! There are two different ways to deploy from GitHub: Automatic and Manual.

Automatic deployments are not recommended for live production sites, as any changes to the code in the repository are automatically deployed from GitHub to the live site. Instead, you may decide to set up an automatic deployment to a staging site and then sync the staging site 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. Click the ellipsis menu (three dots) on the repository you wish to deploy.
2. Choose Trigger manual deployment. You should see a notification that says, “Deployment run created,” and the deployment status will change to “Queued.”
3. Wait for the deployment to complete (the status will change to “Deployed”), and then click the ellipsis menu (three dots) again and choose See deployment runs. 
4. The Deployment runs list displays the Author and the deployed commit. If you click the deployment run entry, you can view more information about the deployment. 
5. To verify that the files were deployed successfully, you can:
   1. Connect via SSH into your site and check that the repository files were mirrored to the Destination directory that you specified above.
   2. Go to the /wp-admin/plugins.php page in your wp-admin to view and activate the plugin if you deployed a plugin.
   3. Go to the /wp-admin/themes.php page in your wp-admin to view and activate the theme if you deployed a theme.

Manage Existing Connections

The connection list is shown if there is at least one connection between a 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 (three dots):

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

Disconnect a repository

When disconnecting a repository from the site, subsequent changes to the repository won’t affect your site. By default, the files deployed from the repository are kept on your site; however, you may remove them while disconnecting if desired.

To remove a repository:

1. Click the ellipsis menu (three dots) on the repository.
2. Select Disconnect repository
3. A dialog window will appear. Click the switch to remove associated files from the site.

4. 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.

Disconnect WordPress.com from GitHub

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.

Code will still be able to be deployed, even if you revoke authorized app access. This is because the WordPress.com for Developers app is still installed in 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.

Deployment Run Logs

After a new deployment run is created, whether automatic or manual, the logs for the deployment will be accessible as a subpage of the deployments list. You can view the logs from the last 10 runs within the last 30 days.

To check the logs of a deployment:

1. Click the ellipsis menu (three dots) on the repository.
2. Select See deployment runs.
3. The Deployment runs list view shows commits that were deployed to the site, the deployment status, the date, and the duration.
4. Click anywhere on the run to expand and view more information about the deployment.

The logs contain detailed information about the commands that were run, from grabbing the code from GitHub to placing the code inside the specified directory. Logs will contain any step, even successful ones, so you can track each step and debug in case of failures.

You can expand log lines to see more information by clicking show more.

Frequently Asked Questions

After setting up a connection, why can’t I see the plugin or theme in my server folder?

Setting up a connection prepares the environment but doesn’t automatically deploy your code.

Solution: For the deployment to happen, we need to either commit a new code in the selected branch (when using Automatic deployments) or trigger a manual deployment using the connection menu.

I deployed, but can’t find my changes in the server. Why? 

This probably indicates your repository files are trying to override one or more protected paths (internal files + managed plugins and themes). In these cases, the deployment files will be ignored during the transfer, and you’ll see a “Cannot deploy to protected directory” error in case you try to deploy to a protected folder.

Solution: Review your repository files and ensure you’re not trying to deploy protected files or folders.

How can I find the protected paths?

To understand which paths are protected, you can list them by running an SSH command in your server: cd /htdocs && find -not -writable

Solution: In case you want to include a plugin or theme that’s listed as a protected path, with the exception of Jetpack and Akismet, symlinked plugins can be removed by deleting the plugin via the dashboard, via SFTP, or by using CLI.

Next Steps and Feedback

We hope our GitHub Deployments tool allows you to streamline your development process and ship code quicker. Be sure to check out our other developer tools and platform features that will provide you with the flexibility and control you need to build on WordPress.com.

If you have any feedback about GitHub Deployments (or anything else on WordPress.com), we want to hear it! Contact support here with your thoughts and suggestions.

Last updated: April 22, 2024

Ready to get started with WordPress.com?

Start free trial