Git Version Control System

Git is a version control system which allows a person to record changes to a file or set of files over time so that specific version can be reproduced later. WP Engine provides a tool called GitPush, which works with Git to allow the secure pushing of code from a local machine to a WP Engine website.

---

Generate SSH Key

The first step to enabling GitPush on a WP Engine site is to add an SSH Key to the User Portal. SSH Keys are key-based authentication  using public and private keys to create an encrypted connection between the local machine and a remote Git repository on WP Engine.

If an SSH Key does not already exist, use the steps below to generate a public/private key pair:

Option A: Generate Key Pair in Terminal
Option B: Generate Key Pair with PuTTY

---

Option A: Generate Key Pair in Terminal

1. Open a Terminal window
   1. Mac: Use the Spotlight utility and type “Terminal”
   2. Windows: Use Git Bash
2. Use ssh-keygen to generate a new key as shown below. Be sure to replace [email protected] with the specific email address.
   • ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/wpegitkey
3. Leave the passphrase blank by hitting enter or return again, without typing anything.
   • If a password is needed, this may be set. However WP Engine support cannot help it be recovered if lost.
4. Press enter or return again to confirm the password entry
5. Doing this will generate a public/private key pair
6. Print and copy the text of the new public key file, called wpegitkey.pub
   • cat ~/.ssh/wpegitkey.pub | pbcopy
7. Use this output when adding the key to the GitPush page in the User Portal.
8. Key content will begin with ssh-ed25519 and end with the email address used in the keygen command previously.

---

Option B: Generate Key Pair with PuTTY

If the PuTTY program on Windows is in use, this requires that the PuTTYgen utility also be installed.

1. When the PuTTY program, also install the PuTTYgen utility
2. Open the PuTTYgen utility to generate an SSH key
3. When asked which type of key to generate, select ED25519
4. Click the Generate button to create a public and private key pair
5. Save both the public key and the private key locally and take note of where the files will reside on the computer

This key will be needed when entering the public key into the WP Engine User Portal later on. We recommend copying the key from the top of the window in PuTTY.

---

Create SSH Config

The SSH configuration file tells the computer which key file to use when connecting to a specific server hostname. SSH Gateway and GitPush use different hostnames on WP Engine.

Setting up an SSH config file, and telling the computer in advance which SSH key is used for a service, will prevent any possible connection issues.

1. On the local machine, first navigate to the .ssh directory.
   • MacOS – Open Terminal and type:
     • cd ~/.ssh/
   • Windows – Use Git Bash and navigate to:
     • /c/Users/[youruser]/.ssh/
2. Create the config file by running:
   • touch config
   • If they file already exists, proceed to the next step.
3. Open the new config file, below is an example using nano, but any editor would work:
   • nano config
4. Once open, use the arrow keys to ensure the cursor is at the very bottom of the file
5. Paste the following contents:
   • Host git.wpengine.com
   User git
   Hostname git.wpengine.com
   PreferredAuthentications publickey
   IdentityFile ~/.ssh/wpegitkey
   IdentitiesOnly yes
6. Then save and exit. For nano:
   • Hold ctrl button then press x

If a different key file than what was generated previously, be sure to update ~/.ssh/wpegitkey to the desired private key file path.

If  SSH Gateway and Git are used together, additional SSH Config contents must be added for SSH Gateway.

---

Add SSH Key to User Portal

To securely use GitPush with a WP Engine environment, an SSH key must be added to the User Portal in the GitPush section. The key must be added to each environment independently to use GitPush.

If a key still needs to be generated, review the previous step here. A Developer name will be a label for the SSH key being added, and can be considered a name associating the local machine (aka the developer) that will be using GitPush. We recommend that a combination of environment name, first initial, and last name separated by a hyphen be used for the name. Only letters, numbers, hyphens, and underscores are allowed with a maximum 30 characters for the developer name.

1. Navigate to the User Portal
2. Select the environment name, for example “Dev” or “Prd”
3. Then click GitPush in the left-hand navigation (You may have to expand the Advanced dropdown section)
4. Fill in a Developer name
   • If a name that is already in use, it will receive an error and will be prompted to choose another name
