Skip to content

Add CI workflow to detect extensions missing from documentation index #207

@bexelbie

Description

@bexelbie

Summary

When a new extension is added to release_build_versions.txt (i.e. it becomes part of the automated build and release pipeline), there is no automated check to ensure it also gets a corresponding entry in the documentation at docs/index.md and a dedicated docs/<extension>.md page. This can lead to extensions being built and released but not discoverable via https://flatcar.github.io/sysext-bakery/.

Proposal

Add a GitHub Actions workflow that runs whenever release_build_versions.txt is pushed to main. The workflow would:

  1. Parse the extension names from release_build_versions.txt.
  2. Parse the extension names listed in the table in docs/index.md.
  3. For each extension present in the build list but absent from the docs index, open a GitHub issue — if an open issue for that extension does not already exist.

Issue deduplication

To avoid duplicate issues, each opened issue should use a consistent title pattern (e.g. docs: add documentation for <extension> sysext) and/or a label (e.g. missing-docs). Before opening, the workflow should search for existing open issues matching the extension name and that label.

Issue content

Each opened issue should include:

  • The extension name
  • A note that it was detected as present in release_build_versions.txt but missing from docs/index.md
  • A checklist of what's needed:
    • Add a row to the extensions table in docs/index.md
    • Create docs/<extension>.md with a description, upstream project link, and a Butane configuration snippet
    • Verify the extension's releases are accessible at https://github.com/flatcar/sysext-bakery/releases/tag/<extension>

Scope

This workflow intentionally does not auto-generate documentation or open PRs with draft docs, since each extension's docs page requires human-written content (upstream project description and link, extension-specific configuration notes, and a tested Butane snippet).

The reverse case — an extension removed from release_build_versions.txt that still has docs listing it as "released" — is out of scope for now but could be added later.

Existing gap

For reference, there are extensions today that appear in release_build_versions.txt but are not listed in the docs/index.md table (e.g. btop, tilde). This workflow would have caught those.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions