release-scope 0.1.1

release-scope collects what sits between production and the default branch across GitLab services: tags, MRs, Jira keys, failed jobs.

For every service it reads the latest successful production deployment, walks the default branch down to that commit, and writes one JSON report: a row per merge request or direct commit, newest first, with the tags that point into it, the environments running it, the Jira keys its MR mentions, and the failed jobs of its main-branch and tag pipelines.

Quickstart

export RELEASE_SCOPE_GITLAB__ENDPOINT=https://gitlab.example.com
export RELEASE_SCOPE_GITLAB__TOKEN=glpat-...          # read_api scope
export RELEASE_SCOPE_ENVIRONMENTS='["prod", "preview"]'
export RELEASE_SCOPE_PRODUCTION_ENVIRONMENT=prod

uvx release-scope collect --group team/backend --output report.json --cache cache.json

--group and --project are repeatable and can be mixed. The command exits 1 when any service failed to collect; the report is still written and names the error on that service. A service GitLab denies access to fails alone, and its error lists the project settings and member page to check. A project with CI/CD or Environments disabled is reported with a warning and no rows, without querying it. Only a rejected token, or a group or project passed on the command line that the token cannot see, stops the run.

Configuration

Every setting is an environment variable; nothing about a GitLab or Jira instance is built in.

Report

The report is versioned by schema_version; the models live in release_scope/_report.py. One row, trimmed:

{
  "kind": "merge_request",
  "tags": [{"name": "1.2.0", "url": "...", "pipeline": {"id": 201, "status": "success", "failed_jobs": []}}],
  "merge_requests": [{"iid": 12, "title": "SHOP-12 new endpoint", "url": "..."}],
  "commits": [{"sha": "c3...", "title": "Merge branch 'feature/SHOP-12'"}],
  "jira_keys": [{"key": "SHOP-12", "url": "https://jira.example.com/browse/SHOP-12"}],
  "environments": ["preview"],
  "main_pipeline": {"id": 103, "status": "failed", "failed_jobs": [{"kind": "job", "name": "lint", "allow_failure": false}]}
}

Cache

--cache names a JSON file that is read if present and rewritten atomically after the run. It holds only facts that do not change once settled: which merge requests a commit belongs to, and the failed jobs of a finished pipeline keyed by its updated_at, so a retried job invalidates the entry. Entries the run did not use are dropped. A missing, corrupt, or older-schema cache is ignored with a warning; the cache only saves requests and never changes the report.