Learning | 2i2c

Enabling CloudBank to safely manage their own cluster infrastructure

Tue, 20 Jan 2026 00:00:00 +0000

We recently enabled CloudBank to run Terraform changes for their cluster without needing to wait on 2i2c engineers for each request. They run 50+ hubs for various community colleges, and we want to enable them to self serve as much of that as possible. When we introduced home directory quotas, they were no longer able to set up hubs by themselves without help from 2i2c engineers. Our goal was to empower them to be able to set up new hubs in a safe way while still benefiting from the home directory limits work.

CloudBank simplifies cloud access for computer science research and education.

To do this safely, we needed to avoid granting access to shared Terraform state that could impact other communities. Following Yuvi’s suggestion, we migrated CloudBank’s Terraform state to CloudBank’s own GCP project so that infrastructure changes from the CloudBank team are isolated to their cluster only, making this safe to try. This unblocks CloudBank to run changes like terraform plan and terraform apply themselves, meaning that CloudBank can deploy and update a hub without 2i2c engineers in the loop.

This is a good example of how we aim to balance community autonomy with infrastructure safety. CloudBank can now self-serve routine operations while our broader infrastructure remains protected.

Learn more #

Acknowledgements #

Thanks to Sean Morris and the CloudBank team at UC Berkeley for collaborating on this workflow.

Yuvi on scaling maintainer intuition to facilitate PR review with PR triage boards

Wed, 19 Nov 2025 00:00:00 +0000

Yuvi has a recent post on the Jupyter blog on how his “maintainer intuition” about reviewable pull requests grew into the open-source pr-triage-board-bot, a reusable workflow that keeps GitHub Project boards curated for the JupyterHub, JupyterLab, and GeoJupyter communities. Foundational contributions are rellay important to 2i2c. This is a great example of building clever technical systems that help maintainers prioritize the social work of facilitating contributions to keep ecosystems healthy.

The JupyterHub PR Triage board.

Our favorite quote shares the vibe and cultural principles that drive this effort:

If the author of the PR is a newish contributor, I want to encourage them to stick around by being responsive to their gift. All PRs are gifts that we may or may not choose to accept, but should do so with grace.
Yuvi

Yuvi frames the problem here:

Reviewing PRs is a critical way that maintainers keep an open source project moving forward, but identifying PRs that can productively be merged is hard.

And notes that human scalability is often a big bottleneck:

One key bottleneck we identified in the process was Step 2. In particular, I was relying on my maintainer intuition to pick a single PR that I believe can be merged, so others in the team can do review work. I started exploring what this intuition is, and if it can be scaled.

Here’s his list of “intuitions” that he uses to choose PRs to work on:

PRs that aren’t too big, and are a reasonable size that can be merged within a 2 week window

CI tests passing, so at least our automated checks haven’t caught any issues with it Features or bug fixes that I believe add value to the project and move us in the right direction towards being able to support our users as they need (this is the hardest!)

If the author of the PR is a newish contributor, as I want to encourage them to stick around by being responsive to their gift. All PRs are gifts that we may or may not choose to accept, but should do so with grace.

How long ago the PR was opened. There is such a big difference between a response to your PR 2 days after you make it vs 2 months vs 2 years. I prioritized newer PRs.

What kind of contribution is it primarily? Different engineers on our team have different skillsets (JS, Python, etc) and I wanted to match the PR to what the engineer preferred code reviewing.

And the board essentially tries to capture many of these intuitions by signal-boosting them in one place:

we can roughly say ‘Pick a PR that looks good to you from the top of the “First Time Contributor” or “Seasoned Contributor” list’, and that relieves me from being the bottleneck quite a bit.

Read more in the original article: Scaling “Maintainer Intuition” with Pull Request Triage Boards.

Acknowledgements #

Project Jupyter for trusting us to incubate and now donate the bot code to the broader ecosystem.
JupyterHub and GeoJupyter contributors who tested the triage views and fed real maintainer workflows back into the design.
Jason Grout, Raniere Silva, and Matt Fisher for spotting the experiment early and helping it land across multiple orgs.

Creating a re-usable redirect generator for Jupyter Book 1 migrations

Wed, 12 Nov 2025 00:00:00 +0000

