The Zanc Report

Forgejo, AGit, and Pull Request Templates

2026-02-21T00:00:00Z

I've raised a few PRs against the Guix Codeberg repository recently, and each time I've done so with Forgejo's AGit workflow. This workflow is pretty nice, and allows me to raise a PR entirely from within Emacs. To do that, I've been using this code in my Emacs config to add an extra option to the magit-push transient to use the AGit flow to push to the upstream branch:

(transient-define-suffix magit-push-current-agit (source target args)
  :if #'magit-get-current-branch
  :description (lambda () (concat (magit-push--upstream-description) " (agit)"))
  (interactive
   (let ((source (or (magit-get-current-branch)
                     (user-error "No branch is checked out"))))
     (list source
           (magit-get-upstream-branch source)
           (magit-push-arguments))))

  (magit-push-refspecs
   (magit-get "branch" source "remote")
   (concat source ":"
           ;; Forgejo uses /refs/for/{branch} to target. Locally,
           ;; setting the upstream branch sets the "merge" config item
           ;; to refs/heads/{branch}, so we can easily construct what we need
           (s-replace "/heads/" "/for/"
                      (magit-get "branch" (magit-get-current-branch) "merge"))
           "/" source)
   `(,@args
     ,@(if (or (member "--force" args)
               (member "--force-with-lease" args))
           '("-o" "force-push=true")
         '()))))

(transient-insert-suffix 'magit-push
  '(1 0)
  (list "a" #'magit-push-current-agit))

Once I've set an upstream branch, this makes it easy to push to Codeberg. Either P a to create a new PR, or P - f a to update an existing PR.

One downside to the AGit workflow is that I completely bypass the usual PR template that the Guix project has set up in .forgejo/pull_request_template.md. Instead, it just uses the commit message of the last commit that's being pushed. That's often fine, but I'd like to add at least some of my own commentary. With my existing Magit action I would usually have to go and open the PR to change the description to say what I wanted to say.

I've always been a bit uncomfortable about this, particularly because I think it's rude to just ignore the template.

My discomfort finally got strong enough that I solved this problem tonight, with this change to the final if in the above code snippet:

,@(if (or (member "--force" args)
          (member "--force-with-lease" args))
      '("-o" "force-push=true")
    (let ((info (cz/read-pull-request-from-buffer
                 (concat (magit-gitdir) "../.forgejo/pull_request_template.md"))))
      `("-o" ,(concat "title={base64}" (base64-encode-string (car info) t))
        "-o" ,(concat "description={base64}" (base64-encode-string (cdr info) t)))))

On a force push, we don't do anything (because we're just changing the commits on an existing PR). If we're not force pushing then we're creating a new PR, so we prompt for the title and description, base64 encode them, and send them through as options on the push.

The cz/read-pull-request-from-buffer function, and its associated mode, are not quite so easy. They read out the pull request template, then go into a recursive-edit in a markdown-mode buffer with the template's contents (after skipping the Forgejo header). Technically I'm not using the template correctly, because I should extract the title from the template and add it to the template, but I don't care.

At some point I might extract this out of my config and make a proper package for it. Let me know if that would be helpful to you - it might motivate me to actually do it!

The full relevant section of my config now looks like this:

(define-derived-mode cz/agit-pull-request-mode markdown-mode "AGit PR")

(defvar-local cz/agit-pull-request-title nil)
(defvar-local cz/agit-pull-request-description nil)

(defun cz/agit-pull-request-submit ()
  (interactive)
  (when (y-or-n-p "Are you sure you want to submit this pull request? ")
    (setq-local cz/agit-pull-request-title
                (save-excursion
                  (beginning-of-buffer)
                  (buffer-substring-no-properties
                   (+ (point) 2)
                   (line-end-position))))
    (setq-local cz/agit-pull-request-description
                (save-excursion
                  (beginning-of-buffer)
                  (next-line)
                  (buffer-substring-no-properties
                   (point)
                   (point-max))))
    (exit-recursive-edit)))

