feat(docs): add transfer concept and air-gap transfer guide by jakobmoellerdev · Pull Request #744 · open-component-model/ocm-website

jakobmoellerdev · 2026-03-05T17:52:14Z

What this PR does / why we need it

Creates an OCM Transfer Concept and How to for Transferring Components and content through an air-gap

Which issue(s) this PR is related to

fix open-component-model/ocm-project#887 once merged

Type of content

Tutorial (getting-started/ or tutorials/)
How-to Guide (how-to/)
Explanation / Concept (concepts/)
Reference (reference/)
Other (infrastructure, config, fixes)

Checklist

I have read and followed the Contributing Guide
All commands/code snippets are tested and can be copy-pasted

Summary by CodeRabbit

Documentation
- Added a concept guide on Transfer and Transport: transfer model, Common Transport Format (CTF), resource handling (references vs. copies), localization, transfer patterns, signatures across boundaries, example scenarios, diagrams, and related links.
- Added a how‑to for air‑gap transfers: goals, prerequisites, a five‑step CTF workflow, verification and CLI examples, archive handling tips, troubleshooting, cleanup, and expected outcomes.
Chores
- Expanded public wordlist with two additional terms.

netlify · 2026-03-05T17:52:20Z

✅ Deploy Preview for open-component-model ready!

Name	Link
🔨 Latest commit	`e702d2c`
🔍 Latest deploy log	https://app.netlify.com/projects/open-component-model/deploys/69aada68f5d59b000811cd5b
😎 Deploy Preview	https://deploy-preview-744--open-component-model.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai · 2026-03-05T17:52:30Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Added two new documentation pages: a Transfer concept guide explaining the Transfer model and the Common Transport Format (CTF), and an air‑gap how‑to detailing a step‑by‑step workflow to move signed OCM components via CTF archives across isolated networks. Also added two tokens to the repository wordlist.

Changes

Cohort / File(s)	Summary
Transfer concept `content/docs/concepts/transfer-concept.md`	New concept doc describing the Transfer model, Common Transport Format (CTF), resource handling (references vs. copies / `--copy-resources`), localization, transfer patterns, cross‑boundary signatures, a real‑world example, and related links.
Air‑gap how‑to `content/docs/how-to/air-gap-transfer.md`	New how‑to with goals, prerequisites and a five‑step air‑gap workflow: verify source component, export to a CTF archive, move archive across the air gap, import into target registry, and verify; includes CLI examples, archive inspection, troubleshooting, progress/exit‑code notes, and cleanup guidance.
Wordlist `.github/config/wordlist.txt`	Added two new tokens (`auditable`, `hasmermaid`) to the repository wordlist data.

Sequence Diagram(s)

(omitted — changes are documentation and data-only; no new cross-component control flow requiring a sequence diagram)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

morri-son

Poem

🐰 I hop with a CTF tucked tight,
Across the dark and silent night,
Signed and sealed, I bridge the span,
Archives safe within my hand,
A rabbit's cheer for transfer light 🥕✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(docs): add transfer concept and air-gap transfer guide' clearly and specifically summarizes the main changes: two new documentation files (transfer concept and air-gap guide).
Linked Issues check	✅ Passed	The pull request successfully implements all core requirements from issue `#887`: transfer concept document covering mechanics, CTF usage, and repo-to-repo transfer [`#887`]; and air-gap how-to covering prerequisites, CTF creation, offline import, and verification [`#887`].
Out of Scope Changes check	✅ Passed	Changes are within scope: two documentation files directly address issue `#887` objectives. The wordlist update is a necessary supporting change for spell-checking new terminology introduced in the documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

content/docs/concepts/transfer-concept.md (1)

120-120: Optional wording tighten on Line 120.

Consider replacing “completely different environment” with “different environment” for slightly cleaner phrasing.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/concepts/transfer-concept.md` at line 120, Update the sentence
that begins with "Signatures are stored within the component descriptor and
travel with it during transfer." by replacing the phrase "completely different
environment" with "different environment" so it reads "...verify the signature
in a different environment, even across an air gap." Locate this sentence in the
transfer-concept paragraph (the line containing "Signatures are stored within
the component descriptor and travel with it during transfer.") and make the
wording change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/docs/how-to/air-gap-transfer.md`:
- Around line 56-62: Update the ocm transfer cv command example that currently
ends with a plain filesystem path so it uses the standardized CTF target
notation; locate the example for the 'ocm transfer cv' command and replace the
trailing '<path/to/airgap-transport.ctf>' target with the prefixed form
'ctf::<path/to/airgap-transport.ctf>' to match other CTF references in the
document.

---

Nitpick comments:
In `@content/docs/concepts/transfer-concept.md`:
- Line 120: Update the sentence that begins with "Signatures are stored within
the component descriptor and travel with it during transfer." by replacing the
phrase "completely different environment" with "different environment" so it
reads "...verify the signature in a different environment, even across an air
gap." Locate this sentence in the transfer-concept paragraph (the line
containing "Signatures are stored within the component descriptor and travel
with it during transfer.") and make the wording change.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8ef47410-0f77-4910-b833-0cd226498b89

📥 Commits

Reviewing files that changed from the base of the PR and between a7fb3a4 and 54a865b.

📒 Files selected for processing (2)

content/docs/concepts/transfer-concept.md
content/docs/how-to/air-gap-transfer.md

coderabbitai

♻️ Duplicate comments (1)

content/docs/how-to/air-gap-transfer.md (1)
56-62: ⚠️ Potential issue | 🟡 Minor

Standardize CTF target notation in the transfer example.

Line 61 currently uses a plain path while the rest of this guide consistently uses ctf::... for CTF repositories. Keeping one notation avoids ambiguity for readers.
Suggested edit
   ocm transfer cv \
     --copy-resources \
     --recursive \
     <source-repository>//<component-name>:<version> \
-    <path/to/airgap-transport.ctf>
+    ctf::<path/to/airgap-transport.ctf>
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/air-gap-transfer.md` around lines 56 - 62, In the example
for the ocm transfer cv command, standardize the CTF target notation by
replacing the plain path placeholder `<path/to/airgap-transport.ctf>` with the
CTF-repo style `ctf::<path/to/airgap-transport.ctf>` so it matches the rest of
the guide; update the transfer example line that follows `ocm transfer cv` to
use `ctf::...` notation (e.g., `ctf::<airgap-transport.ctf>`).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@content/docs/how-to/air-gap-transfer.md`:
- Around line 56-62: In the example for the ocm transfer cv command, standardize
the CTF target notation by replacing the plain path placeholder
`<path/to/airgap-transport.ctf>` with the CTF-repo style
`ctf::<path/to/airgap-transport.ctf>` so it matches the rest of the guide;
update the transfer example line that follows `ocm transfer cv` to use
`ctf::...` notation (e.g., `ctf::<airgap-transport.ctf>`).

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9debd782-ec2f-4fe5-8798-34a712766b23

📥 Commits

Reviewing files that changed from the base of the PR and between 54a865b and 3947b8d.

📒 Files selected for processing (2)

content/docs/concepts/transfer-concept.md
content/docs/how-to/air-gap-transfer.md

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

content/docs/how-to/air-gap-transfer.md (1)
135-135: Tighten troubleshooting links for CLI scope.

Line 135 can prioritize CLI-relevant guidance first (for example .ocmconfig creds) and keep controller-specific docs as secondary context to reduce path ambiguity for how-to readers.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/air-gap-transfer.md` at line 135, Reorder the
troubleshooting links in the sentence that currently references "Configuring
Credentials for Controllers" then ".ocmconfig" so that CLI-scoped guidance
appears first: reference "Credentials in .ocmconfig" (creds-in-ocmconfig.md)
before "Configuring Credentials for Controllers"
(configure-credentials-for-controllers.md) in the line containing those links to
prioritize CLI-relevant troubleshooting.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/docs/how-to/air-gap-transfer.md`:
- Around line 56-89: The docs show using `ocm transfer cv` without `--type`
(which defaults to directory CTF) but then show `scp`/`cp` commands without
`-r`, which will fail for directory targets; either make the CTF format explicit
by adding `--type ctf` to the `ocm transfer cv` example (so the transport is a
single file) or change the transfer examples under "Move the archive across the
air gap" to use recursive copy (e.g., `scp -r` and `cp -r`) to match the
directory-style CTF produced by `ocm transfer cv`; update references to
`airgap-transport.ctf` in the `ocm get cv`/`ocm download resources` examples if
you change to file CTF to avoid confusion.

---

Nitpick comments:
In `@content/docs/how-to/air-gap-transfer.md`:
- Line 135: Reorder the troubleshooting links in the sentence that currently
references "Configuring Credentials for Controllers" then ".ocmconfig" so that
CLI-scoped guidance appears first: reference "Credentials in .ocmconfig"
(creds-in-ocmconfig.md) before "Configuring Credentials for Controllers"
(configure-credentials-for-controllers.md) in the line containing those links to
prioritize CLI-relevant troubleshooting.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 40e615c0-b21a-47c2-91cf-86ba5e52247c

📥 Commits

Reviewing files that changed from the base of the PR and between 3947b8d and c5936b0.

📒 Files selected for processing (2)

content/docs/concepts/transfer-concept.md
content/docs/how-to/air-gap-transfer.md

matthiasbruns

