The .sekreton/config.toml file

One file at the root of your repository tells Sekreton how to check, build and ship the project. Because it is versioned with the code, an agent that changes how the project builds or deploys changes this file in the same task, and you review both together. You don't need a CI pipeline file for any of it.

A complete example

schema = 1

[setup]
run = ["npm ci"]

[jobs.lint]
run = "npm run lint"

[jobs.test]
dir = "web"
env = { CI = "1" }
run = ["npm test -- --run"]

[environment]
packages = ["postgresql-client"]

[deploy.staging]
setup = "curl -L https://fly.io/install.sh | FLYCTL_INSTALL=\"$DEPLOY_TOOL_DIR\" sh"
secrets = ["FLY_API_TOKEN"]
on_merge = true
run = "scripts/deploy.sh staging"

[deploy.production]
setup = "curl -L https://fly.io/install.sh | FLYCTL_INSTALL=\"$DEPLOY_TOOL_DIR\" sh"
secrets = ["FLY_API_TOKEN"]
run = "scripts/deploy.sh production"

[publish.npm]
setup = "npm ci"
secrets = ["NPM_TOKEN"]
run = ["npm run build", "npm publish"]

Every table is optional. Any key not listed on this page is an error that names the key, so a typo can't silently do nothing.

schema

schema = 1 is required as soon as the file has a [setup], [jobs.*], [deploy.*] or [publish.*] table. A file with only an [environment] table can leave it out.

[setup]

run is a command, or a list of commands that stops at the first one that fails. It runs once in the task's checkout before any job. It replaces the setup command in the project's settings.

[jobs.<name>]

Each job is a check the work must pass before it can be merged. A job name is 1 to 64 letters, digits, ., _ or -, starting with a letter or digit.

• run (required): a command, or a list of commands run in order.
• dir: the directory inside the checkout to run from.
• env: environment variables for the job, as a table of strings.

The task branch's copy of the file runs, so a branch can add or change jobs. Every job on the base branch is still required by name, so a job can't be skipped by deleting it on a branch. Jobs are read-only and never change the branch. Without the file, the project's Build & gates settings stand in as jobs. Once the base branch's file sets schema, its [setup] and jobs replace those settings even when it declares none, so a file added just for a [deploy.*] table should carry the project's jobs too.

[environment]

packages is a list of up to 64 Debian package names installed into the project's sandbox image. Nothing runs as root inside the sandbox, so system packages go here rather than in a setup command.

[deploy.<name>] and [publish.<name>]

Each table is an action you can run from the board or the project's Deploy & Publish settings. Names follow the same rule as job names.

• run (required): a command, or a list of commands that stops at the first one that fails.
• setup: commands run before run, the same shape as run.
• secrets: the names of the project secrets the action needs.
• on_merge: true to run the action every time work is merged into the base branch.

How an action runs:

• In a fresh sandbox with a checkout of the base branch, not in a task's checkout.
• With $DEPLOY_TOOL_DIR ($PUBLISH_TOOL_DIR for publish) and its bin/ on PATH. The directory persists between runs, so install a CLI there once in setup.
• For at most an hour. Not as root.
• With only the secrets it lists, as environment variables. If one isn't set, the run fails before setup and says which one, and settings shows it as needed so you can add it.

Which copy takes effect

Only the base branch's copy declares actions. A task branch's copy is parsed when the task is checked, so an invalid table fails verification, but it takes effect only once it is merged. That merge is the trust boundary: what a task's agent writes can't run with your secrets until you have reviewed and merged it.

• An action declared in the file runs exactly as committed. Settings shows it read-only, and the run dialog won't let you edit its command.
• Renaming a table makes a new action. Past runs of the old one stay on the board.
• on_merge alone decides whether the action runs on merge. You can pause that under Settings → Automations, and the pause holds. On a project that ships by pull request, Sekreton never merges, so on_merge has no effect.
• If an action made in settings already has the same kind and name, the settings action wins and settings shows the conflict until you rename one.
• If the base branch's file doesn't parse, the last good actions stay in place and settings shows the error.

Secrets

Secret values are set in the project's Deploy & Publish settings, never in the file. They are encrypted and can't be read back. Only their names go in secrets, and agents only ever see the names.