Skip to content

Document that the CLI uses top-level configuration for shared keys - #1181

Merged
mfocko merged 4 commits into
packit:mainfrom
Nitjsefnie-OSC:docs/1083-cli-config-scope
Nov 1, 2026
Merged

mfocko merged 4 commits into
packit:mainfrom
Nitjsefnie-OSC:docs/1083-cli-config-scope

Conversation

@Nitjsefnie

@Nitjsefnie Nitjsefnie commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Documents which configuration values the ordinary Packit CLI uses for keys that exist both at top level and at job level (for example actions or version_update_mask), and which CLI commands do read job-level values.

Related Issues and Pull Requests

Fixes #1083

Changes

  • docs/configuration/jobs.md: new "CLI configuration" section after the job-level override example — job-level values of shared keys are accepted and validated and become part of the job's effective configuration (used by Packit Service), while ordinary CLI commands use the package configuration (top-level, or package-level with packages); enumerates the exceptions (prepare-sources --job-config-index, experimental build in-image-builder, propose-downstream / pull-from-upstream reading the matching job's dist_git_branches, build in-copr reading the qualifying job's project when --project is absent, validate / config validate); notes that invalid job-level values can still fail loading or validation, and that CLI options take precedence.
  • docs/configuration/actions.md: one sentence in the actions caution block pointing CLI readers to the new section.
  • docs/configuration/index.md: qualifies the "Both Packit Service and Packit CLI use this configuration file" statement and links to the new section.
  • docs/cli/index.md: cross-link from the Commands section to the same explanation.

Testing

Docs-only change, checked by the site build (make import + yarn build). Gates that ran, all green on head 22497c097a5c23407d636af35b3ab836dd4178bd: workflow run 40689037979 on the fork (provenance echo names that SHA), upstream Test deployment (run 40689027872), Zuul packit-service/check, and pre-commit.ci. The documented behavior was verified against current packit/packit source: the configuration loader merges job-level shared keys into the job's effective configuration while CLI commands receive the package configuration, with the listed commands consuming job-level values.

Footer

Generated by GLM-5.3-Flash (brief), GPT-6.1 Sol (implementation), GPT-6 Astra (review), GPT-6.1 Terra (implementation), Claude Opus 5.5 (brief)

@centosinfra-prod-github-app

Copy link
Copy Markdown
Contributor

@Nitjsefnie

Copy link
Copy Markdown
Contributor Author

Heads-up: this branch lives in an organization-owned fork, and GitHub doesn't let maintainers push to those. If anything needs changing, just say so here and I'll make the change on this branch right away.

@majamassarini

Copy link
Copy Markdown
Member

/fs-review

@fullsend-ai-review

fullsend-ai-review Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 11:30 AM UTC · Completed 11:40 AM UTC

Commit: 5250e71 · View workflow run →

Runtime: claude · Model: opus → claude-opus-5-5 · Effort: high · Cost: $3.88

@fullsend-ai-review fullsend-ai-review Bot added the risk/low PR risk: low label Oct 28, 2026
@fullsend-ai-review

Copy link
Copy Markdown

<!-- fullsend:risk-assessment -->
Risk Assessment: low (1/5)

Details

Docs-only PR touching 3 Markdown files (+42 lines) from a returning contributor, no protected/security/CI/dependency paths, low churn, and a narrowly scoped linked issue; composite 0.51.13 + 0.31.43 + 0.2*2.00 = 1.39 rounds to 1.

@fullsend-ai-review

Copy link
Copy Markdown

Review

Findings

