Deploying a Jigsaw static site to GitHub Pages using GitHub Actions

jcs224 profile image Joe Sweeney ・2 min read

There are a couple of articles on how to do this already, so I'll put them at the end of this article in case this method doesn't work out for you (and I give them credit as they gave me a starting point and I used some of their code in this article). In the meantime, I want to show you what I believe to be the best and easiest way to deploy your Jigsaw site to GitHub Pages using GitHub Actions after a bit of my own trial and error.

This method assumes that you want to publish one of your personal GitHub projects, or a "project" site. This will probably need to be tweaked for a "user" site, which I don't have any experience with (at least not in GitHub).

It also assumes you've gotten a Jigsaw site that builds properly at least in a local dev environment.


In your repo's GitHub settings, turn on GitHub Pages, using gh-pages as the branch to build from, and / (root) as the folder to build from.

Then, from your repo's root directory, create a new workflow under .github/workflows/main.yml with the following contents:

name: Build & Publish

      - master

    runs-on: ubuntu-latest
    - uses: actions/checkout@v2
    - name: Install Composer Dependencies
      run: composer install --no-ansi --no-interaction --no-scripts --no-suggest --no-progress --prefer-dist
    - name: Install NPM Dependencies
      run: npm install
    - name: Build Site
      run: npm run production
    - name: Stage Files
      run: git add -f build_production
    - name: Commit files
      run: |
        git config --local user.email "actions@github.com"
        git config --local user.name "GitHub Actions"
        git commit -m "Build for deploy"
    - name: Publish
      run: |
        git subtree split --prefix build_production -b gh-pages
        git push -f origin gh-pages:gh-pages
Enter fullscreen mode Exit fullscreen mode

This should literally be everything you need to do. You can test this by manually running the action from the GitHub Action tab, or just commit new code to the master or main branch of your project.

If you're using main, which is possible as GitHub is making it the default for new repos, you'll just need to change anywhere master is referenced to main.

Thanks to James Brooks and Max Kostinevich for your helpful articles getting me even started on the right path and saving me tons of time:



Editor guide
michaelcurrin profile image

Thanks for sharing.

I haven't heard of Jigsaw before and haven't seen the subtree command.

The approach is use for my repos for the commit step is using a popular generic GH Pages action that will work with any given output directory. I covered it in my post here.


I've also seen other workflows which do the commit step themselves like you do.

Also it would be nice for your to explain -f does a force push to overwrite existing changes.

What is the reason for origin gh-pages:gh-pages as origin gh-pages is common and should be sufficient.

jcs224 profile image
Joe Sweeney Author

Cool, I skimmed your article, looks like a straightforward setup! I mostly went the way I did because I didn't know anything about GitHub Actions when starting out and Jigsaw didn't have much guidance other than the articles I mentioned. All I know is it now works the way it should when I push to master.