Skip to content

common.md

Latest commit

 

History

History
315 lines (220 loc) · 8.48 KB

common.md

File metadata and controls

315 lines (220 loc) · 8.48 KB
Raw

Common Workflows

These workflows are ecosystem-agnostic and intended to be reused across any repository. They provide CI hygiene, linting, labeling, change detection, cache maintenance, and release-safety primitives.

Usage Example

jobs:
  spelling:
    uses: EarthmanMuons/reusable-workflows/.github/workflows/check-spelling.yml@main

detect-changed-files.yml

Detects files changed by a pull request (or recent push) using paths-filter and exposes the results as reusable-workflow outputs. This enables conditional execution of downstream jobs without duplicating filter logic.

Required permissions

  • pull-requests: read

Outputs

For each filter name listed below:

  • <filter> is set to 'true' if any changed file matches the filter rules, otherwise 'false'.
  • <filter>_files contains a newline-delimited list of matching files (shell list format as emitted by paths-filter when list-files: shell is enabled).
Filter Meaning
added_or_modified Any file added or modified
css CSS changes
flutter Dart / pubspec / analysis options changes
github_actions Workflow changes under .github/workflows/
html HTML changes
markdown Markdown changes
python Python source changes
rust Rust / Cargo changes
zig Zig / zon changes

Typical usage

jobs:
  detect_changed_files:
    permissions:
      pull-requests: read
    uses: EarthmanMuons/reusable-workflows/.github/workflows/detect-changed-files.yml@main

  check_spelling:
    needs: detect_changed_files
    if: needs.detect_changed_files.outputs.added_or_modified == 'true'
    uses: EarthmanMuons/reusable-workflows/.github/workflows/check-spelling.yml@main
    with:
      files: ${{ needs.detect_changed_files.outputs.added_or_modified_files }}

check-css.yml

Lints CSS files using stylelint. By default, it installs the latest published stylelint, stylelint-config-standard, and stylelint-config-recess-order packages into the runner workspace; callers can pin package versions when they need fixed versions.

Inputs

Name Required Default
files false **/*.css
stylelint_config_recess_order_version false latest
stylelint_config_standard_version false latest
stylelint_version false latest

Typical usage with changed files

jobs:
  detect_changed_files:
    permissions:
      pull-requests: read
    uses: EarthmanMuons/reusable-workflows/.github/workflows/detect-changed-files.yml@main

  check_css:
    needs: detect_changed_files
    if: needs.detect_changed_files.outputs.css == 'true'
    uses: EarthmanMuons/reusable-workflows/.github/workflows/check-css.yml@main
    with:
      files: ${{ needs.detect_changed_files.outputs.css_files }}

check-github-actions.yml

Lints GitHub Actions workflow files using actionlint.

Inputs

Name Required Default
zizmor_persona false regular

zizmor_persona must be regular, pedantic, or auditor.

check-html.yml

Checks HTML formatting using Prettier.

Inputs

Name Required Default
files false **/*.html
prettier_version false latest

Typical usage with changed files

jobs:
  detect_changed_files:
    permissions:
      pull-requests: read
    uses: EarthmanMuons/reusable-workflows/.github/workflows/detect-changed-files.yml@main

  check_html:
    needs: detect_changed_files
    if: needs.detect_changed_files.outputs.html == 'true'
    uses: EarthmanMuons/reusable-workflows/.github/workflows/check-html.yml@main
    with:
      files: ${{ needs.detect_changed_files.outputs.html_files }}

check-markdown.yml

Checks Markdown formatting using Prettier.

Inputs

Name Required Default
files false **/*.md
prettier_version false latest

check-python.yml

Formats and lints Python files using Ruff. Callers can pass a whitespace-delimited list of Python files, or omit files to check the whole repository.

Inputs

Name Required Default
files false .
ruff_version false latest

Typical usage with changed files

jobs:
  detect_changed_files:
    permissions:
      pull-requests: read
    uses: EarthmanMuons/reusable-workflows/.github/workflows/detect-changed-files.yml@main

  check_python:
    needs: detect_changed_files
    if: needs.detect_changed_files.outputs.python == 'true'
    uses: EarthmanMuons/reusable-workflows/.github/workflows/check-python.yml@main
    with:
      files: ${{ needs.detect_changed_files.outputs.python_files }}

check-shell.yml

Formats and lints shell scripts using action-sh-checker.

check-spelling.yml

Detects common misspellings across files using typos.

Inputs

Name Required Default
files false .

label-pull-request.yml

Applies labels to pull requests based on file paths using labeler.

Required permissions

  • pull-requests: write

Recommended trigger

  • pull_request_target

ready-to-merge.yml

Used as a final "gate" job to ensure the overall workflow outcome matches your intent when using needs: and conditional jobs.

GitHub Actions has an edge case where a failure in an upstream job can cause dependent jobs to be skipped, and skipped jobs still appear as successful for the purpose of branch protection unless you explicitly model the failure. This workflow takes the JSON form of the needs context and asserts that every required job is either:

  • success, or
  • skipped (when intentionally conditional)

If any job in the dependency chain is failure or cancelled, this workflow fails, allowing you to use a single required status check ("ready to merge") in branch protection rules.

Inputs

Name Required Default
needs_context true —

needs_context should be set to ${{ toJson(needs) }}.

Typical usage

The caller should depend on all jobs that must be considered for merge, and it should always run:

jobs:
  # ... other jobs ...

  ready_to_merge:
    needs:
      - detect_changed_files
      - check_github_actions
      - check_markdown
      - check_spelling
    if: always()
    uses: EarthmanMuons/reusable-workflows/.github/workflows/ready-to-merge.yml@main
    with:
      needs_context: ${{ toJson(needs) }}

preload-caches-actionlint.yml

Caches the latest actionlint binary in GitHub Actions cache.

flush-caches.yml

Deletes GitHub Actions cache entries for the current branch.

Required permissions

  • actions: write

tag-if-missing.yml

Create and push a missing SemVer tag (via Toolbox Envy scripts).

Inputs

Name Required Default
toolbox_envy_bins true —

The toolbox_envy_bins entries must exist as bin/<name> in Toolbox Envy and may be newline- or comma-separated; invalid names will fail the job.

Required secrets

  • APP_ID
  • APP_PRIVATE_KEY

Authentication

This workflow uses a GitHub App installation token (via APP_ID and APP_PRIVATE_KEY) instead of GITHUB_TOKEN so that any tag push reliably triggers downstream workflows.