forked from
mitchellh.com/tack
Stitch any CI into Tangled
sourcehut: add docs
+89
+1
README.md
+1
README.md
+88
docs/sourcehut.md
+88
docs/sourcehut.md
···
1
+
# sourcehut
2
+
3
+
The sourcehut provider submits jobs to a
4
+
[builds.sr.ht](https://man.sr.ht/builds.sr.ht/) instance. Each Tangled
5
+
workflow becomes one job: tack submits the job via GraphQL, polls it
6
+
until terminal, and publishes `sh.tangled.pipeline.status` records on
7
+
each transition.
8
+
9
+
## Configure tack
10
+
11
+
| Env var | Description |
12
+
| ----------------------- | ------------------------------------------------------ |
13
+
| `TACK_SOURCEHUT_TOKEN` | Personal access token for builds.sr.ht (enables provider) |
14
+
| `TACK_SOURCEHUT_INSTANCE` | Base URL override (default `https://builds.sr.ht`) |
15
+
16
+
Generate a token at `https://meta.sr.ht/oauth2/personal-token` with
17
+
`builds.sr.ht/JOBS:RW` access, set the `TACK_SOURCEHUT_TOKEN=$token` env var,
18
+
then start tack.
19
+
20
+
## Workflow YAML
21
+
22
+
Your sourcehut build manifest is defined via tangled workflow inline - see `tack.sourcehut.manifest`.
23
+
It is submitted to builds.sr.ht verbatim, with a few `TACK_*` environment
24
+
variables merged into its top-level `environment:` map.
25
+
26
+
```yaml
27
+
when:
28
+
- event: ["push"]
29
+
branch: ["main"]
30
+
31
+
engine: tack
32
+
33
+
tack:
34
+
sourcehut:
35
+
manifest: |
36
+
image: alpine/edge
37
+
sources:
38
+
- https://tangled.org/j3s.sh/testy
39
+
tasks:
40
+
- test: |
41
+
ls -l testy
42
+
```
43
+
44
+
Optional fields:
45
+
46
+
```yaml
47
+
tack:
48
+
sourcehut:
49
+
instance: https://selfhosted.sr.ht.example.org
50
+
tags: ["tack", "ci"]
51
+
note: "manual note for the job list"
52
+
secrets: true
53
+
```
54
+
55
+
* `instance`: full URL (with scheme) of an alternate builds.sr.ht
56
+
deployment. Defaults to the provider's configured instance.
57
+
* `tags`: passed through to the submit API. Defaults to `["tack"]` so
58
+
jobs are filterable in the builds.sr.ht UI.
59
+
* `note`: passed through to the submit API. Defaults to
60
+
`tangled: <workflow> @ <short-commit>`.
61
+
* `secrets`: opt in to sourcehut secret injection. Default `false`.
62
+
63
+
## Injected environment
64
+
65
+
Tack merges the following into the manifest's `environment:` map
66
+
before submitting. These can be overridden via user definition.
67
+
68
+
| Variable | Value |
69
+
| -------------------- | -------------------------------------- |
70
+
| `TACK_KNOT` | Knot host the trigger came from |
71
+
| `TACK_PIPELINE_RKEY` | Pipeline record rkey |
72
+
| `TACK_WORKFLOW` | Workflow name |
73
+
| `TACK_WORKFLOW_RAW` | Raw workflow YAML body |
74
+
| `TACK_ACTOR` | Triggering DID |
75
+
| `TACK_COMMIT` | Commit SHA |
76
+
| `TACK_BRANCH` | Branch ref |
77
+
78
+
## Status mapping
79
+
80
+
| builds.sr.ht status | tack status |
81
+
| --------------------- | ----------- |
82
+
| `pending`, `queued` | `pending` |
83
+
| `running` | `running` |
84
+
| `success` | `success` |
85
+
| `failed`, `timeout` | `failed` |
86
+
| `cancelled` | `cancelled` |
87
+
88
+
Unknown upstream statuses are logged.