aicoded.dev

Settings and secrets

Settings are named values the app is configured with, such as the address of a team; secrets are values nobody may see, such as an API key. The permission list names both, the runner holds their values, and the app reads them with config.String and secrets.Get.

Declaring them

settings: [team_address, report_day]
secrets: [partner_api_key]

Names are lowercase letters, digits and _, start with a letter and appear once (E-MAN-005). The values are never in the permission list or the repository.

Reading a setting

team, err := config.String(ctx, "team_address")

Reading a secret

key, err := secrets.Get(ctx, "partner_api_key")
if err != nil {
	return err
}
mac := hmac.New(sha256.New, []byte(key.Reveal()))

Both need the context of the app: a request's, a hook's or the one OnStart gets. A context made with context.Background() carries no runner and fails with E-RUN-004.

Keys of outside services

A key that an outside service needs is a secret that egress binds to the service's host:

egress:
  - {host: api.weather.example, secret: weather_api_key, header: Authorization, prefix: "Bearer "}
secrets: [weather_api_key]

The runner adds such a key to every request the app sends to that host with outbound.Client(), so the app never reads it: secrets.Get of a bound secret fails with E-RUN-015. Its value is set like any other secret's, in dev.yaml on your computer and in the console on the platform, and a preview uses the preview's value. The runner keeps a value it read for up to a minute, so a changed key takes effect within a minute. See outside services.

Local values

On your computer, the values come from dev.yaml, outside the repository, under the app's name in its workspace:

workspaces:
  /absolute/path/to/apps:
    apps:
      people:
        settings: {team_address: team@acme.example}
        secrets: {partner_api_key: local-test-key}

See aicoded dev for the rest of dev.yaml.

On the platform

On the platform, the values are set in the console, for each app, by the app's owner or a security admin; neither the app, its builder nor an AI assistant can set them, and the console never shows a secret's value once it is set. A release whose permission list declares a setting or a secret with no value is refused with E-REL-022, which lists the names: ask the app's owner or a security admin to set them, and a Pre-approved publish whose release was asked for goes live by itself about a minute later. Each change of a value is in a change record: a setting's with its value, a secret's without it.

See also

Markdown · Source on GitHub · framework f46741f