5. Paste the contents of the public key in the SSH public key field
   • This is the key generated in the previous step Generate SSH Key
   • Ensure there are no extra spaces or line breaks before or after the key
6. Click Add Developer

The key will typically be published approximately 10 minutes after saving, but may take as long as 45 minutes. There will be an error if connecting  to Git before the key is fully published.

Add Existing GitPush SSH Key to Another Environment

Be sure to add the public key to all environments individually for GitPush. Once the key has been added in WP Engine User Portal it can be added to additional environments by adding the key and same developer name to a different environment, as shown above.

The following prompt  may be seen when reusing SSH keys, and can be accepted to add the same key under a different name.

SSH key in use.
This SSH public key is used by someuser-somesite.
Would you like to add this user's key to your install?

Remove GitPush SSH Key

If the GitPush SSH key needs to be removed from an environment, follow these steps to delete a key.

1. Log in to the User Portal
2. Click on the environment name to remove the Git user key from
3. Click GitPush
4. Scroll to Current developers
5. Click Remove next to the developer’s SSH key to revoke access

If an environment name is seen that does not match an environment, keep in mind that the developer keys are often created with the name of the original environment as part of an identifier for the SSH key. Some developers may have keys that are tied to environments that are not associated with the current account. This does not grant the owners of the referenced environment any unauthorized access to the account, nor does it grant any unauthorized access to the local machine.

---

Test SSH Config

Now that an SSH key has been created, then added to WP Engine and configured in an SSH config file, let’s make sure the configuration is functioning.

Run the following command in a terminal:

ssh [email protected] info

Output similar to the following will be seen if the SSH Config file is successfully configured for Git (line numbers and version numbers will vary):

ssh [email protected] info

hello user-localtesting
R W    localtesting
Please see http://git.wpengine.com for more help

In our example above, the connection was successful. The result shows the information for the environment that can be connected to via ssh. This shows that the SSH config was correctly set up.

If the connection was unsuccessful, run ssh -v [email protected] info then read this output carefully and adjust the local config file settings accordingly. The -v or verbose option is a great place to start when troubleshooting SSH connection issues.

The system will display line numbers in the output. These can help narrow down the source of issues by displaying which lines are or are not being used for the ssh connection.

---

Copy Content Locally

The next step is to download a copy of the site’s content to a local machine so a remote repository can be created.

If there already is a repository for the application’s code, it will only need to be added to the Git ‘remote’ end points before performing a GitPush. Skip to adding the gitignore file if this is the case as it is not required to add a repo from a backup.

If a local copy does not exist, it is recommended to download a backup point from the User Portal to accomplish this step.

1. Log in to the User Portal
2. Select the environment name that is connecting to Git
3. Click Backup points in the left navigation (You may have to expand the Manage dropdown section)
4. Select a backup to use as a starting point for the local repository
   • If a more current backup is needed first, review the steps here.
5. Click Prepare Zip

6. An email alerting that the backup zip file is ready for download will be sent.
7. Click Download ZIP

8. Click the download icon to select where to save the file. We suggest saving it to the folder on the local machine where it will be managing the Git repository.

9. Unzip the backup archive locally

---

Add .gitignore

The next step is to configure a .gitignore file on the local machine, which will define which files and folders should never be edited and pushed via Git. Below we have provided two templates for the .gitignore file.

1. Download the starter .gitignore template of choice
2. Add any other files that should be ignored
3. Move the .gitignore file into the folder on the local machine where it will be managing the Git repository
   • Be sure to place the .gitignore file in the root directory of the local copy of the website

We suggest only tracking the minimal amount of files if possible. This helps reduce issues down the line. For example, if only working on a theme file, the .gitignore file should exclude everything but that file. Feel free to add any of other site-based exclusions as-needed to the provided template files.

Suggested Workflow: Ignore WordPress core files

This option is recommended.

We will automatically keep WordPress core files up-to-date. Check here for more details on our Auto WordPress Updates.

