# SPDX-License-Identifier: Apache-2.0
# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json
#
# 08 · Config — the deployment's authority.
#
# Four authorities can put a value in a workflow. The path has shown two:
# `inputs:` (the caller, per run) and `const:` (the author, fixed in the
# file). `config:` is the third: non-sensitive knobs that belong to the
# DEPLOYMENT — a region, a verbosity switch — read as `${{ config.x }}`.
# The fourth, `secrets:`, needs a real credential and lives with the jobs
# (CONVENTIONS §3).
#
# Demonstrates ·
#   - `config:` · typed, `default:`-carrying deployment knobs
#   - declared-only resolution · an undeclared `${{ config.x }}` is
#     `NIKA-VAR-001` — the engine NEVER falls back to the OS environment
#     (spec/01-envelope.md §config)
#   - `when:` on a config flag · a quiet run and a verbose run, one file
#   - who supplies what · the caller's `--var` reaches `inputs:` ONLY
#
# Run · nika run examples/08-config-values.nika.yaml
#   The verbose twin · flip `verbose.default` to true and run again.
#   Supplying config at launch is an engine-launch concern
#   (spec/01-envelope.md §config); the reference engine resolves `config:`
#   from its declared `default:`.

nika: v1
workflow:
  id: config-values

permits:
  tools: ["nika:jq", "nika:log"]

inputs:
  team:
    type: string
    default: "atelier"
    required: true
    description: "Whose report this is — the CALLER's value · --var team=…"

config:
  # The deployment's knobs. `type:` is required; `default:` is what makes
  # this file runnable everywhere. The caller cannot reach these — measured:
  # `--var region=us` refuses with `unknown input — the workflow declares:
  # team`. Never a credential here: config values appear in logs and traces
  # (spec/01-envelope.md §config-vs-secrets) — a value that must stay
  # masked belongs to `secrets:`.
  region:
    type: string
    default: "eu"
    description: "Which region label the report carries"
  verbose:
    type: bool
    default: false
    description: "Emit the debug dump task when true"

const:
  # The author's number — fixed in the file, never supplied by anyone.
  window_days: 7

tasks:
  report:
    invoke:
      tool: "nika:jq"
      args:
        input:
          team: "${{ inputs.team }}"
          region: "${{ config.region }}"
          window_days: "${{ const.window_days }}"
        expression: '. + {title: "\(.team) · \(.region) · last \(.window_days) days"}'

  debug_dump:
    with:
      report: ${{ tasks.report.output }}
    # A config flag routes WORK — it never stands in for a human decision
    # (spec/10-authority.md · "a `when:` on a config flag is not a gate").
    # False by default: this task settles `skipped`, and nothing downstream
    # reads it, so the quiet run stays quiet. The shape rule (cel-subset)
    # wants an explicit relation — `== true`, never the bare flag.
    when: ${{ config.verbose == true }}
    invoke:
      tool: "nika:log"
      args:
        level: debug
        message: "full report object"
        data: "${{ with.report }}"

outputs:
  report:
    value: ${{ tasks.report.output }}
    description: "The shaped report · title carries team + region + window"

the path · 08

Config — the deployment's authority.

run itnika try 08-config-values

08-config-values.nika.yaml

1# SPDX-License-Identifier: Apache-2.02# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json3#4# 08 · Config — the deployment's authority.5#6# Four authorities can put a value in a workflow. The path has shown two:7# `inputs:` (the caller, per run) and `const:` (the author, fixed in the8# file). `config:` is the third: non-sensitive knobs that belong to the9# DEPLOYMENT — a region, a verbosity switch — read as `${{ config.x }}`.10# The fourth, `secrets:`, needs a real credential and lives with the jobs11# (CONVENTIONS §3).12#13# Demonstrates ·14#   - `config:` · typed, `default:`-carrying deployment knobs15#   - declared-only resolution · an undeclared `${{ config.x }}` is16#     `NIKA-VAR-001` — the engine NEVER falls back to the OS environment17#     (spec/01-envelope.md §config)18#   - `when:` on a config flag · a quiet run and a verbose run, one file19#   - who supplies what · the caller's `--var` reaches `inputs:` ONLY20#21# Run · nika run examples/08-config-values.nika.yaml22#   The verbose twin · flip `verbose.default` to true and run again.23#   Supplying config at launch is an engine-launch concern24#   (spec/01-envelope.md §config); the reference engine resolves `config:`25#   from its declared `default:`.2627nika: v128workflow:29  id: config-values3031⛨permits:32  ⛨tools: ["nika:jq", "nika:log"]3334inputs:35  team:36    type: string37    default: "atelier"38    required: true39    description: "Whose report this is — the CALLER's value · --var team=…"4041config:42  # The deployment's knobs. `type:` is required; `default:` is what makes43  # this file runnable everywhere. The caller cannot reach these — measured:44  # `--var region=us` refuses with `unknown input — the workflow declares:45  # team`. Never a credential here: config values appear in logs and traces46  # (spec/01-envelope.md §config-vs-secrets) — a value that must stay47  # masked belongs to `secrets:`.48  region:49    type: string50    default: "eu"51    description: "Which region label the report carries"52  verbose:53    type: bool54    default: false55    description: "Emit the debug dump task when true"5657const:58  # The author's number — fixed in the file, never supplied by anyone.59  window_days: 76061tasks:62  report:63    ◆invoke:64      tool: "nika:jq"65      args:66        input:67          team: "${{ inputs.team }}"68          region: "${{ config.region }}"69          window_days: "${{ const.window_days }}"70        expression: '. + {title: "\(.team) · \(.region) · last \(.window_days) days"}'7172  debug_dump:73    with:74      report: ${{ tasks.report.output }}75    # A config flag routes WORK — it never stands in for a human decision76    # (spec/10-authority.md · "a `when:` on a config flag is not a gate").77    # False by default: this task settles `skipped`, and nothing downstream78    # reads it, so the quiet run stays quiet. The shape rule (cel-subset)79    # wants an explicit relation — `== true`, never the bare flag.80    when: ${{ config.verbose == true }}81    ◆invoke:82      tool: "nika:log"83      args:84        level: debug85        message: "full report object"86        data: "${{ with.report }}"8788outputs:89  report:90    value: ${{ tasks.report.output }}91    description: "The shaped report · title carries team + region + window"92

nika-spec@6ac29351a · sha256 72d424ded003aa8e…