Secrets and Variables
Store a value once in the Manager, then map it into a repository's shell environment from .ocm/project.json. Secrets and variables use the GitHub Actions reference syntax, so the same mapping text works in a workflow and in the Manager.
Scopes
A value is stored at one of three scopes:
| Scope | Applies to | Managed in |
|---|---|---|
| Global | Every repository on the Manager | Settings → OpenCode Config → Server maintenance → Secrets and variables |
| Repository | One repository and its worktrees | The repository's Secrets tool in the desktop tool rail, or More → Secrets on mobile |
| Environment | A repository entry labelled with an environment name, such as e2e | The same Secrets tool: a repository entry has an optional Environment field |
When the same name exists at several scopes, the most specific one wins: an environment entry first, then the repository entry without an environment, then the global entry. Global entries cannot carry an environment.
Secrets and variables are separate namespaces, so API_URL can exist as both. Secret values are encrypted in the Manager database and are never shown again once saved; variable values are stored in plain text and stay visible.
Mapping Values Into a Repository
Storing a value does nothing on its own. A repository opts in from .ocm/project.json, in the same file that defines its project actions and worktree setup commands:
{
"version": 1,
"environment": "e2e",
"env": {
"OPENAI_API_KEY": "${{ secrets.OPENAI_API_KEY }}",
"BASE_URL": "${{ vars.BASE_URL }}"
}
}
environmentis optional. When it names an environment, repository entries stored under that name are visible to this repository; entries without an environment stay visible either way.envmaps an environment variable name to a value template. Up to 100 entries are allowed.- A template may be a single reference or literal text around one, such as
postgres://app:${{ secrets.DB_PASSWORD }}@localhost/app. - The reference context is case-insensitive and the name is normalized to upper case. Only
${{ secrets.NAME }}and${{ vars.NAME }}are accepted; any other expression makes the file invalid. - A reference with no matching secret or variable resolves to an empty string, matching GitHub Actions. The rest of the template is still used.
Where Values Are Injected
Values reach the shells the Manager and the agent start, and nothing else:
| Execution path | Receives the mapping |
|---|---|
Agent shell tool calls in a local repository | Yes |
Composer !command shell mode | Yes |
| PTY terminals, including the Terminal panel | Yes |
| Project actions and worktree setup commands | Yes |
Agent shell tool calls in a sandboxed session | Yes, forwarded into the microVM |
| OpenCode file tools, plugins, custom tools, MCP servers, formatters, LSP servers, hooks | No; they run in OpenCode's own process environment |
| Repositories on a linked server | No; a linked server runs its own OpenCode process |
The mapping is resolved per directory: a worktree of the repository resolves the same values as the main checkout, because both belong to the same project, and a shell started outside a repository the Manager knows resolves nothing.
Trust
The environment and env mapping is part of the content that must be trusted, alongside actions and setup commands:
- Until the file is trusted, the mapping is ignored and no values are injected.
- Trust covers the whole file, so reviewing a file for its actions also trusts the mapping it declares.
- Both trust prompts list the mapping: the environment name and each
KEY = templateline appear under Environment variables, so you can see what a file will read before you trust it. - Changing the mapping resets trust, exactly like changing an action's command.
Masking
Values that came from ${{ secrets.NAME }} are replaced with *** in tool output before the model sees it, so printenv or env does not put the secret into the transcript.
Masking is a display safeguard, not confinement:
- Only secret values are masked. Values from
${{ vars.NAME }}are shown as-is. - Masking matches the exact string, and only values of four characters or more.
base64,rev, a split, a substring, or an escaped form defeats it. - The agent can read its own environment, so a prompt-injected agent can still exfiltrate a value through a command whose output the mask does not recognize.
Naming and Limits
| Rule | Value |
|---|---|
| Secret and variable name | Letters, numbers, and underscores, starting with a letter or underscore; upper-cased on save; at most 255 characters; must not start with GITHUB_ |
| Reserved names and prefixes | PATH, HOME, NODE_OPTIONS, TMPDIR, XDG_*_HOME, OCM_*, OPENCODE_*, GIT_CONFIG_*, MSB_*, LD_* |
| Secret value | At most 48 KiB, non-empty |
| Environment name | 1–64 characters of letters, numbers, dots, underscores, or hyphens; lower-cased on save |
env variable name | The same name pattern; GH_TOKEN, GITHUB_*, and GIT_* are reserved for git; the Manager supplies GH_TOKEN / GITHUB_TOKEN from the repository's GitHub credential and GIT_AUTHOR_* / GIT_COMMITTER_* from its git identity |
env value | At most 4000 characters |
Related
- Project Actions — the repository file these values are mapped in, and its trust rules.
- Agent Sandboxing — how the mapping crosses into a session's microVM.
- Environment Variables — the server-side variables that configure the Manager itself.