Publish

Montuer natively facilitates the Publish CI Job with the sole purpose to publish its documentations from the repository. This job is mainly for products that has built-in documentation generator to update itself easily and seamlessly.

The objective of the job is simple: to publish the repository’s documentations 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/publish/config.toml file. These are the various settings for customizations.

[Variables]

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

1
2
[Variables]
BuildOptions = "--minify"

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 publishing tasks, you can include or modify the existing [FMTVariables] table. Here is an example:

1
2
[FMTVariables]
SourceDir = '{{- .WorkingDir -}}/public'

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.

Publishers' Configurations

Monteur accepts one publisher configuration file per publishing channel (e.g. one gitlab-pages.toml for GitLab Pages). However, the internal operations allow many programs to publish simultenously and asynchonously (e.g. nginx.toml, gitlab-pages.toml, github-pages.toml, …). Each publishers configuration file shares the same file structure.

Storing Location

All program configuration files SHALL be stored inside .configs/monteur/publish/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 (program.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.

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
[Metadata]
Name = 'Gitlab Pages'
Description = """
Publishing using Hugo static site generator directly onto GitLab Pages.
"""

The Name field will be used for various internal configurations so Monteur recommends keeping it concise and without any weird symbol (space will be replaced by short dash).

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

[Variables]

This table houses all Plain Variables Definition specific to this publisher. Example:

1
2
3
4
[Variables]
MainLang = 'en'
PublishBranch = 'gh-pages'
FirstCommitID = 'Will be overwritten by publish command sequences'

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 publisher. Example:

1
2
3
[FMTVariables]
SourceDir = '{{- .WorkingDir -}}/public'
DestinationDir = '{{- .WorkingDir -}}/{{- .PublishBranch -}}'

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

[[Dependencies]]

The [Dependencies] is an array of program data for checking all required programs only for this Publish task. 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 = 'Hugo'
Condition = 'all-all'
Type = 'command'
Command = 'hugo'

[[Dependencies]]
Name = 'Git'
Condition = 'all-all'
Type = 'command'
Command = 'git'

[[CMD]]

[CMD] is basically an array of instructions for publishing the repository’s documentations to the publisher. 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
[[CMD]]
Name = 'Check Artifact Directory Exists and Ready'
Condition = 'all-all'
Type = 'is-exists'
Source = '{{- .SourceDir -}}/index.html'

[[CMD]]
Name = 'Remove Git Workspace for Publishing Branch'
Condition = 'all-all'
Type = 'command-quiet'
Source = 'git worktree remove "{{- .DestinationDir -}}"'

[[CMD]]
Name = 'Delete Publishing Directory Regardlessly'
Condition = 'all-all'
Type = 'delete-recursive-quiet'
Source = '{{- .DestinationDir -}}'

...

Known Templates

Now that you understand how Monteur executes Publish 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: