Reading · André Ruffert's blog

Intro#

I'm going to quickly share a workflow that I use myself for various things to automate content changes in a GitHub repository. I was inspired to share this by a blog post by Andy Bell, where he is looking for a solution to make his life easier when collecting links for The Index newsletter for Piccalilli.

GitHub Actions workflows#

If you're not familiar with GitHub Actions workflows, it's a way to automate tasks throughout the software development lifecycle.

A workflow is a configurable automated process that can run one or multiple jobs. Workflows are defined by a YAML file in the .github/workflows directory checked into your repository. Workflows can get triggered to run by events in your repository, on a defined schedule, or manually.

Creating our workflow#

For our particular use case we will use the workflow_dispatch event to trigger the workflow manually. This allows us to trigger our workflow run with custom-defined input properties, using the GitHub API.

This example defines inputs called url, title, and description. You pass values for these inputs to the workflow when you run it. This workflow then runs our custom script passing the inputs, and commits the changes back to the repository.

.github/workflows/add-hyperlink.yml

YAML

name: "Add hyperlink"

on:
  workflow_dispatch:
    # Configure input properties
    inputs:
      url:
        description: "Link URL"
        type: string
        required: true
      title:
        description: "Link title"
        type: string
        required: true
      description:
        description: "Link description"
        type: string
        required: true

# To commit and push the added or changed files to the repository, 
# we give the standard GITHUB_TOKEN write permissions.
permissions:
  contents: write

jobs:
  process:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - name: Setup node
        uses: actions/[email protected]
        with:
          node-version: 22

      - name: Run custom script
        run: node .github/workflows/scripts/add-hyperlink.mjs --url="${{ inputs.url }}" --title="${{ inputs.title }}" --description="${{ inputs.description }}"

      - name: Commit and push changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: Add hyperlink from Apple shortcuts

Custom script to create/update our content#

The Node.js script run by the workflow creates a new file for each week in the following format 2025-W01.md (full year, week number) and uses the input arguments passed to dynamically define our content to create/append to the file.

The following script is really just a simple example. Since this is a Node.js script, we could do a lot more here. For example, we could call APIs etc.

.github/workflows/scripts/add-hyperlink.mjs

import fs from 'node:fs';
import path from 'node:path';
import { parseArgs } from 'node:util';

const args = parseArgs({
  options: {
    url: {
      type: 'string',
      required: true
    },
    title: {
      type: 'string',
      required: true
    },
    description: {
      type: 'string',
      required: true
    },
  },
});

const now = new Date();
const fileName = `${now.getFullYear()}-W${getWeekNumber(now)}.md`;
const { url, title, description } = args.values;
const filePath = path.join(process.cwd(), `content/${fileName}`);

const newContent = `## [${title}](${url})
${description}

`;

if (!fs.existsSync(filePath)) {
  fs.writeFileSync(filePath, newContent);
} else {
  fs.appendFileSync(filePath, newContent);
}

function getWeekNumber(date = new Date()) {
  const firstDayOfYear = new Date(date.getFullYear(), 0, 1);
  const pastDaysOfYear = (date - firstDayOfYear) / 86400000;
  const weekNumber = Math.ceil((pastDaysOfYear + firstDayOfYear.getDay() + 1) / 7);
  return weekNumber.toString().padStart(2, '0');
}

Running our workflow using the REST API#

Now that we configured our GitHub Actions workflow to run when the workflow_dispatch webhook event occurs we can trigger a run with a API call e.g.:

SHELL

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches \
  -d '{"ref":"main","inputs":{"url":"…","title":"…","description":"…"}}'

More information on creating a workflow dispatch event with the GitHub API.

Further automation#

The ability to trigger our workflow with a simple API call that passes dynamic data gives us a lot of options, such as using the Apple Shortcuts app and other tools for further automation.

A workflow to automate content changes with GitHub Actions