Command Reference: comment

create

Post a markdown report as a comment on a commit, pull/merge request, or issue.

cml comment create [options] <markdown report file>

update

Update the last CML comment instead of creating a new one. If no previous comment is found, create a new one.

cml comment update [options] <markdown report file>

Options

Any generic option in addition to:

• --target=<pr|commit|issue>[/ref]: Where to post/associate with the comment (pr, commit, issue), optionally with a reference (issue/12, pr/17, commit/rev [default: pr falling back to commit/HEAD].

• --watch: Watch for changes and automatically update the comment (doesn't exit, consider appending & to run in the background).

• --publish=<true|false>: Upload any local images found in the Markdown report [default: true].

• --publish-native: Use --driver's native capabilities to --publish assets instead of --publish-url (not available on --driver=github).

• --publish-url=<...>: Self-hosted image server URL [default: https://asset.cml.dev], see minroud-s3.

• --watermark-title=<...>: Hidden comment marker (useful to specify which comment to update in subsequent cml comment update calls); "{workflow}" and "{run}" are auto-replaced.

Examples

Managing multiple comments

Repeatedly running cml comment create may produce too many comments. Meanwhile cml comment update will only produce/update one comment. What if you'd like to have exactly two comments (corresponding to two different markdown reports, possibly from different parallel workflows) visible at a time?

To mark and subsequently update a particular comment, use --watermark-title="some text". To mark a comment according to the workflow or run ID, include the placeholder text "{workflow}" and "{run}". For example:

# Create and constantly update 2 separate comments
$ cml comment update --watch --watermark-title='first {workflow} report' report.md &
$ cml comment update --watch --watermark-title='second {workflow} report' debug.md &
$ python train.py --report-file=report.md --debug-file=debug.md

# Same, but create a new pair of comments if rerunning a workflow
$ cml comment update --watch --watermark-title='first {run} report' report.md &
$ cml comment update --watch --watermark-title='second {run} report' debug.md &
$ python train.py --report-file=report.md --debug-file=debug.md

FAQs and Known Issues

GitHub

• commit_id has been locked.

  This error is caused by using the default GitHub token with cml comment update. Use a personal access token (PAT) instead.

Bitbucket

• Can't create a pull request or commit comment / Invalid or unknown installation.

  This happens because the Pull Request Commit Links application has not been installed into your BitBucket workspace. You can install it by following these instructions from the Bitbucket docs:

  Pull Request Commit Links app must be installed first before using this API; installation automatically occurs when 'Go to pull request' is clicked from the web interface for a commit's details.

  We don't like ClickOps either, but it's the way it is.