Secrets And Randoms

Three storage locations exist for "values the launcher / template needs":

1. Template variable — declared in x-fibe.gg.variables, bound at template launch.
2. Fibe Secret — separately managed resource referenced by ID.
3. Job ENV entry — Player-scoped or Prop-scoped env vars injected only into job-mode runs.

Pick by lifecycle and audience.

Decision matrix

Value	Storage	Why
App-level config (APP_NAME, DB_PASSWORD, RAILS_ENV) at launch	Template variable	Set once at launch, reused across the lifetime of the Playground.
Generated password for a Postgres in this template	Template variable, random: true	Fibe generates once, reuses on subsequent compiles. Persistent for the Playground.
Sensitive API token to talk to a third party (Stripe, OpenAI)	Fibe Secret	Lives outside the template, audited, can be rotated without changing the template.
Anything you want hidden in launcher UI	Template variable + secret: true and/or sensitive: true	UI cosmetic; the schema permits the flags.
Per-Player or per-Prop secrets injected into job-mode runs	Job ENV entry	Job runs only — won't leak into long-running services.

When to use template variables

Default. Anything that is part of the template launch and not super-secret. Use random: true for values that should be generated by Fibe and persisted, like a DB password that lives inside this Playground and is never seen elsewhere:

x-fibe.gg:
  variables:
    DB_PASSWORD:
      name: "Database password"
      required: true
      random: true
      paths:
        - services.postgres.environment.POSTGRES_PASSWORD
        - services.app.environment.DB_PASSWORD

Optional UI flags:

slack_webhook_url:
  name: "Slack Incoming Webhook URL"
  required: false
  secret: true        # mask in launcher UI
  sensitive: true     # logs/telemetry should not surface
  default: ""
  paths:
    - services.notify.environment.SLACK_WEBHOOK_URL

Use this combination for values such as Slack webhook URLs. See recipe-random-and-secrets.

When to use Fibe Secrets

When the value is not specific to this template — it's the Player's credential for an external service (Stripe key, Anthropic API key, GitHub token, S3 credentials). Secrets are a separate resource.

• Manage via fibe_resource_mutate(resource: "secret", operation: "create"|"update") then reference by ID.
• Reads return non-revealed metadata.
• The template should expose a variable that names which Secret to use, not the Secret value itself.

In job-mode templates, prefer Secrets for credentials so they aren't visible to the launcher UI.

When to use Job ENV entries

Only for job-mode templates. Job ENV entries are key→value pairs at Player scope OR Prop scope. They are injected at job launch into every service of the matching job-mode template.

• Global Job ENV applies to every job-mode Playground launched by the Player.
• Prop-scoped Job ENV applies only when the job-mode template uses that Prop.
• Manage via fibe_resource_mutate(resource: "job_env", operation: "create"|"update") and list via fibe_resource_list(resource: "job_env").

Use case: "every CI job should have an NPM_TOKEN" — set it once as a Job ENV, no need to put the value in the template.

Random secrets — what to know

random: true generates a 32-character lowercase hex value at compile time. Once persisted for that launch, it is reused on subsequent compiles so the password is stable across rollouts.

To rotate, the runtime supports regenerate_variables: ["DB_PASSWORD"] — used by template-author tooling, not exposed to general launchers.

Combine required: true + random: true to make the variable required AND auto-generate when not supplied. Fibe generates the value before the required check, so the combination succeeds without user input.

Where to write the value

• For container ENV: use path: / paths: pointing at services.<name>.environment.<KEY>.
• For label values: target services.<name>.labels.fibe.gg/<key>.
• For inline string composition (e.g. DATABASE_URL): use $$var__NAME inside the string.

Anti-patterns

• Storing a secret as a default: value — it lives in plain YAML, in the template body, in everyone's git history. Use random: true (template-scoped) or a Fibe Secret (Player-scoped).
• Letting the launcher type a long-lived API key every time — once is OK; recurring is not. Store as a Fibe Secret, reference by ID in the template variable.
• Putting secrets in environment files committed to a repo — fibe.gg/env_file points at an example. Never put real values there.
• Re-randomizing a DB password on every launch — without persistence the existing data becomes inaccessible. random: true is fine because it persists; do NOT name variables in regenerate_variables unless you intend rotation.

Related skills

recipe-random-and-secrets, recipe-extract-env-variables, reference-template-variables, decide-job-mode, reference-x-fibe-gg-namespace.