Channel repositories consist of Guile modules that export packages or services. These packages then become accessible via any 'guix' command, once the channel is added to the Guix channels using guix pull.

The use of channels provides numerous advantages:

1. Packages: Channels can host a wide array of software, including those not available in the default Guix package collection. Channels can be pinned to specific commits, ensuring complete reproducibility of the software environment across multiple machines. Or you could get more up-to-date versions than are currently in Guix's main channel.
2. Configuration compnonents: Services for Guix Home and Guix System can be included in channels. In fact Guix Home itself started life in a third-party channel.
3. Modding: Is there some feature of a program you use that you find annoying but can't turn off? With channels, you can check out that code, disable the feature, and apply the patch to the package definition.

Before we start, you need to make sure that you're set up to sign commits with GnuPG. There's several guides out there that you can follow: This one by Fedora is well structured and should answer most of the questions you'd have.

Once you've got GnuPG set up and have generated a keypair, you'll want to add your signing key to Git.

[user]
	email = cdo@mutix.org
	name = Christina O'Donnell
	signingkey = 358B3178BAC1BA9B105C5CDA344C0AA8A41E474A

[commit]
	gpgsign = true

gpgsign = true tells Git to always sign commits without having to pass -S. This is optional but I find it to be a useful default.

Next you need to get your Git signing key. This is a different way of writing your GnuPG. It has the same length as your GnuPG key, but will be seen by Git when signing commits. One easy way to check this is to just sign a commit and then verify the commit to see the key ID used.

cdo@desktop ~$ gpg -K
/home/cdo/.local/secure/gnupg/pubring.kbx
-----------------------------------------
sec#  rsa3072 2022-09-01 [C]
      358B3178BAC1BA9B105C5CDA344C0AA8A41E474A
uid           [ultimate] Christina O'Donnell (master) <cdo@mutix.org>
ssb>  rsa2048 2022-09-05 [A] [expires: 2024-09-04]
ssb>  rsa2048 2022-09-05 [S] [expires: 2024-09-04]
ssb>  rsa4096 2022-09-20 [E] [expires: 2024-09-19]
ssb>  rsa2048 2022-09-21 [S] [expires: 2024-09-20]
ssb>  rsa2048 2022-09-21 [A] [expires: 2024-09-20]

cdo@desktop ~$ mkdir /tmp/test-repo; cd /tmp/test-repo
cdo@desktop /tmp/test-repo$ git init
Initialized empty Git repository in /tmp/test-repo/.git/
cdo@desktop /tmp/test-repo$ touch a
cdo@desktop /tmp/test-repo$ git add a
cdo@desktop /tmp/test-repo$ git commit -S 358B3178BAC1BA9B105C5CDA344C0AA8A41E474A -m "Test"

[master (root-commit) fd61ab6] Test
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 a

Here I have signed a test commit using the key 358B3178 in the gpg -K output.

cdo@desktop /tmp/test-repo$ git verify-commit HEAD
gpg: Signature made Sun 03 Mar 2024 14:27:04 GMT
gpg:                using RSA key D899861B5EAD198ACA062A9B9DA1DD5253A7AA4C
gpg: Good signature from "Christina O'Donnell (master) <cdo@mutix.org>" [ultimate]

However git verify-commit sees a signed commit using a different key name. It's this name (D899861B…) that we want to use.

To create a channel, you first need to establish a Git repository that will home your Scheme files. These files provide the package definitions. To make the repository a channel, initiate it as a Git repository, add your .scm files, and make a signed commit.

cdo@desktop ~$ mkdir ~/src/cdo-guix-channel; cd ~/src/cdo-guix-channel
cdo@desktop ~/src/cdo-guix-channel$ git init

Then add .guix_channel and .guix_authorizations to the directory:

(channel
  (version 0)
  (url "https://git.mutix.org/cdo-guix-channel.git"))

(authorizations
  (version 0)
  (("D899 861B 5EAD 198A CA06   2A9B 9DA1 DD52 53A7 AA4C"
   (name "cdo"))))

Here's what my checkout had in it:

drwxr-xr-x  8 cdo cdo 4096 Mar  3 17:48   .git
-rw-r--r--  1 cdo cdo  107 Mar  3 17:36   .guix-authorizations
-rw-r--r--  1 cdo cdo   77 Mar  3 17:36   .guix-channel