When migrating documentation from Jupyter Book 1 to Jupyter Book 2, URL structures change dramatically and break external links. We spent some time createing a re-usable tool to solve this problem across multiple projects.

You can check out the tool below:

jupyter-book/jb1-redirect-generator

It’s designed to be run in a self-contained way by putting the dependencies in script metadata at the top. This means you can run it like this:

uv run https://raw.githubusercontent.com/jupyter-book/jb1-redirect-generator/main/generate_redirects.py

This let’s you generate redirects from JB1 -> JB2 URL structures and dump them in a _build/html folder with your JB2 built pages.

We tested this out by converting the Jupyter Governance docs to Jupyter Book 2 and running it there. You can find a noxfile that runs these commands here:

jupyter/governance/blob/bcdae30efdecbe75bc4751ef1fe1e602fe82ee10/noxfile.py#L25-L37

And its use in a GitHub Workflow here:

jupyter/governance/blob/bcdae30efdecbe75bc4751ef1fe1e602fe82ee10/.github/workflows/deploy.yml#L39-L44

Learn more #

Community learning: Hub config to pass oauth tokens into user environments

Thu, 06 Nov 2025 00:00:00 +0000

One of our favorite things to see: communities learning from and building on each other’s work!

MAAP recently contributed infrastructure configuration inspired by EarthScope’s approach to handling authentication tokens. Both communities need to pass OAuth tokens into user environments so their SDKs can access protected data - and MAAP adapted EarthScope’s pattern to fit their needs.

This is the kind of peer-to-peer knowledge sharing we hope to foster with our open infrastructure model. When infrastructure is open and communities can see each other’s solutions, they can adapt and build on proven approaches rather than starting from scratch.

Learn more #

MAAP’s PR adapting the configuration
EarthScope’s original config
Our infrastructure repository where all community configurations live

Acknowledgments #

MAAP team for adapting and contributing this configuration
EarthScope Consortium for the original implementation

Refactoring Jupyter Book 2 documentation ahead of a major release

Sat, 01 Nov 2025 00:00:00 +0000

Documentation is what turns open source code into products that people actually want to use. We recently spent a few days refactoring the Jupyter Book documentation to prepare for the upcoming Jupyter Book 2 release, and we’re excited about how much clearer the docs have become!

What we did #

We restructured the docs using the Diataxis framework to better organize content by user type and task:

Reorganized into clear topic areas with landing pages for easier navigation
Added missing content like the feature voting table and contributing guides
Created upgrade guidance to help users understand the relationship between Jupyter Book 2 and MyST

This work helps users find what they need faster and gives the project a stronger foundation to build on going forward.

Why we’re excited about it #

Better documentation reduces maintainer burden by helping users answer their own questions, and it makes the project more welcoming and useful to new contributors. We hope this makes Jupyter Book more accessible to everyone and lays a good foundation for the new release!

We’re also excited because so many others helped provide edits and comments!

Learn more #

Acknowledgements #

Thanks to @rlanzafame, @FreekPols, and @bsipocz for their helpful reviews, edits, and feedback on the PR!
Project Pythia, CryoCloud, NASA Open Science / ScienceCore, and the Berkeley educational projects are our primary member communities using MyST and Jupyter Book. Their support covers the cost of these kinds of foundational contributions.

Communities learning from one another - Project Pythia and ICESat-2 Hackweeks

Tue, 21 Oct 2025 00:00:00 +0000

We wanted to share a short vignette about two of our communities learning from one another.

At the latest Project Pythia community meeting, Project Pythia met with representatives from ICESat-2 to share learning about notebooks and cookbooks in educational settings.

Anthony Arendt from UW’s eScience Institute shared how they’ve used educational notebooks in their hackweek programs. The discussion explored ways to improve cookbooks, especially for large collections that require different computational environments, sparking ideas about higher-level abstractions for organizing educational content. There is a lot of overlap in the needs and workflows of these communities, and we’re hopeful they can find ways to re-use one another’s ideas, content, and infrastructure.

One of our service goals is to make it easier for our member communities to learn from one another - using standardized tools and infrastructure means we can learn what works, what doesn’t, and collectively improve our workflows more quickly. We’re working on ways to encourage this kind of interaction in our member networks, so we wanted to celebrate this little win.

