# Generate PR-review markdown from `kix diff`

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:

<Command expandable {...diffMarkdown} />

Redirect it into the file the job will publish:

<Command commands={["kix diff how-to-application --output markdown > kix-diff.md"]} cwd="kix-examples/" />

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:

```sh title="ci/kix-diff.sh"
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.

:::note[Reference]
See [`kix diff`](/docs/v0.1/reference/cli/diff/) for old-side selection, output
formats, and exit behavior.
:::