Keeping your code inside a version control system like GitHub and automatically deploying changes is widely known as the best way to maintain a stable site. Because of this, we've made it easy to integrate your WordPress site with GitHub Actions.
In this article, we'll show you how to integrate your Pagely VPS with GitHub Actions for automatic deployments.
Always Test on a Staging Site First
Just like setting up any other deployment process, invalid configurations, typos, and other problems are always possible. In case anything goes awry, always test automatic deployments on a staging site before targeting a live site in production.
Setting Up Your GitHub Repository
When setting up a repository that will use automatic deployments, it's important that it correctly matches the environment that you'll be deploying to. If your WordPress site's files differ from what's inside version control, you could lose data when the deployment runs.
For deploying to more than one branch/site, you’ll need to create separate workflows for each environment in the
For example, to set up a staging workflow, you might create a
.github/workflows/staging-deploy.yml file, and for production, a
.github/workflows/production-deploy.yml file. Each file would contain a workflow that triggers on pushes to their respective branches.
If you'd like to learn more about structuring your repository, excluding files, and how automatic deployments work, take a look at our article about setting up Git repositories for automatic deployments.
Creating a New Integration in Atomic
To communicate between your Pagely account and 3rd-party services, Pagely offers an integration interface. These integrations allow you to easily generate a set of credentials for 3rd-party services in just a few clicks.
Further sections in this article assume that you've already created an integration inside Atomic. To learn more, take a look at our article on creating a new integration inside the Atomic control panel.
Setting Up Your Integration Secret Key in GitHub
Storing your integration secret as a secret in GitHub prevents your key from displaying inside your logs or action pipelines. For security, it's always a good idea to put your integration's deploy tokens or any other sort of credentials inside a GitHub secret, even if it's a private repository.
Here's how to set up your integration secret inside your GitHub repository:
- Start by logging into GitHub and accessing the repository that you'll be deploying from.
- Towards the top of the page, click on Settings.
- Once inside the Settings page, access your repository's secrets by clicking on Secrets within the left side menu.
- To add a new secret, click on the New Secret button.
- The first thing we need to do is name our new secret. For this article, we'll enter PAGELY_INTEGRATION_SECRET into the Name field.
- Next, our new secret needs a value. Inside the Value field, enter the Integration Secret that was generated for you in Atomic.
- Once your secret's name and value are filled out, just click on the Add Secret button to add it.
Creating a Deployment Action Step
So that deployments from GitHub can be as seamless as possible, Pagely provides a GitHub Action that is ready to be used with just a few variables. This Action passes your variables over to a Docker container that does the rest of the work for you.
Here's an example of what a full GitHub Action pipeline configuration would look like:
name: Deploy to Pagely
- name: Checkout repo
- name: Run deploy
If you're already familiar with GitHub Actions, you can take this example, drop it into your workflow's YAML file, and customize the variables as needed. To learn more about the variable that we're using in this example, take a look at our deployment Docker image reference.
If you'd prefer to walk through what's going on in the example, here's a tutorial to get you up and running:
- Start by creating a new workflow inside your repository. GitHub workflows are YAML files that live inside of the
For this example, we'll name our file
Inside the file, you can paste in the entire workflow from the example above. Of course, if you already have an existing workflow, you're welcome to grab the "Run deploy" step from the example and add it wherever needed.
- Inside of the deployment step, we'll need to adjust a few variables to match your integration. The first of these is the PAGELY_DEPLOY_DEST variable.
If your GitHub repository contains your entire WordPress site, you can leave the default of
/httpdocs, which reflects your site's root directory.
If you're deploying a single item like a WordPress theme or plugin, you'll want to modify this to reflect the correct destination. For example, if the repository houses just your theme, you would set this to something like
For more information on deployment paths and other variables, take a look at our deployment Docker container reference.
- The next variable in our example is the PAGELY_INTEGRATION_SECRET. As we mentioned earlier, it's best to store it as a secret within your GitHub repository settings.
As long as you named your secret as described in earlier steps, you don't need to make any changes to this variable. Otherwise, you'll need to change it to reflect your secret's name.
- The next two variables that you'll need to configure is the PAGELY_INTEGRATION_ID and PAGELY_APP_ID. Since these are both just identifiers, it's fine to define them either as plain-text inside your configuration (or optionally as a secret if you'd prefer).
Both of these IDs can be found inside Atomic. Your Integration ID can be found within your integration's details, while your App ID can be found inside the App Details page.
- The last variable in the example is optional, but worth mentioning. If your code is located inside of a separate source directory, you can set it with PAGELY_WORKING_DIR. This is helpful if you're performing other build steps that place your production-ready code in a different location.
If you don't need to change your working directory, you can either leave the variable as we've defined it in the example or remove it entirely if you'd prefer.
Once your workflow is configured to use Pagely's deployment GitHub Action, triple-check it over to make sure you didn't make any typos, then push it to GitHub. The next time changes are committed, GitHub will run your workflow and deployment actions to deploy your WordPress site to Pagely!
As always, if you have any further questions that we weren't able to cover here, reach out to Pagely support at any time.
If there are actions you need performed on the server after a deployment is run, please refer to our guide on running additional scripts after an automatic deployment.