ci.annotate

The ci.annotate function attaches an error, warning, or notice to a file and line, so it appears inline on the pull request diff. Locally, it prints the same information as a compiler-style line on stderr.

Usage

ci.annotate(level, message, file = "", line = 0, end_line = 0, title = "")

Arguments

level: Required. The severity, as a string: "error", "warning", or "notice". Any other value fails with an argument error.
message: Required. The text of the annotation, as a string.
file: (Optional) The path of the file the annotation belongs to, relative to the repository root. line and end_line need it: passing either without file fails with an argument error.
line: (Optional) The first line the annotation covers, as an integer. The default of 0 means no line.
end_line: (Optional) The last line the annotation covers, as an integer. Use it to highlight a range. It needs line, and it cannot be smaller than line.
title: (Optional) A short heading shown above the message.

Returns

The return value is None.

Behavior

In CI, the annotation appears on the changed line in the pull request diff and in the run's annotation list.
Locally, the call prints path:line: level: message on stderr, and appends the title in parentheses when one is given. Without a line it prints path: level: message, and without a file it prints level: message.
In CI the call is gated by ci.annotations.enabled. When it is off, the call warns, renders locally, and the script continues. See gating and the CI configuration.

Examples

Flag a line in a file

ci.annotate("warning", "This image tag is not pinned", file = "stacks/prod.yaml", line = 14, title = "Unpinned image")

Locally this prints stacks/prod.yaml:14: warning: This image tag is not pinned (Unpinned image).

Report each finding from a check

findings = json.decode(exec.run(["tflint", "--format=json"], check = False, output = "capture").stdout)
for issue in findings["issues"]:
    ci.annotate(
        "error",
        issue["message"],
        file = issue["range"]["filename"],
        line = issue["range"]["start"]["line"],
        end_line = issue["range"]["end"]["line"],
        title = issue["rule"]["name"],
    )

Errors

An unknown level, or a missing message, fails with an argument error that names ci.annotate.
A line or end_line without file, an end_line without line, or an end_line smaller than line fails with an argument error that names ci.annotate.
A gated-off call never fails.

ci describes the module and the shared behavior rules.
ci.summary and ci.comment report results that are not tied to a line.

Usage​

Arguments​

Returns​

Behavior​

Examples​

Flag a line in a file​

Report each finding from a check​

Errors​

Related​