Setting up the GitHub integration

Benefits of using GitHub

The GitHub integration of Simply Static provides a lot of benefits compared to the classic ZIP and local directory exports:

  • version control (no more backups)
  • deployment on Github Pages, Cloudflare Pages, Vercel, Netlify, FTP, AWS and CDNs
  • automatic push-to-deploy changes from WordPress to your static website

Setup

Go to Simply Static -> Settings -> Deployment and scroll down the page and you will find all necessary settings to configure GitHub deployment in Simply Static:

Setting up the GitHub integration 1

GitHub Account

If you don’t already have an account at GitHub, go and create one at the following link: https://github.com/join

Personal Acess Token

Log in to your GitHub account and click on your profile picture in the right corner of GitHub. A submenu will open, click on “Settings”. Then click on “developer settings” on the left sidebar:

Setting up the GitHub integration 2

Then click on “Personal Access Token” and “Generate new token”:

Setting up the GitHub integration 3

Now we have to configure the scopes that the personal access token is allowed to use.

Simply Static needs the privileges to read and write repositories, delete repositories, and the user settings (to verify actions). I would also recommend activating “Workflows” as this will be integrated into Simply Static in the future to further automate your deployment.

The full configuration should look like that:

Setting up the GitHub integration 4

Click “Generate token” and copy the generated code to add it to Simply Static.

Completing the configuration

Back the Simply Static -> Settings -> Deployment -> GitHub we can add all necessary details to finish the integration.

GitHub User / Organization

Add the name of your GitHub user. In case you are using GitHub as an organization use this account name instead.

GitHub E-Mail

This is the e-mail address of your personal account. This may differ from the one of your organization, so make sure you add the correct e-mail address here.

Personal Access Token

This is the token you generated earlier. Personal Access Tokens are only valid for personal accounts, not for organizations, that’s why you added your personal e-mail address in the field above.

Repository

Add a unique name for your repository. GitHub will tell you if this one already exists or not, so there is not much that can go wrong here.

Visibility of your repository

You can decide if your repository should be public or private. Public repositories can be seen by everyone, private repositories are limited to you and everyone you grant access to.

Name your branch

Simply Static uses “main” as the default branch, but you can modify that. Depending on your static hosting provider you want to configure that. For example, GitHub Pages requires a branch called “gh-pages”.

Webhook URL

We cover that later, but you have the option to ping a Webhook URL once all files/pages are committed to your GitHub repository.

Creating a repository

Save the settings and you should see a new button called “Add repository” – click on it.

Setting up the GitHub integration 5

If your provided details are correct you will see a link next to “Link to your repository” otherwise you get an error message that provides you the solution to your problem.

Here is how it looks like once you added everything correctly:

Setting up the GitHub integration 1

Switch delivery method

One last step to finish the basic configuration of the GitHub deployment in Simply Static is switching the delivery method in Simply Static -> Settings -> General to “GitHub”:

Setting up the GitHub integration 7

GitHub Actions

GitHub Actions are an easy and powerful way to automate your deployment when not using a static hosting provider. There are hundreds of free GitHub Actions you can use to automate the entire process from deployment to code analysis, to messaging in Slack and more, but let’s keep it simple here.

For this introduction, we will be using the following GitHub Action to deploy our static website to your SFTP-Server: https://github.com/SamKirkland/FTP-Deploy-Action

Action Settings

Within your GitHub account, go to the repository of your static website then navigate to Settings -> Actions.

Setting up the GitHub integration 8

You can leave the settings as default or change the permissions of the actions that are allowed to run.

Create workflows

Now head back to your repository and click the button “Add file -> Create new file”.

Setting up the GitHub integration 9

The new file will have the following path:

.github/workflows/main.yml

You will see that GitHub will autocomplete the breadcrumb to make sure you are matching it correctly.

Setting up the GitHub integration 10

Now we can copy and paste the content of the YAML file provided from the SFTP action as seen in the next screenshot. The only thing we need to change here is the SFTP server, the SFTP user, and the SFTP password.

