Config

Reference documentation for Issu’s configuration

Configuration Sources

Configuration is performed using a JSON/Jsonnet configuration file, environment variables, and command line arguments. Configurations from one source will override previous sources, i.e. environment variables override configuration files, command line arguments override environment variables.

Command Line

Every configuration key can be set using -x <a_config_key1>="a value" -x <a_config_key2>="another value", i.e. -x cli_logLevel=debug -x cli_logFormat=kv. Config values can also be set using JSON, i.e. -x cli='{"logLevel": "debug"}'

Command line values override all other sources.

Environment Variables

Every configuration key can be set using issu_config_key=value, i.e. issu_cli_logLevel=debug. A special environment variable, issu_config can be used to specify a complete JSON/Jsonnet configuration.

Environment Variables override a configuration file.

Configuration File

A configuration file be formatted using JSON or Jsonnet. Underscores in config keys are used to represent nesting, i.e. cli_logLevel represents:

{
  "cli": {
    "logLevel": "debug"
  }
}

Issu looks for issu.jsonnet by default, ascending the directory tree to find it. See the Jsonnet reference for more information. Configuration files are rendered at startup, allowing you to use dynamic Jsonnet functions to dynamically alter the config, i.e.:

local getRecord(type, name, fallback=null) = std.native('getRecord')(type, name, fallback);
local level = getRecord('txt', 'level.candid.dev');

{
  cli: [
    logLevel: level,
  ],
}

You can view the rendered configuration by running issu config.

Configuration Values

`cli`

Configurations for the CLI.

`cli_configPath`

String, path to the configuration file. If a filename without a path is specified, Rot will search parent directories for the filename and use the first one found.

Default: "issu.jsonnet"

`cli_configReload`

String, duration to periodically reload the config and reload the application, if greater than 0. Duration can be specified using time units like “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”, or “d”. “1h5m10s” means one hour, five minutes, ten seconds.

Default: ""

`cli_configWatch`

Boolean, if true then the configPath will be watched for changes. On a change, the application will be reloaded.

Default: false

`cli_logFormat`

String, log format to use for logging: human, kv, or raw.

Default: "human"

`cli_logLevel`

String, log level to use for logging: none, debug, info, or error.

Default: "info"

`cli_logMinStatus`

Number, the minimum status to log for error messages. Used to additionally filter logLevel error. Status roughly map to HTTP status codes:

400 will capture all client and server errors
500 will capture only server errors

Default: 0

`cli_macros`

A map of macros to simplify and template CLI arguments. See Macros for more information.

An example macro looks like this:

{
  "cli": {
    "macro": {
      "mymacro": {
        "argumentsRequired": [
          "argument1"
        ],
        "flags": {
          "d": {
            "usage": "D flag usage!"
          },
        },
        "template": "config",
        "usage": "Mymacro usage!",
      }
    }
  }
}

Default: {}

`cli_macros_[macro]_argumentsRequired`

A list of arguments that are required for the macro.

Default: []

`cli_macros_[macro]_argumentsOptional`

A list of arguments that are optional for the macro.

Default: []

`cli_macros_[macro]_flags`

A map of flags for the macro.

Default: {}

`cli_macros_[macro]_flags_[flag]_default`

A list of strings for the default value of the flag.

Default: []

`cli_macros_[name]_flags_[flag]_options`

A list of strings the flag can be set to.

Default: []

`cli_macros_[name]_flags_[flag]_placeholder`

String, the placeholder name for the flag if it accepts a value.

Default: ""

`cli_macros_[name]_flags_[flag]_usage`

String, the usage instructions for the flag.

Default: ""

`cli_macros_[name]_template`

String, the Go template syntax that will be rendered, appended to the CLI, and ran. The Go template can use these custom functions:

{{ getArg i int f string }}
Get an argument at position i or return fallback f.
{{ getEnv e string f string }}
Get an environment variable e or return fallback f.
{{ getFlag f string }}
Get the flag values for f. For flags with a placeholder, this will be an array of string values, otherwise it will be a boolean.
{{ join s []string sep string }}
Join array s with separator sep.

Default: []

`cli_macros_[name]_usage`

String, the usage documentation for a macro.

Default: ""

`cli_noPaging`

Boolean, disables paging of log output using less.

Default: false

`httpClient`

Configurations for the global HTTP client.

`httpClient_noSystemCA`

Boolean, if true, Tunlr will not use the system certificate authorities. All certificate authorities must be specified using httpClient_tlsCABase64 or httpClient_tlsCAPath or no HTTPS URLs will be trusted.

Default: false

`httpClient_tlsCABase64`

String, base64 encoded PEM certificate used by Tunlr’s HTTP client to validate HTTPS endpoints. If this or tlsCAPath are not specified, Tunlr will only use the system CA certificates to validate certificates.

Default: ""

`httpClient_tlsCAPath`

String, path to a PEM certificate used by Tunlr’s HTTP client to validate HTTPS endpoints. If this or tlsCABase64 are not specified, Tunlr will only use the system CA certificates to validate certificates.

Default: ""

`httpClient_tlsCertificatesBase64`

