diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json index b44bfcee..c90fff67 100644 --- a/content/docs/sidebar.json +++ b/content/docs/sidebar.json @@ -17,6 +17,10 @@ { "label": "GitLab", "slug": "gitlab" + }, + { + "label": "Bitbucket", + "slug": "bitbucket" } ] }, diff --git a/content/docs/start/bitbucket.md b/content/docs/start/bitbucket.md new file mode 100644 index 00000000..7c011b27 --- /dev/null +++ b/content/docs/start/bitbucket.md @@ -0,0 +1,78 @@ +# Get Started with CML on Bitbucket + +Here, we'll walk through a tutorial to start using CML. For simplicity, we'll +show the demo in Bitbucket Pipelines, but instructions are pretty similar for +all the supported CI systems. + +1. Fork our + [example project repository](https://bitbucket.org/iterative-ai/example-cml). + + ![](/img/bitbucket_fork_cml_project.png) + + The following steps can all be done in the Bitbucket browser interface. + However, to follow along the commands, we recommend cloning your fork to your + local workstation: + + ```bash + git clone https://bitbucket.org//example-cml + ``` + +2. ⚠️ Follow + [these instructions](https://cml.dev/doc/self-hosted-runners?tab=Bitbucket#personal-access-token) + to configure a Bitbucket token for CML. +3. ⚠️ Follow + [these instructions](https://cml.dev/doc/ref/send-comment#bitbucket) to + enable the Pull Request Commit Links application. + +4. To create a CML workflow, copy the following into a new file on your main + branch, `bitbucket-pipelines.yml`: + + ```yaml + image: iterativeai/cml:0-dvc2-base1 + pipelines: + default: + - step: + name: Train model + script: + - pip install -r requirements.txt + - python train.py + + - cat metrics.txt > report.md + - cml-publish plot.png --md >> report.md + - cml-send-comment report.md + ``` + +5. In your text editor of choice, edit line 15 of `train.py` to `depth = 12`. + +6. Commit and push the changes: + + ```bash + git checkout -b experiment + git add . && git commit -m "modify forest depth" + git push origin experiment + ``` + +7. In Bitbucket, create a Pull Request to compare the `experiment` branch to + `master`. + + ![](/img/bitbucket_make_pr.png) + + Shortly, you should see a comment from your user appear in the Pull Request + with your CML report. This is a result of the `cml send-comment` command in + your workflow. + + ![](/img/bitbucket_cml_first_report.png) + +This is the gist of the CML workflow: when you push changes to your Bitbucket +repository, the workflow in your `bitbucket-pipelines.yml` file gets run and a +report generated. + +CML commands let you display relevant results from the workflow, like model +performance metrics and vizualizations, in Bitbucket checks and comments. What +kind of workflow you want to run, and want to put in your CML report, is up to +you. + +## Final Solution + +An example of what your repository should look like now can be found at +[`iterative-ai/cml-base-case`](https://bitbucket.org/iterative-ai/cml-base-case). diff --git a/static/img/bitbucket_cml_first_report.png b/static/img/bitbucket_cml_first_report.png new file mode 100644 index 00000000..e3a7ef74 Binary files /dev/null and b/static/img/bitbucket_cml_first_report.png differ diff --git a/static/img/bitbucket_fork_cml_project.png b/static/img/bitbucket_fork_cml_project.png new file mode 100644 index 00000000..01a7a2f6 Binary files /dev/null and b/static/img/bitbucket_fork_cml_project.png differ diff --git a/static/img/bitbucket_make_pr.png b/static/img/bitbucket_make_pr.png new file mode 100644 index 00000000..21c65a79 Binary files /dev/null and b/static/img/bitbucket_make_pr.png differ