Getting Started
Set up Git Push in your User Portal
To use Git Push integration with WP Engine, you need to add your SSH Public Key. After generating your SSH Public Key, the next step is to add it to the install of your choice in the User Portal by navigating to the Git Push tab and submitting your developer name and public key in the form. If you need help generating an SSH public key – check out GitHub Help: Generating SSH Keys. If you use multiple SSH keys with git, learn how to create a config file for easy key management.
Once you have added your public SSH key in your User Portal, you’ll need to obtain a snapshot of your application to work with. You can download a backup of your production or staging site in the user portal. If you are already using Git for your application’s source control but just need the details to deploy your application, feel free to skip ahead to Deploying to Production.
Not sure what GIT is? We’ve made a free white paper exactly for you!
Don’t want to read? Here’s one of our webinars all about GIT!
Confirm access
Now you should be able to execute a test to confirm that you can see the Git remotes for your application. If you’ve never connected to git.wpengine.com before, you’ll first be asked to confirm SSH host authenticity. This is normal (provided you aren’t setting StrictHostKeyChecking no in your SSH configuration).
$ ssh [email protected] info The authenticity of host 'git.wpengine.com' can't be established. RSA key fingerprint is 19:17:ee:d2:1d:8d:c9:3e:dc:3e:0d:21:a7:c6:52:fc. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'git.wpengine.com,' (RSA) to the list of known hosts.
These are the host fingerprints for our Git Push feature:
RSA 19:17:ee:d2:1d:8d:c9:3e:
ECDSA 0c:4b:07:92:dd:e0:be:50:
ECDSA SHA256 Jgp8bPftGbM0rzQaeA7KTBrZa1UfEN
If you receive a different fingerprint, do not continue to establish a connection to git.wpengine.com.
Obtaining a snapshot of your application (optional)…
If you already have a version controlled code base, or even just a code base for your application – you can skip ahead to “Setting up the recommended .gitignore”.
Log in to your account at my.wpengine.com and navigate to the Backup Points section for the chosen install that will be setup to use Git. Once there, select Download Zip for the preferred backup point, or create a new backup-point.
Once the download of the preferred backup point is complete, extract the contents to a directory of your choosing. This guide will assume ~/wordpress/my_wp_install_name.
Removing the mu-plugins directory from the snapshot …
The mu-plugins directory that is contained within the snapshot includes several WP Engine scripts. These scripts may conflict with components of your local environment or cause other errors. We suggest that you remove the mu-plugins directory’s content (which can be found within the wp-content directory) to avoid conflicts.
Setting up the .gitignore…
Once a snapshot of the application is obtained and extracted, a .gitignore file will be required to prevent you from pushing back files that would interfere with WP Engine systems or large media files that are better housed on a CDN.
The .gitignore can be modified based on specific application needs, although the deployment process on the WP Engine side will disallow pushing the above files/file types.
Download one of our.gitignore template that makes the most sense for your application requirements. Then rename it to .gitignore and place it in the root directory of your install’s code base.
| Download! | Starter `.gitignore` (keeps WordPress core files versioned) |
| Download! | Starter `.gitignore` (ignores WordPress core files) |
Making the first commit…
Once the .gitignore is in place, the repository will need to be initialized and the initial commit performed so that there is data to push to WP Engine.
git init . command below is only needed if your code base hasn’t already been setup as a git repository. This can be determined by running git status from the project’s root directory.$ cd ~/wordpress/my_wp_install_name $ git init . $ git add . --all $ git commit -m "initial commit..."
At this point, the .gitignore file has been added, repository created, and the initial commit performed. Nothing has changed on any of your WP Engine applications yet. For that, a git remote is needed…
Deploying to Production
Setup ‘git remote’ for production…
In order to ‘git push’ application code to WP Engine, the application repository must be configured to add the production ‘remote’ of the application. The examples here assume an application named my_wp_install_name located in ~/wordpress/my_wp_install_name.
$ cd ~/wordpress/my_wp_install_name $ git remote add production [email protected]:production/my_wp_install_name.git
You can call the ‘remote’ whatever you’d like – in the above example it is production. Some other examples:
$ git remote add wpengine-prod [email protected]:production/my_wp_install_name.git $ git remote add live-site [email protected]:production/my_wp_install_name.git
Above, the ‘remote’ names are wpengine-prod or live-site. You only need one of these, so feel free to call it what works best for you.
To confirm the remote was added, you can execute:
$ git remote -v production [email protected]:production/my_wp_install_name.git (fetch) production [email protected]:production/my_wp_install_name.git (push)
Deploy!
At this point, the Git repository has been initialized, the .gitignore added, and the initial commit performed. In order to update the code on your application/install at WP Engine, a git push needs to be performed:
$ git push production master
In the example above, the code on the master branch is what will end up deployed on the WP Engine application/install. You can use whatever branch you’d prefer to send to WP Engine by running git push production other_branch:master . If you used a different ‘remote’ name above, this command may look like git push live-site master or git push wpengine-prod master.
That’s it! Once WP Engine receives your git push, our systems will automatically take care of the rest.
Deploying to Staging
Create your staging area…
In order to deploy application updates to your staging environment, you first need to create the 1-click staging environment! You can learn how to use our 1-click staging areas in this support article. If you use a separate staging environment as part of a Dev-Stage-Prod site, you will be able to add your git key to this environment separately after creating this staging environment. Learn how the 1-click staging and staging environments differ.
Setup ‘git remote’ for staging…
Once your staging area has been setup, a new remote will need to be added to point to your staging application. A staging remote is very similar to a production remote, and only differs in the path of the remote.
The examples here assume an application named my_wp_install_name located in ~/wordpress/my_wp_install_name.
$ cd ~/wordpress/my_wp_install_name $ git remote add staging [email protected]:staging/my_wp_install_name.git
Similar to the production remote, you can call the ‘remote’ whatever you’d like – in the above example it is staging. Some other examples:
$ git remote add wpengine-stage [email protected]:staging/my_wp_install_name.git $ git remote add stage-site [email protected]:staging/my_wp_install_name.git
Above, the ‘remote’ names are wpengine-stage or stage-site. You only need one of these, so feel free to call it what works best for you.
To confirm the remote was added, you can execute:
$ git remote -v staging [email protected]:staging/my_wp_install_name.git (fetch) staging [email protected]:staging/my_wp_install_name.git (push)
If you have both a ‘staging’ and production’ remote, your output may resemble:
$ git remote -v production [email protected]:production/my_wp_install_name.git (fetch) production [email protected]:production/my_wp_install_name.git (push) staging [email protected]:staging/my_wp_install_name.git (fetch) staging [email protected]:staging/my_wp_install_name.git (push)
Deploy!
In order to update the code on your application/install at WP Engine, a git push needs to be performed:
$ git push staging master
In the example above, the code on the master branch is what will end up deployed on the WP Engine application/install for the staging environment. You can use whatever branch you’d prefer to send to WP Engine by running git push staging other_branch:master . If you used a different ‘remote’ name above, this command may look like git push stage-site master or git push wpengine-stage master.
That’s it! Once WP Engine receives your git push, our systems will automatically take care of the rest.
Git pull
Pull from production
Now that you have successfully setup and deployed to your production remote, you can now git pull code from your repository. Notice: You will not be able to git pull site content that has been deployed to the site by any other means than git, since they will have bypassed the git repository.
The standard git pull command will sync your remote repository effectively with your local repo.
$ git pull production master
Pull from Staging
Once your team has successfully deployed code to the staging remote, you will be able to pull down content from that repository as well.
$ git pull staging master
These tools will effectively allow your team to collaborate on projects using a complete git workflow!
FAQs
- I CAN’T CONNECT, OR RECEIVED AN ERROR IN THE OUTPUT OF A GIT PUSH. WHAT NOW?
- WHY DO I HAVE TO DOWNLOAD A SNAPSHOT OF MY SITE FIRST?
- HOW DO I KNOW GIT PUSH WON’T DELETE FILES FROM MY LIVE SITE?
- SHOULD I VERSION WORDPRESS CORE WITH MY THEMES/PLUGINS?
- WHAT’S WITH THE DISALLOWED FILES/FILE TYPES?
- 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?
- HOW DOES WP ENGINE MANAGE CORE WORDPRESS UPDATES WITH ‘GIT PUSH’?
- CAN I ADD SUBMODULES?
- CAN YOU GIVE ME A PUBLIC KEY OF YOUR GIT USER SO I CAN CLONE PRIVATE REPOSITORIES FROM GITHUB, BIT BUCKET, ET AL.?
- 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?
- 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.
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. |