The local version of WordPress core can be updated via wp-admin, WP_CLI or how it is preferred.

Additional Workflow: Utilizing Smart Plugin Manager

When utilizing Smart Plugin Manager automated plugin updates along with Git on a website, a more specific gitignore should be used. These gitignore files are similar to the workflows above that choose to ignore or keep WordPress core files.

Ignore WordPress core files & Ignore Smart Plugin Manager

Keep WordPress core files versioned & Ignore Smart Plugin Manager

SPM keeps plugins up to date with the version available on the WordPress plugin repo, or Github when utilizing a custom integration. This means the entire plugin directory is excluded so the files can be versioned elsewhere. If SPM has been configured to manage a particular plugin, the gitignore file can be modified to include it by adding the following to the bottom of the # smart plugin manager specific section:

!wp-content/plugins/your-plugin-name/

Disallowed Files and Types

There are certain files and types of files that are not allowed to be versioned using GitPush. Versioning large media files is not an inefficient way to use source control, as most of these files are binary, so tracking the differences between commits is difficult. . In some cases, with these known large file types, it’s best to use a CDN, and use SFTP access to upload these files to an account.

In order to keep applications running smoothly, WP Engine doesn’t allow files that may affect the core functioning of the WordPress site. This includes files like object-cache.php, wp-config.php, and a number of compressed and executable file types. To prevent errors, these files should always be in the .gitignore file and are added by default to both .gitignore examples above.

Below is the full list of disallowed files and types that cannot be pushed with GitPush.

wp-config\.php
_wpeprivate
wp-content\/uploads
wp-content\/blogs\.dir
wp-content\/upgrade
wp-content\/object-cache\.php
wp-content\/mysql\.sql
wp-content\/mu-plugins\/mu-plugin\.php
wp-content\/mu-plugins\/slt-force-strong-passwords\.php
wp-content\/mu-plugins\/wpengine-common
wp-content\/mu-plugins\/limit-login-attempts
\.hqx$
\.bin$
\.exe$
\.dll$
\.deb$
\.dmg$
\.iso$
\.img$
\.msi$
\.msp$
\.msm$
\.mid$
\.midi$
\.kar$
\.mp3$
\.ogg$
\.m4a$
\.ra$
\.3gpp$
\.3gp$
\.mp4$
\.mpeg$
\.mpg$
\.mov$
\.webm$
\.flv$
\.m4v$
\.mng$
\.asx$
\.asf$
\.wmv$
\.avi$

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

---

Confirm Git Access

If it has been at least 10 minutes since adding aSSH public key to the User Portal, GitPush access can be tested for the environment.

1. Copy the command below into a Terminal, Git Bash, or PuTTY window:
   • ssh [email protected] info
2. If this is a new connection to Git on WP Engine , a prompt may be shown to verify host authenticity before connecting, like this:

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)?

3. WP Engine’s 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

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

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

If the Key is Recognized

If the key is recognized by the Git service on WP Engine, a list of environment names that can be accessed will be displayed.

$ ssh [email protected] info

hello developer-name
R W environmentname
Please see http://git.wpengine.com for more help

If a public key was added to Production, Staging, and Development environments within a Site, a unique environment name will be listed for all as environmentname regardless of their Production/Staging/Development status in the User Portal.

If the Key is Not Recognized

If the key is not recognized by the Git service on WP Engine, this error will be shown:

[email protected]: Permission denied (publickey).

This error indicates that the WP Engine Git service does not recognize the key. Either:

1. Enough time has not passed to allow the key to be fully added (up to 45 minutes)
   • Try waiting longer, then attempt to connect again
2. Or, the incorrect key may be in use for the connection
   • Create an SSH config file to ensure the computer presents the correct key to git.wpengine.com

---

First Git Commit

Start by creating a local Git repository if the site hasn’t been used as a Git repository before. This can be done by using the git init command.

cd ~/path/to/localrepo

git init .

Now that the folder is set up as a Git repository, it’s time for the first commit. This commit will add all modified and new files (other than those in the .gitignore file) to Git for them to be tracked. This is a new copy of the website in theGit repository, so most files will be “new” to git.

