Deploy your WP Engine hosted application with the ease of Git

Please note: This article is geared toward users on the new User Portal experience, which allows users to create sites made of three environments: Production, Staging, and Development. For users on the legacy User Portal experience, consult our Legacy Git Guide instead.

Getting Started

Git is a powerful development tool which enables developers or a development team to push code changes from their local machine to their site on WP Engine. In this article we will explain how to get started with git on the WP Engine platform.

Step 1: Add Your SSH Key to User Portal

The first step to enabling git on your WP Engine site is to add your SSH Key to the User Portal. SSH Keys cast aside traditional username and password and opt instead for a public and private key pair for authentication.

Generate SSH Key Pair

If you don’t already have an SSH key, use the steps below to generate your public/private key pair:

  • Open a Terminal window (on Mac you can use the Spotlight utility and type “Terminal”), or Git Bash for Windows.
  • Use ssh-keygen to generate a new key as shown below

ssh-keygen -t rsa -b 4096 -C "[email protected]xample.com"

  • Type a secure passphrase when prompted

Doing this will generate your public/private key pair. In the output you should see text that indicates where your public key has been saved. Navigate in Terminal to this location and copy the text of your id_rsa.pub file.

If You Are Using PuTTY

When you install the PuTTY program, you also install the PuTTYgen utility. Open the PuTTYgen utility to generate your SSH key on your Windows machine.

When asked which type of key to generate, select SSH-2 RSA. Click the “Generate” button to create your public and private key pair. After the key pair has been generated, copy the public key from the top of the Key Generator (NOT using the “Save public key” button). Use the key from the top of the page when entering a key on the Git push page in the User Portal.

Add SSH Key to User Portal

Now that you have your SSH public key copied, navigate to your User Portal. Click the environment to which you would like to connect to get to the Overview page for that environment. Then click Git push from the left-hand navigation.

Here, you will be able to add the public key to your User Portal. Paste the contents of your public key in the box and create a developer name, then click the Add Developer button. Please note: Your key will be effectively published approximately 30-45 minutes after saving. In the meantime you will see an error if you try to connect to git in the following steps.

Be sure to add the public key for all environments in your site for which you wish to use git. After you have added the key to one environment, you will see a banner when adding it to other environments indicating the key is already in use. Click yes in the banner to add the existing key to your other environment(s).

Step 2: Download Production Site Content

The next step is to download a copy of your site’s content to your local machine. If you already have a copy of your site on your local machine you wish to use instead, feel free to skip to Step 3. If you don’t already have a local copy, we recommend downloading a backup point from your User Portal to accomplish this step.

Navigate to the Overview page for your environment in the User Portal. Select Backup points from the left-hand navigation. Now, select the backup point you wish to use as a starting point for your local repository from the list. Last, click Download ZIP and confirm which email address(es) should receive the email containing the backup point zip file.

You will receive an email within a few minutes containing the backup zip file. Move the zip file to the folder on your local machine where you will be managing your git repository and unzip it.

Step 3: Setup .gitignore file

The next step is to configure a .gitignore file on your local machine, which will define which files and folders should never be edited and pushed via git. Below we have provided two templates for your .gitignore file, to which you are free to add any of your own site-based exclusions if needed.

Download the starter .gitignore template of your choice, add any other files that should be ignored, and move it into the folder on your local machine where you will be managing your git repository. Place it in the root directory of your local copy of your website.

Should I version WordPress core files?

We can and will continue to keep your website’s WordPress environments updated with all the latest security and functional WordPress updates. It’s easier for WP Engine if the git repository doesn’t contain WordPress core files (option two). However, if the git repository does contain WordPress core files (option 1), we will commit and push the WordPress core upgrade back to your repo.

Step 4: Confirm Git Access

If it has been at least 30 minutes since adding your SSH public key to User Portal, you may now test to confirm your user has access to git for your environment. Copy the command below into your Terminal, Git Bash, or PuTTY window:

ssh [email protected] info

If you have never connected to git on WP Engine before, you will be prompted to verify host authenticity before connecting.

ssh [email protected] info
The authenticity of host 'git.wpengine.com (<no hostip for proxy command>)' can't be established.
ECDSA key fingerprint is SHA256:Jgp8bPftGbM0rzQaeA7KTBrZa1UfEN1nqQMLIwu5i18.
Are you sure you want to continue connecting (yes/no)?

