Skip to main content
The fetch-schemas command fetches option schemas from multiple git repositories using sparse checkout. This is used in CI to collect schemas from all service repositories before validating option values.

​
Usage

sentry-options-cli fetch-schemas --config <CONFIG> --out <OUT>

​
Arguments

​
--config
string
required
Path to the repos.json configuration file that specifies which repositories to fetch schemas from.The config file should have this structure:
{
  "repos": {
    "seer": {
      "url": "https://github.com/getsentry/seer",
      "path": "sentry-options/",
      "sha": "abc123def456..."
    },
    "relay": {
      "url": "https://github.com/getsentry/relay",
      "path": "sentry-options/schemas/",
      "sha": "def789ghi012..."
    }
  }
}
​
--out
string
required
Output directory where fetched schemas will be written.Each repository’s schemas will be extracted to <OUT>/<namespace>/schema.json.
​
--quiet
boolean
Suppress progress messages. Only errors will be displayed.

​
repos.json format

The configuration file uses this structure:
​
repos
object
required
Map of repository names to their fetch configurations.
​
repos.<name>.url
string
required
GitHub repository URL (HTTPS format).
​
repos.<name>.path
string
required
Path within the repository containing schema directories.Should point to the directory that contains {namespace}/schema.json files.
​
repos.<name>.sha
string
required
Git commit SHA to fetch from. This pins the schema version for reproducibility.When updating schemas, update this SHA to point to the commit containing the new schema.

​
Examples

​
Basic usage

sentry-options-cli fetch-schemas \
  --config repos.json \
  --out schemas/
Output: 
Fetching schemas from seer at abc123def456...
Fetching schemas from relay at def789ghi012...
Successfully fetched schemas to schemas/

​
With quiet mode

sentry-options-cli fetch-schemas \
  --config repos.json \
  --out schemas/ \
  --quiet
No output on success. Errors will still be displayed.

​
CI workflow

# .github/workflows/validate.yml
- name: Fetch schemas
  run: |
    sentry-options-cli fetch-schemas \
      --config repos.json \
      --out schemas/

- name: Validate values
  run: |
    sentry-options-cli validate-values \
      --schemas schemas/ \
      --root option-values/

​
Output structure

Given this repos.json: 
{
  "repos": {
    "seer": {
      "url": "https://github.com/getsentry/seer",
      "path": "sentry-options/",
      "sha": "abc123"
    }
  }
}
And a repository structure: 
seer/
└── sentry-options/
    ├── seer/
    │   └── schema.json
    └── seer-autofix/
        └── schema.json
The output will be: 
schemas/
├── seer/
│   └── schema.json
└── seer-autofix/
    └── schema.json

​
Error handling

​
Missing or invalid config file

$ sentry-options-cli fetch-schemas --config missing.json --out schemas/
I/O error: No such file or directory (os error 2)

​
Invalid JSON format

$ sentry-options-cli fetch-schemas --config invalid.json --out schemas/
JSON error: expected value at line 1 column 1

​
Git command failures

$ sentry-options-cli fetch-schemas --config repos.json --out schemas/
Git command failed: fatal: could not read from repository
Common causes:
  • Network connectivity issues
  • Invalid repository URL
  • SHA not found in repository (not fetched yet)
  • Missing git credentials for private repos

​
Notes

  • The command uses git sparse checkout to efficiently fetch only the schema directories without cloning entire repositories
  • SHAs must be pre-fetched in the local git repository (the command runs git archive which requires the SHA to be available locally)
  • The output directory is created automatically if it doesn’t exist
  • Existing files in the output directory will be overwritten

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us