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