How to Deploy Efficiently to WP Engine Using GitLab CI/CD Pipeline in 8 Simple Steps
Last Updated: August 4, 2025
Efficient website deployment plays a critical role in maintaining a positive user experience and ensuring that websites stay up-to-date. Through optimizing the deployment process, we can decrease downtime and guarantee seamless and efficient implementation of changes. By integrating GitLab CI/CD pipelines with WP Engine, you can reduce errors in your deployment process. This tutorial will guide you through deploying your WordPress website to WP Engine using GitLab pipelines.
1. Generate a SSH Key
An SSH key functions as an authentication credential within the SSH protocol. Analogous to usernames and passwords, SSH keys are predominantly employed for automating tasks and facilitating single sign-on (SSO) for system administrators and power users.
To generate a new key use the following command in a terminal:
Terminal
ssh-keygen -t ed25519 -f ~/.ssh/wpengine-git
After hitting enter it will ask you to set a password. Although this makes the connection even more secure, it may interrupt when setting up automated processes. Therefore, just press Enter to skip this step.
2. Add the public SSH Key to WP Engine
Navigate to the GitPush tab and include the developer’s name along with the SSH public key we created in the previously step. Once the developer account has been successfully added, you can verify the SSH connection by executing the following command:
Terminal
ssh git@git.wpengine.com info
Note: The key will usually be published approximately 10 minutes after saving, but may take up to 45 minutes. There will be an error if you connect to Git before the key is fully published.
3. Add the SSH private key as a variable in GitLab
Access the Settings page within GitLab, then proceed to the CI/CD tab and expand the Variables section. Create a new variable with the default settings, setting the Key to SSH_PRIV_KEY and the Value to the SSH private key generated in step 1.
4. Prepare your GitLab repository
Make sure that your repository is configured to point to the WordPress root directory. If your repository contains WordPress within a folder, you can use the following command, where htdocs is the folder that has the WordPress root, and wpengine-main is the new branch with the content inside the htdocs folder.
Terminal
git subtree split –prefix=htdocs –branch wpengine-main
5. Configure the .gitignore file
WP Engine prohibits the synchronization of certain files, such as the wp-config.php file or *.exe files. Here is a .gitignore file that you can use:
# compiled files
*.com
*.class
*.dll
*.exe
*.o
*.so
*.log
# packaged files
*.7z
*.dmg
*.gz
*.iso
*.jar
*.rar
*.tar
*.zip
# ignore wp-content related
wp-content/uploads/*
wp-content/upgrade/*
#htdocs/wp-content/languages/*
# ignore translations folder
wp-content/languages/*
# specific
#.env
*.sql.gz
db_dump/
.htaccess
.DS_Store
node_modules
package-lock.json
wp-config.php
If some files are already added to your repository, you will have to remove them:
git rm –-cached path/to/your/file
git commit -m “Remove files”
After the files are removed, you can add them back if you still need them locally.
6. Add a GitLab Runner
GitLab runner is a build instance that is used to run the jobs over multiple machines and send the results to GitLab which can be placed on separate users, servers, and local machines. You can register the runner as shared or specific after installing it.
Here is a guide on how to create, register, and run your own project runner.
7. Add a .gitlab-ci.yml file to your GitLab repository
To use GitLab CI/CD, you start with a .gitlab-ci.yml file at the root of your project. This file specifies the stages, jobs, and scripts to be executed during your CI/CD pipeline. It is a YAML file with its own custom syntax.
YAML
stages:
– deploy
.deploy:
image:
name: alpine:latest
before_script:
– ‘which ssh-agent || ( apk add –update openssh )’
– apk add –update bash
– apk add –update git git-subtree
– eval $(ssh-agent -s)
– echo “$SSH_PRIV_KEY” | ssh-add –
– mkdir -p ~/.ssh
– ‘[[ -f /.dockerenv ]] && echo -e “Host *\n\tStrictHostKeyChecking no\n\n” > ~/.ssh/config’
stage: deploy
when: manual
allow_failure: false
deploy_prod:
extends: .deploy
script:
– “git remote add wpengine git@git.wpengine.com:environment.git”
– “git push wpengine HEAD:master –force”
tags:
– wpengine
– master
– wpriders
only:
– master
environment:
name: production
url: https://domain.com
Let’s break down each command from the YML file:
- stages
- This defines the deploy stage in our pipeline.
- .deploy
- This is a script-like template portion that other jobs can inherit using the extends keyword. It defines shared configurations that can be used in multiple jobs.
- image: Specifies the Docker image to be used for our jobs: latest Alpine Linux.
- before_script: Contains a set of commands that are executed before all jobs. It includes commands for installing necessary packages (ssh-agent, bash, git) and setting up SSH keys.
- stage: Indicates that the current job is part of the deploy stage of the pipeline.
- when: Specifies that the job is only run manually by the user and not automatically triggered.
- allow_failure: Indicates that if this job fails, the entire pipeline will be marked as failed.
- This is a script-like template portion that other jobs can inherit using the extends keyword. It defines shared configurations that can be used in multiple jobs.
- deploy_prod
- This is a specific job in the pipeline. It extends the .deploy template defined earlier with additional configurations.
- script: Contains the commands to be executed as part of the deploy_prod job. It adds the WP Engine remote git repository and pushes the code to it.
- tags: Labels assigned to runners that can be used to select specific runners for jobs.
- only: Ensures that this job only runs when changes are made to the master branch.
- environment: Defines the target environment. The name is “production” and the URL indicates the deployment destination URL.
- This is a specific job in the pipeline. It extends the .deploy template defined earlier with additional configurations.
8. Run the job
Now that we have everything in place we can push some changes to our master branch. After running the deploy_prod job we should have something similar to this:
Do you like this article? Share it and send us your feedback! Check out our articles page, where you might find other interesting posts. Also, if you want to learn more about business, check out the WPRiders Blog!
