Firepit

Appearance

Schema ​

The JSON schema file is available here.

Each property section is described as follows:

  • Type: Type of the property. We use Array<{item type}> for arrays, Map<{key type}, {value type}> for objects.
  • Required: Whether the property is required.
  • Default: Default value of the property.
  • Options: Available values of the property.
  • Template: Whether the property is a template string. Only for string or types containing strings.
  • Description: Description of the property.

Project ​

concurrency ​

  • Type: integer
  • Required: no
  • Default: Number of available CPU cores
  • Description: Task concurrency. Valid only in a root project config.
yaml
concurrency: 4

defaults ​

  • Type: Array<DefaultsConfig>
  • Required: no
  • Default: []
  • Description: Default settings applied to tasks matching a selector.
yaml
defaults:
  - tasks: "^(build|test)"
    depends_on:
      - install

depends_on ​

Dependency tasks for all the project tasks.

yaml
depends_on:
  - :install

env ​

  • Type: Map<string, string>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Deprecated: Use defaults instead.

Environment variables for all the project tasks.

yaml
env:
  TZ: Asia/Tokyo

env_files ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: yes
  • Description: Deprecated: Use defaults instead.

Dotenv files for all the project tasks. Their values are templates. In case of duplicated environment variables, the latter one takes precedence.

yaml
env_files:
  - .env
  - .env.local

gantt_file ​

  • Type: string
  • Required: no
  • Template: no
  • Description: Gantt chart output file path, relative to the root project. Valid only in a root project config.
yaml
gantt_file: gantt.mmd

includes ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: yes
  • Description: Additional config files to be included.
yaml
includes:
  - common-vars.yml
  - common-tasks.yml

An included file can include others, with paths relative to the including file.

log ​

  • Type: LogConfig
  • Required: no
  • Default: {"file":null,"level":"warn"}
  • Description: Log configuration. Valid only in a root project config.
yaml
log:
  level: debug
  file: firepit.log

projects ​

  • Type: ProjectsConfig
  • Required: no
  • Default: {}
  • Description: Child projects. Valid only in a root project config.
yaml
projects:
  client: packages/client
  server: packages/server

A list can mix globs, paths, and project names to paths. A glob or a path takes the directory name as the project name, and a glob matches only directories with a config file.

