bk.AnnotatedCmd is the generator-based pull-oriented annotations API to replace sporadic calls to annotate.sh and buildkite-angent annotate, splitting out annotation creation concerns out of check scripts and into the pipeline generator in a style similar to how ArtifactPaths works, but cooler and with way more bad bash from an engineer desperately copy-pasta-ing from Stackoverflow late at night (myself).
It should be simple enough that you can add annotations from any shell script → see usage below
Do not break the scripts if not run on the CI → biggest win here - we completely detach annotation commands from check scripts, and make annotations meaningful locally as well since you can find them in ./annotations. Potential sg check integration maybe?
Define what is a good (and bad) annotation and document it. → with bk.AnnotatedCmd as the main touch point for users, I've included a big docstring there including this information which should make it easy to discover for users of bk.AnnotatedCmd
You either create a MultiJobContext, or all annotations from a job go into a single annotation block.
For both MultiJobContext and default per-job annotations, annotations of different levels go into separate annotation blocks
Limited formatting options: content is either directly appended into annotation, or we include the name of the annotation file and include that as a heading.
.md files in annotations are treated as markdown content, otherwise we format them as terminal content
How it works
annotated-command.sh, aliased as ./an, turns pipeline options into arguments and runs the given command
Once the command has run, we then scan the ./annotations directory for files
Pass each file to annotate.sh with the generated arguments and some other parameters based on the name of the file, e.g. if it has a .md extension or if we should include the file name.
Done!
Benefits:
no more enterprise scripts being called in your check scripts
