~evhan/chicken-sourcehut

CHICKEN client library and CLI for the sr.ht REST API
Add smoke test for bundled man page
Add build manifests for FreeBSD and OpenBSD
Add example of using CLI from build manifest to README

clone

read-only
https://git.sr.ht/~evhan/chicken-sourcehut
read/write
git@git.sr.ht:~evhan/chicken-sourcehut

You can also use your local clone with git send-email.

#chicken-sourcehut

Command line interface and CHICKEN client library for sr.ht.

#Resources

#Installation

#Extension Library

Use your distribution's package manager to install CHICKEN 5.2 or newer, then run:

chicken-install -s sourcehut

On some platforms you may be required to install the OpenSSL development libraries first.

#Command Line Interface

If you just want to use the CLI program without installing CHICKEN first, you can download prebuilt binaries for some common platforms here.

#Examples

#Using the Extension Library

Create a new job on builds.sr.ht and fetch information about it:

(import (sourcehut)
        (sourcehut builds))

(access-token "your-access-token-goes-here")

(create (job manifest: "xyz"))
; => ((#:service "builds" #:path "/api/jobs")
;     (id . 1234))

(retrieve (job 1234))
; => ((#:service "builds" #:path "/api/jobs/1234")
;     (id . 1234)
;     (status . "running")
;     (setup_log ...)
;     (tasks . #(...))
;     (runner ...))

(retrieve (manifest 1234))
; => "xyz"

#Using the Command Line Interface

As above, but using the sourcehut CLI program.

$ export SOURCEHUT_CLI_ACCESS_TOKEN="your-access-token-goes-here"

$ sourcehut create job --manifest build.yaml --note "Example build"
((id . 1234))

$ sourcehut get job 1234
((id . 1234)
 (status . "running")
 (setup_log ...)
 (tasks . #(...))
 (runner ...))

$ sourcehut get job 1234 -o json | jq
{
  "id": 1234,
  "status": "running",
  "setup_log": ...,
  "tasks": [...],
  "note": "Example build",
  "runner": ...
}

#Using the CLI in a Build Manifest

To use the CLI within a Linux-based build manifest, you'll need to create a secret file containing an access token, add it to your job configuration, and set SOURCEHUT_CLI_ACCESS_TOKEN to that file path. Then, you can download and run the sourcehut binary in your build tasks without exposing the token. For example:

image: alpine/latest
packages:
  - wget
  - jq
secrets:
  # add a secret containing a personal access token in /home/build/.token
  - 43b6093b-85f0-4a19-97c9-9758a447e5fa
environment:
  # specify the path to the access token
  SOURCEHUT_CLI_ACCESS_TOKEN: /home/build/.token
  SOURCEHUT_CLI_OUTPUT: json
tasks:
  # install the program
  - setup: |
      sudo wget -qO /usr/bin/sourcehut https://foldling.org/sourcehut/sourcehut-x86_64-linux
      sudo chmod +x /usr/bin/sourcehut
  # use the program
  - usage: |
      sourcehut get jobs -n1 | jq

#Documentation

Full API documentation for the Scheme library is available on wiki.call-cc.org and api.call-cc.org.

For CLI documentation, refer to the program's man page. This is available online here or via the sourcehut help command once the program is installed. To view the latest version in your terminal without installing the program first, you can run:

wget -qO- https://git.sr.ht/~evhan/chicken-sourcehut/blob/master/sourcehut.1 | man /dev/stdin

#License

Three-clause BSD. See LICENSE for details.