hugo-linear-sync

A reusable GitHub Action that syncs Hugo content to Linear issues. Add a linearIssueId to your Hugo frontmatter and this action updates the Linear issue description with metadata and transitions it to Done when published.

What it does

• Finds all published (non-draft) Hugo content files
• For each file with a Linear issue ID in frontmatter, updates the Linear issue with:
  • Title, published date, and live URL
  • Description and summary from frontmatter
  • Tags and categories
• Optionally transitions the issue to Done (skips if already completed or canceled)

Quick start

1. Add linearIssueId to your Hugo content frontmatter:

---
title: "My Post"
date: 2025-01-15
linearIssueId: "TEAM-123"
---

2. Create a workflow in your Hugo repo at .github/workflows/linear-sync.yml:

name: Sync to Linear
on:
  push:
    branches: [main]
    paths: ['content/**/*.md']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true

      - uses: ethanolivertroy/hugo-linear-sync@v1
        with:
          linear-api-key: ${{ secrets.LINEAR_API_KEY }}
          site-url: 'https://mysite.com'

3. Add your Linear API key as a repository secret named LINEAR_API_KEY.

Inputs

Input	Required	Default	Description
linear-api-key	Yes	—	Linear API key
site-url	Yes	—	Base URL of your Hugo site (e.g. https://mysite.com)
hugo-version	No	0.154.2	Hugo Extended version to install
transition-to-done	No	true	Auto-transition issues to Done on publish
frontmatter-key	No	linearIssueId	Frontmatter field name containing the Linear issue ID

How state transitions work

When transition-to-done is true (default):

• If the issue is not already in a completed or canceled state, it gets transitioned to the team's Done state
• If the issue is already completed or canceled, only the description is updated

Set transition-to-done: 'false' to only update descriptions without changing issue state.

Linear issue description format

The action updates the Linear issue description with:

# Post Title

**Published**: 2025-01-15

**Live URL**: https://mysite.com/posts/my-post/

## Description
The post description from frontmatter.

## Summary
The post summary from frontmatter.

**Categories**: category1, category2

**Tags**: tag1, tag2

---
*Updated automatically on publish*

License

MIT