Skip to content

Automate HydePHP sites using GitHub Actions and GitHub Pages

Posted by author in the category "Guides"

2024 Update: We now have a custom GitHub Action that makes it even easier to build and deploy HydePHP sites. Check out the HydePHP GitHub Action for more information.


HydePHP is a framework for building static websites. While the most common way to interact with HydePHP is through the command line, you can actually manage an entire site using GitHub.

In this tutorial, we will do the following, right in our browser!

  1. Create a new Hyde project.
  2. Setup a CI/CD pipeline to automatically compile the site.
  3. Deploy the site to GitHub Pages.


Impatient? Here is a link to the workflow we'll be creating:, and here is a live preview:


This guide assumes you are moderately familiar with GitHub and Actions and will not go into detail on the basics. There are links to the GitHub documentation at the end of the article in case you get stuck.

Step 1: Create a new Hyde project

While the traditional way to create a new Hyde project is using composer in the command line, here we'll take advantage of the fact that the Hyde repository acts as a complete template.

To create our project, navigate to On this page, you will see a big green button that says "Use this template".

Let's click it! Tip: You can also use this direct link

Next, fill in the repository details, then press the "Create repository from template" button. This will then create a brand new repository with everything we need to set up our Hyde site!

Having issues? Check out the GitHub documentation for this subject.

Step 2: Setting up the GitHub Actions workflow

There are many ways and methods to use GitHub Actions, I personally like decoupling jobs. So for our workflow, we will use two jobs, one to build the site, and one to deploy it.

We will use workflow artifacts to pass the built data between the jobs. Don't take this as gospel though, you can use any method you like.

From your GitHub repository page, head on over to the Actions tab, and hit the "New workflow" button. On this page, you want to select the "set up a workflow yourself" button. This will create a new workflow file in your repository. Here we'll add the first job, to build the site.

1# This is a basic workflow to help you get started with using HydePHP with GitHub Actions
3name: Build & Deploy
5# Controls when the workflow will run
7 # We only want to run this workflow when changes are pushed to the master/main branch
8 push:
9 branches: [ "master" ]
11 # Allows you to run this workflow manually from the Actions tab
12 workflow_dispatch:
14# A workflow run is made up of one or more jobs that can run sequentially or in parallel
16 # First we need to build the site
17 build:
18 # The type of runner that the job will run on
19 runs-on: ubuntu-latest
21 # Steps represent a sequence of tasks that will be executed as part of the job
22 steps:
23 # Checks-out your repository under $GITHUB_WORKSPACE, so the job can access it
24 - uses: actions/checkout@v4
26 # (optional) Validate the Composer files to catch any errors early on
27 - name: Validate composer.json and composer.lock
28 run: composer validate --strict
30 # (optional) Cache the Composer packages to speed up future builds
31 - name: Cache Composer packages
32 id: composer-cache
33 uses: actions/cache@v4
34 with:
35 path: vendor
36 key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
37 restore-keys: |
38 ${{ runner.os }}-php-
40 # Install the Composer packages
41 - name: Install dependencies
42 run: composer install --prefer-dist --no-progress
44 # Now we can build the site! We do this using the HydeCLI
45 - name: Build the site
46 run: php hyde build --no-interaction
48 # Our site is now compiled into the _site directory, so we'll upload it to an artifact to use in the next job
49 - name: Upload site artifact
50 uses: actions/upload-artifact@v4
51 with:
52 name: site
53 path: _site

Paste the code above into the web editor and commit the changes.

Head on over to the Actions tab, here you'll see a new workflow called "Build & Deploy" which should already be running, otherwise it will start shortly. When it's finished, which for me took just half a minute, click on the run link. This will take you to a page where you will see that an artifact called "site" has been created.

If you want, you can click on the artifact to download the zip file to your computer. Open it up, and you'll see that your site is now built and ready to be deployed!

Step 3: Deploying the site to GitHub Pages

We're almost there! Now we need to deploy the site to GitHub Pages. There are two routes we can go here, we could just upload the compiled site into the docs/ directory, however, I prefer to have it on a dedicated branch, so that's what we will do here, but you can use any method you like.

Preparing the repository

Stuck? See for help.

First, you need to enable the Pages feature on your repository. This is done by going to the repository settings page, and clicking on the "Pages" tab, and selecting the gh-pages branch as your site source.

Don't have a gh-pages branch? I created mine in the web interface by selecting a Jekyll theme on the pages settings tab and then removing the two generated files. This quickly left me with an empty gh-pages branch. If you know a better way to do this using the web editor, please let me know!

Updating the workflow

Now that our repository is ready, we need to update our workflow to upload the site to the new GitHub Pages branch.

Add the following code after the build job in the workflow we made before:

1# Now we can deploy the site to GitHub Pages!
3 runs-on: ubuntu-latest
4 needs: build # Run the build job first, otherwise we won't have anything to deploy
6 steps:
7 - uses: actions/checkout@v4
8 with:
9 ref: 'gh-pages' # Checkout the gh-pages branch
11 # (optional) Remove any old files from the gh-pages branch
12 - name: Empty site directory
13 run: rm -rf *
15 # Download the compiled site into the current directory
16 - name: Download site artifact
17 uses: actions/download-artifact@v4
18 with:
19 name: site
20 path: '.'
22 # Create a .nojekyll file to prevent GitHub from attempting to compile a Jekyll site
23 - name: Create .nojekyll file
24 run: touch .nojekyll
26 # Commit the changes to the gh-pages branch
27 - name: Commit changes
28 uses: EndBug/add-and-commit@v9
29 with:
30 add: '.'
31 message: 'Upload compiled site ${{ github.sha }}'

Now when you commit the changes, the site will be built and uploaded to GitHub Pages.

Congratulations! You've now set up a new site with HydePHP and GitHub Actions. From here on, the opportunities are limitless. Why not try out creating a few new pages? You can also customize your site in the config files.

You can keep managing your site in the cloud using GitHub, or you can clone the repository to take advantage of the powerful realtime compiling and content scaffolding offered by the HydeCLI.

Next steps

If you want to take your CI further, here are some ideas that the DocsCI uses:

  • Hyde already comes with compiled Tailwind CSS for all the built-in templates, however, if you add your own classes, you can always use the pre-installed Laravel Mix feature to compile the assets in the CI build process.

  • Want to enable code syntax highlighting? Hyde has first-party support for, an API service for amazing syntax highlighting. Note that Torchlight requires a (free) API token. You should never store credentials in your GitHub repository. Instead, store the API key in your GitHub Action Secrets and add it to your .env file during the CI build process.

Syntax highlighting by

End of article