baur configuration files are in TOML format.
Information about the TOML syntax can be found at: https://toml.io.

When baur is run it looks for a .baur.toml file in the current directory, if it does not exist, it searches recursively in the parent directories until either a .baur.toml file is found or the filesystem root is reached. The directory containing the .baur.toml file is the root of the baur repository.

An initial .baur.toml file can be generated by running:

baur init repo

The file defines general option that are valid for the whole repository.

• config_version
  REQUIRED
  is an internal value and should not be changed manually. It is used by baur to check if the configuration file format is compatible with the executed baur binary. \

• application_dirs
  REQUIRED
  is a list of directory paths in which baur finds applications by searches for .app.toml configuration files.
  The paths must be relative and subdirectories of the baur repository root.

• search_depth
  REQUIRED
  specifies how many directories the search descends from each listed application_dirs directory.

The file specifies configuration options for a baur application.
An exemplary .app.toml file can be generated by running:

baur init app

• name
  REQUIRED
  defines the name of the application.
  Application names must be unique per baur repository.
  See also Reserved Characters.

• includes
  lists include sections Tasks. The tasks in the referenced section become a part of the application.
  See also Include IDs.

• name
  REQUIRED
  defines the name of a task.
  Task names must be unique per application.
  See also Reserved Characters.

• command
  REQUIRED
  specifies the command that the task executes when it is run.
  The first element in the list is the name of a file to be executed. If the name does not contain a path separator character, the location of the binary is looked up via the PATH environment variable.
  The following elements are arguments for the binary.
  The working directory when the command is executed is the application directory.

• includes
  lists Input or Output sections defined in include files that become part of the task.
  See also Include IDs.

Defines the Inputs, that when changed, can alter the result and the created outputs command. \

A task must define at least 1 Input.

The sections defines names of environment variables that are tracked as inputs.

• names
  REQUIRED
  is a list of environment variable names.
  Glob patterns can be specified to match multiple variables.
  Environment variable names are case-sensitive.
  Variables that are declared but not assigned are treated the same then non-existing variables.
  Variables that are defined but have an empty string assigned, are tracked.
  As glob patterns the syntax from Golang's filepath.Match() function is supported.

• optional
  When false, baur commands that evaluate the inputs of the task fail if one of the names elements do not match an existing environment variables.
  If the name is a glob pattern, it must match at least one environment variable.
  Default: false

The section defines files that are tracked as inputs.

• paths
  REQUIRED
  Is a list of glob patterns that match files.
  All paths are relative to the application directory.
  As glob patterns the syntax from Golang's filepath.Match() function is supported.
  Additionally the ** pattern can be used to match files in all subdirectories.

• optional
  If false, all patterns in paths must match at least one file and all parts in a pattern that are directories must exist.
  Otherwise baur commands that evaluate the inputs of the task fail.
  Default: false

• git_tracked_only
  If enabled, file patterns only match files that are tracked in the git repository, untracked files are ignored.
  Default: false

Resolves Golang packages to source files, all imported packages are resolved recursively.
Source files that belong the standard library are ignored.

• queries
  REQUIRED
  This is a list of either:

  • a file glob pattern in the format: fileglob=<GLOB-PATTERN>, it supports ** or
  • a go package query that is passed to the underlying Go package driver (usually go list). The query syntax described at https://github.com/golang/tools/blob/027eab55ae11cdaf85b7e426cd74249b206070a3/go/packages/doc.go#L17 All elements that do not start with fileglob= are passed as they are to the Go package driver. Example: queries = ["./..."] resolves to all go source files in the application directory and the source files that are recursively imported.

• environment
  Specifies environment variables that are defined when the Go package driver tool (go list) runs.
  The format of each element is <VARIABLE-NAME>=<VALUE>.
  The tool runs in a clean environment that only inherits the following variables from the current environment:

  • PATH
  • GOCACHE
  • XDG_CACHE_HOME
  • HOME
  • home
  • LocalAppData
  • USERPROFILE

• build_flags
  Is a list of command-line flags that are passed through to the go package driver tool. This can be used to e.g. limit the discovered source files to ones with a specific build tag.

• tests
  If enabled test files (*_test.go) are included.
  Default: false

