1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
MiniCI
======
MiniCI runs jobs defined in the `minici.yaml` file in the root of the project
(on the same level as the `.git` directory). With that, `minici` invocation can
execute the jobs for local commits that are not yet in upstream (remote) branch
or for any manually given commit range.
Job definition
--------------
The basic top-level elements of the YAML file are `job <name>` defining steps
to perform the job and potentially listing artifacts produced or required.
Example:
```
job build:
shell: |
./configure
make
artifact bin:
path: build/example
job test:
uses:
- build.bin
shell: |
./build/example test
```
Each job is a map with the following attributes:
`shell`
: Shell script to perform the job.
`artifact <name>`
: Defines artifact `<name>` produced by this job. Is itself defined as a dictionary.
`artifact <name>.path`
: Path to the produced artifact file, relative to the root of the project.
`uses`
: List of artifact required for this job, in the form `<job>.<artifact>`.
`checkout`
: List of repositories to checkout into the work directory before starting
the job (see below). If not specified, the default repository (containing
the YAML file) will be checked out to the root of the work directory.
`publish`
: List of artifacts (produced by this or other jobs) to publish to specified
destinations (see below).
Usage
-----
To run jobs for a git commit range:
```
minici run <commit>..<commit>
```
or:
```
minici run --range=<commit>..<commit>
```
To run jobs for commits that are in local `<branch>`, but not yet in its upstream:
```
minici run --since-upstream=<branch>
```
For current branch, the name can be omitted:
```
minici run
```
To run selected jobs with the current working tree, including uncommitted
changes, list the job names on command line:
```
minici run <job name> [<job name> ...]
```
To watch changes on given `<branch>` and run jobs for each new commit:
```
minici run --new-commits-on=<branch>
```
To watch new tags and run jobs for each tag matching given pattern:
```
minici run --new-tags=<pattern>
```
The above options `--range`, `--since-upstream`, etc can be arbitrarily combined.
Explicit script file
--------------------
Normally, `minici` uses the `minici.yaml` file from the repository in the current working directory;
the path to a repository used can also be specified on the command line before the command (e.g. `run`).
That path must contain a slash character to disambiguate it from a command name, e.g.:
```
minici ../path/to/some/other/repo run some_job
```
Whether using the implicit repository or one specified on the command line, when
executing jobs for a range of commits, `minici` uses the `minici.yaml` file
version from each individual commit. So for example, running:
```
minici run HEAD~5..HEAD
```
can execute different jobs for each commit, if the job file was changed in each of the last five commits.
To force usage of particular version of `minici.yaml` file, explicit path to that file can be given:
```
minici ./minici.yaml run HEAD~5..HEAD
```
In this case, the jobs specified in the current version of `minici.yaml` will
be used for all of the five commits.
Additional repositories and checkouts
-------------------------------------
Jobs can also use repositories other than the default one (which contains the `minici.yaml` file).
The additional repositories need to be declared at the top level of the `minici.yaml` file as:
```
repo <name>:
path: <path/to/repository> (optional, only relevant for explicit script file)
```
The path of a repository `<name>` can be given (or overridden) on command line by passing argument in the form `--repo=<name>:<path>` before the command name.
To explicitly set what repositories to check out, set the list in the `checkout` element of the job definition:
```
job some_job:
checkout:
- repo: some_repo
dest: destination/path
...
```
The elements of the `checkout` list are dictionaries with following elements:
`repo`
: Name of the repo to checkout from. If not given, the default repo (containing the `minici.yaml` file) is used.
`dest`
: Path within the work directory to use for the checkout. If not given, the root of the work directory is used.
`subtree`
: If provided, checkout only given subtree of the repository. If the given path does not exist within a particular commit, the checkout and the whole job fail.
All checkouts are performed before running the script given in the `shell` element.
If no `checkout` list is given, the whole default repo is checked out to the root of the work directory.
Destinations
------------
Apart from a recipe, a job can also contain instructions to publish artifacts to given destinations.
The artifacts can be produced either by the publishing job or other jobs, and the destination must be declared at the top of the job file:
```
destination <name>:
url: <destination url> (optional, only relevant for explicit script file)
```
**Note**: only local filesystem path is currently supported as `url`.
The URL of a destination `<name>` can be given (or overridden) on command line by passing argument in the form `--destination=<name>:<url>` before the command name.
The artifacts to publish are then given in the `publish` list of a job definition:
```
job publish_something:
publish:
- to: some_destination
artifact: other_job.some_artifact
```
Elements of the `publish` list are dictionaries with following elements:
`to`
: Name of the destinations to publish to.
`artifact`
: Artifact to publish—either `<artifact-name>` if produced by this job, or `<job-name>.<artifact-name>` if produced by other job.
`path`
: Path within the destination to publish this artifact to. If not given, artifact path from the work directory is used.
|