zuul.el: Interface to Zuul from Emacs

#zuul.el

#Introduction

Browse Zuul build outputs from Emacs. The zuul.el package provides functionality to communicate with Zuul through its Zuul REST API.

The zuul-log-mode major mode makes it as comfortable to browse a build log as it would be to navigate a local compilation. The package implements a custom filename parser for errors in the logs which allows Emacs to open the correct project file when an error is encountered in the log, even though the absolute path may not be found on the local machine.

For screenshots of the package see the blog post Bring Zuul into Emacs.

#Configuration

A minimal use-package configuration.

(use-package zuul
  :custom ((zuul-base-url "https://base.url.to.zuul.net")
           (zuul-tenant "tenant1")
           (zuul-tenant-configs
            '((:name "tenant1"
                     :project-roots (("foo" . "~/git/foo-repo")
                                     ("baz" . "~/git/baz-repo")))
              (:name "tenant2"
                     :project-roots (("bar" . "~/git/bar-repo")))))))

#Usage

The package doesn't provide any commands, except those used by the zuul-log-mode. Other packages, or users themselves, needs to implement commands because retrieving builds or buildsets requires knowledge that might not be general. An example of a package that integrates with zuul.el is egerrit-zuul. It provides the command egerrit-zuul-open-build-log which can be used as inspiration.

The functions zuul-get-builds and zuul-get-buildsets needs to be called to retrieve builds and buildsets from Zuul. Both functions accepts multiple input parameters specified as keys in the call. The simplest example would be to use a change number.

;; For buildsets
(zuul-get-buildsets :change "300203")

;; For builds
(zuul-get-builds :change "300203")

A query to retrieve builds or buildsets can be provided as input to the zuul-open-build-log in order to view a specific build log.

;; Query provided as a list
(zuul-open-build-log
 '(zuul-get-buildsets
   :change "300203"))

;; Query provided as a function
(zuul-open-build-log
 (lambda ()
   '(zuul-get-builds
     :change "300203")))

#Zuul log mode

The major mode zuul-log-mode provides the following commands.

Name	Binding	Description
zuul-switch-build	C-c C-b	Switch to another build
zuul-switch-buildset	C-c C-s	Switch to a build from a specific buildset
zuul-run-build-command	C-c C-r	Run build command from build log
zuul-previous-command	C-c C-p	Go to previous command in build log
zuul-next-command	C-c C-n	Go to next command in build log
zuul-open-build-in-browser	C-c C-o	Open build in browser
zuul-previous-build	C-c [	Switch to previous build
zuul-next-build	C-c ]	Switch to next build
zuul-quit-build	C-c C-q	Quit and delete build log buffers

It also integrates with the following built in features:

imenu: navigate to beginning of tasks in the build log
eldoc: echo descriptive information about where in the log point are

#Remote support

The zuul.el package supports Connection Local Variables which allows the user to customize the zuul-tenant-configs variable when running on a remote host. In this example zuul-tenant-configs are configured the same for all remote hosts.

(connection-local-set-profile-variables
 'remote-zuul
 '((zuul-tenant-configs . ((:name "foo"
                            :project-roots (("bar" . "~/other_location/bar")))))))

(connection-local-set-profiles
 '(:application tramp :protocol "ssh") 'remote-zuul)

#Contributions

The package is part of GNU ELPA which means that if you want to contribute you must have a copyright assignment.