Project Integration: Which Scenario Am I?
This section answers a different question than
Choose Your Workflow. That page picks
a CLI command for one artifact shape you already have on disk right now.
This page picks a project integration lifecycle — how your repository's
CI wires together building, publishing baselines, and gating pull requests
over time, for however many libraries/consumers/plugin contracts your project
ships and however many build profiles it supports.
The underlying model is ADR-047:
a project's ABI/API surface is checked as one or more checks — each an
application of policy to target × profile × baseline channel × evidence
requirement — not as one implicit aggregate report. See
Concepts for the full vocabulary (target, profile, baseline
channel, check, run plan, ...).
Not every scenario below needs a dedicated scenarios/*.md page — where an
existing reference or concept page already answers the question directly,
this index links there instead of duplicating it into a thin wrapper page.
The scenario ID (S-number) is the stable cross-reference either way: it
names a row in
ADR-047 §8's
full catalog, independent of which page currently hosts the answer.
Which Actions building block do I use?
Every scenario below eventually points at one of three composition layers.
They are not a "recommended vs. legacy" ladder — each is the right choice
for a different composition shape. The dependency graph isn't a clean
two-tier "both upper layers built from the primitives below," though:
reusable workflows do call check-target, but check-target itself
internally invokes the root abicheck/abicheck Action (alongside
resolve-baseline/collect-facts as sibling steps) to run the actual
scan/compare — so the root Action sits underneath check-target in the
real call graph, the reverse of a simple bottom-to-top ladder. The practical
answer to "which do I use" doesn't depend on that internal wiring, only on
your own orchestration shape:
| Layer |
What it is |
Reach for it when |
Reference |
| Single-Action step |
The root abicheck/abicheck composite Action — one step you nest inside a job you already have (your own build job, your own checkout). |
You have one target to check and want to add it to an existing job with minimal new CI structure — this is the Quick start path. |
GitHub Action |
| Reusable workflow |
check-single.yml / check-project.yml — a workflow_call job that always runs on its own fresh runner, with its own artifact-staging contract. Internally calls check-target. |
You have several targets/profiles/baseline channels to fan out over (check-project.yml), or you want one isolated check job without hand-composing the primitives yourself (check-single.yml). |
Reusable Workflows |
| Primitive Actions |
actions/check-target, actions/resolve-baseline, actions/baseline, actions/collect-facts — the composable building blocks the reusable workflows are assembled from. check-target itself composes resolve-baseline/collect-facts plus the root single-Action step above for its actual analysis. |
Neither layer above fits your orchestration as-is — e.g. you need resolve-baseline's typed outcome without check-target's report envelope, or a custom job topology around one primitive. |
check-target, resolve-baseline, publish-baseline/update-main-baseline |
check-project.yml's cross-repository artifact-staging convention is newer
and less battle-tested than the single-Action step — see the status note on
Reusable Workflows before committing a
large migration to it.
Getting started
Reusing an existing build
Deeper source/build evidence
Multiple libraries, profiles, or channels
Baselines
Beyond a plain library ABI
Rollout and process
See also
- Concepts — the domain-model glossary (target, profile,
baseline channel, check, run plan, ...) every scenario above is expressed in.
- ADR-047 — the
full design rationale and decision log behind this model.
- Choose Your Workflow — the
CLI-command-level decision guide, for when you already know what you're
comparing and just need the right flags.