The WP Engine host fingerprints are:

  • RSA 19:17:ee:d2:1d:8d:c9:3e:dc:3e:0d:21:a7:c6:52:fc
  • ECDSA 0c:4b:07:92:dd:e0:be:50:90:7d:0d:c3:30:56:fa:9a
  • ECDSA SHA256 Jgp8bPftGbM0rzQaeA7KTBrZa1UfEN1nqQMLIwu5i18

If the host fingerprint matches the above, type yes to continue connecting. You will receive a message indicating git.wpengine.com was added to your known hosts. This does not indicate a successful connection. It simply means your local machine will remember that git.wpengine.com is an accepted host with a valid fingerprint.

Warning: Permanently added 'git.wpengine.com,' (RSA) to the list of known hosts.

If your key is recognized by the git service on WP Engine, you will see a message showing a list environments to which your user has access:

Please note: If you have added your public key to your production, staging, and development environments within a site you should see the environment name for each listed here (the “staging/yourinstall” entry for each environment refers to the legacy 1-Click Staging tool).  

If not, you will see an error:

[email protected]: Permission denied (publickey).

This error indicates that the git service does not recognize the key. This could mean you haven’t waited long enough for the key to be fully added (30-45 minutes), or that you are connecting with an incorrect key. If you have waited longer than 30-45 minutes, try creating an SSH config file to ensure your computer presents the right key to git.wpengine.com.

Step 5: Make the First Commit

If your local copy of your site has not been used as a git repository before, you will need to make it into a repository by using the git init command.

cd ~/path/to/localcopy

git init .

Now that your copy is setup as a git repository, you can make your first commit. This will add all modified and new files (other than those in your .gitignore file) to git to be tracked. Since this is a new copy of your website that we’ve made into a git repository, all files will be “new” to git.

git add . --all

git commit -m “name of my first commit”

Note: At this point, nothing has changed on the front-end of your WP Engine environments. First we will need to setup remotes so we can use the git push command to deploy files.

Step 6: Add Remotes

The next step is to map your local repository to the remote endpoints where you will deploy file changes on WP Engine. If you added your key to production, staging, and development environments within your site in the first step, you will need to add a remote for each of these environments.

cd ~/path/to/localcopy

git remote add production [email protected]:production/prod-env-name.git

git remote add staging [email protected]:production/stage-env-name.git

git remote add development [email protected]:production/dev-env-name.git

In the above commands be sure to replace “prod-env-name,” “stage-env-name,” and “dev-env-name” with the User Portal names of each of these environments within your site. You may also name the “production,” “staging,” and “development” remotes whatever you prefer–we suggest naming them according to their role in your site to avoid confusion (e.g. mysitename-production).

To confirm the remotes were successfully added, use the following command:

git remote -v

This will list all the remotes that were successfully added. Now that the remote endpoints for git have been established, you can perform a git push to deploy code changes.

Step 7: Deploy with Git Push

Last, it is time to deploy using the git push command. To deploy, type git push, followed by the name of the remote you would like to push, and then the name of the local branch you wish to push.

git push production master

The above command will push the local “master” branch to your remote endpoint named “production.” If you named the remote endpoint something else, be sure to replace “production” with that name instead (e.g. git push mysitename-production master).

And that’s it! WP Engine takes care of the rest once we receive your git push, syncing the changes to the applicable environment. Be sure to pay attention to your git push output, as it will indicate whether the push was successful or if it encountered any errors.

If you do encounter errors, please use the troubleshooting steps at the bottom of our guide at https://wpengine.com/git/. If more help is needed, please contact our Support team (available 24/7!) via the User Portal and provide the full output of your git push.  

ERRORS & TROUBLESHOOTING

If you are using the Legacy 1-Click Staging environment rather than the new Sites with Production, Development, and Staging environments, follow our guide at https://wpengine.com/support/using-git-on-sites-with-legacy-staging instead.

When using git push, if you encounter errors, our FAQ section below explains troubleshooting steps and reasons you might encounter an error with git.

If you use multiple SSH keys with git, use our guide to creating an SSH Config file to ensure the right keys are used for the right environments.

