Release

Montuer natively facilitates the Release CI Job with the sole purpose to upstream various packages of the application or libraries for various platform system. This job is mainly for executing consistent upstreaming tasks whenever and whereever is needed easily and seamlessly.

The objective of the job is simple: to execute all the release processes easily and seamlessly whenever requested in a consistent manner with minimal to no further instructions.

Overall Configurations

To configure the job for execution, you need to supply and modify .configs/monteur/package/config.toml file. These are the various settings for customizations.

[Variables]

To configure job-wide variables for all release tasks, you can include or modify the existing [Variables] table. Here is an example:

1
2
[Variables]
TestArguments = "--verbose"

This table only accepts Plain Variables Definition.

The values can be any data types as long as it is sensible for direct replacement in a variable formatting activities.

[FMTVariables]

To configure job-wide formattable variables for all release tasks, you can include or modify the existing [FMTVariables] table. Here is an example:

1
2
[FMTVariables]
MainDir = '{{- .RootDir -}}/gopkg'

This table accepts Formattable Variables Definition (e.g. {{- .Version -}}).

These variables shall be processed after the [Variables] table and all the formatting clauses shall be replaced with the given variables. The processed Key-Value output data shall then be backfilled either create or overwrite back into [Variables] table depending on its Key-Value existence.

Releases' Configurations

Monteur accepts one release configuration file per releasing variant (e.g. one reprepro.toml for linux-amd64.deb, linux-arm64.deb, linux-riscv.deb and etc). However, the internal operations allow many programs to execute release tasks simultenously and asynchonously (e.g. reprepro.toml, flatpak.toml, appimagehub.toml, …). Each configuration file shares the same file structure.

Storing Location

All releasing recipe configuration files SHALL be stored inside .configs/monteur/release/jobs/ directory.

File Nature

The configuration file MUST have the file extension. Otherwise, it will be ignored. Currently the following formats are supported and sorted by priority sequences:

  1. TOML (recipe.toml) - https://github.com/toml-lang/toml

The filename does not affect any of the parsed configurations so feel free to name it according to your own pattern. Monteur recommends using releasing recipe name to keep sorting work sane. Example: reprepro.toml for all .deb packages.

Data Structure

Each configuration file follows the following data structure:

[Metadata]

This table houses all the information about the program metadata such as its name, description, and how to source the program. Here is an example:

1
2
3
4
5
6
[Metadata]
Name = 'Archives'
Description = """
Monteur's .tar.gz and .zip packagers released to hosting repository.
"""
Type = 'archive'

The Name field will be used for various internal configurations for Monteur’s packaging recipe identifications and logging purposes.

The Description is mainly for logging and the config file comprehension purposes. You can write a short description for it.

The Type is the type of supported releasing modes for Monteur to execute the recipes. The current supported modes are:

[Variables]

This table houses all Plain Variables Definition specific to this releasing recipes. It shall appears onto all listed packages. Example:

1
2
3
GPGID = '[email protected]'
GPGExistence = ''
Distribution = '' # to be filled later

All the variables are either create or overwrite to the existing variables list.

[FMTVariables]

This table houses all Formattable Variables Definition (e.g. {{- .Version -}}) specific to this releasing recipe. It shall appears onto all listed packages. Example:

1
DataPath = '{{- .DataDir -}}/debian/reprepro'

All formatted variables are either create or overwrite to the existing variables list.

[[Dependencies]]

The [Dependencies] is an array of programs due for existence checking specifically meant for the entire packaging recipe. Therefore, it has extra square braces when defining its data.

It is compliant to Monteur’s internal Dependencies Checking function.

Here is an example for defining a list of dependencies:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[[Dependencies]]
Name = 'Reprepro'
Condition = 'all-all'
Type = 'command'
Command = 'reprepro'

[[Dependencies]]
Name = 'GPG Tool For Signing'
Condition = 'all-all'
Type = 'command'
Command = 'gpg'

[Releases]

[Releases] are the list of packaged file data to be released by executing the [CMD] table onto each of the item. All these packages shall be iterated with the [CMD] table supplied with the given variables above.

Depending on Metadata.Type, Monteur will execute a preparation executions before executing the [CMD] for a package. This reduces the need to build large [CMD] commands list and promotes consistency.

The code example is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[Releases]
Target = '{{- .ReleaseDir -}}/archives'
Checksum = 'sha512'

[Releases.Data]
Path = '{{- .RootDir -}}/docs/.data/releases/archives'
Format = 'toml'

[Releases.Packages.darwin-amd64]
OS = [ "darwin" ]
Arch = [ "amd64" ]
Source = '{{- .PackageDir -}}/targz/{{- .PkgName -}}-{{- .PkgVersion -}}-{{- .PkgOS -}}-{{- .PkgArch -}}.tar.gz'

...

[[CMD]]

[CMD] is basically an array of releasing commands or instructions for releasing the packaged software file to the upstream. Hence, this is why it has extra square braces.

Its values are complying to Monteur’s Commands Execution Units. Here is an example:

 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
[[CMD]]
Name = "Get GPG Secret Key for Verifications"
Type = 'command'
Condition = [ 'all-all' ]
Source = 'gpg --list-secret-keys "{{- .GPGID }}"'
Save = 'GPGExistence'

[[CMD]]
Name = "Verify GPG Secret Key Must Exists For Signing"
Type = 'is-not-empty'
Condition = [ 'all-all' ]
Source = '{{- .GPGExistence -}}'

[[CMD]]
Name = "Create Necessary Conf Data Directory"
Type = 'create-path'
Condition = [ 'all-all' ]
Source = '{{- .DataPath -}}/conf'

[[CMD]]
Name = 'Get Current Branch'
Type = 'command'
Condition = [ 'all-all' ]
Source = 'git branch --show-current'
Save = 'Distribution'

[[CMD]]
Name = "Verify Distribution is Not Empty"
Type = 'is-not-empty'
Condition = [ 'all-all' ]
Source = '{{- .Distribution -}}'

[[CMD]]
Name = "Release Using Reprepro"
Type = 'command'
Condition = [ 'all-all' ]
Source = """reprepro --basedir {{ .DataPath }} \
--outdir {{ .Target }} \
includedeb {{ .Distribution }} \
{{ .Source }}
"""

Known Templates

Now that you understand how Monteur executes Release CI Job, fortunately, Monteur maintains a number of recipes for you to kick-start your deployment. Here are some currently maintained templates for different deployments: