This repository was archived by the owner on Apr 13, 2026. It is now read-only.
chore: Create and rework docs for topic Security & Trust#731
Merged
morri-son merged 11 commits intoMar 18, 2026
Conversation
✅ Deploy Preview for open-component-model ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
15 tasks
15 tasks
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR adds comprehensive signing and verification documentation including new concept explanations, how-to guides for credential configuration and key generation, and a credential consumer identities reference. It also reorganizes documentation structure through weight adjustments and normalizes file paths from tilde ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (4)
content/docs/how-to/sign-component-version.md (1)
21-24: Inconsistent relref path prefixes.Line 21 uses
"ocm-cli-installation.md"without thedocs/prefix, while lines 22-23 include thedocs/prefix. This inconsistency may cause broken links.🔗 Standardize to full paths
-- [OCM CLI installed]({{< relref "ocm-cli-installation.md" >}}) +- [OCM CLI installed]({{< relref "docs/getting-started/ocm-cli-installation.md" >}})🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/docs/how-to/sign-component-version.md` around lines 21 - 24, Update the inconsistent relref in the checklist so all links use the same path style: change the first entry referencing "ocm-cli-installation.md" to include the "docs/" prefix to match the other two links (so the three relref targets become "docs/ocm-cli-installation.md", "docs/how-to/generate-signing-keys.md", and "docs/how-to/configure-signing-credentials.md"); ensure the visual text labels remain unchanged and verify links render correctly after the change.content/docs/how-to/verify-component-version.md (2)
17-19: Inconsistent relref path prefixes.Line 17 uses
"ocm-cli-installation.md"without thedocs/prefix, while line 18 uses"docs/how-to/configure-signing-credentials.md"with the prefix. This inconsistency could cause broken links depending on Hugo's configuration.🔗 Standardize relref paths
-- [OCM CLI installed]({{< relref "ocm-cli-installation.md" >}}) +- [OCM CLI installed]({{< relref "docs/getting-started/ocm-cli-installation.md" >}})Standardizing all paths to use the full path from
docs/will make link resolution more predictable.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/docs/how-to/verify-component-version.md` around lines 17 - 19, The relref paths are inconsistent: change the first link target "ocm-cli-installation.md" to the full path "docs/ocm-cli-installation.md" so it matches the other relref ("docs/how-to/configure-signing-credentials.md"); update the relref in the list (the entry referencing OCM CLI) to use the "docs/..." prefix to standardize link resolution across the document.
85-86: Consider using more robust YAML querying.The
grep -A 10 signatures:approach is fragile and may not work correctly if the YAML structure varies.🛠️ Use yq or jq for structured YAML querying
If
yqis available:ocm get cv ./transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | yq '.signatures'Or extract just signature names:
ocm get cv ./transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | yq '.signatures[].name'However, this requires users to have
yqinstalled, so the currentgrepapproach may be intentionally simple for accessibility.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/docs/how-to/verify-component-version.md` around lines 85 - 86, The inline grep usage "ocm get cv ./transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | grep -A 10 signatures:" is fragile; replace it with structured YAML querying using yq or jq to reliably extract the signatures field (for example, query the .signatures node or iterate .signatures[].name) and document both the yq/jq commands as the preferred approach and the simple grep fallback for users without those tools so the README shows a robust and an accessible option.content/docs/tutorials/signing-and-verification.md (1)
223-230: Consider clarifying the tampering test behavior.Lines 226 and 229 include commands that may not behave as documented:
- Line 226:
2>/dev/null || truesuppresses all errors, making it unclear if the resource addition succeeded or failed- The comment says "should fail if the descriptor changed" but the test's behavior depends on whether the resource addition actually modified the component
🧪 Make tampering test more explicit
-# Add a new resource (this changes the component descriptor) -echo "malicious content" > /tmp/evil.txt -ocm add resource ./transport-archive//github.com/acme.org/helloworld:1.0.0 \ - --name evil --type plainText --input-file /tmp/evil.txt 2>/dev/null || true +# Add a new resource to change the component descriptor +echo "tampered content" > /tmp/tampered.txt +if ocm add resource ./transport-archive//github.com/acme.org/helloworld:1.0.0 \ + --name tampered --type plainText --input-file /tmp/tampered.txt; then + echo "✓ Component modified - signature should now be invalid" +else + echo "⚠ Note: Resource addition may have failed, try re-signing if verification still passes" +fi -# Try to verify (should fail if the descriptor changed) -ocm verify cv ./transport-archive//github.com/acme.org/helloworld:1.0.0 +# Verification should now fail because the component changed after signing +if ocm verify cv ./transport-archive//github.com/acme.org/helloworld:1.0.0; then + echo "⚠ Unexpected: Verification passed despite tampering" +else + echo "✓ Expected: Verification failed, tampering detected" +fiHowever, the current simpler approach may be intentional for tutorial readability.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/docs/tutorials/signing-and-verification.md` around lines 223 - 230, The tampering test hides whether the malicious resource was actually added because the `ocm add resource ./transport-archive//github.com/acme.org/helloworld:1.0.0 --name evil --type plainText --input-file /tmp/evil.txt 2>/dev/null || true` command suppresses errors; update the tutorial to run the `ocm add resource` command without redirecting stderr and without `|| true` (or add an explicit check of its exit status and/or inspect the component descriptor after the add) and then keep the `ocm verify cv ./transport-archive//github.com/acme.org/helloworld:1.0.0` step, while also clarifying the comment to say “verify should fail if the component descriptor was actually modified by the previous add” so readers know to ensure the add succeeded before expecting verification to fail.
🤖 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/signing-and-verification-concept.md`:
- Around line 112-123: Update the YAML signature example so the
normalisationAlgorithm key uses jsonNormalisation/v2 (to match
sign-component-version.md) while keeping the signature.algorithm value as
RSASSA-PKCS1-V1_5 (to match CLI defaults); modify the example block's
normalisationAlgorithm and ensure the algorithm field reads RSASSA-PKCS1-V1_5
(or add a brief note in the surrounding text if you intend to demonstrate legacy
v1 behavior) so keys normalisationAlgorithm and signature.algorithm in the
example are consistent with current guidance.
In `@content/docs/how-to/configure-credentials-ocm-controllers.md`:
- Around line 309-314: The link to `creds-in-ocmconfig.md` in
content/docs/how-to/configure-credentials-ocm-controllers.md is broken; remove
the bullet referencing `[Tutorial: Configure Credentials in .ocmconfig]({{<
relref "creds-in-ocmconfig.md" >}})` or replace it with a correct existing
target (e.g., point to the actual tutorial file if it exists) so that the relref
no longer references the nonexistent `creds-in-ocmconfig.md`; ensure the other
links to `deploy-helm-chart.md` and `ocm-controllers.md` remain unchanged.
- Line 43: The link in
content/docs/how-to/configure-credentials-ocm-controllers.md points to a
non-existent file creds-in-ocmconfig.md; update the relref target to an existing
doc (e.g., configure-credentials-for-controllers.md) or restore the legacy
creds-in-ocmconfig.md into the current docs so the reference resolves; locate
the inline relref string "{{< relref "creds-in-ocmconfig.md" >}}" in the file
and replace it with the correct slug "{{< relref
"configure-credentials-for-controllers.md" >}}" (or the restored filename) and
repeat for any other identical references in the same file.
In `@content/docs/how-to/configure-signing-credentials.md`:
- Around line 200-201: Replace the broken CLI reference links in the table that
point to "/docs/reference/ocm-cli/ocm_sign_component-version.md" and
"/docs/reference/ocm-cli/ocm_verify_component-version.md" by either linking to
the existing how-to pages "sign-component-version.md" and
"verify-component-version.md" (update the relref targets in the two link
entries) or remove the entire CLI Reference table if auto-generated CLI docs
aren't available; update the two link strings in the table row entries so they
reference the correct, existing docs (or delete the two table rows).
In `@content/docs/how-to/generate-signing-keys.md`:
- Around line 104-111: The relref links in the signing docs are inconsistent;
pick one canonical pattern (e.g., use relative filenames like
"configure-signing-credentials.md" for same-folder targets, or use full
content-root paths like "docs/how-to/..." for cross-folder targets), then update
all relref occurrences in content/docs/how-to/generate-signing-keys.md and
related files (e.g., sign-component-version.md, verify-component-version.md,
signing-and-verification-concept.md, signing-and-verification.md) to that single
pattern so every {{< relref "..." >}} uses the same style; search for all relref
usages across signing docs and replace mismatched paths accordingly, keeping
link targets correct for cross-folder references.
In `@content/docs/how-to/sign-component-version.md`:
- Around line 82-92: Update the YAML example under the signatures block so the
signature algorithm name matches OCM docs: replace the current
signature.algorithm value "RSA/PKCS1v15" with a standard name such as
"RSASSA-PKCS1V15" (or "RSASSA-PSS" if you prefer the PSS variant); keep the
surrounding keys (signatures, digest, normalisationAlgorithm, signature, value)
unchanged so only the signature.algorithm token is corrected.
---
Nitpick comments:
In `@content/docs/how-to/sign-component-version.md`:
- Around line 21-24: Update the inconsistent relref in the checklist so all
links use the same path style: change the first entry referencing
"ocm-cli-installation.md" to include the "docs/" prefix to match the other two
links (so the three relref targets become "docs/ocm-cli-installation.md",
"docs/how-to/generate-signing-keys.md", and
"docs/how-to/configure-signing-credentials.md"); ensure the visual text labels
remain unchanged and verify links render correctly after the change.
In `@content/docs/how-to/verify-component-version.md`:
- Around line 17-19: The relref paths are inconsistent: change the first link
target "ocm-cli-installation.md" to the full path "docs/ocm-cli-installation.md"
so it matches the other relref ("docs/how-to/configure-signing-credentials.md");
update the relref in the list (the entry referencing OCM CLI) to use the
"docs/..." prefix to standardize link resolution across the document.
- Around line 85-86: The inline grep usage "ocm get cv
./transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | grep -A 10
signatures:" is fragile; replace it with structured YAML querying using yq or jq
to reliably extract the signatures field (for example, query the .signatures
node or iterate .signatures[].name) and document both the yq/jq commands as the
preferred approach and the simple grep fallback for users without those tools so
the README shows a robust and an accessible option.
In `@content/docs/tutorials/signing-and-verification.md`:
- Around line 223-230: The tampering test hides whether the malicious resource
was actually added because the `ocm add resource
./transport-archive//github.com/acme.org/helloworld:1.0.0 --name evil --type
plainText --input-file /tmp/evil.txt 2>/dev/null || true` command suppresses
errors; update the tutorial to run the `ocm add resource` command without
redirecting stderr and without `|| true` (or add an explicit check of its exit
status and/or inspect the component descriptor after the add) and then keep the
`ocm verify cv ./transport-archive//github.com/acme.org/helloworld:1.0.0` step,
while also clarifying the comment to say “verify should fail if the component
descriptor was actually modified by the previous add” so readers know to ensure
the add succeeded before expecting verification to fail.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 76173674-b4fc-4b40-92d7-f303e43d519b
📒 Files selected for processing (8)
.github/config/wordlist.txtcontent/docs/concepts/signing-and-verification-concept.mdcontent/docs/how-to/configure-credentials-ocm-controllers.mdcontent/docs/how-to/configure-signing-credentials.mdcontent/docs/how-to/generate-signing-keys.mdcontent/docs/how-to/sign-component-version.mdcontent/docs/how-to/verify-component-version.mdcontent/docs/tutorials/signing-and-verification.md
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (3)
content/docs/how-to/sign-component-version.md (1)
82-92:⚠️ Potential issue | 🟡 MinorFix algorithm field in YAML example to match OCM documentation.
The example uses
algorithm: RSA/PKCS1v15, but OCM documentation consistently showsRSASSA-PSS(default) orRSASSA-PKCS1V15. Update line 90 to use one of these standard algorithm names.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/docs/how-to/sign-component-version.md` around lines 82 - 92, The YAML example's signature.algorithm value is non-standard; update the signature.algorithm field in the example (under the signatures -> signature mapping) to use a standard OCM algorithm name such as "RSASSA-PSS" (preferred) or "RSASSA-PKCS1V15" instead of "RSA/PKCS1v15" so it matches OCM documentation and other examples.content/docs/how-to/configure-signing-credentials.md (1)
200-201:⚠️ Potential issue | 🟡 MinorFix broken CLI reference links.
The links to CLI reference documentation (
/docs/reference/ocm-cli/ocm_sign_component-version.mdandocm_verify_component-version.md) reference files that do not exist according to past review findings.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/docs/how-to/configure-signing-credentials.md` around lines 200 - 201, The CLI reference links in the table for the commands `ocm sign cv --dry-run` and `ocm verify cv` point to non-existent files (`ocm_sign_component-version.md` and `ocm_verify_component-version.md`); update the relref targets to the correct existing reference pages (or remove/replace with the correct canonical filenames) by editing the table rows containing those commands so the `{{< relref ... >}}` values reference the actual docs filenames for the ocm sign and ocm verify CLI commands (verify the real filenames in the reference directory and use those names in place of `ocm_sign_component-version.md` and `ocm_verify_component-version.md`).content/docs/how-to/configure-credentials-ocm-controllers.md (1)
311-311:⚠️ Potential issue | 🟡 MinorFix broken link references to non-existent file.
The referenced file
creds-in-ocmconfig.mddoes not exist in the current documentation structure according to past review findings. Either restore this file or update the reference to point to an existing file.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/docs/how-to/configure-credentials-ocm-controllers.md` at line 311, The markdown link "[How-To: Configure Credentials for Multiple Registries]({{< relref \"creds-in-ocmconfig.md\" >}})" points to a non-existent file; fix by either restoring the missing creds-in-ocmconfig.md page or updating the relref target to the correct existing doc (e.g., the actual how-to page that covers configuring credentials in .ocmconfig). Locate the exact link string in the file and replace the relref argument with the correct filename (or remove the link and leave plain text) so that the documentation builds without broken references.
🤖 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/configure-credentials-ocm-controllers.md`:
- Around line 311-312: Add the required blank lines around the list item
"[How-To: Configure Credentials for Multiple Registries]({{< relref
"creds-in-ocmconfig.md" >}})" so there is an empty line between that list item
and the following "## Related documentation" heading; specifically ensure there
is a blank line before the "## Related documentation" heading and a blank line
after the list item to satisfy MD022/MD032 lint rules.
In `@content/docs/how-to/verify-component-version.md`:
- Around line 130-131: Several documentation relref links point to non-existent
CLI reference files; update the broken links in the listed markdown files to
point to the correct subdirectory locations. Replace references like
`docs/reference/ocm-cli/ocm_verify_component-version.md` and
`docs/reference/ocm-cli/ocm_get_component-version.md` with the actual paths
`docs/reference/ocm-cli/verify/verify_componentversions.md` and
`docs/reference/ocm-cli/get/get_componentversions.md` respectively across the
affected files (`content/docs/how-to/verify-component-version.md`,
`content/docs/how-to/configure-signing-credentials.md`,
`content/docs/how-to/download-resources-from-component-versions.md`, and
`content/docs/getting-started/create-component-version.md`) so the relref
targets match the real filenames and subdirectories.
---
Duplicate comments:
In `@content/docs/how-to/configure-credentials-ocm-controllers.md`:
- Line 311: The markdown link "[How-To: Configure Credentials for Multiple
Registries]({{< relref \"creds-in-ocmconfig.md\" >}})" points to a non-existent
file; fix by either restoring the missing creds-in-ocmconfig.md page or updating
the relref target to the correct existing doc (e.g., the actual how-to page that
covers configuring credentials in .ocmconfig). Locate the exact link string in
the file and replace the relref argument with the correct filename (or remove
the link and leave plain text) so that the documentation builds without broken
references.
In `@content/docs/how-to/configure-signing-credentials.md`:
- Around line 200-201: The CLI reference links in the table for the commands
`ocm sign cv --dry-run` and `ocm verify cv` point to non-existent files
(`ocm_sign_component-version.md` and `ocm_verify_component-version.md`); update
the relref targets to the correct existing reference pages (or remove/replace
with the correct canonical filenames) by editing the table rows containing those
commands so the `{{< relref ... >}}` values reference the actual docs filenames
for the ocm sign and ocm verify CLI commands (verify the real filenames in the
reference directory and use those names in place of
`ocm_sign_component-version.md` and `ocm_verify_component-version.md`).
In `@content/docs/how-to/sign-component-version.md`:
- Around line 82-92: The YAML example's signature.algorithm value is
non-standard; update the signature.algorithm field in the example (under the
signatures -> signature mapping) to use a standard OCM algorithm name such as
"RSASSA-PSS" (preferred) or "RSASSA-PKCS1V15" instead of "RSA/PKCS1v15" so it
matches OCM documentation and other examples.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 38164db3-7c6b-4779-ae40-87873c9e8c09
📒 Files selected for processing (8)
.github/config/wordlist.txtcontent/docs/concepts/signing-and-verification-concept.mdcontent/docs/how-to/configure-credentials-ocm-controllers.mdcontent/docs/how-to/configure-signing-credentials.mdcontent/docs/how-to/generate-signing-keys.mdcontent/docs/how-to/sign-component-version.mdcontent/docs/how-to/verify-component-version.mdcontent/docs/tutorials/signing-and-verification.md
There was a problem hiding this comment.
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/how-to/configure-credentials-ocm-controllers.md`:
- Line 44: In the sentence containing the link "[Configure Credentials for
Multiple Registries]({{< relref "configure-multiple-credentials.md" >}})",
remove the extraneous word "with" so the phrase reads "supports creating this
file." (i.e., change "supports with creating this file." to "supports creating
this file.") to correct the grammar.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 70b7b4a0-cf93-40e8-b123-d34a434eedd9
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (3)
content/docs/how-to/configure-credentials-ocm-controllers.mdcontent/docs/how-to/sign-component-version.mdpackage.json
🚧 Files skipped from review as they are similar to previous changes (1)
- content/docs/how-to/sign-component-version.md
Contributor
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
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/tutorials/signing-and-verification.md`:
- Around line 214-232: Remove the stderr suppression and forced-success in the
tampering test command (remove the `2>/dev/null || true` suffix from the `ocm
add resource ...` invocation) so any failures are visible to the user, and
update the explanatory note after the verification step to be definitive (e.g.,
"Verification will fail because the component descriptor changed and the
signature no longer matches") rather than conditional; locate and update the
commands and note text inside the "Test tampering detection (optional)" step
that contains the `ocm add resource` and `ocm verify cv` lines.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: abf1039a-476b-4436-b668-559ea7ee70fa
📒 Files selected for processing (17)
content/docs/concepts/components.mdcontent/docs/concepts/coordinates.mdcontent/docs/concepts/credential-system.mdcontent/docs/concepts/ocm-controllers.mdcontent/docs/concepts/resolvers.mdcontent/docs/concepts/signing-and-verification-concept.mdcontent/docs/concepts/transfer-concept.mdcontent/docs/how-to/air-gap-transfer.mdcontent/docs/how-to/configure-credentials-ocm-controllers.mdcontent/docs/how-to/configure-multiple-credentials.mdcontent/docs/how-to/configure-signing-credentials.mdcontent/docs/how-to/download-resources-from-component-versions.mdcontent/docs/how-to/legacy-credential-compatibility.mdcontent/docs/how-to/resolve-components-from-multiple-repositories.mdcontent/docs/how-to/sign-component-version.mdcontent/docs/how-to/verify-component-version.mdcontent/docs/tutorials/signing-and-verification.md
✅ Files skipped from review due to trivial changes (6)
- content/docs/concepts/resolvers.md
- content/docs/concepts/transfer-concept.md
- content/docs/concepts/components.md
- content/docs/how-to/legacy-credential-compatibility.md
- content/docs/how-to/resolve-components-from-multiple-repositories.md
- content/docs/how-to/download-resources-from-component-versions.md
🚧 Files skipped from review as they are similar to previous changes (5)
- content/docs/how-to/sign-component-version.md
- content/docs/how-to/configure-signing-credentials.md
- content/docs/how-to/verify-component-version.md
- content/docs/how-to/configure-credentials-ocm-controllers.md
- content/docs/concepts/signing-and-verification-concept.md
Contributor
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
content/docs/tutorials/signing-and-verification.md (1)
296-307: Consider using consistent relref path format within the document.Lines 298-301 use short format (
{{< relref "filename.md" >}}), while lines 305-307 use full path format ({{< relref "docs/path/filename.md" >}}). While both formats are acceptable and work correctly in Hugo, using a consistent style within the same document improves maintainability.♻️ Suggested consistency improvement
Option 1: Use short format throughout (if filenames are unique):
## Related Documentation -- [Concept: Signing and Verification]({{< relref "docs/concepts/signing-and-verification-concept.md" >}}) - Understand the theory behind OCM signing -- [How-to: Generate Signing Keys]({{< relref "docs/how-to/generate-signing-keys.md" >}}) - Detailed key generation guide -- [How-to: Configure Signing Credentials]({{< relref "docs/how-to/configure-signing-credentials.md" >}}) - Multi-environment and advanced configurations +- [Concept: Signing and Verification]({{< relref "signing-and-verification-concept.md" >}}) - Understand the theory behind OCM signing +- [How-to: Generate Signing Keys]({{< relref "generate-signing-keys.md" >}}) - Detailed key generation guide +- [How-to: Configure Signing Credentials]({{< relref "configure-signing-credentials.md" >}}) - Multi-environment and advanced configurationsOption 2: Use full path format throughout:
## Next Steps -- [How-to: Generate Signing Keys]({{< relref "generate-signing-keys.md" >}}) - Step-by-step creating RSA key pairs. -- [How-to: Configure Signing Credentials]({{< relref "configure-signing-credentials.md" >}}) - Set up OCM to use your keys for signing and verification -- [How-to: Sign a Component Version]({{< relref "sign-component-version.md" >}}) - Step-by-step signing instructions -- [How-to: Verify a Component Version]({{< relref "verify-component-version.md" >}}) - Step-by-step verification instructions +- [How-to: Generate Signing Keys]({{< relref "docs/how-to/generate-signing-keys.md" >}}) - Step-by-step creating RSA key pairs. +- [How-to: Configure Signing Credentials]({{< relref "docs/how-to/configure-signing-credentials.md" >}}) - Set up OCM to use your keys for signing and verification +- [How-to: Sign a Component Version]({{< relref "docs/how-to/sign-component-version.md" >}}) - Step-by-step signing instructions +- [How-to: Verify a Component Version]({{< relref "docs/how-to/verify-component-version.md" >}}) - Step-by-step verification instructionsBased on learnings, both relref formats are acceptable in this repository and Hugo resolves unique filenames without a path prefix.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/docs/tutorials/signing-and-verification.md` around lines 296 - 307, The relref links in the "Next Steps" and "Related Documentation" sections are inconsistent: some use short form (e.g., {{< relref "generate-signing-keys.md" >}}) while others use full path form (e.g., {{< relref "docs/how-to/generate-signing-keys.md" >}}); pick one style (prefer the short form if filenames are unique) and update the occurrences for the files referenced—generate-signing-keys.md, configure-signing-credentials.md, sign-component-version.md, verify-component-version.md, and signing-and-verification-concept.md—to use the chosen relref format consistently throughout the document.
🤖 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/signing-and-verification-concept.md`:
- Line 63: Update the default algorithm mention "The default algorithm
(`jsonNormalisation/v4alpha1`)" to match the rest of the docs by replacing
`jsonNormalisation/v4alpha1` with `jsonNormalisation/v2` (or remove the explicit
version to make it generic), ensuring consistency with the recursive reference
and signature storage examples and the examples in sign-component-version.md.
---
Nitpick comments:
In `@content/docs/tutorials/signing-and-verification.md`:
- Around line 296-307: The relref links in the "Next Steps" and "Related
Documentation" sections are inconsistent: some use short form (e.g., {{< relref
"generate-signing-keys.md" >}}) while others use full path form (e.g., {{<
relref "docs/how-to/generate-signing-keys.md" >}}); pick one style (prefer the
short form if filenames are unique) and update the occurrences for the files
referenced—generate-signing-keys.md, configure-signing-credentials.md,
sign-component-version.md, verify-component-version.md, and
signing-and-verification-concept.md—to use the chosen relref format consistently
throughout the document.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6b6715b2-7d5e-4e39-be20-3b4074be8d12
📒 Files selected for processing (3)
content/docs/concepts/signing-and-verification-concept.mdcontent/docs/how-to/generate-signing-keys.mdcontent/docs/tutorials/signing-and-verification.md
🚧 Files skipped from review as they are similar to previous changes (1)
- content/docs/how-to/generate-signing-keys.md
matthiasbruns
left a comment
Contributor
There was a problem hiding this comment.
I still think we should't have an own how-to just to explain how to create keys - but this is your call. Did you test your tutorial/how-tos completely? I will do that now, but I am good with the content as is
frewilhelm
reviewed
Mar 17, 2026
frewilhelm
left a comment
Contributor
There was a problem hiding this comment.
Well done with the How-Tos and Tutorial. Only found some nits!
fabianburth
reviewed
Mar 18, 2026
487a5ec to
ed0b475
Compare
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Co-authored-by: Frederic Wilhelm <fre.wilhelm@gmail.com> Signed-off-by: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
ed0b475 to
7ee41df
Compare
fabianburth
reviewed
Mar 18, 2026
Co-authored-by: Fabian Burth <fabian.burth@sap.com> Signed-off-by: Gerald Morrison <67469729+morri-son@users.noreply.github.com>
jakobmoellerdev
approved these changes
Mar 18, 2026
ocmbot Bot
pushed a commit
that referenced
this pull request
Mar 18, 2026
<!-- markdownlint-disable MD041 --> #### What this PR does / why we need it This PR creates documents across the types concept, how-to and tutorials that explain how the OCM security & trust model works. It contains basically one concept and a tutorial that have been split of the existing tutorial "signing and verification" and several how-to docs that build on that explanatory docs. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added comprehensive signing & verification conceptual docs and practical how‑to guides (key generation, configuring signing/verification credentials, signing component versions, verifying signatures) * Reworked tutorial into a concise end‑to‑end sign/verify workflow with clearer steps and navigation * Minor metadata and wording updates across multiple how‑to and concept pages * Added new glossary/shortcodes entries for improved search/navigation * **Chores** * Updated build dependency (hugo-extended) <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Co-authored-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> Co-authored-by: Matthias Bruns <git@matthiasbruns.com> Co-authored-by: Fabian Burth <fabian.burth@sap.com> 92a14d6
This was referenced Mar 20, 2026
This was referenced Mar 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does / why we need it
This PR creates documents across the types concept, how-to and tutorials that explain how the OCM security & trust model works.
It contains basically one concept and a tutorial that have been split of the existing tutorial "signing and verification" and several how-to docs that build on that explanatory docs.
The PR also touches several other docs, but only their frontmatter to correct the weight of the pages on the site. We'll start with
weight: 1for the first doc in each section.Summary by CodeRabbit
Documentation