nice read - nothing to complain, just a question thats up to you

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/docs/concepts/transfer-concept.md`:
- Line 141: The external link anchored as "sovereign conformance scenario"
currently returns 404 and breaks CI; update the markdown text to point to a
stable reachable target (e.g., replace the deep link
https://github.com/open-component-model/conformance/tree/main/scenarios/sovereign
with the repository root https://github.com/open-component-model/conformance or
another confirmed scenario URL) so the link resolves or remove the deep link and
link to the parent repo page instead.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 91df325a-d40e-47a7-b27d-daa525858c64

📥 Commits

Reviewing files that changed from the base of the PR and between c5936b0 and 52bd1b9.

📒 Files selected for processing (3)

.github/config/wordlist.txt
content/docs/concepts/transfer-concept.md
content/docs/how-to/air-gap-transfer.md

🚧 Files skipped from review as they are similar to previous changes (1)

content/docs/how-to/air-gap-transfer.md

coderabbitai

♻️ Duplicate comments (1)

content/docs/concepts/transfer-concept.md (1)

141-141: ⚠️ Potential issue | 🟠 Major

Fix the broken sovereign scenario URL (currently CI-blocking).

The link target at Line 141 still returns 404, which is failing markdown/link checks. Please switch to a reachable interim URL (e.g., repository root) until the scenario path exists.

Suggested patch

-The [sovereign conformance scenario](https://github.com/open-component-model/conformance/tree/main/scenarios/sovereign) demonstrates this complete flow end-to-end. It builds a product as OCM components, signs them, transfers them through a simulated air gap using CTF archives, imports them into an isolated cluster registry, and deploys them using OCM controllers. This scenario validates that signatures, resources, and references survive the entire journey intact.
+The [sovereign conformance scenario](https://github.com/open-component-model/conformance) demonstrates this complete flow end-to-end. It builds a product as OCM components, signs them, transfers them through a simulated air gap using CTF archives, imports them into an isolated cluster registry, and deploys them using OCM controllers. This scenario validates that signatures, resources, and references survive the entire journey intact.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/concepts/transfer-concept.md` at line 141, Update the broken
markdown link target for "sovereign conformance scenario" so it points to a
reachable interim URL (for example the repository root) instead of the current
404 path; locate the markdown anchor text "sovereign conformance scenario" in
the transfer-concept content and replace the href with the working URL to
satisfy link/markdown checks.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@content/docs/concepts/transfer-concept.md`:
- Line 141: Update the broken markdown link target for "sovereign conformance
scenario" so it points to a reachable interim URL (for example the repository
root) instead of the current 404 path; locate the markdown anchor text
"sovereign conformance scenario" in the transfer-concept content and replace the
href with the working URL to satisfy link/markdown checks.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 82fba2af-8be7-4b44-b2f5-afc55dac5096

📥 Commits

Reviewing files that changed from the base of the PR and between 52bd1b9 and b9a65b7.

📒 Files selected for processing (3)

.github/config/wordlist.txt
content/docs/concepts/transfer-concept.md
content/docs/how-to/air-gap-transfer.md

🚧 Files skipped from review as they are similar to previous changes (1)

.github/config/wordlist.txt

Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

morri-son · 2026-03-05T19:43:15Z

Great docs, I'm quite impressed. With regards to the steps in the how-to, I propose that we always use the <steps> even if we just have 2 of them to keep all our guides, gettings started, how-to and tutorials consistent. There's just one (current) downside which really sucks: callouts cannot be rendered correctly inside <steps> and <tabs>. This is nothing to be solved simply, but requires a bit of invest if we want to get this solved. A poor man's approach I took is to use

📣 Note: 📣
Skip this step if you're using a remote Kubernetes cluster.

inside the steps, but this is just a workaround. I would really like to have both, steps and tabs and working callouts, but first just use the steps. WDYT?

Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

#### What this PR does / why we need it Creates an OCM Transfer Concept and How to for Transferring Components and content through an air-gap #### Which issue(s) this PR is related to  fix open-component-model/ocm-project#887 once merged #### Type of content  - [ ] Tutorial (`getting-started/` or `tutorials/`) - [x] How-to Guide (`how-to/`) - [x] Explanation / Concept (`concepts/`) - [ ] Reference (`reference/`) - [ ] Other (infrastructure, config, fixes) #### Checklist - [x] I have read and followed the [Contributing Guide](https://github.com/open-component-model/ocm-website/blob/main/CONTRIBUTING.md) - [x] All commands/code snippets are tested and can be copy-pasted  ## Summary by CodeRabbit * **Documentation** * Added a concept guide on Transfer and Transport: transfer model, Common Transport Format (CTF), resource handling (references vs. copies), localization, transfer patterns, signatures across boundaries, example scenarios, diagrams, and related links. * Added a how‑to for air‑gap transfers: goals, prerequisites, a five‑step CTF workflow, verification and CLI examples, archive handling tips, troubleshooting, cleanup, and expected outcomes. * **Chores** * Expanded public wordlist with two additional terms.  --------- Signed-off-by: Jakob Möller <contact@jakob-moeller.com> cd47f13

jakobmoellerdev requested a review from a team as a code owner March 5, 2026 17:52