Generate PR-review markdown from `kix diff`

This content is for the v0.1 version. Switch to the latest version for up-to-date documentation.

Use Markdown output when a CI job will post the result of kix diff on a pull request. Kix formats the package and resource changes for a Markdown renderer.

This guide assumes the job can reach the target Kubernetes cluster. For an offline comparison, pass a reliable snapshot or previous build as the old side of the diff.

Write the Markdown file

Run the diff against the target cluster and redirect stdout:

Run in kix-examples/

❱ kix diff how-to-application --output markdown Show output

⠁ Fetching live cluster state...                                                Discovering API resources...
Fetching managed resources (60 resource types)...
Fetched 16 resources across 60 resource types
### kix diff

**Plan:** 1 updated, 0 added, 0 removed, 2 unchanged
**Resources:** 1 with real content changes, 4 dep-affected (hash bump only)

#### Changed packages

<details>
<summary><code>how-to-app/production</code> 1.0.0 (1 changed, 4 dep-affected)</summary>

**Modified resources:**

- `ConfigMap/production@how-to-app` (1 diffs)

**Dep-affected (hash bump only, no content change):**

- `Deployment/production@how-to-app`
- `Job/production-health@how-to-app`
- `PackageInstance/production@how-to-app`
- `Service/production@how-to-app`

</details>

**Activation:** `how-to-application-aq1zdgf9gsnb` → `how-to-application-h9nqwqrpw48l`
(exit code: 2)

Redirect it into the file the job will publish:

Run in kix-examples/

❱ kix diff how-to-application --output markdown > kix-diff.md

The file contains GitHub-flavored Markdown suitable for a pull request comment or job summary. Publish it with the integration used by your CI provider.

Preserve the diff exit status

kix diff exits with 2 when it finds changes. Many shells running in CI stop immediately on any non-zero status, which would prevent the Markdown from being published. Capture the status, publish the file, then decide whether differences should fail the job:

set +e
kix diff production --output markdown > kix-diff.md
diff_status=$?
set -e

if [ "$diff_status" -ne 0 ] && [ "$diff_status" -ne 2 ]; then
  exit "$diff_status"
fi

# Publish kix-diff.md here.
exit "$diff_status"

The three outcomes are:

Exit code	Meaning	Suggested CI handling
`0`	No differences	Publish or replace the previous comment, then pass
`2`	Differences found	Publish the review, then fail if approval is required
`1`	Evaluation, cluster access, or another command error	Report the command failure

If expected changes should not fail the pull request, exit 0 after publishing when diff_status is 2. Keep genuine command errors as failures.