List of base64 encoded PEM certificate strings used by Tunlr’s HTTP client to perform TLS Client authentication.

Default: ""

`httpClient_tlsCertificatesPath`

List of path strings to PEM certificates used by Tunlr’s HTTP client to perform TLS Client authentication.

Default: ""

`httpClient_tlsKeysBase64`

List of base64 encoded PEM key strings used by Tunlr’s HTTP client to perform TLS Client authentication.

Default: ""

`httpClient_tlsKeysPath`

List of path strings to PEM keys used by Tunlr’s HTTP client to perform TLS Client authentication.

Default: ""

`httpClient_tlsCAPath`

Default: ""

`httpClient_tlsSkipVerify`

Boolean, configures Tunlr’s HTTP client to skip TLS verification for HTTPS endpoints. Use with caution.

Default: false

`httpClient_timeoutDial`

String, duration to wait for HTTP requests to connect. 0 disables the timeout. Duration can be specified using time units like “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”, or “d”. “1h5m10s” means one hour, five minutes, ten seconds.

Default: "10s"

`httpClient_timeoutTLSHandshakeSec`

String, duration to wait for HTTP requests to negotiate TLS. 0 disables the timeout. Duration can be specified using time units like “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”, or “d”. “1h5m10s” means one hour, five minutes, ten seconds.

Default: "10s"

`issuesPath`

String, the relative or absolute path to the directory containing issues. Will be created if it doesn’t exist.

Default: "issues"

`jsonnet`

Configuration toggles for disabling Jsonnet Native Functions. Some of these functions are disabled by default–namely anything that could perform an external call, like running a command, or performing HTTP or DNS requests. These should only be enabled for Jsonnet files you trust, as they could lead to data exfiltration or worse.

`jsonnet_disableGetArch`

Disable the getArch function.

Default: false

`jsonnet_disableGetCmd`

Disable the getCmd function.

Default: true

`jsonnet_disableGetConfig`

Disable the getConfig function.

Default: false

`jsonnet_disableGetEnv`

Disable the getEnv function.

Default: false

`jsonnet_disableGetFile`

Disable the getFile function.

Default: false

`jsonnet_disableGetFileHTTP`

Disable the getFileHTTP function.

Default: true

`jsonnet_disableGetOS`

Disable the getOS function.

Default: false

`jsonnet_disableGetPath`

Disable the getPath function.

Default: false

`jsonnet_disableGetRecord`

Disable the getRecord function.

Default: true

`labels`

Labels is a map of label names to configurations that define labels/metadata for issues. See Labels for more details.

Default:

{
  "labels": {
    "created": {
      "default": ["today"],
      "required": true,
      "type": "date"
    },
    "name": {
      "required": true,
      "type": "name"
    },
    "rank": {
      "default": ["last"],
      "type": "positional"
    },
    "status": {
      "required": true,
      "type": "text",
      "values": [
        "To Do",
        "In Progress",
        "Done",
      ]
    },
    "time": {
      "type": "time"
    }
  }
}

`labels_[label]_default`

Single or list of default string values that are added to issues during creation or organize for the label, if it’s required. Must match regexp and values, if they’re defined.

Default: []

`labels_[label]_required`

Boolean, determines if the label is required. Issues that do not have this label will cause linting failures.

Default: false

`labels_[label]_regexp`

String, a valid Regular Expression to check label values against. Issues that do not have an appropriate value will cause linting failures.

Default: ""

`labels_[label]_type`

String, the type of the underlying Label. See Labels for supported values.

Default: ""

`labels_[label]_values`

Single or list of allowed string values for the label. Issues that do not have a value from this list will cause linting failures.

Default: []

`licenseKey`

String, the Issu license key provided to your organization.

Default: ""

`listColumns`

List of label names to show by default when listing issues.

Default:

{
  "listColumns": [
    "rank",
    "id",
    "name",
    "time",
  ]
}

`listFilter`

String, the default filter to apply when listing issues.

Default: "status!=Done"

`listLimit`

Number, the default number of issues to display when listing.

Default: 10

`listSort`

List of label names to sort by default when listing issues. Issues will be sorted by each label sequentially. ! can be prepended to the label name to invert the sort.

Default: []

`pomodoro`

Configuration for the Pomodoro timer. See [Time Tracking]https://issu.dev/docs/guides/time-tracking/ for more information.

`pomodoro_durationBreakLong`

String, the duration for a Pomodoro long break. Duration can be specified using time units like “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”, or “d”. “1h5m10s” means one hour, five minutes, ten seconds.

Default: "20m"

`pomodoro_durationBreakShort`

String, the duration for a Pomodoro short break. Duration can be specified using time units like “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”, or “d”. “1h5m10s” means one hour, five minutes, ten seconds.

Default: "5m"

`pomodoro_durationPomodoro`

String, the duration for a Pomodoro working session. Duration can be specified using time units like “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”, or “d”. “1h5m10s” means one hour, five minutes, ten seconds.

Default: "25m"

`pomodoro_intervals`

Number, how many Pomodoro intervals until a long break.

Default: 4

`pomodoro_nagSeconds`

Number, how many seconds until a nag notification is emitted repeatedly.

Default: 15