/scully-gh-pages-action

Primary LanguageTypeScriptMIT LicenseMIT

Scully Publish

GitHub Action to build and deploy your Scully site to GitHub Pages ❤️🎩

Node Version

As of Angular 12, you will need to explicitly set you Node version since the node12 within Github actions is outdated.

You can set it as your node version using setup-node:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v2
        with:
          node-version: "20"
      - uses: cmgriffing/scully-gh-pages-action@v11
        with:
          access-token: ${{ secrets.ACCESS_TOKEN }}

Usage

This GitHub Action will run npm run build --prod && npm run scully at the root of your repository and deploy it to GitHub Pages for you! Here's a basic workflow example:

name: Scully Publish

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cmgriffing/scully-gh-pages-action@v11
        with:
          access-token: ${{ secrets.ACCESS_TOKEN }}

NOTE: In order to support npm and yarn, this Action relies on having a build script defined in your package.json file. Angular automatically creates one for you when you create a project via Angular CLI.

Knobs & Handles

This Action is fairly simple but it does provide you with a couple of configuration options:

  • access-token: A GitHub Personal Access Token with the repo scope. This is required to push the site to your repo after Scully finishes building it. You should store this as a secret in your repository. Provided as an input.

  • deploy-branch: The branch expected by GitHub to have the static files needed for your site. For org and user pages it should always be master. This is where the output of npm run scully will be pushed to. Provided as an input. Defaults to master.

  • install-args: Additional arguments that get passed to npm ci (e. g. --legacy-peer-deps). Provided as an input. Defaults to nothing.

  • build-args: Additional arguments that get passed to npm run build. See the Angular documentation for a list of allowed options. Provided as an input. Defaults to nothing.

  • scully-args: Additional arguments that get passed to npm run scully. See the Scully documentation for a list of allowed options. Provided as an input. Defaults to nothing.

Org or User Pages

Create a repository with the format <YOUR/ORG USERNAME>.github.io, push your Scully source code to a branch other than master and add this GitHub Action to your workflow! 🚀😃

CNAME

You have a custom domain you would like to use? Fancy! 😎 This Action's got you covered! Assuming you have already set up your DNS provider as defined in the GitHub Pages docs, all we need next is a CNAME file at the root of your project with the domain you would like to use. For example:

example.com

Notice that it's all capitals CNAME 😊.

This is how GitHub keeps track of the domain you want to use. This action will copy the file to the dist/static directory generated by Scully before pushing your site so that the domain is persisted between deploys.

Assumptions

This Action assumes that your Scully code sits at the root of your repository and npm run scully outputs to the dist/static directory.

Additionally, a build script on package.json is expected for this Action to to work (as mentioned at the beginning). Ultimately, this is what builds your Angular assets.

That's It

Have fun building! ✨

Special Thanks

This repo would not have been possible without inspiration and guidance from the fantastic Gatsby-based example here: https://github.com/enriikke/gatsby-gh-pages-action