Jupyter & Co: GitHub Action For Colab Badges Generation

Taras Savchyn — Thu, 09 Dec 2021 07:07:59 +0000

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.

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:

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

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.


      # 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:


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

trsvchn / colab-badge-action

GitHub Action that generates "Open In Colab" Badges for you

Colab Badge GitHub Action

Adds "Open in Colab" badges to Jupyter Notebooks and Markdown files. Updates badges for renamed or moved notebooks.

Usage

Badge Tag

Use {{ badge }} tag to generate a badge for the notebook containing this tag (self-linking). Works only for Jupyter notebooks.

The following options work for bath Jupyter and Markdown files (new in v4):

Use {{ badge nb_path }} tag to generate a badge for a local notebook nb_path, and insert it to the file containing that tag (tag will be replaced with generated badge code). e.g. {{ badge dir1/di2/nb.ipynb }}.
Use {{ badge /nb_path }} tag to generate a badge for a remote (located in another repo) notebook /nb_path, and insert it to the file containing that tag. e.g. {{ badge /usr2/repo/blob/main/nb.ipynb }}. You can use full link (url) as well: {{ badge https://github.com/usr2/repo/blob/main/nb.ipynb }}.
Use {{ badge…

View on GitHub

Open source projects that are using Colab Badge Action

huggingface/workshops Materials for workshops on the Hugging Face ecosystem.
UT-Covid/episimlab Framework for development of epidemiological models.
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.

DEV Community: Taras Savchyn