Specifies files that are excluded from the inputs.
Excluding files is applied after all other Input sections.

• paths
  REQUIRED
  Is a list of glob patterns that match files to be excluded.
  All paths are relative to the application directory.
  As glob patterns the syntax from Golang's filepath.Match() function is supported.
  Additionally the ** pattern is supported, to match files recursively.
  If a path part of a pattern does not exist, it does not result in error.

TaskInfo defines that information about a task from the same application are written to a file are made available while the task command is executed. The TaskInfo file is in JSON format. It contains the total input digest, application directory and if the task is not in pending status the URIs of the outputs that the run with matching inputs produced. Example:

{
  "TotalInputDigest":"sha384:0e29ec1e484636414bca5acc8a522bc131d6bf673e35c9aff4a0df1f226846055cff715af4f84c8a5d032ed4b2a7f871",
  "AppDir":"/home/fho//sisu.sh/mail-service",
  "Outputs":[
    {"URI":"europe-docker.pkg.dev/my-registry/mail-service:f27b2fd2a4ef82c5179eb64f63e3c3355ad83f5f"}
  ]
}

• task_name
  REQUIRED
  The name of the task for that information should be written to the file.

• env_var
  REQUIRED
  The name of an environment variable that is defined when the command is executed and set to the path of the file that contains the task information.

Defines artifacts that are produced by running the command of the task and their upload locations. The section is optional.
If no outputs are specified, baur still records in the database successful task execution. \

• idfile
  REQUIRED
  Specifies the path of a file containing the docker image ID of the image creates by the task.
  The path is relative to the application directory.
  The file can be created by running docker build with the --idfile parameter.

Defines where the image is uploaded to.
The Docker environment files described at https://github.com/simplesurance/baur/blob/d65e01d6b2b2679bdffc2e56d7cda026e72ad32e/vendor/github.com/fsouza/go-dockerclient/client.go#L262-L264 are respected.
Authentication data is read from the config files as described here: https://github.com/simplesurance/baur/blob/d65e01d6b2b2679bdffc2e56d7cda026e72ad32e/vendor/github.com/fsouza/go-dockerclient/auth.go#L124-L137.

• registry
  The address of the docker registry.
  If it's empty the default of the docker daemon is used.

• repository
  REQUIRED
  The repository.

• tag
  REQUIRED
  The tag that is applied to the image.

Specifies that the file is uploaded to a S3 bucket.
Authentication information can be supplied via environment variables and the configuration files supported by the AWS SDK.
See https://web.archive.org/web/20221118163559/https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html for more information.

• bucket
  REQUIRED
  The name of the S3 bucket. \

• key
  REQUIRED
  The S3 object key. \

Specifies a location to which the output file is copied.

• path
  REQUIRED
  The destination path to which the file is copied.

Include configuration files specify shareable section that can be imported in .app.toml files.

An initial include configuration file can be generated by running:

baur init include

The fields in the include files have the same meaning then their equivalent in the application config file. The format is very similar.

An include configuration file can have one or more [[Input]], [[Task]] or [[Output]] section.
Each section has an include_id field. The field specifies the ID to be used when referencing it in includes fields.
See also Include IDs.

baur configuration files have limited support for templating.
Templating syntax can only be used in values of configuration fields.
See Go Templates for further information about the templating engine.

Apart from the standard features of the Go Templates, the following is supported:

• {{ .Root }}
  Is replaced with path to the repository root directory.

• {{ .AppName }}
  Is replaced with the name of the application.

• {{ gitCommit }}
  Arguments: none
  Returns the Git commit ID of the HEAD reference in the baur repository.

• {{ env }}
  Arguments: string, environment variable name
  Returns the value of an environment variable. If the variable is not defined baur will fail.
  Example: Get the value of the environment variable $TERM: {{ env "TERM" }}

• {{ uuid }}
  Arguments: none
  Generates and returns an UUID.

The following characters are reserved and can not be used in names and include IDs:

• .
• ,
• *
• #

Reusable configuration sections (includes) have a include_id field that assigns them a name. When includes are references to be included, the references are specified in the format:

FILEPATH#INCLUDE_ID

FILEPATH is relative to the directory of the configuration file that includes it.

The template variable {{ .Root }} can be used in the file path, to reference the repository root directory.