Here, we'll walk through a tutorial to start using CML with GitLab CI/CD.

1. Fork our example project repository.

   

2. ⚠️ Follow these instructions to configure a GitLab access token for CML.

The following steps can all be done in the GitLab browser interface. However, to follow along the commands, we recommend cloning your fork to your local workstation:

$ git clone https://gitlab.com/<your-username>/example_cml
$ cd example_cml

3. To create a CML workflow, copy the following into a new file named .gitlab-ci.yml:

   train-and-report:
     image: iterativeai/cml:0-dvc2-base1
     script:
       - pip install -r requirements.txt
       - python train.py # generate plot.png
       # Create CML report
       - cat metrics.txt >> report.md
       - echo '![](./plot.png "Confusion Matrix")' >> report.md
       - cml comment create report.md

4. In your text editor, open train.py and modify line 15 to depth = 5.

5. Commit and push the changes:

   $ git checkout -b experiment
   $ git add . && git commit -m "modify forest depth"
   $ git push origin experiment
   

6. In GitLab, create a Merge Request to compare the experiment branch to master.

   

   The "New Merge Request" page will let you Change branches:

   

   Ensure the target is your fork (under your username):

   

   Continue and submit the Merge Request. Shortly, you should see a comment appear in the Merge Request with your CML report. This is a result of the cml comment create command in your workflow.

   

This is the gist of the CML workflow: when you push changes to your GitLab repository, the workflow in your .gitlab-ci.yml file gets run and a report generated.

CML commands let you display relevant results from the workflow, like model performance metrics and visualizations, in GitLab comments. What kind of workflow you want to run, and want to put in your CML report, is up to you.

An example of what your repository should look like now can be found at iterative.ai/cml-base-case.