Tutorial

Automating Release Notes with Texkit and GitHub Actions

Compose. Compile. Ship.

Multiple terminal windows showing Texkit pipeline runs and GitHub Actions workflow

By Alex Chen | October 24, 2023

The Problem

Manual release notes are a bottleneck.

Every time you ship a new version of your product, you have to manually curate a changelog. This process is prone to human error—features get missed, typos creep in, and the tone varies from release to release. Worse, it creates a disconnect between what your engineering team actually built and what your customers see.

By treating release notes as a first-class artifact in your CI/CD pipeline, you can ensure consistency, accuracy, and speed. Texkit allows you to generate these documents programmatically from your version metadata and commit history.

Architecture

How the pipeline works.

The workflow is straightforward:

Trigger: A GitHub Release is created or a tag is pushed.
Fetch Data: The Action pulls the version number and commit hashes.
Compile: Texkit reads the version data and generates the release notes.
Output: The notes are saved as Markdown (for GitHub) and HTML (for email).

This decouples your documentation generation from your release process, making it fully automated and reproducible.

Architecture diagram showing GitHub Actions triggering Texkit pipeline

Step 1

Define your release notes template.

Create a file named release-notes.txk in your project root. This template defines the structure of your output. We'll use variables to inject the version and a list of changes.

# Release Notes Template
version: {{ version }}
date: {{ date }}

## What's New

{% for change in changes %}
- {{ change.description }}
  {% if change.author %}by {{ change.author }}{% endif %}
{% endfor %}

## Fixes
{% for fix in fixes %}
- {{ fix.description }}
{% endfor %}

Step 2

Structure your version data as JSON.

Texkit needs a source of truth for the version details. Create a release-data.json file. You can generate this automatically in your GitHub Action, but for this tutorial, we'll define it statically to keep the focus on the pipeline.

{
  "version": "2.4.0",
  "date": "2023-10-24",
  "changes": [
    { "description": "Added dark mode support", "author": "Sarah J." },
    { "description": "Improved CLI performance", "author": "Mike T." }
  ],
  "fixes": [
    { "description": "Resolved issue with YAML parsing" }
  ]
}

Step 3

Write the GitHub Actions YAML workflow.

Create .github/workflows/release-notes.yml. This workflow triggers on a tag push and runs the Texkit CLI to compile the template.

name: Generate Release Notes
on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Texkit
        run: npm install -g texkit
      - name: Compile Notes
        run: texkit run --input release-data.json --template release-notes.txk --output release-notes.md

Step 4

Configure output formats.

Often, you need the same data in different formats. Texkit's pipeline model makes this easy. You can add a second render step to output HTML for your email newsletter.

name: Compile Notes
run: |
  texkit run --input release-data.json --template release-notes.txk --output release-notes.md
  texkit run --input release-data.json --template release-notes.txk --output release-notes.html --format html

The HTML output will include the Markdown content wrapped in standard HTML5 boilerplate, ready to be sent via your email service.

Step 5

Test locally before deploying.

Before committing your workflow, test it locally to ensure your template syntax is correct and the data binding works as expected.

$ texkit run --input release-data.json --template release-notes.txk --dry

The --dry flag will render the output to your terminal without saving it to disk, allowing you to verify the formatting immediately.

Gotchas & Tips

Common pitfalls to avoid.

Handle Empty Arrays

Always check if your arrays are empty before looping in your template to avoid rendering empty bullet points.

Version Semantics

Ensure your version tags match the regex in your GitHub Action trigger (e.g., v*.*.*) to prevent accidental runs.

Secrets Management

Never hardcode API keys or tokens. Use GitHub Secrets for any external integrations required by your pipeline.

Conclusion

Ship better documentation, faster.

By integrating Texkit into your GitHub Actions workflow, you eliminate the manual drudgery of writing release notes. You gain a single source of truth for your changelog and the ability to generate multiple formats from a single template.

Explore Integrations