Connect a Repository

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

Configure the connection

To connect a repository:

1. Visit your site’s wp-admin dashboard and navigate to Hosting → Overview (or Settings → Hosting Configuration if using the default interface style).
2. Click on the Deployments tab.
3. Click the “Select repository” button. Then, if you see repositories listed, you have already connected your GitHub account. Continue to step 10.
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 haven’t already done so. Then you’ll see this screen:

6. Click the “Authorize WordPress.com for Developers” button.
7. Select the GitHub 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 GitHub account. This 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 GitHub account. 
9. Once you’ve selected an option, 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 GitHub 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.
• 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 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.

Advanced deployment

With Advanced Deployment, you can provide a workflow script to process the files in your repository before deploying them. 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. Click the repository’s name to manage the connection.
2. On the right side, under Pick your deployment mode, choose 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. 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.

That’s it. Your repository is connected, and you can proceed with deploying code.