From 026bfb3332dca173208562f3bea1b3c7deb87c8d Mon Sep 17 00:00:00 2001 From: Nitjsefnie Date: Thu, 16 Jul 2026 21:00:37 +0000 Subject: [PATCH] docs: clarify that job-level actions replace top-level actions as a whole When a job defines its own `actions`, the whole mapping replaces the top-level `actions` instead of merging per action: actions not listed in the job (e.g. `fix-spec-file`, `post-upstream-clone`) are not inherited and do not run. Add a concrete example on the actions page and a cross-reference from the jobs page. Fixes packit/packit.dev#443 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/configuration/actions.md | 28 ++++++++++++++++++++++++++-- docs/configuration/jobs.md | 5 ++++- 2 files changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/configuration/actions.md b/docs/configuration/actions.md index 1e7aca1750..76ab89e5d1 100644 --- a/docs/configuration/actions.md +++ b/docs/configuration/actions.md @@ -39,8 +39,32 @@ e.g. cloning an upstream repo. :::caution Like other keys, the `actions` can be defined on the top, package or job level. -Be aware that when overriding, the whole `action` mapping is replaced -instead of merging. +Be aware that when overriding, the whole `actions` mapping is replaced +instead of merging per action. + +For example, with `actions` defined both at the top level and in a job: + +```yaml +actions: + create-archive: + - "make archive" + fix-spec-file: + - "make fix-spec-file" + post-upstream-clone: + - "make post-upstream-clone" + +jobs: + - job: copr_build + trigger: pull_request + actions: + create-archive: + - "make custom-archive" +``` + +when the `copr_build` job is triggered, only the actions listed in the job are +effective, i.e. just `create-archive` (running the job's own commands). The +top-level `fix-spec-file` and `post-upstream-clone` are **not** inherited and +will **not** run. If you need them, repeat them in the job's `actions` mapping. If you want to reduce duplications, you can use the following YAML syntax to do this: diff --git a/docs/configuration/jobs.md b/docs/configuration/jobs.md index b1bab6976f..afbf835349 100644 --- a/docs/configuration/jobs.md +++ b/docs/configuration/jobs.md @@ -80,7 +80,10 @@ jobs: Do not forget that you can also define common Packit config options at the top level (such as `targets` or `actions`) and only override them when -needed in the `jobs` or `packages` section. +needed in the `jobs` or `packages` section. Note that overriding replaces the +whole value, not individual keys — for `actions` this means a job's `actions` +mapping [replaces the top-level one as a whole](/docs/configuration/actions), +rather than being merged per action. For more complex structures it can be useful to have yaml-anchors that are ignored, in which case you can use the top-level `_` key, for example: