Skip to content

📖 [Docs]: Standardize separating reusable workflows from their action library#44

Draft
Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
mainfrom
docs/separate-workflow-from-action-library
Draft

📖 [Docs]: Standardize separating reusable workflows from their action library#44
Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
mainfrom
docs/separate-workflow-from-action-library

Conversation

@MariusStorhaug

Copy link
Copy Markdown
Member

What & why

There was no standard for how to split a reusable workflow from the actions
only it consumes. This documents it.

A shared reusable workflow loads only its own file into the caller's run — its
repository is not checked out — so a ./-relative action reference resolves
against the caller's checkout and breaks. A shared reusable workflow must
therefore reference actions by full owner/repo/path@<sha>, which dictates where
those actions have to live.

Changes

  • Coding-Standards/GitHub-Actions.md — new section "Separate a reusable
    workflow from the actions it consumes"
    (right after "Choose an action or a
    reusable workflow"
    ):
    • why a shared reusable workflow ships only its own file, and the contrast that
      a composite action's ./ resolves within its own repo at the same ref
      (the asymmetry that lets a set of actions ship together);
    • the two cross-repo homes — a standalone action repo (consumed on its own)
      vs an action-library repo (a cohesive set built, tested, and released
      together as one package), tied into the
      Repository Segmentation
      shared-lifecycle principle;
    • a pointer bullet added to "Start local; promote when it is reused."

Companion

Companion to AI-Platform/ai-platform#411, which adds the same standard to the
mirrored coding standards (and a matching rule in that repo's
repository-segmentation.md). MSXOrg's Repository-Segmentation.md already
carries the shared-lifecycle principle, so only the coding standard changes here.

Validation

  • markdownlint (repo config) clean.
  • New section and all anchor targets (in-file and the cross-file segmentation
    anchor) verified to resolve.

… library

A shared reusable workflow ships only its own file to the caller, so a co-located ./ action cannot be resolved. Extend the GitHub Actions standard's action-vs-workflow guidance: reference actions from a shared reusable workflow by full owner/repo/path@sha, and house them either in a standalone repo (consumed alone) or a cohesive action-library repo (a set built/tested/released together, one SHA to pin) kept separate from the workflow that stitches them into a process. Ties into the Repository Segmentation shared-lifecycle principle. Companion to AI-Platform/ai-platform PR #411.
@MariusStorhaug Marius Storhaug (MariusStorhaug) added the documentation Improvements or additions to documentation label Jul 14, 2026
…e two lifecycle reasons

Add the job.workflow_* self-checkout escape hatch (and why it is a poor foundation: GHES-unavailable, extra machinery, no independent action version line), plus the two lifecycle reasons a separately versioned action repo beats co-located local actions (development tests the branch; a release cannot pin actions to its own not-yet-existing commit). Companion to AI-Platform/ai-platform PR #411.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant