Commands

Command

A Command is the smallest unit of work within Etcha. Patterns contain build and run properties which are lists of Commands, as well as Signing and Verify commands for integrating JWT signing/verification with other systems.

Within a list of Commands, Commands are executed in the order they are listed. Additionally, a list of Commands can contain nested lists of Commands. Etcha will flatten the lists into one ordered list automatically.

Execution

A Command is executed using the values within exec. Exec overrides mean the Command may need to support, handle, or not run within other Exec configurations.

Environment Variables

A Command is passed environment variables within the exec configuration (or inherited values from the parent process). Etcha will attempt to resolve environment variables before running commands, e.g. if ${MYVAR} is present in a command, Etcha will resolve this if a match environment variable exists before passing it to the underlying command.

Each command can also add environment variables to subsequent check/change/command executions:

ETCHA_EVENT_ID

This variable will be set for Commands in eventReceive Pattern run lists. It contains the id of the Command that triggered the event.

ETCHA_EVENT_NAME

This variable will be set for Commands in eventReceive Pattern run lists. It contains the event name that triggered the event.

ETCHA_EVENT_PUBLIC_KEY

This variable will be set for Commands in eventReceive Pattern run lists. It contains the public key ID used to sign the pattern or shell that triggered the event.

ETCHA_EVENT_SRC

This variable will be set for Commands in eventReceive Pattern run lists. It contains the remote address (IPv4 or IPv6, where applicable) of the source push or shell event.

ETCHA_EVENT_OUTPUT

This variable will be set for Commands in eventReceive Pattern run lists. It contains the stdout/stderr of the change that triggered the event.

ETCHA_JWT

This variable will be set for verifyCommands. It contains the JWT that needs to be verified.

ETCHA_PAYLOAD

This variable will be set for signCommands. It contains the base64 JWT payload that needs to be signed.

ETCHA_SOURCE_NAME

This variable will be set for Commands in eventReceive or webhookPaths Pattern run lists. It contains the name of the source receiving the Event or Webhook Pattern.

ETCHA_SOURCE_TRIGGER

This variable will be set for Commands in eventReceive or webhookPaths Pattern run lists. It contains the type for the trigger, event or webhook.

ETCHA_WEBHOOK_BODY

This variable will be set for Commands in webhookPaths Pattern run lists. It contains the base64 encoded body of the webhook request.

ETCHA_WEBHOOK_HEADERS

This variable will be set for Commands in webhookPaths Pattern run lists. It contains a list of all webhook headers, separated with a newline (\n).

ETCHA_WEBHOOK_METHOD

This variable will be set for Commands in webhookPaths Pattern run lists. It contains the name of the webhook method (DELETE|GET|POST|PUT).

ETCHA_WEBHOOK_PATH

This variable will be set for Commands in webhookPaths Pattern run lists. It contains the request path for the webhook.

ETCHA_WEBHOOK_QUERY

This variable will be set for Commands in webhookPaths Pattern run lists. It contains the request query params separated with a &.

envPrefix

This variable will be set to the stdout and stderr of the check execution of a Command with envPrefix. This variable will not be set if the Command wasn’t checked. If no envPrefix is defined, this variable will not be set.

<envPrefix>_CHECK

This variable will be set to 0 if a Command is checked without any error or skipped checking due to no check value, always set to false, or not changed by anything. It will be 1 if it had errors while checking. If no envPrefix is defined, the variable will be _CHECK and will show the previously run command.

<envPrefix>_CHANGE

This variable will be set to 0 if a Command is changed without any error, or 1 if it had errors. This variable will not be set if the Command didn’t have any change executed. If no envPrefix is defined, the variable will be _CHANGE and will show the previously run command.

<envPrefix>_CHANGE_OUT

This variable will be set to the stdout and stderr of the change execution of a Command. This variable will not be set if the Command didn’t have any change executed. If no envPrefix is defined, this variable will not be set.

<envPrefix>_REMOVE

This variable will be set to 0 if a Command is removed without any error, and 1 if it had errors. If no envPrefix is defined, the variable will be _REMOVE and will show the previously run command.

<envPrefix>_REMOVE_OUT

This variable will be set to the stdout and stderr of the remove execution for a Command. If no envPrefix is defined, this variable will not be set.

Operating Modes

A Command is ran within three different operating modes:

Change (default)

The default, will always run check if specified, and run change if always is true, check is non-zero, or the id is changed by another command.

Check

Will always run check if specified only. sources can be forced to run in check mode, and patterns can be ran in check mode using checkOnly.

Remove

Will always run check if specified, and run remove if always is true, check is zero, or the id is removed by another command.

For push and pull, Etcha by default diff Patterns and run checks and removes for Commands that are no longer present in the new Pattern, as well as for any Commands that have a modified change values (unless changeIgnore is specified).

Properties

always

Boolean, when true, change will always be ran during Change Mode

change

String, the commands or executable to run during Change Mode. Can be multiple lines. Will be appended to exec.command. Should return 0 if successful, otherwise it will produce an error.

changeIgnore

Boolean, will ignore changes to the change Command. By default, change differences will trigger a remove and change cycle for the Command.

check

String, the commands or executable to run during Change Mode or Check Mode. Can be multiple lines. Will be appended to exec.command. If this returns 0, remove will be ran in Remove Mode. If this does not return 0, change will be ran in Change Mode. If omitted, change or remove will never run unless always is true or id is changed by another Command via onChange or removed by another Command via onRemove

commands

A list of sub Commands. Other properties for this Command will be ignored except id. These Commands will be ran in a group and not affect other groups.

envPrefix

String, an environment variable name prefix to add to all Environment Variables created by this command. Must be a valid environment variable (does not start with a number, must only contain word characters or _).

exec

See exec. Specifies a custom exec configuration for this command. Parent exec configurations must allow overrides for this to work.

id (required)

An ID for the Command. Must be specified. Can overlap with other Commands.

onChange, onFail, onRemove

A list of:

• Other Command ids to run
• Regular expressions to match Command ids to run
• Events to trigger, if this Command changes, removes or fails. Event names must be prefixed with etcha:.

Cannot specify the current command ID (can’t target self). For onChange, targets must exist and occur after the current Command in the Command list (onRemove is the opposite, must occur before), or there will be an error during compilation.

These IDs can only target IDs within the current Command list:

[
  {
    "id": "a",
    "commands": [
      {
        "id": "b"
      },
      {
        "id": "c"
      },
    ],
  },
  {
    "id": "d"
  }
]

In this example, b can target c but cannot target d.

remove

String, the commands or executable to run during Remove Mode. Can be multiple lines. Will be appended to exec.command. Should return 0 if successful, otherwise it will produce an error.

removeAfter

Boolean, will change the ordering of remove to be executed after the Command’s change is ran. By default, remove is executed before change.

stdin

String, sets the stdin for the Command for change, check, and remove.