Files
heartwood/radicle-cli/examples/rad-job.md
T
Lars Wirzenius df44cee9ef cob: Add an experimental "job" COB
This is meant to record in Radicle that automated "jobs" have been run
on a repository. The job might be, for example, a CI run that builds
the software and runs its tests. The recording is done in a "job COB",
which can be in three states:

* fresh -- when the job has been triggered, but has not yet started running
* running -- when it's running
* finished -- when it's finished running

The finished state also records whether the job was successful or if
it failed.

A job COB records the git commit that it runs on, and the "run ID" of
the job. The run ID represents an external identifier, such as one
assigned by a remote CI system. The COB can optionally store a URL
related to the job, such as to the build log from CI.

Add the "rad job" subcommand to create and manage job COBs. For
production use, the COBs should be created and updated using
`heartwood` as a library instead of running "rad job", if at all
possible. However, "rad job list" lists the jobs that have been run on
the repository.

The COB type name is xyz.radicle.beta.job, until we've gained
experience with the COB and its implementation and are ready to
declare it stable.

Signed-off-by: Lars Wirzenius <liw@liw.fi>
2024-11-06 17:26:00 +01:00

88 lines
4.1 KiB
Markdown

The `rad job` command lets you manage job COBs. Let's first checkout the
`heartwood` repository:
```
$ rad checkout rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji
✓ Repository checkout successful under ./heartwood
$ cd heartwood
```
Using the `rad job` (or `rad job list`) command we can see that there are
currently no jobs listed:
```
$ rad job
Nothing to show.
```
Let's create a job to represent a new CI run. We check what the current `HEAD`
of the repository is, and use the `rad job trigger` to start a fresh job for
that commit:
```
$ git rev-parse HEAD
f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354
$ rad job trigger f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354
╭──────────────────────────────────────────────────╮
│ Job fbbda2447c30ebbab9b746498cd41a383ff05225 │
│ Commit f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354 │
│ State fresh │
╰──────────────────────────────────────────────────╯
```
Let's check the list again, and we should we see our fresh job there:
```
$ rad job
╭───────────────────────────────╮
│ ● ID Commit State │
├───────────────────────────────┤
│ ● fbbda24 f2de534 fresh │
╰───────────────────────────────╯
```
From there we can start a new job, assigning an arbitrary identifier `xyzzy`,
which would usually from the CI system that is running the job:
```
$ rad job start fbbda2447c30ebbab9b746498cd41a383ff05225 xyzzy
```
Checking the job again, we can now see that the job is `running`:
```
$ rad job
╭─────────────────────────────────╮
│ ● ID Commit State │
├─────────────────────────────────┤
│ ● fbbda24 f2de534 running │
╰─────────────────────────────────╯
$ rad job show fbbda2447c30ebbab9b746498cd41a383ff05225
╭──────────────────────────────────────────────────╮
│ Job fbbda2447c30ebbab9b746498cd41a383ff05225 │
│ Commit f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354 │
│ State running │
│ Run ID xyzzy │
╰──────────────────────────────────────────────────╯
```
When a job has finished, we can mark it as done -- either with a `--success` or
`--failed` flag -- using the `rad job finish` command:
```
$ rad job finish --success fbbda2447c30ebbab9b746498cd41a383ff05225
$ rad job
╭───────────────────────────────────╮
│ ● ID Commit State │
├───────────────────────────────────┤
│ ● fbbda24 f2de534 succeeded │
╰───────────────────────────────────╯
$ rad job show fbbda2447c30ebbab9b746498cd41a383ff05225
╭──────────────────────────────────────────────────╮
│ Job fbbda2447c30ebbab9b746498cd41a383ff05225 │
│ Commit f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354 │
│ State succeeded │
│ Run ID xyzzy │
╰──────────────────────────────────────────────────╯
```