A Github Action to automatically build and publish blogs on any GitHub event.

WELL. After 3 days of endless headaches, 50+ failed Github action runs, and unnecessary releases I am finally ready to make my submission. This blog is going to be a walk-through of the ideation, process, and working of my project submission and most importantly of all, the lessons learned.

Ideation

I became aware of Hashnode`s API hackathon on Twitter or X :) when i saw someone's post on how they were building their project. I have participated in hackathons before so I was obviously interested. Signed up for a hash node account and registered, it was at least a week and 2 days remaining till submission day.

Anyway me and my procrastination I never got started until 3 days ago. 4 days remaining I thought I had all the time in the world. I started plotting ideas Ἲ8. So what should I build? I had a lot of ideas as always. I had used Graphqueel (in prime's voice) in the past but that was like part of a course i did on Linked in Learning like 2 years ago so i knew the technical debt here was huge.

I didn't have a lot of time so i had to come up with a project that i could complete early enough to test for at least a day.

I even tried asking chatGPT to come up with ideas but the damn thing came up with wild ideas that even it could not implement. Right in the thick of it as i was rereading the hackathon reqs, i realized that in my haste i had not seen that hashnode itself had project ideas right on the site. I quickly chose one that would be most beneficial for me i.e fast to build, and at the end i want to feel like i learnt something even if i don`t win.

I chose A GitHub action that publishes a blog post on every commit because it fitted my criteria. I had copy pasted github actions into my workflows before but i had never really understood how they worked let alone create my own reusable one that would be published on Github marketplace.

Building

To build this i had to learn GraphQL fast. Well i am a fast learner and was not entirely blank on the thing. So i quickly searched GraphQL on youtube and clicked on fireship's 100 seconds OF GraphQL video. That was enough to jog my memory but i needed something longer that would really get me going. I watched Web Dev Simplified's 33 minute video on the same. Well the video was fine but it taught mostly how to build graphql APIs rather than how to consume them. I however had now a better understanding.

After somemore research and playing with the Hashnode API playground i finally felt like i had enough understanding. So i quickly wrote my 'first' query to fetch a publication and run it on my local machine and it worked.

I felt quite nice about myself. I didn't know that the hard part was coming. Remember at this point i didn't know how a github action is to be created. Now i have this open source project i maintain called react daraja my plan was to see if the existing actions could deploy a blog to hashnode on push to a test branch. That was when all hell broke loose. I bundle my project using plugins like changesets and tsup. I don`t push node modules to github..

My Graphquuueel code obviously makes post and Get reqs to the hashnode API. I need axios on runtime. At this point i even had not understood my project yet. Confidence was running low. I Remember before going to bed i had a realization. Im not going to win this if it only works on my one repo. Part of the judgement is obviously the reusability of whatever it is the participants are building.

Creating a reusable github action on Github marketplace

I decided to procrastinate my node modules dilemma. I started researching on how im going to create a reusable action. Read a lot on the github documentation about creating javascript actions. It seemed so easy i quickly spun one up that could make just one request to fetch a publication Id from hashnode.

My code looked something like this in the action.yml file.

//most parts omitted.
runs:
  using: 'node20'
  main: 'index.js'

Now there is a problem with this approach. You guessed it! Node modules. At this point remember i don`t even know that you can self test a github action. I kept compiling one, making a release , pushing it to github marketplace, only for me to test it from another repos action and have it fail. (I ended up doing this something like 25 times.) I'm not kidding you can check out the number of release on the github repo if i have not deleted them out of embarrassment.

Nothing worked brothers. I kept running into all sorts of module not found errors. I remember i kept asking myself. I run pnpm install --frozen-lock-file why tf does it still not find the damn MODULaaaarrr. Jezus.

I later came to find out that pnpm install installs the dependencies of the checked out repo not your stupid action.

