Github Action: Fork Sync With Upstream

On github:

View action on Github
Follow @aormsby on Github

These days, automation is key to saving time and minimizing errors. But if you’ve never worked with automation, it’s good to start small. This was exactly my thought when I made my first Github Action. It’s available now on the Github Marketplace if you want to try it out - Fork Sync With Upstream. Let’s see what it does!

How It Works

Remember my post on making modifications to a Hugo theme? We forked a theme repository and saw how to make custom modifications to our local version of it. Whenever we wanted to pull updates from the source repo, we ran a bunch of git commands to pull new commits from the upstream repo and then push them to our fork. Syncing with commands like that is all well and good, but let’s save ourselves a little time by automating that process.

The Fork Sync With Upstream action takes care of all those updates for us without any work on our part. At its core, the action is a shell script that runs on a Github server and automatically does the following:

• Checkout your fork (needed for the sync process)
• Set the upstream repo to pull updates from
• Check if there are any new commits to sync (and print the commit information)
• Pull from the upstream repo
• Push to the target branch of the target repo

Just add my action to a Github workflow file in your repo, and voila! All that update work you were doing manually is now automated!

Running the Fork Sync

If you’ve never made a Github workflow before, it’s a little bit confusing to figure out at first. (At least, it all was for me.) I recommend reading some of the Github Actions documentation to get a better feel for how all the pieces work together.

For those looking for a quick sample workflow, here’s the one I’m using in my fork of Hello Friend.

on:
  schedule:
    - cron: '0 7 * * 1,4'
    # scheduled at 07:00 every Monday and Thursday

jobs:
  sync_with_upstream:
    runs-on: ubuntu-latest
    name: Sync master with upstream latest

    steps:
    - name: Checkout master
      uses: actions/checkout@v2
      with:
        ref: master

    - name: Pull upstream changes
      id: sync
      uses: aormsby/Fork-Sync-With-Upstream-action@v1
      with:
        upstream_repository: panr/hugo-theme-hello-friend
        upstream_branch: master

    - name: Timestamp
      run: date

(Actual file at .github/workflows/wf-fork-sync.yaml.)

This may not be the only Action built for syncing with a remote, but it certainly has a better README than many of the other ones I’ve seen! For more details on using input variables and options, visit the official Marketplace page for Fork Sync With Upstream.

Behind The Scenes

Just some extra dev notes if you’re interested. 🙂

Github Actions currently have to be created as Docker container actions or JavaScript actions. I went with JavaScript because it’s more familiar to me, and I don’t need to run this action in any specific Docker-simulated environment.

The action.yaml file declares all the input variables needed for the action and then runs main.js. At the moment, main.js exists only to run the shell script upstream-sync.sh, which is where the sync really happens. This could change in the future.

I used both @actions/core and @actions/exec from the Github Actions Toolkit to simplify the functionality in main.js. The shell script is called by exec, which I think of as an ‘easy’ version of the exec function in node.js. Some of the actions and tools that Github has made are really quite useful.

Anyway, try it out! Let me know how you like it. I’m also planning on turning my shell deploy script into an action, so be on the lookout for that. And if you like my work, please consider buying me a coffee. Cheers!

View action on Github
Follow @aormsby on Github