GitHub Action for deploying a WordPress site using using PHP's Deployer.org
This action is a part of GitHub Actions Library created by rtCamp.
A GitHub Action to deploy WordPress on a server using PHP's Deployer.org project.
Please note that, this action expects git repo structure in a certain way. Your webroot should include content
inside wp-content
except uploads
. You may use our WordPress Skeleton
as a base, or restructre existing project to fit in.
During deployment, by default this action will download WordPress, put the content
of the repo in wp-content
directory and then deploy the entire WordPress setup on the deploy path specified
in hosts.yml
.
hosts.yml
is Deployer's inventory file.
.github/workflows/deploy.yml
file in your GitHub repo, if one doesn't exist already.deploy.yml
file.on: push
name: Deploying WordPress Site
jobs:
deploy:
name: Deploy
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Deploy
uses: rtCamp/action-deploy-wordpress@v3
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
SSH_PRIVATE_KEY
secret
using GitHub Action's Secret and store the
private key that you use use to ssh to server(s) defined in hosts.yml
..github/hosts.yml
inventory file, based
on Deployer inventory file format. Make sure you explictly
define GitHub branch mapping. Only the GitHub branches mapped in hosts.yml
will be deployed, rest will be filtered
out. Here is a sample hosts.yml.Variable | Default | Possible Values | Purpose |
---|---|---|---|
user |
null | valid username. eg: root |
Username for ssh. |
deploy_path |
null | valid path. eg: /opt/easyengine/sites/example.com/app/htdocs |
path where action will deploy. |
hostname |
null | hostname/ip. eg: example.com |
hostname for ssh. |
Variable | Default | Possible Values | Description |
---|---|---|---|
block_emails |
null | true /false |
If set to true, this will enable email blocking functionality. |
block_emails_plugin_path |
null | Accept relative path from wp-content directory, eg: custom-mu-plugins |
If you have set the MU_PLUGIN_DIR constant in your wp-config.php file to specify a custom path for mu-plugins, you can use this variable to install Block Emails into your custom mu-plugins directory. |
block_emails_plugin_file_name |
000-block-emails | String without the .php extension. | If you wish to modify the loading position of this plugin within the mu-plugins loading phase. |
WP_VERSION |
null | Any valid WordPress version | If you specify a WordPress version, then that speicifc WordPress version will be downloaded, instead of latest WordPress version. Note: Please use double quotes while giving value to this variable. This will have higher priority then the one defined in workflow file. |
This GitHub action's behavior can be customized using following environment variables:
Variable | Default | Possible Values | Purpose |
---|---|---|---|
MU_PLUGINS_URL |
null | vip, any git repo url | If value is vip , then action will clone VIP's MU plugins as mu-plugins folder. If you want to specifiy a non-VIP mu-plugins repo, you can provide a publicly accessible mu-plugins repo URL as the value. |
WP_VERSION |
latest | Any valid WordPress version | If you specify a WordPress version, then that speicifc WordPress version will be downloaded, instead of latest WordPress version. Note: Please use double quotes while giving value to this variable. Also, WP_VERSION , if defined in hosts.yml will have higher priority then the one defined in workflow file. |
WP_MINOR_UPDATE |
null | true / false |
If set to true , latest minor version of WP_VERSION will be taken. |
JUMPHOST_SERVER |
null | Hostname/IP address of the jumphost server | If the deployment server is not directly accessible, and needs a jumphost, then this method should be used. (Note: The SSH_PRIVATE_KEY env variable should have access to the jumphost as well as deployment server for this to work. Also, this method does not work with vault.) |
SUBMODULE_DEPLOY_KEY |
null | Read access deploy key created in the submodule repo's deploy keys. | Only required for privated submodule repo. For now only one private submodule deploy key is allowed. All public submodules in repo will be fetched by default without the need of this env variable. (To create a deploy key go to: Settings > Deploy Keys > Add deploy key) |
SKIP_WP_TASKS |
null | true /false |
If set to true , WordPress specific deplyment tasks will skipped. |
PHP_VERSION |
7.4 | Valid PHP version | Determines the cachetool version compatible to use for purging opcache. |
NPM_VERSION |
null | Valid NPM Version | NPM Version. If not specified, latest version will be used. |
NODE_VERSION |
null | Valid Node Version | If not specified, default version built into action will be used. |
NODE_BUILD_DIRECTORY |
null | path to valid directory on repository. | Build directory. Generally root directory or directory like frontend. |
NODE_BUILD_COMMAND |
null | npm run build or similar command. |
Command used to to build the dependencies needed on deployment. |
NODE_BUILD_SCRIPT |
null | path to valid shell script | Custom or predefined script to run after compilation. |
All node related variables are completely optional. You can use them if your site needs to have node dependencies built.
The Deployer.org expects server setup in a particular way.
--public-dir=current
during site creation.current
folder using rm -r /opt/easyengine/sites/example.com/app/htdocs/current
.The current
folder will be automatically created by Deployer during execution.
/opt/easyengine/sites/example.com/config/nginx/conf.d/main.conf
./var/www/htdocs
with /var/www/htdocs/current
.ee site reload example.com
.wp-config.php
to htdocs
. You can use following command:mv /opt/easyengine/sites/example.com/app/wp-config.php /opt/easyengine/sites/example.com/app/htdocs/wp-config.php
current
subdirectory inside original webroot. Make sure current
subdirectory
do NOT exist actually.wp-config.php
as we need in above section.This GitHub action supports Hashicorp Vault. This comes in handy if you manage multiple
servers and providing SSH_PRIVATE_KEY
as GitHub secret per project becomes cumbersome.
To enable Hashicorp Vault support, please define following GitHub secrets:
Variable | Purpose | Example Vaule |
---|---|---|
VAULT_ADDR |
Vault server address | https://example.com:8200 |
VAULT_TOKEN |
Vault token | s.gIX5MKov9TUp7iiIqhrP1HgN |
You will need to change secrets
line in deploy.yml
file to look like below.
on: push
name: Deploying WordPress Site using vault
jobs:
deploy:
name: Deploy
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Deploy
uses: rtCamp/action-deploy-wordpress@v3
env:
VAULT_ADDR: ${{ secrets.VAULT_ADDR }}
VAULT_TOKEN: ${{ secrets.VAULT_TOKEN }}
GitHub action uses VAULT_TOKEN
to connect to VAULT_ADDR
to
retrieve Signed SSH Certificates
and uses it for deployment.
Please remember that you must configure each of your target deployment server to accept ssh connection via signed certificate using Vault beforehand. Ususally, you need to run following commands once per server:
export VAULT_ADDR='https://example.com:8200'
export VAULT_TOKEN='s.gIX5MKov9TUp7iiIqhrP1HgN'
# Add the public key to all target host's SSH configuration.
curl -o /etc/ssh/trusted-user-ca-keys.pem "$VAULT_ADDR/v1/ssh-client-signer/public_key"
# Add the path where the public key contents are stored to the SSH configuration file as the TrustedUserCAKeys option.
echo "TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem" >> /etc/ssh/sshd_config
# Restart ssh service. This may differ according to the OS.
systemctl restart ssh
.github/deploy/deploy.php
in your git repository to provide your own Deployer.org
script.
.github/deploy/deploy.php
.deploy.php
, you can create a file at
location .github/deploy/addon.php
in your git repository. Checkout the example addon.php to
see how to customize it.main.sh
shell script of this action, you can create a file at
location .github/deploy/addon.sh
in your git repository. Checkout the example addon.sh to see
how to customize.MIT © 2022 rtCamp