Commit these with -S to sign it.

cdo@desktop ~/src/cdo-guix-channel$ git add .
cdo@desktop ~/src/cdo-guix-channel$ git commit -S -m "Initial commit"

Next, create a keyring branch based off master. And add your public key to the repo like so:

cdo@desktop ~/src/cdo-guix-channel$ git branch keyring master
cdo@desktop ~/src/cdo-guix-channel$ gpg -a --export cdo@mutix.org >cdo-358B3178.key
cdo@desktop ~/src/cdo-guix-channel$ git add .
cdo@desktop ~/src/cdo-guix-channel$ git commit -S -m "Add cdo-358B3178.key"

Then we create a remote repo using SSH. This will be different depending on the software running on the server. Here's how you'd do it for a bare git --daemon:

cdo@desktop ~/src/cdo-guix-channel$ ssh git@mutix.org -- git init /srv/git/cdo-guix-channel.git
cdo@desktop ~/src/cdo-guix-channel$ git remote add origin git@git.mutix.org:cdo-guix-channel.git
cdo@desktop ~/src/cdo-guix-channel$ git push --all origin

Make a note of the first signed commit to use in the next step as the 'channel introduction' in the next step.

cdo@desktop ~/src/cdo-guix-channel$ git log
commit 8802797eb54c7bd83be7540446fe2efd6ffb1cb8 (HEAD -> keyring, origin/keyring)
Author: Christina O'Donnell <cdo@mutix.org>
Date:   Sun Mar 3 17:49:24 2024 +0000

    Add cdo key.

commit 45db57dc9add2f175b23ec72c222915baafe879b (origin/master, master)
Author: Christina O'Donnell <cdo@mutix.org>
Date:   Sun Mar 3 17:36:57 2024 +0000

    Initial commit

Now write a guix-channels.scm on your machine to represent the channel:

;; ...

(define %cdo-local-channel
  (channel
   (name 'cdo)
   (url "file:///home/cdo/src/cdo-guix-channel")
   (introduction
    (make-channel-introduction
     "45db57dc9add2f175b23ec72c222915baafe879b"
     (openpgp-fingerprint
      "D899 861B 5EAD 198A CA06  2A9B 9DA1 DD52 53A7 AA4C")))))


(define %cdo-channel
  (channel
   (name 'cdo)
   (url "git@git.mutix.org:cdo-guix-channel.git")
   (introduction
    (make-channel-introduction
     "45db57dc9add2f175b23ec72c222915baafe879b"
     (openpgp-fingerprint
      "D899 861B 5EAD 198A CA06  2A9B 9DA1 DD52 53A7 AA4C")))))

(define-public %channels
  (list ;; ... Other channels
        %cdo-channel))

Next run guix pull:

cdo@desktop ~/src/cdo-guix-channel$ guix pull -C guix-channels.scm

If this succeeds then you're all done.

If guix pull fails, then you may have to check the channel introduction, to see if you copied all the values correctly.

If you get an error like this:

guix pull: error: Git error: error authenticating: no auth sock variable

You'll need to have either ssh-agent or gpg-agent running in SSH mode.

I found that adding the home service home-ssh-agent-service-type to my Guix Home configuration and logging in again fixed it for me. If you're not using Guix Home, then you'll want to start up ssh-agent and ensure that you've added the key that you use for connecting to your remote.

Otherwise you can test it locally by using a file:// URL, to diagnose the issue.

Once your Git repository is set up, it's time to write package definitions. This can be accomplished by creating Guile modules that export the packages you want to add to your channel. It's important to note that the package definitions should be assigned to an exported variable name using define-public. This assigns the package to a variable so it can be referenced, even as a dependency of other packages.

It's common practice to create your own top level directory where all your files would sit. For example, all my packages are under a cdo directory:

cdo/packages.scm
cdo/services.scm
cdo/config/channels.scm
cdo/config/desktop.scm
cdo/config/home.scm
cdo/config/system-common.scm
cdo/config/vps.scm

As mentioned above, if you're working on Guix packages on only one system, you can use a local file URL (file://) for a package channel. This is useful when developing on/using a channel.