|
| 1 | +# Annotation CLI |
| 2 | + |
| 3 | +A CLI tool for creating and storing annotation properties in Harness CI/CD pipelines, similar to Buildkite's annotate functionality. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **File-based summaries**: Reads markdown content from user-created files |
| 8 | +- **Execution context**: Automatically captures Harness environment variables |
| 9 | +- **Cross-platform**: Compatible with Linux, Mac, and Windows |
| 10 | +- **Multi-step support**: Single annotations.json file for multiple pipeline steps |
| 11 | +- **Append functionality**: Can append additional content to existing steps |
| 12 | + |
| 13 | +## Usage |
| 14 | + |
| 15 | +```bash |
| 16 | +./cli annotate --context "context-name" --summary "summary-file.md" [options] |
| 17 | +``` |
| 18 | + |
| 19 | +### Required Parameters |
| 20 | + |
| 21 | +- `--context`: Context identifier (used as grouping key) |
| 22 | +- `--summary`: Path to markdown file containing summary content |
| 23 | + |
| 24 | +### Optional Parameters |
| 25 | + |
| 26 | +- `--style`: Annotation style (replaces existing value) |
| 27 | +- `--priority`: Priority level (default: 5, replaces existing value) |
| 28 | + |
| 29 | +### Environment Variables |
| 30 | + |
| 31 | +The CLI automatically reads these Harness environment variables: |
| 32 | + |
| 33 | +- `HARNESS_EXECUTION_ID`: Current execution ID |
| 34 | +- `HARNESS_STEP_ID`: Current step ID |
| 35 | +- `HARNESS_ACCOUNT_ID`: Account identifier |
| 36 | +- `HARNESS_PROJECT_ID`: Project identifier |
| 37 | +- `HARNESS_ANNOTATIONS_FILE`: If set, target path where the CLI writes annotations JSON |
| 38 | + |
| 39 | +## Examples |
| 40 | + |
| 41 | +### Basic annotation |
| 42 | +```bash |
| 43 | +./cli annotate --context "build-validation" --summary "test-results.md" --priority 8 |
| 44 | +``` |
| 45 | + |
| 46 | +### Append to existing context (in the same step) |
| 47 | +```bash |
| 48 | +# Reuse the same --context to append additional content within the same step |
| 49 | +./cli annotate --context "build-validation" --summary "additional-notes.md" |
| 50 | +``` |
| 51 | + |
| 52 | +### With custom style |
| 53 | +```bash |
| 54 | +./cli annotate --context "deployment" --summary "deploy-results.md" --style "success" --priority 9 |
| 55 | +``` |
| 56 | + |
| 57 | +## Output Files |
| 58 | + |
| 59 | +- **annotations JSON**: Structured data containing all annotations and metadata. The output path is: |
| 60 | + 1. `HARNESS_ANNOTATIONS_FILE` environment variable (if set) |
| 61 | + 2. `./annotations.json` (default) |
| 62 | +- User-created **.md files**: Summary content files (not modified by CLI) |
| 63 | + |
| 64 | +### Notes on Step ID |
| 65 | +- The Harness step identifier is sourced from the environment and stored in `execution_context.harness_step_id`. |
| 66 | +- There is no separate `--stepid` argument; per-step annotations are written to a per-step file (via `HARNESS_ANNOTATIONS_FILE`), and context-based entries are merged within that file. |
| 67 | + |
| 68 | +## Build |
| 69 | + |
| 70 | +```bash |
| 71 | +go build -o cli main.go |
| 72 | +``` |
| 73 | + |
| 74 | +For cross-platform builds: |
| 75 | +```bash |
| 76 | +# Linux |
| 77 | +GOOS=linux GOARCH=amd64 go build -o cli-linux main.go |
| 78 | + |
| 79 | +# Windows |
| 80 | +GOOS=windows GOARCH=amd64 go build -o cli-windows.exe main.go |
| 81 | + |
| 82 | +# macOS |
| 83 | +GOOS=darwin GOARCH=amd64 go build -o cli-macos main.go |
0 commit comments