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:

ScopeApplies toManaged in
GlobalEvery repository on the ManagerSettings → OpenCode Config → Server maintenance → Secrets and variables
RepositoryOne repository and its worktreesThe repository's Secrets tool in the desktop tool rail, or More → Secrets on mobile
EnvironmentA repository entry labelled with an environment name, such as e2eThe 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 }}"
  }
}
  • environment is 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.
  • env maps 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 pathReceives the mapping
Agent shell tool calls in a local repositoryYes
Composer !command shell modeYes
PTY terminals, including the Terminal panelYes
Project actions and worktree setup commandsYes
Agent shell tool calls in a sandboxed sessionYes, forwarded into the microVM
OpenCode file tools, plugins, custom tools, MCP servers, formatters, LSP servers, hooksNo; they run in OpenCode's own process environment
Repositories on a linked serverNo; 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 = template line 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

RuleValue
Secret and variable nameLetters, 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 prefixesPATH, HOME, NODE_OPTIONS, TMPDIR, XDG_*_HOME, OCM_*, OPENCODE_*, GIT_CONFIG_*, MSB_*, LD_*
Secret valueAt most 48 KiB, non-empty
Environment name1–64 characters of letters, numbers, dots, underscores, or hyphens; lower-cased on save
env variable nameThe 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 valueAt most 4000 characters