Adding single click dev environment links to your open source project for easy contributions
Written on
I have been using DevContainers a lot. If you haven’t heard about them, it’s a standard for defining development environements using container technologies. The idea is pretty simple: you define a base container for your development environment —which can be a special DevContainer one, or any regular old container— along with any service containers you need. Whenever you or anyone else needs a new development environment, their development environment grabs and runs these docker containers, and runs any commands you defined in the configuration to set things up.
This comes with many benefits:
- Assuming you deploy with containers, your development environment can more closely match your production environment.
- There are no “works on my machine” issues, everyone has the same development environment.
- If anything goes wrong with your development environment, instead of trying to figure out what happened, you can delete it and start over in seconds.
- You were in the middle of something, and an urgent bug came up? Instead of trying to stash your work and clean up your environment, leave it where it is and launch another fresh development environment and get to work.
- New contributors to your open source project, or new hires can start developing immediately without having to set up anything, beyond installing Docker.
The last point here is the one I want to focus on in this blog post. Especially with open source projects, one of the biggest barriers to contribution is that it can be hard to install and set up everything you need to contribute to a project. Especially if you were trying to fix or add something small, it can be harder to set up the development environment than it is to actually develop whatever you were actually trying to do. The same issue applies for companies. Onboarding new employees is hard. Writing good onboarding documentation and keeping it up to date takes a lot of work. But without good documentation, new hires have to keep bugging experienced developers so they can start working. This slows down how soon new hires can start doing productive work, takes up time of experienced devs, and leaves everyone frustrated.
If I have sold you on DevContainers, check out my previous blog post on the topic on how to get started or VSCode docs (note: DevContainers are not exclusive to VSCode, support is being added to JetBrains products, and a CLI implementation is available as well). Once you have your DevContainers set up though, you get an amazing opportunity to make contributions or development even easier. Enter cloud development environments.
DevContainer support is built into Github Codespaces and CodeSandbox. These projects allow you to spin up machines in the cloud for development, and work on it through a web interface. Combined with DevContainers, you can click one button to get a fully-fledged development environment in your web browser within seconds. Along with these, DevPod is an open source solution that you can install on your own machine, and use with a local Docker install, remote VMs, or one of their many supported providers like AWS or Azure or DigitalOcean. You can take advantage of this yourself by just having these services/tools clone your repository, but we can make it even better and help newcomers by adding links to these services.
To do so, simply add the following links to your Readme, replacing <Owner> and
<Repo> with your own username and repository. Note that besides Github
Codespaces, these are not restricted to Github and
can be used with other forge services like Gitlab or Codeberg.
[](https://codespaces.new/<Owner>/<Repo>)
[](https://devpod.sh/open#https://github.com/<Owner>/<Repo>)
[](https://codesandbox.io/p/devbox/github/<Owner>/<Repo>)Having these links in your Readme is nice, but what if we went one step further? We could use these tools to make PR reviews easier too. You can click one button on Github or your favorite forge to see the changes in a PR, wouldn’t it be great if you can click one button to launch a fresh development environment with that PR? It would be, and we can do this!
To make this happen, I wrote a Github Actions workflow to post a comment to PRs with the appropriate links. Let’s see what that workflow looks like:
on: pull_request
permissions:
pull-requests: write
jobs:
comment_click_dev:
runs-on: ubuntu-latest
name: Comment Cloud Dev Buttons
steps:
- name: Comment PR
uses: thollander/actions-comment-pull-request@v2
with:
message: |
Click links below to open this PR in a dev environment:
[](https://codespaces.new/<Owner>/<Repo>/tree/${{github.head_ref}})
[](https://devpod.sh/open#https://github.com/<Owner>/<Repo>@${{github.head_ref}})
[](https://githubbox.com/<Owner>/<Repo>/tree/${{github.head_ref}})
comment_tag: comment_click_devThis workflow uses this cool action by Térence Hollander
to post a comment to the PR from a workflow.
Like the Readme example, replace the <Owner> and <Repo> with your username and repository.
These work great. Whenever you’re reviewing a PR, if you want to run the code or use a more comfortable environment than Github’s changes view, you can click these buttons and get the PR in a new development environment, without having to stash or discard anything you were already working on.
The only caveat with these links is that I couldn’t figure out how to make it work for CodeSandbox without going through the githubbox.com URL.
This URL seems to be owned by CodeSandbox from what I gather so it’s not dangerous or anything, but it limits it to repositories on Github only.