f4ban/codespaces.el

#+TITLE: codespaces.el

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

** About

This package provides support for managing [[https://github.com/features/codespaces][GitHub Codespaces]] in Emacs and connecting to them via [[https://www.gnu.org/software/tramp/][TRAMP]]. It provides a handy =completing-read= UI that lets you choose from all your created codespaces.

[[./demo.gif]]

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. It normally is enabled by default. 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

• Recommended Configurations

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/%C
ControlPersist 10m
#+end_src

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

#+begin_src emacs-lisp
(setq tramp-ssh-controlmaster-options nil)
#+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.
• =codespaces-create= prompts for a repository, branch, and machine to then create a Codespace. Default branch is fetched via gh.
• =codespaces-delete= brings up a list of codespaces, and upon selection deletes the selected codespaces.

• Missing features

• Completion should sort codespaces by most-recently-used.
• 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.
• Thanks to [[https://github.com/patrickt][Patrick Thomson]] for writing the entire logic behind codespaces.el.

• License
  GPL3