github / github/actions-migrations-via-copilot
Follow-up to #41: cross-pipeline dependency mapping (map only, no conversion)
- Dominant language
- Shell
- Stars
- 74
- Forks
- 17
- Avg merge
- 33m
- Merged PRs (30d)
- 1
Description
### Why
#41 gives us a reliable *per-pipeline* dependency preflight - each run flags the hidden dependencies it can''t fully see. This follow-up adds the *estate-level* view #41 intentionally leaves out: when pipelines depend on each other, **what is the correct order to migrate them?**
**This is about mapping, not conversion.** The goal is to consume #41''s preflight output across many pipelines, build an accurate **cross-pipeline dependency map**, and propose a **leaves-first (bottom-up) migration order**. No file conversion, no fetching, no execution. **It flags and proposes - humans approve.**
### Scope (MVP)
- **Input:** a bundle of #41 preflight reports (one per pipeline), each with a stable machine-readable dependency block. Consumes provided reports only - no remote/cross-repo fetching.
- **Core:** build nodes/edges from cited references ? detect cycles (strongly-connected components) ? topological sort dependencies-first ? export map (JSON + DOT/Mermaid).
- **Output:**
1. a dependency map (machine-readable + visual)
2. a proposed ordered migration plan (Phase 0 shared resources ? shared leaves ? consumers ? orchestrators)
3. an **"unorderable / needs-human"** bucket (cycles, dynamic refs, unresolved externals)
- **Human review gate** before the order is treated as actionable.
### Prior art - candidates to vet (build-vs-reuse) :warning: *needs further vetting*
We should evaluate leaning on existing tooling for the graph/rendering rather than building from scratch. Initial findings:
| Tool | What it offers | Gap for our use |
|---|---|---|
| **Eirmos** (`pip install eirmos`) | Multi-platform CI parser ? Mermaid/Graphviz/DOT, runs locally | Parses source files directly (crosses our no-fetch boundary); visualizes, doesn''t *order* for migration |
| **DepViz** (`moul/depviz`) | Generic GitHub/GitLab dependency graph | Needs a preprocessing script to feed CI edges |
| **Pipeline Visualizer** (VS Code ext.) | In-editor job/stage graphs, many platforms | Single-pipeline; weak cross-pipeline/cross-repo |
| **Graphviz + small topo-sort** (DIY) | Full control over rendering + ordering | We own the extraction/ordering layer |
| Native GitLab graph / Jenkins Blue Ocean | Built-in | Single-pipeline only, no cross-repo |
**Assessment:** none do the migration-specific job end-to-end - they visualize but don''t produce a *bottom-up migration order*, don''t consume #41''s confidence/status semantics, and most parse source directly (crossing #41''s trust boundary). Recommended direction: **reuse a rendering/graph engine (Graphviz/Mermaid, or Eirmos as a parsing reference) and build only the thin layer on top** - consuming #41 reports, cycle?cluster handling, ordered plan, Phase-0 shared-resource bucket, human gate.
### Depends on #41 providing
A stable per-pipeline contract (`schemaVersion: migration-preflight/v1`) per reference: `kind`, `raw`, `status` (known-local / missing-local / external / dynamic / opaque), local target, location, impact, `executionCritical`, `confidence`. Every edge must cite evidence - **no citation, no hard edge.**
### Key design decisions
- **Cycles are output, not errors** - collapse into "migrate-together" clusters; never auto-break.
- **Partial graphs expected** - unresolved externals become explicit placeholder nodes; coverage is a metric, not a failure.
- **Dynamic/runtime refs** (`shared-${BRANCH_NAME}`, `curl | bash`) are low-confidence symbolic edges that don''t silently drive ordering.
- **Shared resources** (runners, secrets, variable groups, service connections) modeled as **Phase 0 prerequisites**, not graph nodes.
### Non-goals
File conversion/migration, recursive/remote resolution, fetching, execution, auto-pruning steps, auto-breaking cycles, guaranteeing runtime equivalence, live GitHub org inventory.
### Open questions
- Canonical pipeline id: `repo/path`, `repo/ref/path`, or platform-native?
- Do low-confidence edges influence ordering or only warn?
- Do cycles block the whole plan or become independent cluster tasks?
- Reuse an existing engine (Eirmos/DepViz/Graphviz) or thin custom build?
Relates to #41.
Contributor guide
Research direction
Start by reading issue #41 and its proposed migration-preflight/v1 contract, then vet the listed graph and rendering candidates against the no-fetch boundary. Define how cited references become nodes and edges, including cycles, unresolved externals, dynamic references, and Phase 0 shared resources. Done means a machine-readable and visual map, a dependencies-first migration plan, an unorderable/needs-human bucket, and a human review gate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- shell
- Domain
- ci-cd, devops, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100