How To Deploy to WP Engine using git push

13 May 2021

What is Git push?

Git push is a service or feature provided by some hosting companies like WP Engine, Siteground. It allows you to deploy changes to a WordPress website instead of using traditional FTP methods. The “git push” name came from the widely used git push command we use for the deployment in Github or Bitbucket repositories. Here git push is directly pointed to the remote repository of the hosting which is your website.

How to configure “Git push” in WP Engine hosting? 

Generate SSH key:

To enable “Git push” on WP Engine you need to generate a new SSH key and need to add it into the user portal of the website. SSH key is used for the public and private key pair for authentication. Refer to the Generating a new SSH key article on Github for generating a new SSH key.

Create SSH config:

SSH configuration file is used when your computer needs to connect to the specific hostname. Please use separate keys for Git and SSH gateway as WP Engine uses different hostnames for the Git and SSH gateway. SSH keys tell your computer in advance which key needs to be used for specific service.

Steps to create SSH config file:

Open the .ssh directory on your local machine,

• If you are using a Mac OS on your machine then open terminal and type:
  cd ~/.ssh/
  
• If you are using a windows OS on your machine then open Git bash and open the folder below:
  c:/Users/[your_name]/.ssh/
  OR
  c:/Users/Admin/.ssh/
  

Create a new configuration file by using the command below:

touch config

Open the new configuration file by running the command below:

nano config

Ensure cursor is at the bottom of the page by pressing arrow keys and add the following content:

Host git.wpengine.com

User git

Hostname git.wpengine.com

PreferredAuthentications publickey

IdentityFile ~/.ssh/wpegitkey

IdentitiesOnly yes

To save the above changes and exit from nano editor press ‘ctrl+x’ button on the keyboard
Make sure the private key path in provided clearly in the config file

Eg. IdentityFile ~/.ssh/wpegitkey

Add SSH key to WP Engine hosting ‘User Portal’:

1. Sign in to WP Engine account to access the User Portal
2. If you have created different environments for the website like staging, development then click on the specific environment for which you have to connect with Git
   
3. After that click on the ‘Git push’ link from the left navigation list
4. Fill the name of the developer whose SSH public key needs to be added. WP Engine will append the environment name automatically to the developer name.
   ie. environmentname-developername
5. Add the SSH public key generated in the SSH key generation step
6. Newly added key will be published within approximately 20 minutes

Test SSH configuration:

1. Run the following command using terminal or command prompt

   ssh -v git@git.wpengine.com info

2. Executing the above command will show the output as like in the example below:

   OpenSSH_8.1p1, LibreSSL 2.7.3
   debug1: Reading configuration data /Users/yourlocaluser/.ssh/config
   debug1: /Users/yourlocaluser/.ssh/conf.d/wpengine line 1: Applying options for git.wpengine.com
   debug1: /Users/yourlocaluser/.ssh/config line 4: Applying options for *debug1: /Users/yourlocaluser/.ssh/config line 31: Applying options for git.wpengine.com
   debug1: Reading configuration data /etc/ssh/ssh_config
   debug1: /etc/ssh/ssh_config line 47: Applying options for *
   debug1: auto-mux: Trying existing master
   hello user-environment
   R W    production/environment
   R W    staging/environment

Copy Content From User Portal to Local machine:

1. Click on the specific environment for which you have to connect with Git
2. Click on the ‘Backup points’ from the left side navigation menu
3. Select any latest backup point from the displayed backup list and click on the ‘Prepare ZIP’ button and select full backup option
4. Add the email address on which you want a backup created notification and creating ZIP in WP Engine user portal
5. Click on the download link after backup creation to download a zip file
   

Add .gitignore file:

1. This file is used to define which files and folders not needed to edit or pushed through Git
2. You can use the following example of the .gitignore file. Please add other files or folders location in it if you don’t want to pushed through Git

   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$

Confirm Git access:

• Wait for the 20 minutes after adding the SSH key in the user portal then you can confirm the Git access
  Enter the command below in terminal, command prompt or in Git bash window:

  ssh git@git.wpengine.com info

  If you’ve never connected before to Git on WPEngine, you will get a message to verify the host authentication before connecting to Git as shown below:

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

  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

  If you sees the above WP Engine’s fingerprints then type yes to connect

  After successful connection it will show the below message:

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

• If the key is Recognized:
  Enter the command below:

  ssh git@git.wpengine.com info
  

  Entering the above command will show the list of environment which have access to users like below:

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

  If you have added key to different environments then it will show details specific to the environment name

• If the key is NOT Recognized:
  If the key is NOT recognized it will show the following message:

  git@git.wpengine.com: Permission denied (publickey).

  Above message indicates that WPEngine git doesn’t recognize the key or you are connecting with an incorrect key. Please check key generation steps properly.

Do First Git Commit:

• Navigate to the local copy of the downloaded backup in the command line or terminal and use the following command if you have not initialized git earlier:

  git init .

• Make any changes in the local copy if you want to add in the first commit and enter the commands below:

  git add . --all

  git commit -m "First Commit"

• Above will make changes in the local git repository we need to move these commit changes to remote repository on the WP Engine hosting

Add Git Remotes:

Here we are mapping the local repository to the remote repository on the WP Engine. If you have separate environment on WP Engine you need to add the separate remote URLs for each environment like below:

• Make sure you have selected same codebase location in the command line or terminal
• Use the below command if you have separate environments:

  git remote add production git@git.wpengine.com:production/prodenvname.git

  git remote add staging git@git.wpengine.com:production/stageenvname.git

  git remote add development git@git.wpengine.com:production/devenvname.git

• We have added remote’s by considering production, staging and development environments in the above command. If you require you can use anyone from the above where you want to map local repository.
• Simultaneously you can add a bitbucket or Github repository remotes if you want to push changes (If require)
• To check the remote URLs are added properly use the command below using command line or terminal

  git remote -v

Add Git Remotes:

Now we have to push the locally implemented changes to the remote WP Engine repository. Use the command below to push the files to remote repository:

git push -v remote-name branch-name

• remote-name: This is the name of the environment where you want to push changes
• branch-name: This is the name of the local branch

Executing the above command will give output message about push successful or if any errors encountered

Repeat the above steps for the further commits.