Skip to main content
This guide covers the initial setup required in your service repository (e.g., getsentry/seer) to integrate sentry-options.

​
Prerequisites

Before starting, ensure you understand:
  • Your service’s namespace naming (must be {repo} or {repo}-*)
  • The options your service needs and their types
  • Your service’s Docker build process

​
Setup steps

1

Create your schema

Create a schema definition at sentry-options/schemas/{namespace}/schema.json in your service repository.Namespace naming rules:
  • Must be either {repo} (exact match) or {repo}-* (prefixed)
  • For example, in the seer repo: seer, seer-autofix, seer-grouping are valid
  • autofix alone is not valid
sentry-options/schemas/seer/schema.json
{
  "version": "1.0",
  "type": "object",
  "properties": {
    "feature.enabled": {
      "type": "boolean",
      "default": false,
      "description": "Enable the feature"
    },
    "feature.rate_limit": {
      "type": "integer",
      "default": 100,
      "description": "Rate limit per second"
    },
    "feature.enabled_slugs": {
      "type": "array",
      "items": {"type": "string"},
      "default": ["getsentry"],
      "description": "Which orgs to enable the feature for"
    }
  }
}
See schema definition for complete format details and supported types.
2

Update Dockerfile

Schemas must be baked into your Docker image so the client library can validate values and provide defaults even before any ConfigMap is deployed.
Dockerfile
# Copy schemas into image (enables validation and defaults)
COPY sentry-options/schemas /etc/sentry-options/schemas

ENV SENTRY_OPTIONS_DIR=/etc/sentry-options
The schemas are read-only and embedded at build time. Values are mounted separately at runtime via ConfigMap.
3

Add client library dependency

Add the sentry-options client library to your project dependencies.
pyproject.toml
dependencies = [
    "sentry_options>=0.0.14",
]
4

Add schema validation to CI

Create a GitHub Actions workflow to validate schema changes and enforce evolution rules.
.github/workflows/validate-sentry-options.yml
name: Validate sentry-options schema

on:
  pull_request:
    paths:
      - 'sentry-options/schemas/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
        with:
          fetch-depth: 0  # Required for comparing base and head commits
      - uses: getsentry/sentry-options/.github/actions/validate-schema@sha
        with:
          schemas-path: sentry-options/schemas
Replace @sha with a specific commit SHA from the sentry-options repository for reproducibility.
This workflow will:
  • Validate schema JSON syntax and structure
  • Enforce schema evolution rules (no type changes, no removing options, etc.)
  • Check if deleted options are still in use in sentry-options-automator
5

Initialize and use in code

Initialize the library early in your application startup, then access options by namespace.
from sentry_options import init, options

# Initialize early in startup (call once)
init()

# Get options namespace
opts = options('seer')

# Read values (returns schema default if ConfigMap doesn't exist)
if opts.get('feature.enabled'):
    rate = opts.get('feature.rate_limit')
    print(f"Rate limit: {rate}")
See using clients for complete usage examples.

​
What happens after setup

Once you’ve completed these steps in your service repository:
  1. Your service runs with defaults: The library uses schema defaults when no ConfigMap exists yet
  2. CI validates schema changes: Any PR modifying schemas will be validated automatically
  3. You can test locally: Create a values.json file to test different option values (see local testing)

​
Next steps

Define schemas

Learn about supported types, requirements, and evolution rules

Register in automator

Add your service to sentry-options-automator to deploy values

​
Deployment order

All service repo changes can be deployed together. The library gracefully handles missing ConfigMaps by falling back to schema defaults. You don’t need to coordinate deployment timing between your service and the automator repo.
The typical integration flow:
  1. Service repo: Add schema, update Dockerfile, use client library → Deploy
  2. Automator repo: Register service, add values → CI/CD deploys ConfigMaps
  3. Ops repo: Add pod annotations → ConfigMaps auto-mounted
Each step is independent and can happen in any order.

Build docs developers (and LLMs) love

Get started for freeTalk to us