Environments

Long-lived dev, staging, and prod branches mapped 1:1 to GitHub Environments, with per-environment YAML config and a typed Python loader.

Artemis City ships with three long-lived environment branches that map 1:1 to GitHub Environments and deploy targets. Use them to separate integration work from pre-production rehearsals and production traffic, and to keep production credentials unreachable from lower environments.

The names dev, staging, and prod are kept identical across the branch, the GitHub Environment, and the file under config/environments/ so there is no mapping layer to forget.

When to use this

• You are deploying Artemis City from a fork or self-hosted clone and need a promotion path between dev, staging, and prod.
• You want CI to run on every push and PR to each environment branch, with the active config validated automatically.
• You want production secrets and approvals enforced by GitHub Environments rather than living in repo-wide secrets.

If you only run Artemis City locally, you can ignore the branch and workflow setup and just set ARTEMIS_ENV=dev (the default) when loading config.

Branches and approvals

Branch	GitHub Environment	Purpose	Approvals
dev	dev	Integration of feature work	0
staging	staging	Pre-production rehearsal, synthetic data	1
prod	prod	Production. Default branch.	2

Promotion flow:

feature/* --PR--> dev --PR--> staging --PR--> prod

Feature branches always target dev. Promote dev → staging and staging → prod either by opening a PR manually or by running the Promote workflow from the Actions tab, which opens a draft PR with the right base and head.

Configuration files

Each environment has a YAML file under config/environments/:

• config/environments/dev.yaml
• config/environments/staging.yaml
• config/environments/prod.yaml

A dev.yaml looks like this:

name: dev
description: Local and shared developer integration environment.

mcp:
  base_url: http://localhost:3000
  log_level: DEBUG

obsidian:
  base_url: http://localhost:27124

exo:
  base_url: http://localhost:52415

vector_store:
  path: data/vector_store.dev.db

governance:
  strict_atp: false
  trust_default_level: 2

deploy:
  branch: dev
  github_environment: dev
  approvals_required: 0

Keep the same top-level keys across all three files so the loader can return a consistent shape. Secrets do not belong in these YAML files — they live in per-environment GitHub Environment secrets.

Selecting the active environment

The active environment is selected by the ARTEMIS_ENV variable. Valid values are dev, staging, and prod; unset defaults to dev.

# .env or shell
ARTEMIS_ENV=staging

Load the matching config in code:

from src.utils.environments import load_environment, current_environment

env = current_environment()      # "dev" | "staging" | "prod"
cfg = load_environment()         # respects ARTEMIS_ENV, defaults to dev
cfg = load_environment("prod")   # or load an explicit environment

load_environment() raises ValueError if ARTEMIS_ENV is set to anything outside the valid set, and FileNotFoundError if the YAML file for the requested environment is missing — both surface early in CI.

Workflows

The repo ships three workflows wired to the environment branches:

• ci.yml — runs on every push and PR to dev, staging, prod. Runs the test suite and asserts the env loader can round-trip all three configs.
• deploy.yml — runs on push to an env branch and deploys to the matching GitHub Environment. The deploy step is a provider-agnostic placeholder; wire your container build or aws / az / gcloud deploy action there.
• promote.yml — manual workflow that opens a draft promotion PR (dev → staging or staging → prod) on demand.

The previous third-party apisec-scan and jscrambler-code-integrity workflows have been removed. API security scanning and JavaScript code protection should be handled through alternative mechanisms outside the default workflow set.

One-time setup after merge

1. Default branch. Settings → Branches: rename main → prod, set prod as the default branch, and delete the old main ref.
2. GitHub Environments. Settings → Environments: create dev, staging, and prod. Attach required reviewers, wait timers, and per-environment secrets (cloud credentials belong here, not in repo-wide secrets).
3. Branch protection. Require CI green and the approval counts above on dev, staging, and prod before merging. These rules live under Settings → Rules → Rulesets as Protect dev, Protect staging, and Protect prod.
4. Provider wiring. Replace the placeholder Deploy step in deploy.yml with the chosen provider action (AWS, Azure, GCP, etc.).

Secrets model

Secrets are scoped per GitHub Environment, not per repo, so production credentials are unreachable from dev or staging deploys. A workflow that targets the dev environment can only read dev secrets, even if it runs from a branch with write access to the repo. Required approvals are configured on the Environment itself in repo Settings, so promotion to prod always passes through reviewer gates regardless of who opens the PR.