11/25/2021

Aren't the standard actions going too far for you? Write your own one!

#github #node #typescript #github-actions

Motivation

Why do you build something like that? The reason is quite simple: everything that I have to do regularly and is essentially always the same, I automate. Tests run automated, linter checks run automated, the CI pipeline runs automated. So why not automate the screenshots as well? ;)

My Workflow

My Github Action is essentially a small NodeJS app that ships as a Dockerfile and can be found in the Marketplace. It uses Github’s @actions/core package, which makes interacting with the infrastructure a breeze.

NodeJS
@actions/core

Those who have already implemented NodeJS applications will have no problems building their own Github Action. I would like to highlight a few things to make it even easier for others to get started.

You need an action.yaml which describes the action:

name: "Websiteshot" 
description: "Github Action to schedule a new Screenshot Job with Websiteshot." 
branding: 
  icon: "camera" 
  color: "blue" 
runs: 
  using: "docker" 
  image: "Dockerfile"

The associated Dockerfile contains a few labels that are necessary for the Marketplace:

FROM node:slim 
# A bunch of `LABEL` fields for GitHub to index 
LABEL "com.github.actions.name"="Websiteshot" 
LABEL "com.github.actions.description"="Github Action to schedule a new Screenshot Job with Websiteshot." 
LABEL "com.github.actions.icon"="gear" 
LABEL "com.github.actions.color"="blue" 
LABEL "repository"="https://github.com/websiteshot/github-action" 
LABEL "homepage"="https://websiteshot.app" 
LABEL "maintainer"="Adam Urban <[email protected]>" 
# Copy over project files 
COPY . . 
# Install dependencies 
RUN npm install 
# Build Project 
RUN npm run build 
# This is what GitHub will run 
ENTRYPOINT ["node", "/dist/index.js"]

The app itself is quite manageable, because it uses the also existing NodeJS package of websiteshot and creates new jobs with the service:

import { Runner } from "./controller/runner.controller"; 
import { Validation } from "./controller/validation.controller"; 
const core = require("@actions/core"); 

async function run() { 
  try { 
    Validation.checkEnvVars(); 
    const jobId: string = await Runner.run(); 
    core.info(`Created Job with Id: ${jobId}`); 
  } catch (error) { 
    core.setFailed(error.message); 
  } 
} 
run();

In this code snippet you can see how the @actions/core package makes it very easy to end an action with an error or to write a log output.

But now to the workflow itself, which is also used by Websiteshot itself to generate new screenshots. After the CI pipeline has run, the last step is to start the Websiteshot action. You have to set a some environment variables that are used by the action.

name: Publish 
on: [push] 
# ... 
jobs: 
  create-screenshot: 
    runs-on: ubuntu-latest 
    name: "Create Screenshot via Template" 
    steps: 
      - uses: websiteshot/github-action@main 
        env: 
          PROJECT_ID: ${{ secrets.PROJECT_ID }} 
          API_KEY: ${{ secrets.API_KEY }} 
          TEMPLATE_ID: "abcdef-ghi..."

My Workflow

Marketplace
Repository
Eat your own dogfood: used to generate screenshots for documentation of Websiteshot: https://docs.websiteshot.app/

Additional Resources / Info

Github Core NodeJS Package

Disclaimer

While writing this post I noticed that it could be interpreted as an ad for Websiteshot. It’s not meant to be, it’s one of my side projects and I think the description of the action can help others or serve as inspiration to build your own action for your own use case. Of course, it’s also possible to create all the screenshots within a Github action (without using an external service). All you need is a headless browser and you’re ready to go. Have fun!