(keymap-set cz/agit-pull-request-mode-map "C-c C-c" #'cz/agit-pull-request-submit)

(defun cz/agit-pull-request-cancel ()
  (interactive)
  (abort-recursive-edit))

(keymap-set cz/agit-pull-request-mode-map "C-c C-k" #'cz/agit-pull-request-cancel)

(defun cz/read-pull-request-from-buffer (template-file)
  (if (get-buffer "*Pull Request*")
      (user-error "Other pull request already open - aborting this one.")
    (let ((buffer (get-buffer-create "*Pull Request*")))
      (with-current-buffer buffer
        (insert "# ")
        (save-excursion
          (insert "\n\n")
          (when (file-exists-p template-file)
            (let ((start (point)))
              (insert-file-contents-literally template-file)
              (beginning-of-buffer)
              (save-match-data
                (re-search-forward "^---")
                (re-search-forward "^---")
                (next-line)
                (beginning-of-line))
              (delete-region start (point)))))
        (cz/agit-pull-request-mode)
        (pop-to-buffer (current-buffer)
                       '(display-buffer-same-window)))
      (unwind-protect
          (progn
            (recursive-edit)
            (with-current-buffer buffer
              (if cz/agit-pull-request-title
                  (cons cz/agit-pull-request-title
                        cz/agit-pull-request-description)
                (user-error "No pull request information"))))
        (with-current-buffer buffer
          (if (get-buffer-window)
              (quit-window 'kill (get-buffer-window))
            (kill-buffer)))))))

;; Define a command for an AGit flow to upstream (this is suitable for
;; opening PRs on Codeberg)
(transient-define-suffix magit-push-current-agit (source target args)
  :if #'magit-get-current-branch
  :description (lambda () (concat (magit-push--upstream-description) " (agit)"))
  (interactive
   (let ((source (or (magit-get-current-branch)
                     (user-error "No branch is checked out"))))
     (list source
           (magit-get-upstream-branch source)
           (magit-push-arguments))))

  (magit-push-refspecs
   (magit-get "branch" source "remote")
   (concat source ":"
           ;; Forgejo uses /refs/for/{branch} to target. Locally,
           ;; setting the upstream branch sets the "merge" config item
           ;; to refs/heads/{branch}, so we can easily construct what we need
           (s-replace "/heads/" "/for/"
                      (magit-get "branch" (magit-get-current-branch) "merge"))
           "/" source)
   `(,@args
     ,@(if (or (member "--force" args)
               (member "--force-with-lease" args))
           '("-o" "force-push=true")
         (let ((info (cz/read-pull-request-from-buffer
                      (concat (magit-gitdir) "../.forgejo/pull_request_template.md"))))
           `("-o" ,(concat "title={base64}" (base64-encode-string (car info) t))
             "-o" ,(concat "description={base64}" (base64-encode-string (cdr info) t))))))))

(transient-insert-suffix 'magit-push
  '(1 0)
  (list "a" #'magit-push-current-agit))

I'm confident that this code can be improved, but I think it'll solve my problem for now.

Alternatives

After writing this post two alternatives have been mentioned:

agitjo, as a more fully-featured implementation of the AGit workflow, and
sarg's config, which is similar to the code above, but also stores the branch title/description in the Git branch description.

There's also a Magit discussion about having an AGit implementation upstream, which tarsius seems on board for.

Setting Up Cuirass Locally

2026-02-15T00:00:00Z

Recently I've been trying to get a PR merged with some fixes for Lua. I thought this would be a pretty straightforward thing to merge, but it turns out that modifying the Lua packages leads to 990 packages needing to be rebuilt. This is more than the 300 limit for a merge to master, so instead of merging my changes directly Andreas has kindly pushed them to a lua-team branch and queued it up behind go-team, gnome-team, and rust-team.

While I'm waiting for that, I have some more drastic changes that I'd like to try out (e.g. packaging Lua 5.5.0, and using it as the default Lua for building packages). In order to do that, I'd like to be able to test my changes before the lua-team branch gets to the front of the queue. I'm not a committer to Guix, so instead I figured I'd spin up Cuirass on my local machine to help me try things out.

Why Cuirass?

It's worth spending a moment on why I want to use Cuirass, rather than just doing the builds using Guix directly. guix refresh -l already gives you a list of the packages that you need to build to test your changes, why not just use that with guix build?

There are two reasons why I want to use Cuirass: live feedback, and tracking changes over time.

For live feedback, Cuirass gives me more information about what's going on that guix build does. Even though I'm only running on my local machine, seeing the list of scheduled/succeeded/failed builds, and in-progress builds, is helpful for me to keep track of where things are up to. It lets me get started investigating build failures right away, without interrupting the rest of the builds.

For tracking changes over time, Cuirass helps me by reporting not just whether a package has built or not, but whether that has changed since the last build. This tells me whether my changes are breaking things, or whether things were already broken before I started. I need to know this so I know where to spend effort trying to fix things.

Given Cuirass is now a sunk cost for me, we're going to proceed with the assumption that this was a good idea. 🙂

Initial Setup

Setting up Cuirass on a Guix system is shockingly easy. I just added these three services to my operating-system's services:

(service cuirass-service-type
         (cuirass-configuration
          (specifications
           #~(list (specification
                    (name "lua-team")
                    (build '(manifests #$(local-file "lua-manifest.scm")))
                    (channels (list (channel
                                     (name 'guix) ; has to be called guix for pull to work
                                     (url "https://git.sr.ht/~czan/guix") ; my unlisted fork
                                     (branch "lua-team")))))))))
(service postgresql-service-type
         (postgresql-configuration
          (postgresql (specification->package "postgresql@16"))))

This sets up a local instance of the cuirass-service-type configured to poll the listed channels and build things locally whenever anything changes.

The manifest that I wrote looks for all the packages which (transitively) depend on one of the Lua version. I took inspiration for the code for guix refresh -l, and this is the result::

;; lua-manifest.scm
(use-modules (guix)
             (guix packages)
             (gnu packages)
             (guix profiles)
             (guix monads)
             (guix graph)
             (guix scripts graph)
             (ice-9 match)
             (gnu packages lua))

(define packages
  (list lua-5.4 lua lua-5.2 lua-5.1 luajit))

(packages->manifest
 (with-store store
   (run-with-store store
     (mlet %store-monad ((edges (node-back-edges %bag-node-type
                                                 (package-closure (all-packages)))))
       (return (node-transitive-edges packages edges))))))

Problem: not authenticated

The first problem I ran into was that Guix will fail a pull for the guix channel if it tries to authenticate the commits but can't. Since I'm not a committer, I can't authenticate my commits without doing some more work (setting up a key, adding to the keyring, signing a commit, setting up an introduction, ...). I didn't really want to do that, so I hunted through the Cuirass manual and found the authenticate-channels? property. Setting it to #f does an unauthenticated pull. Dangerous in some circumstances, but acceptable for what I'm doing.

(service cuirass-service-type
         (cuirass-configuration
          (specifications
           #~(list (specification
                    ;; ... As above ...
                    ;; I'm not a committer, so we can't authenticate my commits
                    (properties `((authenticate-channels? . #f))))))))

Problem: evaluations failing

I got the pulls working, but then the evaluations kept failing. It turns out the path listed in the build option need to exist in the pulled channels. In my first attempt I passed a (local-file ...) call, but this did not work at all.

I had to commit my manifest into the repository and reference it in the build option:

(service cuirass-service-type
         (cuirass-configuration
          (specifications
           #~(list (specification
                    (name "lua-team")
                    (build '(manifests "etc/teams/lua/lua-manifest.scm"))
                    ;; ... As above ...
                    )))))

Problem: no builds running

The next problem I ran into was that this configuration didn't run any builds. It would poll the git repository, and successfully pull the changes and build Guix, but it would never get to building any packages. I couldn't see any reason for it not working, but the documentation for the local build mode also had this warning:

When Cuirass is used to build a large amount of jobs, the remote build mechanism described below should be preferred.

I figured I should try that. Again, configuring this in a Guix system to just use the local machine as a builder is easy. I just added the remote-server setting to my cuirass-configuration:

(service cuirass-service-type
         (cuirass-configuration
          (remote-server (cuirass-remote-server-configuration))
          (specifications
           ;; ... As above ...
           )))

and I added one more service to my list of services:

(service cuirass-remote-worker-service-type
         (cuirass-remote-worker-configuration))

With that, Cuirass started to build my packages locally. I saw my CPUs get busy, and all was well.

Problem: killed my machine

Unfortunately, the default configuration for the Cuirass remote worker is to run a single build, and to let it use all the cores for its build. My machine has an i7-8700 with 6 cores running 12 threads, and 32GiB of RAM. It turns out that building some Guix packages will cause that configuration to lock up (I assume it's swapping, but I didn't investigate at all).

I looked through the Cuirass manual to try to find some way to set the equivalent of --cores in the builds it runs, but I couldn't find anything. I had a look at the Cuirass source where the parameter is set, which itself comes from dividing the number of CPU cores by the number of workers. This assumes that the Cuirass workers can take up all the cores on the machine (which is not ideal for the computer that I use as my desktop), but it at least gives me enough control to avoid the builds locking up the whole machine.

Once again, the configuration for this is straightforward:

(service cuirass-remote-worker-service-type
         (cuirass-remote-worker-configuration
          (workers 6)))

Now I have six concurrent builds, with each using two threads. This has kept my memory usage under 50% thus far, and builds are continuing unimpeded.

Final configuration

The end result of my service configuration looks like this:

(service cuirass-service-type
         (cuirass-configuration
           (remote-server (cuirass-remote-server-configuration))
           (specifications
            #~(list (specification
                     (name "lua-team")
                     (build '(manifests "etc/teams/lua/lua-manifest.scm"))
                     (channels (list (channel
                                       (name 'guix)
                                       (url "https://git.sr.ht/~czan/guix")
                                       (branch "lua-team"))))
                     (properties `((authenticate-channels? . #f))))))))
(service postgresql-service-type
         (postgresql-configuration
           (postgresql (specification->package "postgresql@16"))))
(service cuirass-remote-worker-service-type
         (cuirass-remote-worker-configuration
          (workers 6)))

Want to help?

If you're interested in helping to maintain Lua packages in Guix (because I have no idea what I'm doing), get in touch on guix-devel in the thread I started. I'm particularly interested in getting a Guix committer on board, so I don't have to keep bothering Andreas. (Thanks Andreas!)

Ruby Development Using Guix

2026-02-08T00:00:00Z

Up until a few months ago, I was working on a Ruby on Rails monolith. In the four years that I worked on the project, we went through a few ways of building a local development environment:

directly using Bundler on our machine, then
using Bundler inside a Docker image, then
using Nix[], then
back to using Bundler inside a Docker image (not everyone liked Nix).

All of these options were fine, but my package manager of choice is Guix. I really wanted a way for me to work with my Ruby on Rails project alongside the rest of my team, but using Guix to build my development environment.

In 2015 David Thompson posted about using Guix for Ruby development which describes using Guix packages to build a Ruby development environment. Guix has a lot of Ruby packages, but it doesn't package all of RubyGems, nor does it package all the different versions of each Gem. This makes it difficult to use Guix to get precise dependencies that are needed for most real-world Ruby projects.

To make things easier for myself, I built Guix Ruby. A Guix channel that provides a guix ruby command which imports a Gemfile.lock and constructs Guix packages for all the listed dependencies.

To install it, just need to add this to your channels file (~/.config/guix/channels.scm):

(cons* (channel
        (name 'guix-ruby)
        (url "https://git.sr.ht/~czan/guix-ruby")
        (branch "main"))
       %default-channels)

Your next guix pull will add a new Guix command: guix ruby!

Basic Usage

Running guix ruby in the root of a Bundler project will read Gemfile and Gemfile.lock to produce a new file: Gemfile.lock.scm. It looks something like this:

(use-modules ...) ; imports
(lambda* (#:key (ruby ruby) (groups '(default)) (gem-transformers %default-gem-transformers))
  ...) ; gem definitions

You can then load this file in your manifest.scm or guix.scm file, and call the resulting function to get a list of Guix package objects which match your Bundler dependencies.

;; An example manifest.scm
(define bundler-packages (load "Gemfile.lock.scm"))
(packages->manifest
 (cons* ruby (bundler-packages #:groups '(default development test))))

Too easy.

When you're first setting up a project, you can ask guix ruby to create a manifest.scm file by passing the --init flag. It will be a bit more complicated than the example above, because it is more explicit about the Ruby version that it uses.

Adding New Dependencies

When it's time to add dependencies, you may find that using bundle install does not work due to a read-only file system. Instead, you can use bundle lock to update Gemfile.lock, then run guix ruby to update Gemfile.lock.scm.

You can also ask guix ruby to do this in one step with the --lock flag.

Updating Dependencies

At the moment, guix ruby doesn't have a shortcut to update dependencies, but bundle lock --update can still be used.

Git Dependencies

Sometimes it's useful to have Bundler clone dependencies directly from Git. This is supported by guix ruby, which will write an appropriate Guix package definition. However, when using bundle lock and bundle lock --update, you may run into issues. Bundler tries to clone the referenced repository in order to get some information about it. Unfortunately, the way Gemfile.lock.scm defines packages causes this to break (because it defines GEM_HOME pointing to a read-only directory).

Setting GEM_HOME to point to some readable directory should be enough to get it working, at the expense of an extra clone of the repos:

$ bundle lock --update # no good :(
...
There was an error accessing `/gnu/store/...`
The underlying system error is Errno::EROFS: Read-only file system @ dir_s_mkdir

$ GEM_HOME=/tmp/bundle-cache bundle lock --update # works :)
Fetching https://git.sr.ht/...
Fetching gem metadata from https://rubygems.org/..........
Resolving dependencies...
Writing lockfile to /.../Gemfile.lock

Gem Transformers

You may have noticed the gem-transformers parameter defined in Gemfile.lock.scm. This provides a mechanism for you to provide "transformations" to the automatically generated packages, to do things like adding inputs that are needed to build extensions. A default set of transformers is built into Guix Ruby itself, but you can provide your own transformers if a Gem isn't already supported.

I'm keen to support as much as we can in Guix Ruby, though, so if you find you need to define a transformer then let me know on the mailing list and I can add it to the default set.

Try it out!

I've been using guix ruby for a while to manage the dependencies on my Ruby projects. I've managed to get a few complex projects working using it (including Rails!), and I'm finding it very convenient to use Guix for Ruby development. If you're looking to bring together Ruby and Guix, please try it out. If you run into any issues, let me know on the mailing list and I'll do my best to help you.