REPOSITORY CALLER
Trigger + declared inputs
Events, supported runtime values, environment intent and the minimum permissions granted to the called workflow.
ENGINEERING ARTICLE / DELIVERY ARCHITECTURE
From 1:1 pipelines to
reusable GitHub Actions.
A platform migration should not preserve every duplication simply because the old system made it familiar.
See the architecture- Professional context
- Classic Azure DevOps pipelines were converted during a 30+ repository migration to GitHub.
- Architecture decision
- Move away from one-to-one translations. Establish reusable workflows around common delivery practices.
- Evidence boundary
- No proprietary workflow code or unsupported reduction percentage is presented here.
01 / THE TRANSLATION TRAP
New syntax is not
new architecture.
During the migration from Azure DevOps and TFS to GitHub, the pipelines had to move too. The fastest-looking approach was to translate each classic pipeline into its own GitHub Actions workflow: old pipeline in, equivalent YAML out.
That would have delivered a familiar shape on a new platform. It also would have preserved the one-to-one ratio—and every duplicated convention embedded inside it.
Moving technical debt to a newer platform does not make it less technical debt.
I chose to create reusable workflows and reduce the one-to-one pattern through common practices. The goal was not to make every repository identical. It was to stop asking every repository to independently solve the same delivery problems.
BEFORE / COPIED OWNERSHIP
Each repository carries the delivery mechanism.
REPO A
PIPELINEREPO B
PIPELINEREPO C
PIPELINE
PIPELINEREPO B
PIPELINEREPO C
PIPELINE
Repeated validation, permissions, packaging and evidence behavior drift independently.
AFTER / SHARED CONTRACT
Repositories declare variation; the platform owns the common path.
THIN
CALLER ATHIN
CALLER BTHIN
CALLER C
CALLER ATHIN
CALLER BTHIN
CALLER C
VERSIONED REUSABLE WORKFLOW
Common controls and evidence change in one reviewed boundary.
02 / FIND THE CONTRACT
Standardize the promise,
not every implementation detail.
| Classic-pipeline symptom | Platform question | Reusable boundary |
|---|---|---|
| The same validation is defined repeatedly. | Which checks must every participating repository execute? | Shared validation stages and a consistent required-check contract. |
| Packaging differs mostly by names and paths. | Which values are true variation, and which are copied implementation? | Typed inputs for supported variation; shared packaging and evidence behavior. |
| Deployment credentials are handled in each pipeline. | Can identity and permission boundaries be defined once and constrained per caller? | A shared authentication pattern with explicit caller permissions and environments. |
| Every failure produces different evidence. | What must an operator be able to inspect after any run? | Consistent summaries, artifacts, exit behavior and retention expectations. |
| Exceptions are hidden in copied steps. | Is the difference a real product need or accumulated drift? | A named input, a supported extension point or an explicitly separate workflow. |
03 / REFERENCE ARCHITECTURE
Thin callers.
Strong shared contracts.
A reusable delivery boundary
The repository owns when work runs and supplies approved variation. The shared workflow owns the common delivery mechanism. Its outputs give later promotion work something explicit to consume.
SHARED WORKFLOW
Validation + build + security
The versioned contract executes common checks, produces consistent evidence and exposes deliberate outputs.
CONTROLLED OUTPUT
Artifact + evidence
A traceable result can move into an environment-specific approval, deployment or release process.
GitHub implements this boundary with reusable workflows declared through workflow_call. Inputs and secrets become part of the called workflow’s interface, while the caller invokes the workflow as a job. That mechanism matters; the architecture matters more.
A reusable workflow is useful when it represents a stable contract. A giant YAML file with dozens of switches is merely a different place to hide duplication.
04 / OWNERSHIP BOUNDARY
Centralize the mechanism.
Keep context close to the repository.
Shared workflow owns
- Common quality and security gates
- Supported inputs and their defaults
- Artifact and evidence conventions
- Baseline permissions and authentication pattern
- Failure behavior teams can recognize
Repository caller owns
- Events that should start the workflow
- Application-specific build context
- Approved environment intent
- Real exceptions that do not belong in every consumer
- Adoption of a reviewed workflow version
The boundary is a product decision. If the platform team centralizes application-specific behavior, it becomes a ticket queue. If every repository owns the delivery mechanism, standards decay back into copies. The useful middle is a constrained interface with clear ownership on both sides.
05 / SECURITY AS CONTRACT
Reuse should narrow trust,
not spread it.
Shared automation increases the importance of its trust boundary. Callers should grant explicit permissions rather than treating inherited secrets as a convenience layer. Cross-repository workflow references need deliberate versioning; GitHub identifies a full commit SHA as the safest reference for stability and security.
For cloud access, OpenID Connect is the reference pattern I would favor when the provider and organization support it: the workflow exchanges its GitHub identity for a short-lived cloud token instead of storing a long-lived cloud credential in GitHub. That is an architectural recommendation here, not a claim about the client implementation.
Reusable workflows also do not replace GHAS. CodeQL, secret scanning, dependency security, Dependabot, policy, remediation and developer education remain part of the wider developer platform. The workflow should make those controls consistent without pretending that enabling a scanner completes the security program.
06 / MIGRATION SEQUENCE
Reduce duplication
without hiding risk.
Inventory behavior before translating syntax
Capture triggers, agents, feeds, service connections, artifacts, approvals and dependencies. Unknowns stay visible.
Group pipelines by delivery shape
Find repeated behavior and separate genuine application differences from historical drift.
Design the smallest useful contract
Expose supported variation as deliberate inputs. Keep application-specific work outside the shared core.
Pilot with representative repositories
Choose ordinary and difficult consumers. Compare observable outcomes and preserve a recovery path.
Move repositories to thin callers
Adopt the shared workflow in controlled groups, keeping exceptions explicit rather than forking the entire implementation.
Retire the old path only after acceptance
Confirm required checks, artifacts, permissions, promotion behavior and operator evidence before removing the previous pipeline.
07 / FAILURE MODES
Four ways reuse
turns against you.
The universal-workflow fantasy
One workflow attempts to serve every language, product and deployment model until nobody can reason about it.
Inputs without boundaries
Every exception becomes another switch. The interface grows, combinations multiply and the shared path becomes harder to test.
Convenient inherited privilege
Secrets and permissions spread farther than the contract requires, turning reuse into a larger trust surface.
Unversioned central change
A shared workflow changes beneath every consumer at once. Adoption becomes accidental instead of reviewed.
08 / WHAT THE WORK SUPPORTS
Make the claim
only as large as the evidence.
The professional record supports a clear claim: while converting classic Azure DevOps pipelines to GitHub Actions, I created reusable workflows and moved away from a one-to-one pipeline ratio through common practices.
It does not preserve a defensible count of workflows before and after, a measured maintenance reduction or a quantified change-failure improvement. I will not invent those numbers for a cleaner headline.
LET’S TALK
Bring me the
interesting problems.
I’m looking for Senior DevOps and Platform Engineering opportunities where I can improve cloud delivery, build useful automation and help teams do their best work.
bailey.n.fitchett@gmail.comAPPLY THE APPROACH TO YOUR ENVIRONMENT
Pipeline Divination
Review one pipeline for fragile handoffs, duplicated logic and unclear release contracts.
Separate consulting assessment. The evidence and limitations above remain specific to the original project or demonstration.
Email WitchOps Explore the assessment ↗