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 notebooknb_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
…
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.
Top comments (0)