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
17`builds.sr.ht/JOBS:RW` access, set the `TACK_SOURCEHUT_TOKEN=$token` env var,
18then start tack.
19
20## Workflow YAML
21
22Your sourcehut build manifest is defined via tangled workflow inline - see `tack.sourcehut.manifest`.
23It is submitted to builds.sr.ht verbatim, with a few `TACK_*` environment
24variables merged into its top-level `environment:` map.
25
26```yaml
27when:
28 - event: ["push"]
29 branch: ["main"]
30
31engine: tack
32
33tack:
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
44Optional fields:
45
46```yaml
47tack:
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
65Tack merges the following into the manifest's `environment:` map
66before 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
88Unknown upstream statuses are logged.