Low

  • [edge-case] docs/configuration/jobs.md:224 — The text says packit prepare-sources --job-config-index N "selects a job and executes its actions". In packit/packit, get_packit_api (packit/cli/utils.py) replaces the whole package configuration with package_config.jobs[N], so every job-level value is used (specfile_path, release_suffix, files_to_sync, ...), not only actions. With packages configurations the index counts within that package's job list.
    Remediation: Reword, e.g. "selects the N-th job (0-based) and uses that job's effective configuration, including its actions, instead of the package configuration."

  • [edge-case] docs/configuration/jobs.md:227 — "selects a vm_image_build job (the first by default, or by index)" can be read as "the N-th vm_image_build job". --job-config-index actually indexes the whole job list with no type filter, and the selected job must itself be vm_image_build, as the existing docs/cli/build/in-image-builder.md help text says.
    Remediation: e.g. "uses the first vm_image_build job by default, or the job at the given --job-config-index (counting all jobs), which must be a vm_image_build job."

  • [pattern-inconsistency] docs/configuration/jobs.md:207 — The whole body of ### CLI configuration (lines 207–238) sits inside one :::note. Elsewhere in docs/configuration, admonitions under a heading are short callouts followed by plain prose, and the sibling section "Overriding global parameters in jobs" is plain prose. Content that other pages link to reads like an aside.
    Remediation: Write the section as normal prose plus a list. Optionally keep a short :::note only for the key point (ordinary CLI commands do not use job-level overrides).

  • [incomplete-doc] docs/configuration/actions.md:41 — This page is the main reference for actions, the key named in Document that non-job-specific job-level keys are ignored with CLI #1083, and the PR leaves it unchanged. Its caution block says actions can be set at the top, package or job level and shows a job-level override, but it does not say that ordinary CLI commands use the top-level/package-level value, and it does not link to the new section.
    Remediation: Add a sentence in that caution block saying that job-level overrides apply to Packit Service jobs, while ordinary CLI commands use top-level/package-level actions. Link to /docs/configuration/jobs#cli-configuration.


Labels: Documentation-only PR describing how the Packit CLI uses configuration values.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

@fullsend-ai-review fullsend-ai-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review comment for full details.

Comment thread docs/configuration/jobs.md Resolved
Comment thread docs/configuration/jobs.md Resolved
Comment thread docs/configuration/jobs.md Resolved
@fullsend-ai-review fullsend-ai-review Bot added kind/documentation Improvements to docs area/cli Impact on packit's command-line interface area/config Related to the configuration labels Oct 28, 2026
@Nitjsefnie
Nitjsefnie marked this pull request as draft October 28, 2026 12:35
@Nitjsefnie
Nitjsefnie force-pushed the docs/1083-cli-config-scope branch from 5250e71 to 22497c0 Compare October 28, 2026 12:35
@centosinfra-prod-github-app

Copy link
Copy Markdown
Contributor

@Nitjsefnie
Nitjsefnie marked this pull request as ready for review October 28, 2026 12:39
@Nitjsefnie

Copy link
Copy Markdown
Contributor Author

The actions caution block in docs/configuration/actions.md now says job-level actions apply to Packit Service jobs while ordinary CLI commands use the top-level or package-level actions, and links the new CLI configuration section (a744f12). Separately, docs/configuration/index.md says multiple triggers cannot be combined in one job; filed as #1185.

Nitjsefnie and others added 4 commits October 30, 2026 14:34
Explain which configuration ordinary CLI workflows use when shared keys differ between package and job levels. Describe the commands that read job-level values, validation behavior, CLI option precedence, and how Packit Service applies job overrides.

Signed-off-by: Nitjsefnie <zmatek.peter@gmail.com>
Co-Authored-By: GPT-6.1 Sol <noreply@openai.com>
Signed-off-by: Nitjsefnie <zmatek.peter@gmail.com>
Co-Authored-By: GPT-6.1 Terra <noreply@openai.com>
Signed-off-by: Nitjsefnie <zmatek.peter@gmail.com>
Co-Authored-By: GPT-6.1 Terra <noreply@openai.com>
Signed-off-by: Nitjsefnie <zmatek.peter@gmail.com>
Co-Authored-By: GPT-6.1 Terra <noreply@openai.com>
@mfocko
mfocko force-pushed the docs/1083-cli-config-scope branch from 22497c0 to 052834b Compare October 30, 2026 13:34
@centosinfra-prod-github-app

Copy link
Copy Markdown
Contributor

@mfocko
mfocko merged commit b4d449b into packit:main Nov 1, 2026
21 of 22 checks passed
@github-project-automation github-project-automation Bot moved this from New to Done in Packit pull requests Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/cli Impact on packit's command-line interface area/config Related to the configuration kind/documentation Improvements to docs risk/low PR risk: low

Projects

Development

Successfully merging this pull request may close these issues.

Document that non-job-specific job-level keys are ignored with CLI

3 participants