Jupyter & Co: GitHub Action For Colab Badges Generation 
Tags: actionshackathon21, jupyter, datascience, python
Published: 2021-12-09 07:07:59


### My Workflow

> GitHub, take these badges off of me I can't use them anymore...

The following workflow aims to help you to organize your data science/machine learning code. If you maintain the project on GitHub with dozens of Jupyter notebooks, and in addition, you or your target audience are active Google Colab users there is a non-zero chance that you will find this action pretty useful. At least it will help you to reduce some boilerplating by introducing some automation to "Open in Colab" badge generation.

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)]()

#### Colab Badge Action

The usage is extremely straightforward, you just need to add the following badge tag: `{{ badge }}` to the notebook (think of it like Liquid or Jinja), and action will generate a valid "Open in Colab" badge for that notebook. For example, you added the badge tag to the `my_notebook.ipynb`, during the run action will find that tag and replace it with the badge containing a link for that notebook. Now you are able to open `my_notebook.ipynb` in Colab by pressing on that badge.

In addition, action tracks the changes, and if the file was moved or renamed, action will update the badge information of that particular notebook.

**Note:** you can use this tag only inside markdown cells, all the `code` and `raw` cells are ignored.

**Note:** Before the version 4 release, only one option was available - to generate a badge for the notebook pointing to itself (self linking). In other words, it wasn't possible to generate a badge for `notebook2` and put it inside `notebook1` and vice versa (cross-linking).

#### Announcing Colab Badge Action v4!

The new release of Colab Badge Action introduces some major changes. First of all, support for cross-linking and markdown files. Now you can generate a badge for any notebook hosted on GitHub, or Google Drive, and insert it not only in the markdown cell of your notebook but in plain markdown files, for example in `README.md`.

Let's a take look at how it works with the examples.

This update introduces an argument `notebook_path` to the already known `{{ badge }}` tag: ``{{ badge <notebook_path> }}``. Where `<notebook_path>` can be a local path: `{{ badge notebooks/my_nb.ipynb }}`, a link to the notebook from another repo `{{ badge https://github.com/not_me/not_my_repo/not_my_notebooks/blob/main/not_my_nb.ipynb }}` or Google Drive id with `//drive` prepended: `{{ badge //drive/112345 }}`.

For the 2nd example you can omit `https://github.com` part and simply do `{{ badge /not_me/not_my_repo/not_my_notebooks/blob/main/not_my_nb.ipynb }}`. But it is important to keep the leading `/`, it indicates that the notebook is not local (no leading `/`, and as you may also notice local path has no repo name, no branch name, cwd is a repo dir, so there is need to specify) and not from Google Drive (`//drive`).

In all cases (except drive) you can omit file extension, action will append it for you: `{{ badge notebooks/my_nb }}` and `{{ badge /not_me/not_my_repo/not_my_notebooks/blob/main/not_my_nb }}`.

Another useful feature added in this release is that during the badge generation procedure action now will verify the existence of the provided `<notebook_path>`. This feature works for notebooks hosted on GitHub and currently is not supported for notebooks from Google Drive.

In this case, when the file was found, action will provide information about the problem:

![Example error](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w4uq2hhbne4cd57liu6s.png)

and point to the exact file and line using the awesome GitHub Actions Annotations feature.

![Example error in PR](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/q4mh1w0gjnfuqursr5pw.png)

As you can see, Colab Badge Action does only one thing: "Open in Colab" badge creation. To get it to work you need checkout action - to pull a repo and commit&push action - to push the updated notebooks. You can find example workflows below.

### Submission Category: 

Maintainer Must-Haves

### Yaml File or Link to Code

Here is how to use the action in general, for example, if you want to adopt it to your existing workflow.

**Note:** use newly released version `v4`.

```yaml

      # First do checkout
      ...
      - name: Add Colab Badges
        uses: trsvchn/colab-badge-action@v4
        with:
          check: "all"
          target_branch: main
          target_repository: my_user_name/my_repo
          update: true
      ...
      # Use your favorite action for push and commit changes after

```

A complete end-to-end example, with required checkout and push steps, looks like this:

```yaml

name: Add Colab Badges
on:
  push:
    paths:
      # Trigger workflow only for notebooks or md file changes
      - "**.ipynb"
      - "**.md"
  pull_request:
    paths:
      # The same for PR
      - "**.ipynb"
      - "**.md"
jobs:
  badges:
    name: Colab Badge
    runs-on: ubuntu-latest
    steps:
      # First do checkout
      - name: Checkout
        uses: actions/checkout@v2

      # Then launch the colab-badge-action (v4)
      - name: Add/Update badges
        uses: trsvchn/colab-badge-action@v4
        with:
          target_branch: main
          target_repository: usr/repo
          check: "all"  # Check all notebook/md files
          update: true  # Update self-badges for renamed/moved notebooks
          verbose: true  # Print some info during the run

      # After that we have to commit and push changes
      # Note: this step requires GitHub token
      - name: Commit and Push
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "Add Colab Badges"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # And that's it!

```

### Additional Resources / Info

{% github trsvchn/colab-badge-action %}

#### Open source projects that are using Colab Badge Action

- [huggingface/workshops](https://github.com/huggingface/workshops) Materials for workshops on the Hugging Face ecosystem.
- [UT-Covid/episimlab](https://github.com/UT-Covid/episimlab) Framework for development of epidemiological models.
- [ulissigroup/math-methods-chemical-engineering
](https://github.com/ulissigroup/math-methods-chemical-engineering) Course notes for the CMU course 06-262 Math Methods of Chemical Engineering (ODE's, linear algebra, PDEs, stats) in the form of jupyter notebooks.