Github Action: Fork Sync With Upstream
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. 🙂
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/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!