docs: clarify that job-level actions replace top-level actions as a whole

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:
 

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: