Issue 7595 - Sync the agent docs with the current CI workflows

[droideck]

Description: The agent docs and skills still described the CI as it was before the queue-relief change:
push-triggered pytest runs, no doc-only path ignores, no web-UI-only PR scoping, no dispatcher and no backport workflow in the workflow table.

The container recipe also lacked the reserved-ports sysctl and the pull retry loop that the workflow has used since issues 7605 and 7528.

Bring building.md, ui.md and the affected skills in line with the workflow files.

Relates: #7528
Relates: #7595
Relates: #7605

Reviewed by: ?

Summary by Sourcery

Align agent guidance and CI documentation with the workflows currently used to build and test the project.

Enhancements:

• Synchronize agent and UI documentation with the current CI triggers, workflow matrix, dispatcher, backport process, and web-UI-only PR behavior.
• Document the container test environment requirements and retry behavior used by CI.

Documentation:

• Update building, UI, and verification skill documentation to reflect current workflow scope, path filtering, test selection, and workflow coverage.

[sourcery-ai]

Hey - I've found 3 issues

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/agents/building.md" line_range="37" />
<code_context>
+- A PR that touches nothing outside `src/cockpit/389-console/` builds the RPMs and then runs only the `webui` suite, on both backends; a renamed file counts under both its paths, and any API failure falls back to the full matrix (`.github/scripts/pr_scope.py`; `.github/workflows/pytest.yml` (Check if the diff is limited to the Web UI step)).
</code_context>
<issue_to_address>
**issue:** The documentation says every UI-only PR runs the `webui` suite, but a UI-only PR whose only changed file is a Markdown file is filtered out by the workflows' `**.md` `paths-ignore` rule and runs no pytest workflow at all.

**Triggers:** When a UI-only PR changes only one or more `*.md` files under `src/cockpit/389-console/`.

**Suggested fix:** Qualify the statement to apply only when the PR contains at least one non-ignored UI file, or document the Markdown path-ignore exception.

```suggestion
- A PR that touches nothing outside `src/cockpit/389-console/` and includes at least one non-ignored UI file builds the RPMs and then runs only the `webui` suite, on both backends; a renamed file counts under both its paths, and any API failure falls back to the full matrix (`.github/scripts/pr_scope.py`; `.github/workflows/pytest.yml` (Check if the diff is limited to the Web UI step)).
```
</issue_to_address>

### Comment 2
<location path="docs/agents/building.md" line_range="36" />
<code_context>
+- A doc-only change runs no GitHub Actions workflow: every push- or PR-triggered workflow above ignores `**.md`, `docs/agents/**`, `docs/design/**`, `LICENSE*`, `.packit.yaml` and `.github/renovate.json`, while `docs/slapi.doxy.in` and the doxygen assets stay CI-visible because `make all` consumes them. Packit's COPR builds, the `rpm-build:*` checks, still run on such a PR because `.packit.yaml` has no path filter (`.github/workflows/pytest.yml` (`paths-ignore`); `.packit.yaml` (`copr_build`)).
</code_context>
<issue_to_address>
**nitpick:** The statement that a doc-only change runs no GitHub Actions workflow is false for a merged doc-only PR carrying a `backport/X.Y` label: `backport.yml` is triggered by `pull_request_target` on `closed` and processes that label regardless of changed paths.

**Triggers:** When a documentation-only PR is merged with a `backport/X.Y` label.

**Suggested fix:** Limit the statement to the build/test workflows, or explicitly mention the conditional backport workflow exception.

```suggestion
- A doc-only change runs no build or test GitHub Actions workflow: every push- or PR-triggered build/test workflow above ignores `**.md`, `docs/agents/**`, `docs/design/**`, `LICENSE*`, `.packit.yaml` and `.github/renovate.json`, while `docs/slapi.doxy.in` and the doxygen assets stay CI-visible because `make all` consumes them. A merged doc-only PR carrying a `backport/X.Y` label is still processed by `backport.yml`, which runs on `pull_request_target` `closed`. Packit's COPR builds, the `rpm-build:*` checks, still run on such a PR because `.packit.yaml` has no path filter (`.github/workflows/pytest.yml` (`paths-ignore`); `.packit.yaml` (`copr_build`)).
```
</issue_to_address>

### Comment 3
<location path=".agents/skills/verify-changes/references/container-recipe.md" line_range="18" />
<code_context>
 *inside* the quay.io/389ds/ci-images:test image as a GitHub Actions container job;
 "BDB Test" drives docker from the runner. Locally one systemd container serves both
-stages; `podman` accepts the same flags wherever `sudo docker` appears.
+stages; `podman` accepts the same flags wherever `sudo docker` appears. CI pulls the
+image first in a five-attempt backoff loop because quay.io pulls time out transiently
+(issue 7528); locally a plain pull is fine.

 ## Stage 1 — start the systemd test container (run from the repo root)
</code_context>
<issue_to_address>
**nitpick:** The recipe claims to document the CI container flow and describes the five-attempt pull backoff, but its executable recipe contains no `docker pull` retry loop; following the recipe still relies on an implicit pull from `docker run`, which fails immediately on a transient quay.io timeout instead of retrying.

**Triggers:** When a developer follows the container recipe during a transient quay.io image-pull timeout.

**Suggested fix:** Add the workflow's character-exact five-attempt `docker pull` loop before the `docker run` command, or clearly state that the loop is intentionally omitted from the local recipe.

```suggestion
    for i in 1 2 3 4 5; do
      sudo docker pull quay.io/389ds/ci-images:test && break
      if [ "$i" -eq 5 ]; then
        echo "Image pull failed after $i attempts"
        exit 1
      fi
      echo "Pull failed, retrying in $((i * 15))s..."
      sleep $((i * 15))
    done
    CID=$(sudo docker run -d -h server.example.com --ulimit core=-1 --cap-add=SYS_PTRACE --privileged --rm --shm-size=4gb --sysctl net.ipv4.ip_local_reserved_ports=38900-39399 -v ${PWD}:/workspace quay.io/389ds/ci-images:test)
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

issue: The documentation says every UI-only PR runs the webui suite, but a UI-only PR whose only changed file is a Markdown file is filtered out by the workflows' **.md paths-ignore rule and runs no pytest workflow at all.

Triggers: When a UI-only PR changes only one or more *.md files under src/cockpit/389-console/.

Suggested fix: Qualify the statement to apply only when the PR contains at least one non-ignored UI file, or document the Markdown path-ignore exception.

Suggested change

	- A PR that touches nothing outside `src/cockpit/389-console/` builds the RPMs and then runs only the `webui` suite, on both backends; a renamed file counts under both its paths, and any API failure falls back to the full matrix (`.github/scripts/pr_scope.py`; `.github/workflows/pytest.yml` (Check if the diff is limited to the Web UI step)).
	- A PR that touches nothing outside `src/cockpit/389-console/` and includes at least one non-ignored UI file builds the RPMs and then runs only the `webui` suite, on both backends; a renamed file counts under both its paths, and any API failure falls back to the full matrix (`.github/scripts/pr_scope.py`; `.github/workflows/pytest.yml` (Check if the diff is limited to the Web UI step)).

[sourcery-ai]

nitpick: The statement that a doc-only change runs no GitHub Actions workflow is false for a merged doc-only PR carrying a backport/X.Y label: backport.yml is triggered by pull_request_target on closed and processes that label regardless of changed paths.

Triggers: When a documentation-only PR is merged with a backport/X.Y label.

Suggested fix: Limit the statement to the build/test workflows, or explicitly mention the conditional backport workflow exception.

Suggested change

- A doc-only change runs no GitHub Actions workflow: every push- or PR-triggered workflow above ignores `**.md`, `docs/agents/**`, `docs/design/**`, `LICENSE*`, `.packit.yaml` and `.github/renovate.json`, while `docs/slapi.doxy.in` and the doxygen assets stay CI-visible because `make all` consumes them. Packit's COPR builds, the `rpm-build:*` checks, still run on such a PR because `.packit.yaml` has no path filter (`.github/workflows/pytest.yml` (`paths-ignore`); `.packit.yaml` (`copr_build`)).

- A doc-only change runs no build or test GitHub Actions workflow: every push- or PR-triggered build/test workflow above ignores `**.md`, `docs/agents/**`, `docs/design/**`, `LICENSE*`, `.packit.yaml` and `.github/renovate.json`, while `docs/slapi.doxy.in` and the doxygen assets stay CI-visible because `make all` consumes them. A merged doc-only PR carrying a `backport/X.Y` label is still processed by `backport.yml`, which runs on `pull_request_target` `closed`. Packit's COPR builds, the `rpm-build:*` checks, still run on such a PR because `.packit.yaml` has no path filter (`.github/workflows/pytest.yml` (`paths-ignore`); `.packit.yaml` (`copr_build`)).

[sourcery-ai]

nitpick: The recipe claims to document the CI container flow and describes the five-attempt pull backoff, but its executable recipe contains no docker pull retry loop; following the recipe still relies on an implicit pull from docker run, which fails immediately on a transient quay.io timeout instead of retrying.

Triggers: When a developer follows the container recipe during a transient quay.io image-pull timeout.

Suggested fix: Add the workflow's character-exact five-attempt docker pull loop before the docker run command, or clearly state that the loop is intentionally omitted from the local recipe.

Suggested change

	CID=$(sudo docker run -d -h server.example.com --ulimit core=-1 --cap-add=SYS_PTRACE --privileged --rm --shm-size=4gb --sysctl net.ipv4.ip_local_reserved_ports=38900-39399 -v ${PWD}:/workspace quay.io/389ds/ci-images:test)
	for i in 1 2 3 4 5; do
	sudo docker pull quay.io/389ds/ci-images:test && break
	if [ "$i" -eq 5 ]; then
	echo "Image pull failed after $i attempts"
	exit 1
	fi
	echo "Pull failed, retrying in $((i * 15))s..."
	sleep $((i * 15))
	done
	CID=$(sudo docker run -d -h server.example.com --ulimit core=-1 --cap-add=SYS_PTRACE --privileged --rm --shm-size=4gb --sysctl net.ipv4.ip_local_reserved_ports=38900-39399 -v ${PWD}:/workspace quay.io/389ds/ci-images:test)

[packit-as-a-service]

Congratulations! One of the builds has completed. 🍾

You can install the built RPMs by following these steps:

• sudo dnf install -y 'dnf*-command(copr)'
• dnf copr enable packit/389ds-389-ds-base-7793
• And now you can install the packages.

Please note that the RPMs should be used only in a testing environment.

[progier389]

LGTM