Patterns

Patterns are what Etcha uses to build and run Commands.

Build vs Run

Patterns have two separate list of Commands: build and run. build Commands are ran on the local instance when the Pattern is built using etcha build. run Commands are ran on an instance when a Pattern is push, pulled, manually applied via CLI, or triggered via eventsReceive and webhookPaths in a source.

Jsonnet

Patterns are typically written in Jsonnet. A Pattern will have one “entrypoint” file with the extension .jsonnet, such as main.jsonnet. This file should return a JSON object containing the Pattern Properties. It can import other Jsonnet files (with the file extension .libsonnet) or any other file to create the Pattern.

Properties

audience

String, a list of audience values to set in the JWT aud property.

build

A list of Commands to execute when building a JWT.

buildExec

See exec. Specifies a custom exec configuration for the Pattern build Commands. Parent exec configurations must allow overrides for this to work.

buildOutput

Specifies the path and filename for the output build JWT. Defaults to etcha.jwt.

expiresInSec

Integer, specifies the number of seconds from the current time until the JWT expires. Defaults to 0/JWTs do not expire. If a JWT expires, it will not be trusted/ran.

id

String, the ID to set in the JWT jti property.

issuer

String, the Issuer to set in the JWT iss property.

run

A list of Commands to execute when a Pattern is push, pulled, manually applied via CLI, or triggered via eventsReceive and webhookPaths in a source.

runExec

See exec. Specifies a custom exec configuration for the Pattern run Commands. Parent exec configurations must allow overrides for this to work.

runVars

A map of values that will be combined with vars when the Pattern is rendered. These can be set for Patterns by specifying them in the Pattern config, or by using the [runVar_ build event]({{ ref “/docs/references/events#runvar” }}).

These are exposed using the Jsonnet native function, getConfig, for rendering these values during a run:

{
  run: [
    id: 'run a thing',
    change: std.native('getConfig')().vars.myVar,
  ],
}

subject

String, the Subject to set in the JWT sub property.

Rendering

Patterns are rendered from Jsonnet everytime they are ran. That means all of the Jsonnet functions, lookups, and environment variables are all executed/evaluated on the current instance that is running the Pattern.

Variables

The native Jsonnet function, getConfig() object, can be used to retrieve the combined exec and vars for the source. Given a configuration like this:

{
  "sources": {
    "source1": {
      "exec": {
        "command": "/bin/bash"
      },
      "vars": {
        "var1": false,
        "var2": "value"
      }
    }
  },
  "vars": {
    "var1": true,
    "var2": "original"
  }
}

Running getConfig().exec within a Pattern for the source source1 will render a Jsonnet object like this:

{
  "command": "/bin/bash"
}

Running getConfig().vars within a Pattern for the source source1 will render a Jsonnet object like this:

{
  "var1": false,
  "var2": "value",
  "var3": "original"
}