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.

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

Information

Note

For additional assistance generating SSH keys, see GitHub’s “Generating a new SSH key” article.

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.

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.

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.

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 Sites page of the User Portal.
2. Click on the environment name for the environment you want to update with a Git SSH key.
3. Then select 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

Information

Note

If an error is received, please ensure that it is copied directly from the wpegitkey.pub file that was created when following the Generating SSH Keys instructions. To view the file contents again run cat ~/.ssh/wpegitkey.pub .

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?

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

1. Go to the Sites page in the User Portal.
2. Click on the environment name for the environment that you’re working with.
3. Select GitPush from the secondary left menu. (You may have to expand the Advanced dropdown section).
   
4. Scroll down to the Developers list section.
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.