Anyway. At some point i even pushed node_modules to github. I felt bad to be honest. Its really easy for me to feel guilty by temparament but i had to do it. I infact still have an open question on github discussions asking how to install modules. Some guy actually says its okay to push node_modules to github but i still feel cringe. actually that approach doesnt work anyway. I kept running into dependencies of dependencies not being available on the pushed node-modules.

I abandoned the idea and decided to research like an engineer and stop taking shortcuts. Turns out there is a composite action which i still don't fully understand but it kind of helps you define steps that will run before executing your action. And you can even define the directory on which the step will run. Damn! Newver have i ever loved a green checkmark more. My action runs for the first time. Orgasms.

So how does it work?

The action helps you write blogs inside a BLOG.md file in your .hashnode folder. Its highly customizable for example by default it willpick up your changelog, readme and publish it alongside your blog . You can be sure to read through the readme im sure it will be included in this blog too. yes im going to publish this blog itself using my action You think im going to create something i myself im not using. Come on.

Well the project is not perfect. Im very sure there are bugs to be caught and errors to be thrown. But well you can`t loose if you gave it your all.

Lessons learnt

• Start early and embrace change. Whatever project you are doing you probably don`t understand it as good as you think.

• Don't give up. I know its been cliched to death but you just cant stop. It will work eventually.

• Keep learning. As a budding software engineer (graduated from campus two months ago). The importance of learning cannot be understated. I learnt a lot. Actually i bet like 67% of my head is aching right now.

• chatGPT is most helpful when you know wtf you are doing. Cant save you if you know nothing. It will actually help you tie your feet and hands together.

• Don't test your work on submission deadline.

The source code of this action can be found on this repo..

THA NEEEIIM - action.YAMOL AGEN.

From here below the action automatically created the blog.

CHANGELOG# release-auto-blogger

0.1.23

README# RELEASE AUTO BLOGGER

A github action to auto publish a blog to your hashnode publication each time you make a change to your repo.

Installation

To use this github action just include it in the uses field of your github action. Here is an example.

name: 'Hashnode Publisher'

on:
  push:
    branches:
      - 'testing-hashnode-blog'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v3

      - name: release-auto-blogger
        uses: amosmachora/release-auto-blogger@v0.1.25
        with:
          project-name: 'React Daraja'
          subtitle: 'Release Blog'
          hashnode-host: amosmachora.hashnode.dev
          cover-image: https://github.com/amosmachora/react-daraja/raw/main/public/full-logo.png
        env:
          HASHNODE_TOKEN: ${{ secrets.HASHNODE_PERSONAL_ACCESS_TOKEN }}

You can then use it however you see fit. When someone creates a pull request, deletes a branch , creates an issue etc.

Pre Requisites

You need your HASHNODE_PERSONAL_ACCESS_TOKEN that you can find by going to https://hashnode.com/settings/developer. set it in your github repo.

Make sure you reference it in your github action like in the example above.

GUIDE

The action works best if you include a file BLOG.md in a folder at the root of your repo called .hashnode. This way you can write your blog right from vscode and have it published on git commit.

However if you don't want to bother yourself you can live it at that. The action will automatically pick up your README.md , your CHANGELOG.md and your RELEASE-NOTES.md.

If you want to opt out of that functionality set the blog-only field to true. This will only publish your BLOG.md file.

If you want to explicitly define the files to be included, include them in a comma separated field called files and they will be used to construct your blog. no spaces

example

  files: 'fileA.md,fileB.md'

There are only 3 required fields. 1. project-name 2. hashnode-host 3. tags the rest are for customization to make look things better and granular.

For tags. Supply at-least one tag in a comma separated string. A valid tag will be used to publish your blog. If no tag is found your blog won`t be published.

  files: 'taga,tagb'

Support

This project is a hackathon submission for the hashnode api hackathon. If you would wish to support me you can star this repo and try generate as much noise as possible around this project.

If you are reading this on hashnode the github url is https://github.com/amosmachora/release-auto-blogger

Tech Stack

Client: GITHUB

Server: Blood, Sweat and Tears.