nel.pet
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`: This is a **required** field that 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.
23
24For 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:
25
26```yaml
27when:
28 - event: ["push", "manual"]
29 branch: ["main", "develop"]
30 - event: ["pull_request"]
31 branch: ["main"]
32```
33
34## Engine
35
36Next is the engine on which the workflow should run, defined using the **required** `engine` field. The currently supported engines are:
37
38- `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.
39
40Example:
41
42```yaml
43engine: "nixery"
44```
45
46## Clone options
47
48When 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:
49
50- `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.
51- `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.
52- `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.
53
54The default settings are:
55
56```yaml
57clone:
58 skip: false
59 depth: 1
60 submodules: false
61```
62
63## Dependencies
64
65Usually 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.
66
67Say 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:
68
69```yaml
70dependencies:
71 # nixpkgs
72 nixpkgs:
73 - nodejs
74 - go
75 # custom registry
76 git+https://tangled.org/@example.com/my_pkg:
77 - my_pkg
78```
79
80Now these dependencies are available to use in your workflow!
81
82## Environment
83
84The `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.**
85
86Example:
87
88```yaml
89environment:
90 GOOS: "linux"
91 GOARCH: "arm64"
92 NODE_ENV: "production"
93 MY_ENV_VAR: "MY_ENV_VALUE"
94```
95
96## Steps
97
98The `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:
99
100- `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.
101- `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.
102- `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.**
103
104Example:
105
106```yaml
107steps:
108 - name: "Build backend"
109 command: "go build"
110 environment:
111 GOOS: "darwin"
112 GOARCH: "arm64"
113 - name: "Build frontend"
114 command: "npm run build"
115 environment:
116 NODE_ENV: "production"
117```
118
119## Complete workflow
120
121```yaml
122# .tangled/workflows/build.yml
123
124when:
125 - event: ["push", "manual"]
126 branch: ["main", "develop"]
127 - event: ["pull_request"]
128 branch: ["main"]
129
130engine: "nixery"
131
132# using the default values
133clone:
134 skip: false
135 depth: 1
136 submodules: false
137
138dependencies:
139 # nixpkgs
140 nixpkgs:
141 - nodejs
142 - go
143 # custom registry
144 git+https://tangled.org/@example.com/my_pkg:
145 - my_pkg
146
147environment:
148 GOOS: "linux"
149 GOARCH: "arm64"
150 NODE_ENV: "production"
151 MY_ENV_VAR: "MY_ENV_VALUE"
152
153steps:
154 - name: "Build backend"
155 command: "go build"
156 environment:
157 GOOS: "darwin"
158 GOARCH: "arm64"
159 - name: "Build frontend"
160 command: "npm run build"
161 environment:
162 NODE_ENV: "production"
163```
164
165If 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).