Learn more about these communities #

Project Pythia - An educational resource for geoscience computing with open-source Python
Project Pythia Cookbooks - Domain-specific example workflows for geoscience
ICESat-2 Hackweeks - Collaborative learning events combining tutorials, peer learning, and team projects

TIL: GitHub Action secrets are only available from non-forked repositories

Wed, 08 Oct 2025 00:00:00 +0000

If you’ve worked with GitHub Actions in open source projects, you might encounter a hard-to-debug error where repository secrets are simply empty. That’s probably because the PR is from a forked repository! Here’s a little learning we had after losing a bunch of time figuring this out:

Our PR from a fork was using empty strings for repository secrets #

github-activity is a tool we help maintain for generating changelogs from a wider variety of contributions than GitHub’s defaults. We needed to set a secret to raise the API rate limits for the tool’s tests. These tests pull data from repositories outside of the github-activity repository itself, which quickly hit GitHub’s rate limits without authentication.

The problem seemed straightforward at first: we added the secret, but the workflow was acting as if the secret didn’t exist at all. After updating the code to explicitly check for empty strings, we discovered the authentication token was actually an empty string, even though it had been set.

After some debugging, we uncovered the root cause: the PR was opened from a fork of github-activity. GitHub intentionally makes secrets appear as empty strings when a PR originates from a forked repository. This is a security measure to prevent unauthorized access to sensitive credentials.

A quick fix: re-open the PR from the base repository #

The immediate fix was simple: re-open the PR from a branch in the base repository rather than from the fork. This worked perfectly, but it’s not a sustainable solution for open source projects that rely on community contributions from forks. We don’t want to create a dynamic where maintainers have different PR workflows because they’re operating on the base repository.

How use secrets with forked repositories in a safe-ish way #

If you need to make secrets available to PRs from forks, there are a few approaches we learned about, each with security trade-offs:

The `pull_request_target` workflow #

GitHub provides a pull_request_target workflow that can access secrets even when triggered by forked PRs. In this case, GitHub will always run the test suite on main, instead of any changes your PR introduces.

Why this is dangerous: malicious actors could add code to a PR that exfiltrates your secrets (for example, Python code that prints os.environ["MY_SECRET"]).

As a result, only use secrets that you’re OK with being public. In this case, we generated a read-only token with restricted permissions. However, this is still kinda risky so use at your own peril.

If your repository workflows require a secret that absolutely cannot be public (e.g., a publishing key for a package repository), try a method like the following:

Using GitHub Environments for granular control #

A safer approach is to use GitHub Environments, which let you restrict which secrets are available to specific jobs. This way, you can ensure that only non-critical secrets (like those needed for testing) are available to jobs that run on forked PRs, while keeping sensitive secrets (like PyPI publishing tokens) restricted to trusted contexts.

This is the approach we implemented in github-activity, and it provides a good balance between security and community contribution workflows. We created a separate environment for publishing to PyPI so that its secret is never available to the job that runs with pull_request_target.

We hope this saves you time! #

Hopefully this learning is useful to others who run into the same confusing behavior. We’ve added a few improvements to github-activity to more reliably check for empty strings to surface this kind of condition, but knowing the basic behavior of GitHub environments and forked PRs is even better.

Learning | 2i2c

Enabling CloudBank to safely manage their own cluster infrastructure

Learn more #

Acknowledgements #

Yuvi on scaling maintainer intuition to facilitate PR review with PR triage boards

Acknowledgements #

Creating a re-usable redirect generator for Jupyter Book 1 migrations

Learn more #

Community learning: Hub config to pass oauth tokens into user environments

Learn more #

Acknowledgments #

Refactoring Jupyter Book 2 documentation ahead of a major release

What we did #

Why we’re excited about it #

Learn more #

Acknowledgements #

Communities learning from one another - Project Pythia and ICESat-2 Hackweeks

Learn more about these communities #

TIL: GitHub Action secrets are only available from non-forked repositories

Our PR from a fork was using empty strings for repository secrets #

A quick fix: re-open the PR from the base repository #

How use secrets with forked repositories in a safe-ish way #

The pull_request_target workflow #

Using GitHub Environments for granular control #

We hope this saves you time! #

Learn more #

The `pull_request_target` workflow #