codespaces.el

codespaces.el copied to clipboard

#+TITLE: codespaces.el

[[https://github.com/patrickt/codespaces.el/actions/workflows/check.yml][file:https://github.com/patrickt/codespaces.el/actions/workflows/check.yml/badge.svg]] [[https://melpa.org/#/codespaces][file:https://melpa.org/packages/codespaces-badge.svg]] [[https://raw.githubusercontent.com/patrickt/codespaces.el/main/LICENSE][file:https://img.shields.io/github/license/patrickt/codespaces.el.svg]]

This package provides support for connecting to [[https://github.com/features/codespaces][GitHub Codespaces]] in Emacs via [[https://www.gnu.org/software/tramp/][TRAMP]]. It provides a handy =completing-read= UI that lets you choose from all your created codespaces. Here's a screenshot (running with [[https://github.com/minad/vertico][vertico]]):

[[./screenshot.png]]

Here is an example =use-package= declaration:

#+begin_src emacs-lisp (use-package codespaces :config (codespaces-setup) :bind ("C-c S" . #'codespaces-connect)) #+end_src

You will need to:

1. Have the GitHub [[https://cli.github.com][command line tools]] (=gh=) installed.

• If you use =use-package-ensure-system-package=, Emacs can install this for you automatically:

#+begin_src emacs-lisp (use-package use-package-ensure-system-package :ensure t) (use-package codespaces :ensure-system-package gh :config (codespaces-setup)) #+end_src

2. Authorize =gh= to access your codespaces:

• Running =gh codespace list= will verify if permissions are correctly set.
• You can grant the required permission by running =gh auth refresh -h github.com -s codespace=.

Because the TRAMP package, which underpins this package's functionality, connects to remote servers over SSH, your codespace needs to have an SSH server running on it. If the Docker image that your codespace uses doesn't have an SSH server, install ~sshd~ in your Dockerfile; for codespaces that use Debian-based images, you can add the following to ~.devcontainer/devcontainer.json~:

#+begin_src javascript "features": { "ghcr.io/devcontainers/features/sshd:1": { "version": "latest" } } #+end_src

• Other recommended configs

I /strongly/ recommend you customize ~vc-handled-backends~ and remove the ones that you don't use. I suffered considerable lag to Codespace instances before I did so.

#+begin_src emacs-lisp (setq vc-handled-backends '(Git)) #+end_src

Use the host's PATH as TRAMP's [[https://www.gnu.org/software/emacs/manual/html_node/tramp/Remote-programs.html][remote path]]:

#+begin_src emacs-lisp (add-to-list 'tramp-remote-path 'tramp-own-remote-path) #+end_src

Use SSH connection sharing to reduce the number of new SSH connections that TRAMP needs to spawn for refreshing buffers. In your ~~/.ssh/config~ file, add the lines:

#+begin_src ControlMaster auto ControlPath ~/.ssh/sockets/%r@%h-%p ControlPersist 600 #+end_src

And to disable TRAMP's default ControlMaster settings in your Emacs config, add:

#+begin_src emacs-lisp (setq tramp-ssh-controlmaster-options "") #+end_src

• User-facing commands

• =codespaces-connect= brings up a list of codespaces, and upon selection opens a Dired buffer in =/workspaces= (the default Codespaces location).
• =codespaces-start= brings up a list of inactive codespaces and upon selection spawns a task that starts the selected codespace.
• =codespaces-stop= does the same but for stopping active codespaces.

• Missing features

• Should ensure that =gh codespace list= works okay.
• Completion should sort codespaces by most-recently-used.
• Should have an unobtrusive =special-mode= buffer for outputs.
• Should have a nice ~transient.el~ UI.

• Credits Thanks to [[https://github.com/anticomputer][Bas Alberts]] for writing the code to register =ghcs= as a valid TRAMP connection method.

• License GPL3.