Please do not add your password here directly, we use secrets here (we cover that next). Click “Commit new file” and we can move forward.

Setting up the GitHub integration 11

Secrets

To store sensitive data (like passwords) in your GitHub repository you have to use secrets. In our example, we used a placeholder called:

${{ secrets.ftp_password }} 

Go to your repository then Settings->Secrets and click on “New repository secrets”.

Setting up the GitHub integration 12

Add the placeholder and the value it should be replaced with and click “Add secret”

Setting up the GitHub integration 13

Congrats that’s it for the setup now. An action gets triggered every time you push to your repository.

Monitor Actions

If you like to monitor your actions, you can check the details in the “Actions” tab within your repository. It provides detailed logs, an overview of all running and planned actions, and more:

Setting up the GitHub integration 14

Useful Actions for deployment

SFTP

To deploy to an SFTP server I highly recommend the following action: FTP Deploy Action. To make things a bit easier I created a simple main.yaml file with a subdirectory as this will be the most used case for that deployment method:

on: push
name: 🚀 Deploy website on push
jobs:
  web-deploy:
    name: 🎉 Deploy
    runs-on: ubuntu-latest
    steps:
    - name: 🚚 Get latest code
      uses: actions/checkout@v2
    
    - name: 📂 Sync files
      uses: SamKirkland/FTP-Deploy-Action@4.0.0
      with:
        server: sftp.yourserver.com
        username: youruser
        password: ${{ secrets.ftp_password }}
        server-dir: public_html/www/mysubdirectory

AWS S3

To deploy to AWS S3 I highly recommend the following action: S3 Deploy. To make things a bit easier I created a simple main.yaml from the documentation that you can copy, to begin with:

name: Example workflow for S3 Deploy
on: [push]
jobs:
  run:
    runs-on: ubuntu-latest
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    steps:
        - uses: actions/checkout@v2

        - name: Deploy
          uses: reggionick/s3-deploy@v3
          with:
            folder: build
            bucket: ${{ secrets.S3_BUCKET }}
            bucket-region: ${{ secrets.S3_BUCKET_REGION }}
            dist-id: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }}
            invalidation: /
            delete-removed: true
            no-cache: true
            private: true

Webhooks

The GitHub integration supports executing a webhook after all files are committed to GitHub. This is useful if you are using a static hosting service like Netlify or Cloudflare Pages. Due to the API limitation of GitHub, Simply Static has to commit one file per commit, this can result in a lot of builds when using the push-to-deploy solutions provided by these hosting services. This is where the webhooks come into play.

Cloudflare Pages Builds

To use the webhook integration with Cloudflare Pages you log in to your account, go to Pages and select the project you want to configure.

Within this project, you go to the settings tab and switch to Builds & deployments

Setting up the GitHub integration 15

Scroll down to “Automatic Deployments” and click on “Pause deployments”:

Setting up the GitHub integration 16

Then move to “Deploy Webhooks” and click “Add”, give it a name, and save your settings:

Setting up the GitHub integration 17

You get a Webhook URL that you can copy. Copy that URL and go back to your WordPress website in your admin area navigate to Simply Static -> Settings -> Deployment -> GitHub and paste the URL in the Webhook URL field:

Setting up the GitHub integration 18

Save your settings and you are done. Now Simply Static will trigger a deployment on Cloudflare Pages after all files are committed to GitHub.

Netlify Builds

Log in to your Netlify account and go to your project overview in the tab “Deploys” and click on “Stop auto-publishing”:

Setting up the GitHub integration 19

Then click on the button called “Deploy Settings”. Within Build & deploy -> Continuous Deployment you will find a section called “Build Hooks”. Click on “Add new”, enter a name for the webhook and save:

Setting up the GitHub integration 20

You get a Webhook URL that you can copy. Copy that URL and go back to your WordPress website in your admin area navigate to Simply Static -> Settings -> Deployment -> GitHub and paste the URL in the Webhook URL field:

Setting up the GitHub integration 21

Save your settings and you are done. Now Simply Static will trigger a deployment on Netlify after all files are committed to GitHub.