FAQs

  1. I CAN’T CONNECT, OR RECEIVED AN ERROR IN THE OUTPUT OF A GIT PUSH. WHAT NOW?
  2. WHY DO I HAVE TO DOWNLOAD A SNAPSHOT OF MY SITE FIRST?
  3. HOW DO I KNOW GIT PUSH WON’T DELETE FILES FROM MY LIVE SITE?
  4. SHOULD I VERSION WORDPRESS CORE WITH MY THEMES/PLUGINS?
  5. WHAT’S WITH THE DISALLOWED FILES/FILE TYPES?
  6. I MADE CHANGES TO MY APPLICATION FILES VIA SFTP OR THE WORDPRESS THEME/PLUGIN EDITOR TOOL IN WP-ADMIN, BUT I’M NOT SEEING THESE CHANGES IN MY GIT REPOSITORY. WHY NOT?
  7. HOW DOES WP ENGINE MANAGE CORE WORDPRESS UPDATES WITH ‘GIT PUSH’?
  8. CAN I ADD SUBMODULES?
  9. CAN YOU GIVE ME A PUBLIC KEY OF YOUR GIT USER SO I CAN CLONE PRIVATE REPOSITORIES FROM GITHUB, BIT BUCKET, ET AL.?
  10. I NO LONGER WANT TO VERSION MY WORDPRESS CORE FILES, THEMES OR PLUGINS. HOW DO I REMOVE THEM FROM MY REPOSITORY WITHOUT REMOVING THEM FROM THE SITE?
  11. I STILL NEED TO USE SFTP FOR CERTAIN COMPONENTS WITHIN MY SITE. HOW DO I AVOID CODE CONFLICTS?

I CAN’T CONNECT, OR RECEIVED AN ERROR IN THE OUTPUT OF A GIT PUSH. WHAT NOW?

Check out our Getting Support section…

WHY DO I HAVE TO DOWNLOAD A SNAPSHOT OF MY SITE FIRST?

You don’t! We recommend that you do so that you start with a repository that most closely matches your live application at WP Engine. If you already have a repository for your application’s code, you would only need to add the Git ‘remote’ end points and perform a push.

Further reading:

HOW DO I KNOW GIT PUSH WON’T DELETE FILES FROM MY LIVE SITE?

The deployment end of the Git push process will only remove files from your application that you have removed from your repository. For example:

  • You add a file to your application, commit and push it to WP Engine,
  • You later decide this file is no longer needed,
  • You remove this file from your application, commit and push back to WP Engine,
  • The file is now removed from your live application.

If a file never existed in your repository at all, it won’t be removed from either your live or staging application.

SHOULD I VERSION WORDPRESS CORE ALONG WITH MY THEMES/PLUGINS?

It’s up to you. We didn’t want to dictate branching methodologies or whether or not you should version WordPress core. There’s several schools of thought around this, so go with the option that works best for you.

OK, OK… if you’re going to push us to an answer – then our recommendation would be not to version it. For a few reasons:

  • We can and will continue to keep your application’s WordPress install up-to-date – it’s just easier if the repository doesn’t contain WordPress core files. If it does, we will commit and push the WordPress core upgrade back to your repo.
  • WordPress core is available from wordpress.org or directly from several locations (svn, git mirrors) – why version something someone else is already versioning somewhere else?

WHAT’S WITH THE DISALLOWED FILES/FILE TYPES?

In envisioning what Git deployment would look like and how it would function, it was important to be providing a means to quickly deploy code, not manage repositories. Sure, a repository is created as a result of using Git but it’s important to us to not be in the business of repository management. Plenty of others in the space are doing this, and doing it well – GitHub.com, BitBucket.org, Unfuddle, et. al.

We also wanted the deployment process to be fast and agile. Versioning 300x10MB MP4 files is not only an inefficient way to use source control (as the files are binary so differences between commits are not easily tracked or displayed), but it can also make the process time consuming. In some cases for these known large file types, it’s best to use a CDN, and you can continue to use your SFTP access to upload these files to your account.

In order to keep your application running smoothly, we don’t allow you to push any files that are essential to the operation of your application. This includes files like object-cache.php, wp-config.php, and a number of compressed and executable file types. Paths used to house static content and images are also disallowed:

