docs/config.md
# Config
A configuration file defines tasks (units of work) and plans (configurations of tasks). The following properties are supported.
| Name | Default | Description |
| ----------- | ---------- | ----------- |
| env-file | [] | A list paths to [environment file](https://github.com/efritz/ij/blob/master/docs/environment.md#user-content-environment-files) on the host. Value may be a string or a list. |
| environment | [] | A list of environment variable definitions. Value may be a string or a list. |
| export | {} | An [export file list object](https://github.com/efritz/ij/blob/master/docs/config.md#user-content-export-file-lists) describing the export phase. |
| extends | '' | The path (relative/absolute on-disk, or an HTTP(S) URL) to the parent configuration. |
| import | {} | An [import file list object](https://github.com/efritz/ij/blob/master/docs/config.md#user-content-import-file-list) describing the import phase. |
| metaplans | {} | A name-metaplan mapping object. See [plans](https://github.com/efritz/ij/blob/master/docs/plans.md#user-content-metaplans) for the definition of these objects. |
| options | {} | An [options object](https://github.com/efritz/ij/blob/master/docs/config.md#user-content-options). |
| plans | {} | A name-plan mapping object. See [plans](https://github.com/efritz/ij/blob/master/docs/plans.md#user-content-plans) for the definition of these objects. |
| registries | [] | A list of [docker registries](https://github.com/efritz/ij/blob/master/docs/registries.md#user-content-registries) used for login. |
| tasks | {} | A name-task mapping object. See [tasks](https://github.com/efritz/ij/blob/master/docs/tasks.md#user-content-tasks) for the definition of these objects. |
| workspace | /workspace | The default workspace to use for [run tasks](https://github.com/efritz/ij/blob/master/docs/tasks.md#user-content-run-task). |
See the section on [extending a config](https://github.com/efritz/ij/blob/master/docs/extend.md#user-content-extending-a-config) about the semantics of the `extends` property.
See the documentation on [environments](https://github.com/efritz/ij/blob/master/docs/environment.md#user-content-environment) for details on the `env-file` and `environment` properties.
## Options
The following options can be amended/overridden by [override files](https://github.com/efritz/ij/blob/master/docs/override.md#user-content-override-files) or via command line arguments.
| Name | Default | Description |
| -------------------- | ------- | ----------- |
| force-sequential | false | If true, running tasks in parallel will be disabled. |
| healthcheck-interval | 5s | The duration to wait between health checks of a service container. |
| ssh-identities | [] | A set of SSH key fingerprints (SHA256 or MD5). Value may be a string or a list. |
| path-substitutions | {} | A map of replacements applied to paths of extended configuration files. |
Path substitutions may **only** be supplied in an [override file](https://github.com/efritz/ij/blob/master/docs/override.md#user-content-override-files). This option is provided in order to easily change the target of remote configs. The following example replaces all external references to `ij-repo.com` with a local filepath.
```yaml
options:
path-substitutions:
'http://ij-repo.com': /etc/ij-repo
```
If any ssh-identities are supplied in the configuration file or on the command line, then at least one matching fingerprint must exist in the host's SSH agent. On success, the SSH auth socket will be mounted in all containers launched by a *run* task.
The following example object supplies two SHA256 SSH key fingerprints (one prefixed with the checksum type).
```yaml
options:
ssh-identities:
- 4aIf67ySUwltykmcwNCDEnCdpkvJ/GRweCdtGuNno9c
- SHA256:bpCS6MPUbsg3iOmQet2bNZ3m8DAED7ym6h9IrlYzPTU
```
Alternatively, specifying the fingerprint '*' will allow any key that's been added to the host's SSH agent (if at least one exists).
```yaml
options:
ssh-identities: '*'
```
## Import File Lists
An import list object controls the files which move into the workspace on import.
| Name | Default | Description |
| ------- | ------- | ----------- |
| exclude | [] | Glob patterns for files to be ignored during import. Value may be a string or a list. |
| files | [] | Glob patterns for files targeted for transfer during import. Value may be a string or a list. |
Files matching a pattern in the `files` property will be *recursively* transferred into the workspace. If that file also matches a pattern in the `exclude` property, it will be skipped. All symlinks are skipped during transfer. Glob patterns support `*` for optional text and `**` for multiple directories. The directories `.ij` and `.git` are implicitly blacklisted on import.
A file pattern may also have the form `src:dest`. This allows importing the source file into the workspace at a particular target location in the workspace, and exporting the source file from the workspace into a particular location in the project directory. If this form is used, glob patterns are not allowed. This form is also not allowed for exclude patterns.
```yaml
import:
files:
- src
- test
excludes:
- .hg
- node_modules
```
## Export File List
An import list object controls the files which move back into the project directory on export.
| Name | Default | Description |
| -------------- | ------- | ----------- |
| clean-excludes | [] | Glob patterns for files to be ignored during the clean command. Value may be a string or a list. |
| exclude | [] | Glob patterns for files to be ignored during import. Value may be a string or a list. |
| files | [] | Glob patterns for files targeted for transfer during import. Value may be a string or a list. |
Files matching a pattern in the `files` property will be *recursively* transferred from the workspace. If that file also matches a pattern in the `exclude` property, it will be skipped. Glob patterns are also supported, as described above.
```yaml
export:
files:
- '**/junit*.xml'
clean-excludes:
- vendor
```