Document run-condition action

Signed-off-by: Nikola Forró <nforro@redhat.com>

Author: nforro

docs/configuration/actions.md

@@ -89,6 +89,13 @@ These apply to the `srpm` command and building in COPR.
 | [hook] | `post-modifications`  | upstream git repo | after all modifications to the spec file and before running rpmbuild command |                                                      |
 |        | `changelog-entry`     | upstream git repo | when adding a new changelog entry to the specfile                     | stdout is used as a changelog entry                  |
 
+
+### Job-level actions
+
+|        | name                  | working directory | when run                                                              | description                                          |
+|--------|-----------------------|-------------------|-----------------------------------------------------------------------|------------------------------------------------------|
+| [hook] | `run-condition`       | upstream git repo | before a job would run                                                | exit code of this action determines if the job will run |
+
 ## Actions details
 
 All actions are executed in a locked-down OpenShift pod. Your commands are
@@ -157,6 +164,34 @@ Our internal API differentiates between the commit title and description, so we
 have an additional requirement on separating the commit title by an empty line.
 You can, of course, provide *just* the commit title.
 
+### `run-condition`
+
+This action only makes sense at a job level and the exit code of the last command executed
+determines if the job will run. If the exit code is non-zero, the job will be skipped.
+If [`clone_repos_before_run_condition`](/docs/configuration/#clone_repos_before_run_condition)
+is `true`, upstream and/or downstream git repos (depending on the job in question and its trigger)
+will be cloned before the action is run.
+
+For example:
+
+```yaml
+jobs:
+  - job: koji_build
+    trigger: commit
+    dist-git-branches:
+        - fedora-all
+    actions:
+      run-condition:
+        # run only if version is not a pre-release
+        - bash -c 'echo $PACKIT_PROJECT_VERSION | grep -Pvq -- "-(alpha|beta|rc)\d*$"'
+```
+
+:::note
+
+The action is currently enabled only for downstream jobs.
+
+:::
+
 #### Debugging
 
 For your own debugging purposes we allow arbitrary output before outputting the
@@ -246,6 +281,12 @@ when syncing upstream release downstream, e.g. `rhbz#123 rhbz#124`
 * `PACKIT_RESOLVED_BUGS` - bugs resolved by the release separated by space, 
   e.g. `rhbz#123 rhbz#124`
 
+### `run-condition`
+
+* `PACKIT_PROJECT_VERSION` — current version of the project
+* `PACKIT_UPSTREAM_REPO` — absolute path to cloned upstream git repo, presence depends on context
+* `PACKIT_DOWNSTREAM_REPO` — absolute path to cloned downstream git repo, presence depends on context
+
 ### Release-synchronization actions
 
 Related to the `propose-downstream` and `pull-from-upstream` jobs.

docs/configuration/index.md

@@ -765,6 +765,12 @@ build job statuses. When set to `false`, while test jobs are waiting for their c
 to finish, their statuses remain in pending state and only build job statuses are updated, for example with
 `SRPM build is in progress...` or `Starting RPM build...`.
 
+#### clone_repos_before_run_condition
+
+(*bool*) When set to `true`, upstream and/or downstream (depending on context) git repos will be cloned
+before any configured `run-condition` action is run. The option has no effect if there is no `run-condition`
+action configured. Defaults to `false`.
+
 #### osh_diff_scan_after_copr_build
 
 (*bool*) Whether to run a differential scan in [OpenScanHub](https://openscanhub.fedoraproject.org/)