docs: add workspace configuration reference with examples for all fields - #843
Open
marcusburghardt wants to merge 4 commits into
Open
docs: add workspace configuration reference with examples for all fields#843marcusburghardt wants to merge 4 commits into
marcusburghardt wants to merge 4 commits into
Conversation
marcusburghardt
added
the
documentation
em-redhat
previously approved these changes
Sep 11, 2026
em-redhat
left a comment
em-redhat
left a comment
Contributor
There was a problem hiding this comment.
PR Review: #843 — docs: add workspace configuration reference with examples for all fields
CI Status
All 28 checks passed. No failures.
Walkthrough
| File | Change | Focus |
|---|---|---|
README.md |
Expand YAML example with complypacks/verification; field table 6→13 fields; cross-references | documentation |
cmd/complyctl/cli/init.go |
Expand emptyConfigTemplate with all config sections (complypacks, variables, verification) | cli-ux |
docs/QUICK_START.md |
Rewrite config skeleton with inline comments; add variable discovery, verification, complypack sections | documentation |
docs/man/complyctl.1 |
Add CONFIGURATION section with full schema reference (generated troff) | documentation |
docs/man/complyctl.md |
Add CONFIGURATION section with full schema reference (pandoc source) | documentation |
Linked Issues
| Issue | Title | Criteria |
|---|---|---|
| #712 | Complytime workspace config needs examples for variable replacement | COVERED — ${VAR} expansion semantics documented in all four surfaces; variable discovery via complyctl doctor --verbose documented |
Summary
Comprehensive documentation of the complytime.yaml schema across four surfaces (README, init template, Quick Start, man page). All documented fields, types, validation rules, and behavioral descriptions verified accurate against source code (internal/complytime/config.go structs and validation functions). The ${VAR} expansion scope distinction (targets-only, not workspace variables) directly addresses #712.
Alignment
- No scope drift. All changes are documentation-only. The
init.gotemplate change is inline comments, not behavioral logic. - Spec workflow exemption applies (docs-only PR).
Security
- No issues found. Examples use
${GITHUB_TOKEN}placeholders, not real secrets.
Constitution Compliance
- No issues found. Documentation-only PR is exempt from spec workflow requirement.
Verdict
APPROVE
Well-structured documentation that accurately reflects the implementation. Two minor suggestions noted in inline comments.
This review was generated by /review-pr (AI-assisted).
marcusburghardt
enabled auto-merge
September 11, 2026 13:58
marcusburghardt
disabled auto-merge
September 11, 2026 13:58
Add a comprehensive CONFIGURATION section to the complyctl(1) man page
documenting the complete complytime.yaml schema:
- policies: OCI references with url, id, per-entry verification,
skip_verify fields and auto-derived ID behavior
- complypacks: provider-specific content bundles with evaluator-id
relationship and discovery via `complyctl providers`
- targets: scan target binding with policy references and
provider-specific variables with ${VAR} expansion
- variables: workspace-scoped constants (no env var expansion)
- verification: keyless (issuer/identity) and keyed (public key)
modes, trusted_root for private Sigstore, per-entry overrides,
mutual exclusivity rules
- Complete annotated example showing all sections together
- Note about `complyctl doctor --verbose` for variable discovery
Update FILES entry for complytime.yaml to reference the new section.
Regenerate complyctl.1 via pandoc.
Ref: complytime#712
Assisted-by: OpenCode (claude-opus-4-6)
Signed-off-by: Marcus Burghardt <maburgha@redhat.com>
…iable discovery
Rewrite the complytime.yaml skeleton in Step 3 with inline comments
explaining where each value comes from (OCI reference format, ID
derivation, evaluator-id matching, ${VAR} expansion).
Add new subsections:
- Discovering target variables: run `complyctl doctor --verbose` to
see required/optional variables and one-of groups; links to
provider-specific configuration docs
- Verification: keyless (Sigstore OIDC) and keyed (cosign public key)
examples, trusted_root for private Sigstore, per-entry overrides
and skip_verify, --skip-verify flag for one-time bypass
- Complypack entry added to the ampel example
Expand the field table with complypacks, verification, and improved
descriptions. Add note about unset ${VAR} causing config errors.
Cross-reference man page CONFIGURATION section.
Ref: complytime#712
Assisted-by: OpenCode (claude-opus-4-6)
Signed-off-by: Marcus Burghardt <maburgha@redhat.com>
README Workspace Configuration section:
- Add complypacks and verification blocks to the YAML example
- Expand field table with complypacks[].url/id, verification.issuer/
identity/key, policies[].verification, policies[].skip_verify
- Add cross-references to QUICK_START.md and man page
- Add note about `complyctl doctor --verbose` for variable discovery
Init empty config template:
- Add commented-out complypacks section with format example
- Add commented-out variables section (workspace-scoped, no expansion)
- Add commented-out verification section showing keyless mode
- Add ${VAR} expansion example in target variables
- Add `complyctl doctor --verbose` hint for variable discovery
- Update reference to docs/QUICK_START.md and man page
Ref: complytime#712
Assisted-by: OpenCode (claude-opus-4-6)
Signed-off-by: Marcus Burghardt <maburgha@redhat.com>
marcusburghardt
force-pushed
the
docs/workspace-config-reference
branch
from
September 11, 2026 14:21
5eaa9d8 to
b180535
Compare
Thanks @em-redhat Co-authored-by: Em <290096679+em-redhat@users.noreply.github.com>
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
3 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.
Summary
Document the complete
complytime.yamlworkspace configuration schema across all user-facing documentation. Users previously had no way to discover verification options, complypack configuration, or target variable requirements without reading Go source code.Fixes #712
Man page (
docs/man/complyctl.md)Add a CONFIGURATION section documenting the full config schema:
policies: OCI references withurl,id, per-entryverification,skip_verifycomplypacks: provider-specific content bundles with evaluator-id relationshiptargets: scan target binding with policy references and ${VAR} expansionvariables: workspace-scoped constants (no env var expansion)verification: keyless (issuer/identity) and keyed (public key) modes,trusted_rootfor private Sigstore, per-entry overrides, mutual exclusivity rulesQuick Start (
docs/QUICK_START.md)complyctl doctor --verbose, one-of groups, provider-specific docs linksskip_verify,--skip-verifyflagcomplypacksandverificationREADME + init template
complypacksandverificationblocksemptyConfigTemplateininit.gowith commented-outcomplypacks,variables,verificationsectionsRef: #712