git add . --all

git commit -m "First Commit"

---

Add Git Remote Repository

The next step is to map the local repository to the remote repository where it will deploy file changes on WP Engine. If a key has been added to production, staging, and development environments within the site in the first step, a remote will need to be added for each of these environments. It will be a one-to-one relationship between remote repository and environment.

In the below commands, replace prodenvname, stageenvname, and devenvname with the unique User Portal names of each environment.

First, navigate to the local Git directory that was created:

cd ~/path/to/localcopy

Then add the remotes for each environment:

git remote add production [email protected]:prodenvname.git

git remote add staging [email protected]:stageenvname.git

git remote add development [email protected]:evenvname.git

The remotes “production,” “staging,” and “development”  can be renamed by running git remote rename old_name new_name. WP Engine suggests naming them according to their role in the site to help with repository management that scales easier.

For example:

git remote add mysitename-production [email protected]:myprodenvname.git

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

git remote -v

This will list all the remotes that were successfully added. Now a GitPush command can be done to deploy code changes.

---

GitPush Deploy

Now it’s time to deploy using the GitPush command. After a local change has been made and staged (EX: using git add and git commit), use a Terminal, Git Bash, or PuTTY window and move to the folder where the local git repository was initialized:

• Type git push
• Type the name of the remote that will be pushed
• Type the name of the local branch to push
• It is recommend to add the -v flag to show a verbose output, which can be helpful if there are any errors.

EX: git push -v remote-name branch-name

To push the production main branch, for example, would look like this:

git push -v production main

The above command will push the local “main” branch to the remote endpoint named “production.” If the remote endpoint is named something else, be sure to replace “production” with that name instead (EX: git push -v mysitename-production main).

Pay attention to the GitPush output, as it will indicate whether the push was successful or if it encountered any errors.

If more help is needed, please contact our Support team via the User Portal and provide the full output of the GitPush.

Remove Files with GitPush

The deployment end of the GitPush process will only remove files from the application that have also been removed from the repository. For example:

• Add a file to the application, commit and push it to WP Engine,
• Later this file is no longer needed,
• Remove this file from the application, commit and push back to WP Engine,
• Now the file is removed from the live application.

If a file never existed in the repository it will not be removed from the application upon pushing.

Additionally, we recommend including the flag to remove empty directories for additional cleanup when removing files via GitPush: remove-empty-dirs

For example:

git push -v -o remove-empty-dirs production main

GitPush for AWS

Git pushing to a website hosted on AWS will require the web servers to sync, which could cause issues. Pushing with the flag --push-option=blue-green-deploy can help resolve these sync issues.

While a blue-green deployment will not make the process faster, it will restore to a separate directory on the server and then move it into place. Be aware that due to this, the site will occupy 2x the disk space during the process.

git push --push-option=blue-green-deploy -v production my_branch

The blue-green deploy will not work on Google or Azure hosted websites.

---

Git Support Commands

Should you need to reach support with a GitPush question or issue, below are some helpful commands to execute and provide output to speed up the support process, and get the issue addressed efficiently. 

Requested Output	Reasoning
ssh-keygen -E ed25519 -lf ~/path/to/keyfile.pub	Outputs the SSH public key. The example, ~/path/to/keyfile.pub , should be replaced with the actual path to the SSH public key on the system that matches the SSH public key that was added to User Portal. If the fingerprint for the SSH public key matches the output, then authentication to the repository will be successful.
ssh -vv [email protected] info	Provides verbose output of the SSH connection to git.wpengine.com which can be used to troubleshoot connection and authentication issues.
git remote -v	Provides a list of all the Git remote endpoints associated with the Git repository. This allows us to see that the endpoints have been configured correctly.
git push -v	Provides output and feedback during the ‘git push’ deployment. This output can be used to diagnose an issue or error with a ‘git push’ attempt.

---

SFTP and GitPush

