Edit on GitHub

Using CML

You'll need a GitHub or GitLab account to begin. Users may wish to familiarize themselves with Github Actions or GitLab CI/CD. Here, will discuss the GitHub use case.

⚠️ GitLab users: Please see our docs about configuring CML with GitLab.

🪣 Bitbucket Cloud users We support you, too- see our docs here.🪣 Bitbucket Server support is in the works.

The key file in any CML project is .github/workflows/cml.yaml.

name: your-workflow-name
on: [push]
    runs-on: [ubuntu-latest]
    container: docker://dvcorg/cml-py3:latest
      - uses: actions/checkout@v2
      - name: cml_run
          repo_token: ${{ secrets.GITHUB_TOKEN }}
        run: |

          # Your ML workflow goes here
          pip install -r requirements.txt
          python train.py

          # Write your CML report
          cat results.txt >> report.md
          cml-send-comment report.md

CML Functions

CML provides a number of helper functions to help package outputs from ML workflows, such as numeric data and data vizualizations about model performance, into a CML report. The library comes pre-installed on our custom Docker images. In the above example, note the field container: docker://dvcorg/cml-py3:latest specifies the CML Docker image with Python 3 will be pulled by the GitHub Actions runner.

Below is a list of CML functions for writing markdown reports and delivering those reports to your CI system (GitHub Actions or GitLab CI).

cml-send-commentReturn CML report as a comment in your GitHub/GitLab workflow.<path to report> --head-sha <sha>
cml-send-github-checkReturn CML report as a check in GitHub<path to report> --head-sha <sha>
cml-publishPublish an image for writing to CML report.<path to image> --title <image title> --md
cml-tensorboard-devReturn a link to a Tensorboard.dev page--logdir <path to logs> --title <experiment title> --md

Customizing your CML report

CML reports are written in GitHub Flavored Markdown. That means they can contain images, tables, formatted text, HTML blocks, code snippets and more - really, what you put in a CML report is up to you. Some examples:

📝 Text. Write to your report using whatever method you prefer. For example, copy the contents of a text file containing the results of ML model training:

cat results.txt >> report.md

🖼️ Images Display images using the markdown or HTML. Note that if an image is an output of your ML workflow (i.e., it is produced by your workflow), you will need to use the cml-publish function to include it a CML report. For example, if graph.png is the output of my workflow python train.py, run:

cml-publish graph.png --md >> report.md

🐛 Found an issue? Let us know! Or fix it:

Edit on GitHub

Have a question? Join our chat, we will help you:

Discord Chat


  • Install
  • Use cases
  • Blog
  • Github

By iterative.ai - An open platform to operationalize AI