yaml
projects:
  - packages/*
  - tools/cli
  - www: apps/website

shell ​

  • Type: ShellConfig
  • Required: no
  • Default: {"args":["-c"],"command":"bash"}
  • Description: Deprecated: Use defaults instead.

Shell configuration for all the project tasks.

yaml
shell:
  command: "bash"
  args: ["-eux", "-c"]

tasks ​

  • Type: Map<string, TaskConfig>
  • Required: no
  • Default: {}
  • Template: no
  • Description: Task definitions.

ui ​

  • Type: UI
  • Required: no
  • Default: cui
  • Description: UI configuration. Valid only in a root project config.
yaml
ui: cui

vars ​

  • Type: Map<string, VarsConfig>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Template variables for all the project tasks. A variable declared without a value has no default, so it is required: running any task of the project without giving it a value by the <name>=<value> CLI argument is an error.
yaml
vars:
  registry: docker.io/example
  image: "{{ registry }}/server"

working_dir ​

  • Type: string
  • Required: no
  • Default: .
  • Template: yes
  • Description: Deprecated: Use defaults instead.

Working directory for all the project tasks.

yaml
working_dir: src

DefaultsConfig ​

depends_on ​

  • Type: Array<DependsOnConfig>
  • Required: no
  • Default: []
  • Description: Dependency tasks

env ​

  • Type: Map<string, string>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Environment variables

env_files ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: yes
  • Description: Dotenv files. Their values are templates.

inputs ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: no
  • Description: Inputs file glob patterns

outputs ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: no
  • Description: Output file glob patterns

service ​

  • Type: ServiceConfig
  • Required: no
  • Description: Service configurations

shell ​

  • Type: ShellConfig
  • Required: no
  • Description: Shell configuration

stop_timeout ​

  • Type: integer
  • Required: no
  • Description: Grace period in seconds given to the task process after SIGINT is sent, before it is forcibly killed with SIGKILL.

tasks ​

  • Type: TaskSelector
  • Required: no
  • Description: Task selector. A string is a regex pattern, an array is an explicit list of task names. If omitted, all tasks are matched.

vars ​

  • Type: Map<string, VarsConfig>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Template variables

wait_for ​

  • Type: Array<WaitForConfig>
  • Required: no
  • Default: []
  • Description: Tasks to run after, without depending on them

working_dir ​

  • Type: string
  • Required: no
  • Template: yes
  • Description: Working directory

DependsOnConfig ​

DependsOnConfigStruct ​

cascade ​

  • Type: boolean
  • Required: no
  • Default: true
  • Description: Whether the task restarts if this dependency task restarts.

optional ​

  • Type: boolean
  • Required: no
  • Default: false
  • Description: Whether to ignore this entry when the task does not exist, ex: on a project that lacks it.

task ​

  • Type: string
  • Required: yes
  • Template: yes
  • Description: Dependency task name

vars ​

  • Type: Map<string, VarsConfig>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Variables to override the dependency task vars.

DynamicVars ​

cache ​

  • Type: boolean
  • Required: no
  • Default: false
  • Description: Whether the command output is reused by the other variables running the same command in the same working directory. A variable shared by several projects runs in each project directory, so sharing one run across them takes an explicit working_dir. Leave it off for a command that must run every time, ex: allocating a resource.

command ​

  • Type: string
  • Required: yes
  • Template: yes
  • Description: Command

env ​

  • Type: Map<string, string>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Environment variables

env_files ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: yes
  • Description: Dotenv files. Their values are templates.

shell ​

  • Type: ShellConfig
  • Required: no
  • Description: Shell configuration

type ​

  • Type: VarType
  • Required: no
  • Description: Type of the variable, following JSON Schema. The command output is interpreted as this type; without it, the type is inferred from the output.

working_dir ​

  • Type: string
  • Required: no
  • Template: yes
  • Description: Working directory

ExecProbeConfig ​

command ​

  • Type: string
  • Required: yes
  • Template: yes
  • Description: Command to check if the service is ready

env ​

  • Type: Map<string, string>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Environment variables. Merged with the task env.

env_files ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: yes
  • Description: Dotenv files. Merged with the task env_files. Their values are templates.

interval ​

  • Type: integer
  • Required: no
  • Default: 5
  • Description: Interval in seconds. The command will run interval seconds after the task is started, and then again interval seconds after each previous check completes.

retries ​

  • Type: integer
  • Required: no
  • Default: 3
  • Description: Number of consecutive readiness-check failures allowed before giving up.

shell ​

  • Type: ShellConfig
  • Required: no
  • Description: Shell configuration

start_period ​

  • Type: integer
  • Required: no
  • Default: 0
  • Description: Initialization period in seconds. Probe failure during that period will not be counted towards the maximum number of retries.

timeout ​

  • Type: integer
  • Required: no
  • Default: 5
  • Description: Timeout in seconds

working_dir ​

  • Type: string
  • Required: no
  • Template: yes
  • Description: Working directory

FinalizedByConfig ​

FinalizedByConfigStruct ​

optional ​

  • Type: boolean
  • Required: no
  • Default: false
  • Description: Whether to ignore this entry when the task does not exist, ex: on a project that lacks it.

task ​

  • Type: string
  • Required: yes
  • Template: yes
  • Description: Finalizer task name

vars ​

  • Type: Map<string, VarsConfig>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Variables to override the finalizer task vars.

HealthCheckConfig ​

LogConfig ​

file ​

  • Type: string
  • Required: no
  • Template: no
  • Description: Log file path, relative to the root project.

level ​

  • Type: string
  • Required: no
  • Default: warn
  • Template: no
  • Description: Log level. Valid values: error, warn, info, debug, trace. warn and above report what a user needs to act on, info what Firepit is doing to each task, debug and below the internals.

LogProbeConfig ​

log ​

  • Type: string
  • Required: yes
  • Template: yes
  • Description: Log regex pattern to determine the task service is ready

timeout ​

  • Type: integer
  • Required: no
  • Default: 20
  • Description: Timeout in seconds

ProjectEntryConfig ​

  • Type: string | Map<string, string>
  • Template: no

ProjectsConfig ​

Restart ​

  • Type: string
  • Options: always, on-failure, never
  • Template: no

ServiceConfig ​

ServiceConfigStruct ​

healthcheck ​

restart ​

  • Type: Restart
  • Required: no
  • Default: never
  • Description: Restart policy

ShellConfig ​

args ​

  • Type: Array<string>
  • Required: no
  • Default: ["-c"]
  • Template: no
  • Description: Arguments of the shell command.

command ​

  • Type: string
  • Required: no
  • Default: bash
  • Template: no
  • Description: Shell command.

TaskConfig ​

command ​

  • Type: string
  • Required: no
  • Template: yes
  • Description: Command to run

depends_on ​

  • Type: Array<DependsOnConfig>
  • Required: no
  • Default: []
  • Description: Dependency tasks

description ​

  • Type: string
  • Required: no
  • Template: no
  • Description: Description

env ​

  • Type: Map<string, string>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Environment variables. Merged with the project env.

env_files ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: yes
  • Description: Dotenv files. Merged with the project env_files. Their values are templates.

finalized_by ​

  • Type: Array<FinalizedByConfig>
  • Required: no
  • Default: []
  • Description: Tasks to run after this task finishes, whether it succeeds or fails. They run only when this task is part of the run (as a target or a dependency), so running a finalizer on its own does not run the task it finalizes. Write an entry in object form to override the finalizer's vars, as with depends_on.
yaml
finalized_by:
  - db-down
  - task: notify
    vars:
      channel: ci

inputs ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: no
  • Description: Inputs file glob patterns

label ​

  • Type: string
  • Required: no
  • Template: yes
  • Description: Label to display instead of the task name.

outputs ​

  • Type: Array<string>
  • Required: no
  • Default: []
  • Template: no
  • Description: Output file glob patterns

service ​

  • Type: ServiceConfig
  • Required: no
  • Description: Service configurations

shell ​

  • Type: ShellConfig
  • Required: no
  • Description: Shell configuration

stop_timeout ​

  • Type: integer
  • Required: no
  • Description: Grace period in seconds given to the task process after SIGINT is sent, before it is forcibly killed with SIGKILL.
yaml
stop_timeout: 30

vars ​

  • Type: Map<string, VarsConfig>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Template variables. A task variable shadows the project variable of the same name, and the <name>=<value> CLI argument overrides both. Can be used at label, command, working_dir, env, env_files, depends_on, depends_on.{task, vars}, wait_for, wait_for.{task, vars}, service.healthcheck.log and service.healthcheck.exec.{command, working_dir, env, env_files}

A variable declared without a value has no default, so it is required: give it a value with the CLI argument or the dependent task's depends_on.vars.

wait_for ​

  • Type: Array<WaitForConfig>
  • Required: no
  • Default: []
  • Description: Tasks to run after, without depending on them.

Unlike depends_on, the listed tasks are not added to the run. They only order this task after them when they are going to run anyway. Naming a task orders this one after every variant of it. Write an entry in object form to wait only for the variants whose vars match the given ones.

yaml
wait_for:
  - lint
  - task: migrate
    vars:
      database: app

working_dir ​

  • Type: string
  • Required: no
  • Template: yes
  • Description: Working directory
yaml
working_dir: dist

TaskSelector ​

  • Type: string | Array<string>
  • Template: no
  • Description: Task selector for defaults. A string value is treated as a regex pattern matched against the task name. An array value is treated as an explicit list of task names. If omitted, all tasks are matched.
yaml
defaults:
  - tasks: "^build"        # regex
    env:
      NODE_ENV: production
  - tasks: [test, lint]    # explicit list
    depends_on:
      - install
  - env:                   # no tasks field = all tasks
      LOG_LEVEL: info

TypedVars ​

default ​

  • Type: any
  • Required: no
  • Description: Default value. Without it the variable is required.

type ​

  • Type: VarType
  • Required: yes
  • Description: Type of the variable, following JSON Schema

UI ​

  • Type: string
  • Options: cui, tui
  • Template: no

VarType ​

  • Type: string
  • Options: string, number, integer, boolean, array, object
  • Template: no
  • Description: Variable types, following JSON Schema

VarsConfig ​

A variable is one of:

  • a scalar value (foo: bar), whose type is inferred from the value
  • a typed declaration (foo: { type: array, default: [a, b] }), see [TypedVars]
  • a dynamic variable (foo: { command: ... }), see [DynamicVars]

Array and object values are only accepted as the default of a typed declaration, so that an object is never ambiguous between a value and a declaration.

An object with command is dynamic (tried first, so { type, command } is a typed dynamic variable), otherwise an object with type is a typed declaration.

WaitForConfig ​

WaitForConfigStruct ​

optional ​

  • Type: boolean
  • Required: no
  • Default: false
  • Description: Whether to ignore this entry when the task does not exist, ex: on a project that lacks it.

task ​

  • Type: string
  • Required: yes
  • Template: yes
  • Description: Name of the task to wait for

vars ​

  • Type: Map<string, VarsConfig>
  • Required: no
  • Default: {}
  • Template: yes
  • Description: Variables narrowing down which variants of the task to wait for. Only the variables given here are compared, so the variants may differ in the others.