kot.pink
1# spindle pipelines
2
3Spindle workflows allow you to write CI/CD pipelines in a simple format. They're located in the `.tangled/workflows` directory at the root of your repository, and are defined using YAML.
4
5The fields are:
6
7- [Trigger](#trigger): A **required** field that defines when a workflow should be triggered.
8- [Engine](#engine): A **required** field that defines which engine a workflow should run on.
9- [Clone options](#clone-options): An **optional** field that defines how the repository should be cloned.
10- [Dependencies](#dependencies): An **optional** field that allows you to list dependencies you may need.
11- [Environment](#environment): An **optional** field that allows you to define environment variables.
12- [Steps](#steps): An **optional** field that allows you to define what steps should run in the workflow.
13
14## Trigger
15
16The first thing to add to a workflow is the trigger, which defines when a workflow runs. This is defined using a `when` field, which takes in a list of conditions. Each condition has the following fields:
17
18- `event`: This is a **required** field that defines when your workflow should run. It's a list that can take one or more of the following values:
19 - `push`: The workflow should run every time a commit is pushed to the repository.
20 - `pull_request`: The workflow should run every time a pull request is made or updated.
21 - `manual`: The workflow can be triggered manually.
22- `branch`: Defines which branches the workflow should run for. If used with the `push` event, commits to the branch(es) listed here will trigger the workflow. If used with the `pull_request` event, updates to pull requests targeting the branch(es) listed here will trigger the workflow. This field has no effect with the `manual` event. Supports glob patterns using `*` and `**` (e.g., `main`, `develop`, `release-*`). Either `branch` or `tag` (or both) must be specified for `push` events.
23- `tag`: Defines which tags the workflow should run for. Only used with the `push` event - when tags matching the pattern(s) listed here are pushed, the workflow will trigger. This field has no effect with `pull_request` or `manual` events. Supports glob patterns using `*` and `**` (e.g., `v*`, `v1.*`, `release-**`). Either `branch` or `tag` (or both) must be specified for `push` events.
24
25For example, if you'd like to define a workflow that runs when commits are pushed to the `main` and `develop` branches, or when pull requests that target the `main` branch are updated, or manually, you can do so with:
26
27```yaml
28when:
29 - event: ["push", "manual"]
30 branch: ["main", "develop"]
31 - event: ["pull_request"]
32 branch: ["main"]
33```
34
35You can also trigger workflows on tag pushes. For instance, to run a deployment workflow when tags matching `v*` are pushed:
36
37```yaml
38when:
39 - event: ["push"]
40 tag: ["v*"]
41```
42
43You can even combine branch and tag patterns in a single constraint (the workflow triggers if either matches):
44
45```yaml
46when:
47 - event: ["push"]
48 branch: ["main", "release-*"]
49 tag: ["v*", "stable"]
50```
51
52## Engine
53
54Next is the engine on which the workflow should run, defined using the **required** `engine` field. The currently supported engines are:
55
56- `nixery`: This uses an instance of [Nixery](https://nixery.dev) to run steps, which allows you to add [dependencies](#dependencies) from [Nixpkgs](https://github.com/NixOS/nixpkgs). You can search for packages on https://search.nixos.org, and there's a pretty good chance the package(s) you're looking for will be there.
57
58Example:
59
60```yaml
61engine: "nixery"
62```
63
64## Clone options
65
66When a workflow starts, the first step is to clone the repository. You can customize this behavior using the **optional** `clone` field. It has the following fields:
67
68- `skip`: Setting this to `true` will skip cloning the repository. This can be useful if your workflow is doing something that doesn't require anything from the repository itself. This is `false` by default.
69- `depth`: This sets the number of commits, or the "clone depth", to fetch from the repository. For example, if you set this to 2, the last 2 commits will be fetched. By default, the depth is set to 1, meaning only the most recent commit will be fetched, which is the commit that triggered the workflow.
70- `submodules`: If you use [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) in your repository, setting this field to `true` will recursively fetch all submodules. This is `false` by default.
71
72The default settings are:
73
74```yaml
75clone:
76 skip: false
77 depth: 1
78 submodules: false
79```
80
81## Dependencies
82
83Usually when you're running a workflow, you'll need additional dependencies. The `dependencies` field lets you define which dependencies to get, and from where. It's a key-value map, with the key being the registry to fetch dependencies from, and the value being the list of dependencies to fetch.
84
85Say you want to fetch Node.js and Go from `nixpkgs`, and a package called `my_pkg` you've made from your own registry at your repository at `https://tangled.sh/@example.com/my_pkg`. You can define those dependencies like so:
86
87```yaml
88dependencies:
89 # nixpkgs
90 nixpkgs:
91 - nodejs
92 - go
93 # custom registry
94 git+https://tangled.org/@example.com/my_pkg:
95 - my_pkg
96```
97
98Now these dependencies are available to use in your workflow!
99
100## Environment
101
102The `environment` field allows you define environment variables that will be available throughout the entire workflow. **Do not put secrets here, these environment variables are visible to anyone viewing the repository. You can add secrets for pipelines in your repository's settings.**
103
104Example:
105
106```yaml
107environment:
108 GOOS: "linux"
109 GOARCH: "arm64"
110 NODE_ENV: "production"
111 MY_ENV_VAR: "MY_ENV_VALUE"
112```
113
114## Steps
115
116The `steps` field allows you to define what steps should run in the workflow. It's a list of step objects, each with the following fields:
117
118- `name`: This field allows you to give your step a name. This name is visible in your workflow runs, and is used to describe what the step is doing.
119- `command`: This field allows you to define a command to run in that step. The step is run in a Bash shell, and the logs from the command will be visible in the pipelines page on the Tangled website. The [dependencies](#dependencies) you added will be available to use here.
120- `environment`: Similar to the global [environment](#environment) config, this **optional** field is a key-value map that allows you to set environment variables for the step. **Do not put secrets here, these environment variables are visible to anyone viewing the repository. You can add secrets for pipelines in your repository's settings.**
121
122Example:
123
124```yaml
125steps:
126 - name: "Build backend"
127 command: "go build"
128 environment:
129 GOOS: "darwin"
130 GOARCH: "arm64"
131 - name: "Build frontend"
132 command: "npm run build"
133 environment:
134 NODE_ENV: "production"
135```
136
137## Complete workflow
138
139```yaml
140# .tangled/workflows/build.yml
141
142when:
143 - event: ["push", "manual"]
144 branch: ["main", "develop"]
145 - event: ["pull_request"]
146 branch: ["main"]
147
148engine: "nixery"
149
150# using the default values
151clone:
152 skip: false
153 depth: 1
154 submodules: false
155
156dependencies:
157 # nixpkgs
158 nixpkgs:
159 - nodejs
160 - go
161 # custom registry
162 git+https://tangled.org/@example.com/my_pkg:
163 - my_pkg
164
165environment:
166 GOOS: "linux"
167 GOARCH: "arm64"
168 NODE_ENV: "production"
169 MY_ENV_VAR: "MY_ENV_VALUE"
170
171steps:
172 - name: "Build backend"
173 command: "go build"
174 environment:
175 GOOS: "darwin"
176 GOARCH: "arm64"
177 - name: "Build frontend"
178 command: "npm run build"
179 environment:
180 NODE_ENV: "production"
181```
182
183If you want another example of a workflow, you can look at the one [Tangled uses to build the project](https://tangled.sh/@tangled.sh/core/blob/master/.tangled/workflows/build.yml).