From 50b509b2e2d8837d38311cca9b8a22b71df65dbf Mon Sep 17 00:00:00 2001 From: Nitjsefnie Date: Thu, 22 Oct 2026 20:25:22 +0200 Subject: [PATCH 1/4] Document that the CLI uses top-level configuration for shared keys 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 Co-Authored-By: GPT-6.1 Sol --- docs/cli/index.md | 3 +++ docs/configuration/index.md | 4 ++++ docs/configuration/jobs.md | 35 +++++++++++++++++++++++++++++++++++ 3 files changed, 42 insertions(+) diff --git a/docs/cli/index.md b/docs/cli/index.md index 027cf4c499..6b5f96f113 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -126,6 +126,9 @@ For the macOS you can also use seamless virtualization via [Lima](https://lima-v ## Commands +See [CLI configuration](/docs/configuration/jobs#cli-configuration) for which +configuration values CLI commands use and which commands read job-level values. + * [build](/docs/cli/build/) * [create-update](/docs/cli/create-update/) * [init](/docs/cli/init/) diff --git a/docs/configuration/index.md b/docs/configuration/index.md index c6dcbfd397..453c30a7f1 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -15,6 +15,10 @@ You should place the file in the root of your upstream repo. Packit accepts thes * `packit.yml` Both Packit Service and Packit CLI use this configuration file. +Ordinary CLI commands use top-level or package-level values for keys shared with +jobs, rather than job-level overrides. See +[CLI configuration and exceptions](/docs/configuration/jobs#cli-configuration) +for the commands that read job-level values. :::tip Writing complex configurations diff --git a/docs/configuration/jobs.md b/docs/configuration/jobs.md index afbf835349..451f25f667 100644 --- a/docs/configuration/jobs.md +++ b/docs/configuration/jobs.md @@ -202,6 +202,41 @@ jobs: In this example, the job `some-job` would override [`specfile_path`](/docs/configuration#specfile_path) to `somewhere/else/package.spec` instead of using `./package.spec`. +### CLI configuration + +:::note + +Job-level values of keys also available at the top level, such as `actions`, +`version_update_mask` and `notifications`, are accepted and validated when the +configuration is loaded. They become part of that job's effective configuration, +following the override rules above. Packit Service selects the matching job and +uses its effective configuration. + +Ordinary Packit CLI commands use the package configuration instead: top-level +values, or package-level values when using `packages`. For example, if you set +different `actions` or `version_update_mask` values at the top level and in a job, +the ordinary CLI workflow uses the top-level value. Valid job-level overrides +do not change that workflow. Invalid job-level values can still make loading or +validation fail, even when a valid value would not be used by the CLI. + +The following CLI commands read job-level values: + +* `packit prepare-sources --job-config-index N` selects a job and executes its + `actions`. This is an internal option used by Packit Service. +* The experimental `packit build in-image-builder` selects a `vm_image_build` + job (the first by default, or by index) and reads its image settings. +* `packit propose-downstream` and `packit pull-from-upstream` read the matching + job's `dist_git_branches`. +* `packit build in-copr` reads the first qualifying Copr job's `project` when + no `--project` option is given. +* `packit validate` and `packit config validate` validate job-level values. + Invalid values fail validation; valid values do not change the CLI workflow. + +CLI options, such as `--project` and branch options, take precedence over both +package-level and job-level configuration values. + +::: + ## Supported jobs * Upstream jobs From 351c6c958128b1a8a0dd84db99813617ffa31a4f Mon Sep 17 00:00:00 2001 From: Nitjsefnie Date: Wed, 28 Oct 2026 12:54:16 +0100 Subject: [PATCH 2/4] docs(config): clarify CLI job selection Signed-off-by: Nitjsefnie Co-Authored-By: GPT-6.1 Terra --- docs/configuration/jobs.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/configuration/jobs.md b/docs/configuration/jobs.md index 451f25f667..42b82a5221 100644 --- a/docs/configuration/jobs.md +++ b/docs/configuration/jobs.md @@ -204,8 +204,6 @@ In this example, the job `some-job` would override [`specfile_path`](/docs/confi ### CLI configuration -:::note - Job-level values of keys also available at the top level, such as `actions`, `version_update_mask` and `notifications`, are accepted and validated when the configuration is loaded. They become part of that job's effective configuration, @@ -221,10 +219,14 @@ validation fail, even when a valid value would not be used by the CLI. The following CLI commands read job-level values: -* `packit prepare-sources --job-config-index N` selects a job and executes its - `actions`. This is an internal option used by Packit Service. -* The experimental `packit build in-image-builder` selects a `vm_image_build` - job (the first by default, or by index) and reads its image settings. +* `packit prepare-sources --job-config-index N` uses the effective configuration + of the job at index N (0-based) instead of the package configuration, and + executes its `actions` as needed. With `packages`, the index counts the jobs + associated with each package. This is an internal option used by Packit Service. +* The experimental `packit build in-image-builder` uses the first + `vm_image_build` job by default, or the job at `--job-config-index` (counting + all jobs for the package), which must be a `vm_image_build` job, and reads its + image settings. * `packit propose-downstream` and `packit pull-from-upstream` read the matching job's `dist_git_branches`. * `packit build in-copr` reads the first qualifying Copr job's `project` when @@ -235,8 +237,6 @@ The following CLI commands read job-level values: CLI options, such as `--project` and branch options, take precedence over both package-level and job-level configuration values. -::: - ## Supported jobs * Upstream jobs From a1b5a4cf30b3d78fef18b34263cede7fd91dec76 Mon Sep 17 00:00:00 2001 From: Nitjsefnie Date: Wed, 28 Oct 2026 12:54:32 +0100 Subject: [PATCH 3/4] docs(config): clarify action configuration scope Signed-off-by: Nitjsefnie Co-Authored-By: GPT-6.1 Terra --- docs/configuration/actions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/configuration/actions.md b/docs/configuration/actions.md index 76ab89e5d1..7d9b7f463c 100644 --- a/docs/configuration/actions.md +++ b/docs/configuration/actions.md @@ -40,7 +40,9 @@ e.g. cloning an upstream repo. Like other keys, the `actions` can be defined on the top, package or job level. Be aware that when overriding, the whole `actions` mapping is replaced -instead of merging per action. +instead of merging per action. Job-level `actions` apply to Packit Service jobs; +ordinary CLI commands use the top-level or package-level `actions` (see +[CLI configuration](/docs/configuration/jobs#cli-configuration)). For example, with `actions` defined both at the top level and in a job: From 052834ba92d6c352511f764ad553319f942249c5 Mon Sep 17 00:00:00 2001 From: Nitjsefnie Date: Wed, 28 Oct 2026 13:14:58 +0100 Subject: [PATCH 4/4] docs(config): clarify indexing with multiple triggers Signed-off-by: Nitjsefnie Co-Authored-By: GPT-6.1 Terra --- docs/configuration/jobs.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/configuration/jobs.md b/docs/configuration/jobs.md index 42b82a5221..41e5cb866a 100644 --- a/docs/configuration/jobs.md +++ b/docs/configuration/jobs.md @@ -221,12 +221,13 @@ The following CLI commands read job-level values: * `packit prepare-sources --job-config-index N` uses the effective configuration of the job at index N (0-based) instead of the package configuration, and - executes its `actions` as needed. With `packages`, the index counts the jobs - associated with each package. This is an internal option used by Packit Service. + executes its `actions` as needed. A job with multiple triggers counts once per + trigger; with `packages`, only jobs associated with each package are counted. + This is an internal option used by Packit Service. * The experimental `packit build in-image-builder` uses the first `vm_image_build` job by default, or the job at `--job-config-index` (counting - all jobs for the package), which must be a `vm_image_build` job, and reads its - image settings. + all jobs for the package after expanding multiple triggers), which must be a + `vm_image_build` job, and reads its image settings. * `packit propose-downstream` and `packit pull-from-upstream` read the matching job's `dist_git_branches`. * `packit build in-copr` reads the first qualifying Copr job's `project` when