runtime_secrets
Secrets such as API keys: sandboxes see a placeholder, and the egress proxy adds the value on HTTPS to the hosts you name. exposed: true gives named machines the value itself. set(name, value, hosts?, header?, format?, rules?, only?, githubApp?, git?, api?, env?, exposed?, expectedVersion?): Store or replace one. Sandboxes see a placeholder in the environment variable of this name; the egress proxy swaps in the value in a credential header (Authorization, x-api-key and the like) of HTTPS requests to hosts, or sets header on each; never in the URL or another header. rules (an account with credit) limit it by method and path. exposed: true gives the machines only names by id the value itself. The value is never returned. list(after?, limit?): Names, kind (exposed), version, hosts, header and placeholder; never values. By name, limit at a time (default 50); pass the answer's next as after for the next page. get(name): One by name, as list shows it; never its value. delete(name): Erase one by name; its placeholder stops being replaced. It does not revoke the key at its provider. jobs_ actions: the copy a scheduled job puts in its run's environment. jobs_list(after?, limit?), jobs_get(id), jobs_put(name, value), jobs_rotate(id, value, expectedVersion), jobs_delete(id, expectedVersion), jobs_share(id, agents), jobs_reveal(id, version?). Bind one with runtime_jobs create input.secrets: [{name: ENV_NAME, secretId}]. It belongs to the person whose key stored it and is versioned; a deleted name cannot be reused. Only the key that stored it, the agents it names and its person may list, bind, reveal, rotate or delete it; share(id, agents) replaces the agents named (only its person or the key that stored it). delete stops future use, not the provider's token; reveal shows a value and needs its own permission, so prefer binding.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| api | No | Optional. Each sandbox's hour with the secret, the far end's reserve, GraphQL's mutations and shared copies. | |
| env | No | Optional. The variable the placeholder (or the real value) is in, when not the secret's name. Secrets whose scopes (only) share no sandbox may share one, such as one GITHUB_TOKEN per repository; two in one sandbox is 409. The secret's own name gives the name back; absent on a replacement, the variable stays. | |
| git | No | Optional. What a git push over HTTPS carrying the secret may update. A push to any other ref, a tag, or a delete is refused before it leaves the server, in git's own words (! [remote rejected]). The API is held to the same: with git, the secret makes an API write only when its rules name it (none without rules) and a GraphQL mutation only when api.graphql lists it; even then it makes no REST call that writes a file, merges, makes or deletes a ref, renames or protects a branch, or makes a release, moves by PATCH only a branch its patterns allow, and makes no GraphQL mutation that does any of these (createCommitOnBranch, updateRef, mergePullRequest and the like). With githubApp, git needs githubApp.permissions, without admin, administration or secrets, and workflows, actions and environments at most read. | |
| name | No | The secret's name, unique in the organization, and the environment variable its placeholder is in unless env names another. Upper case letters, digits and underscores. | |
| only | No | Optional. Which sandboxes get the secret: those matching labels, those named in sandboxes, and every copy of the Apps in apps; any other sees no placeholder and never sends the value. {} is every sandbox. Absent: a replacement keeps its scope, a new secret goes to every sandbox. A real value (exposed) needs sandboxes or apps, no labels. | |
| after | No | The next of the previous page: the secrets named after it. | |
| hosts | No | Where the value may go: the proxy puts it only into HTTPS requests to these hosts. Required unless exposed. | |
| limit | No | Page size, 1 to 100. | |
| rules | No | Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them. | |
| value | No | The secret. Visible ASCII and spaces, at most 8 KiB; with githubApp, the App's PEM private key; with exposed, any text up to 64 KiB, several lines too. Stored sealed and never returned. | |
| action | Yes | ||
| agents | No | share: the principalId of each agent (GET /v1/me) that may use it besides the key that stored it; [] leaves only that key. | |
| format | No | Optional, with header. The header's value, with {value} where the secret goes. Default "{value}". | |
| header | No | Optional. Set this header on every request to the hosts, replacing the sandbox's, so code needs no placeholder; the value goes into it and nowhere else. Without it, the placeholder is replaced only in a credential header: Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token. | |
| exposed | No | Optional. true: the machines only names by id get the value itself, no hosts. The key needs exec in each; give it on every write. | |
| version | No | ||
| githubApp | No | Optional. The value is this GitHub App's private key (PEM), and the servers make its installation tokens themselves, each for an hour: the key goes into no request, and each request the rules allow carries the current token, as Authorization: Bearer to the API and as git's x-access-token to git over HTTPS. Takes no header or format. | |
| idempotencyKey | No | Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error. | |
| expectedVersion | No | Optional. Write only over this version (0: a new one); else 409. |