wp-content/uploads
wp-content/blogs.dir

For the full list of disallowed file types, feel free to download one of our available .gitignore templates, whether you would like to version core or not. Remember it needs to be named .gitignore  to work properly.

In addition, it’s never wise to store sensitive information in source control such as passwords and/or API keys.

I MADE CHANGES TO MY APPLICATION FILES VIA SFTP OR THE WORDPRESS THEME/PLUGIN EDITOR TOOL IN WP-ADMIN, BUT I’M NOT SEEING THESE CHANGES IN MY GIT REPOSITORY. WHY NOT?

Git is a one-way versioning tool. That means any changes you make to your file system through a web interface or via SFTP will not propagate back into Git. Also, there will be no warning if you push up code via Git that is older than code that’s presently on the installation. This is why we recommend setting up a local dev environment and making all code changes there and pushing those changes to your app through Git. Read more about setting up a local development environment here.

If you would like to preserve changes made to versioned files, download the files via SFTP and commit them to your local repository.

HOW DOES WP ENGINE MANAGE CORE WORDPRESS UPDATES WITH ‘GIT PUSH’?

WP Engine will continue to manage core updates for you. For those who version and deploy WordPress core with git, we will automatically create a new commit point and push the update back to the current branch of your repository. This will require a git pull/merge to update and sync to your local repository. If you don’t version WP core then you’ll get the upgrades as a part of our existing upgrade process.

CAN I ADD SUBMODULES?

Yes! So long as the submodule can be cloned without requiring a specific SSH key or username/password combination and responds to the ‘git’ protocol, this is possible. It wouldn’t be possible to say, clone a private GitHub repository from your own account though – it has to be publicly accessible.

CAN YOU GIVE ME A PUBLIC KEY OF YOUR GIT USER SO I CAN CLONE PRIVATE REPOSITORIES FROM GITHUB, BIT BUCKET, ET AL.?

Public keys on sites like GitHub require that the key be unique across all of GitHub. If WP Engine were to provide our “Git” user’s public key, it would have to be unique to your account so that other users can benefit from the same thing. This increases the management overhead of the feature because we would have to manage both the public keys provided to us to grant access, and the public keys we provide so that we can clone private repositories during the “git push” process. At this time, we aren’t supporting this feature but it may be something we add in the future!

I NO LONGER WANT TO VERSION MY WORDPRESS CORE FILES, THEMES OR PLUGINS. HOW DO I REMOVE THEM FROM MY REPOSITORY WITHOUT REMOVING THEM FROM THE SITE?

Should you decide to no longer version your WordPress core files via Git Push, you’ll need to remove them from tracking locally with `git rm –cached`, which will remove them from the repository, but leave them in place in your working directory. Once done, commit the change, reset the Git Push point repository, then push your commits to your site.

I STILL NEED TO USE SFTP FOR CERTAIN COMPONENTS WITHIN MY SITE. HOW DO I AVOID CODE CONFLICTS?

If you have code in use on your site that resides outside of your Git repository, it’s best to avoid updates using SFTP and file editors in the WordPress admin unless necessary. If you find either one necessary to use, be sure to avoid making changes to any code that’s versioned via Git Push, as it will be reverted to the versioned content on your next push.

Getting Support

Should you need to reach support with a ‘git push’ question or issue, here are some commands to execute and provide the output of. This will help our support staff get your ‘git push’ issue addressed quickly and efficiently.

Send the output of… …because…
ssh-keygen -E md5 -lf ~/path/to/keyfile.pub It provides your SSH public key. ~/path/to/keyfile.pub should be replaced with the actual path to the SSH public key on your system that matches the SSH public key you provided us. If the fingerprint we have for your SSH public key matches the output, then authentication to your repository will be successful.
ssh -vv [email protected] info It provides verbose output of your SSH connection to git.wpengine.com which can be used to troubleshoot connection and authentication issues.
git remote -v It provides a list of all the git remote endpoints associated with your git repository. This allows us to see that your production and/or staging endpoints have been configured correctly.
git push It provides output and feedback during the ‘git push’ deployment to your production or staging application. This output can be used to diagnose an issue or error with your ‘git push’ attempt.