Skip to main content
orun has no built-in concept of a named environment — instead, it uses Git branches. Each node tracks exactly one branch, and everything on that node derives its configuration from manifests on that branch. Promoting a change from staging to production is a standard Git merge. Creating an ephemeral environment is opening a new branch.

​
How branches map to environments

When you run orun bootstrap, the node is configured with a gitBranch value in its Node manifest. From that point on, the node only reads manifests from that branch. Nodes on different branches are completely independent: they share no state, no communication channel, and no coordination mechanism. 
# nodes/web-prod.yaml — tracks main
spec:
  gitBranch: main

# nodes/web-staging.yaml — tracks staging
spec:
  gitBranch: staging
The gitBranch field defaults to main when omitted. To track a different branch, set it explicitly in the Node manifest before running orun bootstrap.

​
Production vs. non-production

orun distinguishes two environment classes:
  • Production — the primary environment, typically the node tracking main
  • Non-production — all other environments: staging, feature branches, ephemeral worktrees
The domain resolver uses this classification to decide whether to use ingress.domain.default or the ingress.domain.environment template when building the service URL.

​
Worktrees as ephemeral environments

Git worktrees let you check out a branch into a separate directory without affecting the main working tree. orun uses worktrees to scope resources for ephemeral environments. When a node tracks a worktree named feat-auth, orun scopes that environment’s resources with a dot-separated prefix — for example, feat-auth. — to prevent naming collisions with production or staging resources on the same host.

​
Service domain templates

The ingress.domain.environment field in a Service manifest uses $ENV as a placeholder. At runtime, orun replaces $ENV with the environment suffix derived from the branch name or worktree name. 
apiVersion: run.orcra.dev/v0alpha
kind: Service
metadata:
  name: hello-world
spec:
  deployment: hello-world
  ingress:
    domain:
      default: hello-world.orcra.dev
      environment: hello-world.$ENV.orcra.dev
    ssl: true
With this configuration:
Branch / environmentResolved domain
main (production)hello-world.orcra.dev
staginghello-world.staging.orcra.dev
feat-auth worktreehello-world.feat-auth.orcra.dev
The ingress.domain.default value is used for production nodes where no environment suffix applies. The ingress.domain.environment template is used for all other nodes.

​
Branch-per-environment pattern

The recommended pattern is one branch per long-lived environment and short-lived branches for ephemeral feature environments:
1

Create a node manifest per environment

Write a separate Node manifest for each environment. Point each at the correct branch and host.
nodes/
  web-prod.yaml      # gitBranch: main
  web-staging.yaml   # gitBranch: staging
  web-feat-auth.yaml # gitBranch: feat-auth
2

Bootstrap each node

Run orun bootstrap once per node manifest. After bootstrap, each node tracks its own branch independently.
orun bootstrap nodes/web-prod.yaml
orun bootstrap nodes/web-staging.yaml
3

Deploy to staging by pushing to the staging branch

Merge or cherry-pick changes to staging. The staging node picks them up within one poll cycle (default 5s) without any manual deploy step.
git checkout staging
git merge feat-auth
git push origin staging
4

Promote to production by merging to main

When staging looks good, merge to main. The production node reconciles automatically.
git checkout main
git merge staging
git push origin main

​
Setting up multiple environments

# nodes/web-prod.yaml
apiVersion: run.orcra.dev/v0alpha
kind: Node
metadata:
  name: web-prod
spec:
  host: 203.0.113.10
  gitRepo: git@github.com:org/manifests.git
  gitBranch: main

# nodes/web-staging.yaml
apiVersion: run.orcra.dev/v0alpha
kind: Node
metadata:
  name: web-staging
spec:
  host: 203.0.113.20
  gitRepo: git@github.com:org/manifests.git
  gitBranch: staging
Name your nodes to match their environment (for example, web-staging, web-prod). Because node manifests are committed to the repository, the name appears in Git history and makes it easy to trace which host a configuration change targeted.
Each node independently decides what to run based solely on the manifests in its branch. If you delete a Deployment manifest from main without first removing it from staging, the staging node continues running that container. Always review all branches before removing shared resources.

How orun reconciles containers

Understand the pull-based reconciliation loop that drives every node.

Manifest repository structure

Reference for Node, Deployment, and Service manifest fields.