Automating my Storybook deployment with GitHub Actions

Lifted directly from their website, "Storybook provides a sandbox to build UI components in isolation so you can develop hard-to-reach states and edge cases."

Storybook

Storybook is an app that lives inside your app and makes getting a design system built from scratch extremely approachable.

More details on setting up Storybook from Emma's post on the subject.

Documenting React Components With Storybook

Emma Bostian ✨ ・ May 6 '19 ・ 5 min read

#react

My first exposure to Storybook happened when during my time at Netlify as a developer focused on a timely UI refresh. That design system still exists and is maintained on storybook.netlify.com. Since that time, Storybook has grown to be a pillar in my front end development tooling. Establishing a design system keeps my UI flexible for future changes.

The problem to solve

The problem I encounter frequently is setting up an automated way to keep my public design system up to date. In my current project, Open Sauced, I am using Netlify (still a fan) to continuously deploy my site to production when I push changes to my master branch on GitHub.

Despite having continuously deployment for the production site since day one, I have been unable to automate the Storybook page in that same fashion.

At least until GitHub Actions.

GitHub Actions

GitHub Actions was publically launched this year (13th of November) with a goal of making it easy for anyone to automate all software workflows. This feature personally grants me the ability to integrate GitHub focused automation into my developer workflow, which has made approaching this problem more accessible than my previous attempts.

Solution(s)

I first attempted to solve this with just Netlify and their new monorepo feature, but since Storybook uses the same package.json, it did not quite cut it.

Another solution involved me manually bundling my /storybook-static files locally and then pushing that output to a gh-pages branch. This approach worked fine, but it wasn't automated.

One of the many significant parts about GitHub Actions is the ability to share your automated workflows publically through open source and GitHub Marketplace. Because I have been using GitHub Actions during the beta, I was aware of quite a few Actions that automated the deployment of a GitHub page. I found my way to a publically shared Action, JamesIves/github-pages-deploy-action. It watches my build folder (/storybook-static) and deploys that output to the gh-pages branch on my behalf.

GitHub Actions leverages YAML files to host its automation and abstract the interactions with the GitHub API and Webhooks away and gives me the ability to use "Deploy to GitHub Pages" Action.

This solution I came upon has been implemented in my developer workflow, has been running for a few months and help support my project's new UI refresh.

// .github/workflows/storybook.yml

on: 
  push

name: Publish stories if changed

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@master

    - name: Build and deploy to storybook-static branch
      uses: JamesIves/github-pages-deploy-action@2.0.3
      env:
        ACCESS_TOKEN: ${{ secrets.BDOUGIE_TOKEN }}
        BRANCH: storybook-static
        FOLDER: storybook-static
        BUILD_SCRIPT: npm install && npm run build-storybook

Bonus: Limiting deploys to specific paths.

After a few months with this solution, I noticed that the workflow triggers on every push to master, which is not ideal since every change to the project does not include an update to the design system.

I added a filter to check for changes in the stories and components folders. This filter prevents the CI from triggering a storybook deployment if no changes are present.

That change only needed one additional line, which I have below.

on: 
  push:
    paths: ["stories/**", "src/components/**"]

I recently learned from ethomson's Actions advent blog series.

If you are interested in learning how you can build your own GitHub Action from scratch, please check out the Hello, GitHub Actions! course.

You can find this workflow and a few others in the bdougie/open-sauced .github folder.