Do not attempt to control a file with both SFTP and Git. GitPush is a one-way versioning tool. Any changes that are made to a file system through a web interface or via SFTP will not propagate back into Git. Also there is no warning if code is pushed up via Git that is older than code that’s presently on the installation. We recommend setting up a local dev environment and making all code changes there and pushing those changes to an app through Git. Read more about setting up a local development environment here. If it is needed to preserve changes made to versioned files, download the files via SFTP and commit them to the local repository.

If there is code on the site that resides outside of the Git repository, it’s best to avoid updates using SFTP and file editors in the WordPress admin unless necessary. If this is found necessary to use, be sure to avoid making changes to any code that’s versioned via GitPush, as it will be reverted to the versioned content on the next push.

---

Remove Files From Git

If it is decided to no longer version WordPress files via GitPush, the files will need to be removed from tracking locally with git rm --cached. This will remove them from the repository, but leave them in place in the working directory.

Once done, add a commit with this change, reset the GitPush point repository, then push the commit  for the site.

---

Database Versioning

Pushing a database via Git does not automatically import the database file to a website.

The ideal method is to perform a database export locally, add the SQL file to your repository, then commit and push the change. Once the database file is on a WP Engine server, import the file to your WP Engine website using using SSH Gateway.

The database can also be connected to remotely. If a remote database management system is in use, the database can be imported from the local machine directly to WP Engine. Please see Setting up Remote Database Access for more information.

---

Backups and Git

When a restore is made, the Git repository does not receive an update. The backup will need to be downloaded and merged with the local files, then committed and pushed to the configured remote repository to update the WordPress site.

---

Submodules

Submodules can work with WP Engine GitPush, so long as the submodule can be cloned without requiring a specific SSH key or username/password combination and responds to the ‘git’ protocol. It wouldn’t be possible to say, clone a private GitHub repository from the account – it has to be publicly accessible.

To set up the submodule, the external repository needs to use the HTTPS URL and not the GitHub SSH URL. For example:

[submodule "SUBMODULE"]
path = wp-content/plugins/SUBMODULE
url = https://github.com/USER/REPO.git

---

Git Clone

In order to clone a repo:

1. The repo must exist
2. A commit has to have been Git pushed to WP Engine
3. SSH keys must be added for all users who want to connect to the repo

View a list of remotes a user has access to:

ssh git.wpengine.com

This will give an output similar to:

$ ssh git.wpengine.com

hello user-name
R W environmentname.git

Please see http://git.wpengine.com for more help
Shared connection to git.wpengine.com closed.

To clone the existing repository, take the Git remote address (EX: environmentname.git) and add it to a git clone command. Be sure to replace environmentname with the unique WP Engine name of the environment.

git clone [email protected]:environmentname.git

Successful output is similar to the following:

Cloning into 'environmentname'...
remote: Counting objects: 677, done.
remote: Compressing objects: 100% (532/532), done.
remote: Total 677 (delta 129), reused 669 (delta 126)
Receiving objects: 100% (677/677), 14.11 MiB | 7.69 MiB/s, done.
Resolving deltas: 100% (129/129), done.

A git clone, by default, will create the repository directory. The repository now exists, in this example, in ~/environmentname/. The repo can be pushed normally after making a commit.

WP Engine support for branches is unique in that whichever branch was last pushed is the one that gets copied to the environment on WP Engine. The previous push takes precedence, so switching branches and attempting to have those changes take precedence will not work.

For more information on Git clone, such as flags, please see: https://www.git-scm.com/docs/git-clone

---

GitPush Failure

If a Git push is not reaching your WP Engine environment or otherwise failing, Support may need to clear the Git cache for the environment. This is most common if you’ve recently updated the .gitignore file or have been pushing from different branches. To reset the Git files for your website reach out the WP Engine Support for assistance.

Once Git cache has been cleared you should be able to perform the push again, however you may be required to make a new commit to trigger the Git hooks. This can be as minor as adding a new line or whitespace to a file, committing, and then pushing.

Deleting the Git cache will not affect your local repository or anything outside of WP Engine’s systems, as a deletion of the git-cache directory does not create a commit and cannot affect live or local data.

---

NEXT STEP: Resetting the GitPush repository