devx/.devin/skills/dependency-graph/SKILL.md

dependency-graph

Map of the oblachno ecosystem. Knows which repo produces what, which repos depend on which, and the correct order for cross-repo changes.

When to Invoke

Invoke this skill when:

• Changes span multiple repos
• A change in one repo requires version bumps in downstream repos
• Deploying infrastructure that depends on published packages/images
• Verifying the ecosystem is in a consistent state before deployment
• Determining which repos to update and in what order

Prerequisites

• All repos cloned under /home/emo/dev/ideas/oblachno/
• .env with DEVELOPER_GITEA_API_TOKEN in each repo

Ecosystem Map

                    devx (PyPI package)
                   /    |    \
                  /     |     \
            grm   sso-bridge   infra
           (PyPI)  (PyPI+Docker) (deploys all)
              |        |           |
              v        v           v
         infra bump  infra bump   staging
         (auto PR)   (auto PR)   production
                                      |
                          mattermost-oidc (Docker image)
                          (infra pulls :latest at deploy)

Repositories

Repo	Produces	Consumers	Release Trigger
devx	PyPI package devx	grm, sso-bridge, infra	User-facing changes to src/devx/**
grm	PyPI package grm	infra	User-facing changes to src/grm/** or ansible/**
sso-bridge	PyPI package sso_bridge + Docker image	infra	User-facing changes to src/sso_bridge/** or ansible/**
infra	Staging/production deployment	(end users)	User-facing changes + nightly gate
mattermost-oidc	Docker image mattermost-oidc	infra (pulls at deploy)	Dockerfile or build.yml changes

Dependency Chain

devx → all repos

devx publishes to the Gitea PyPI registry. grm, sso-bridge, and infra pin devx in pyproject.toml:

"devx @ git+https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git@vX.Y.Z"

When devx publishes a new version:

1. grm, sso-bridge, and infra must bump their pinned devx version
2. This is currently manual — no auto-dependency-PR from devx
3. Each repo must make setup to pick up the new version

grm → infra

grm publishes to PyPI. Its post-merge workflow auto-creates an infra dependency PR via devx.ci.create_dependency_pr --repo oblachno/infra --package grm. The PR bumps the pinned grm version in infra's pyproject.toml.

sso-bridge → infra

sso-bridge publishes to PyPI AND builds a Docker image. Its post-merge workflow auto-creates an infra dependency PR via devx.ci.create_dependency_pr --repo oblachno/infra --package sso_bridge. The PR bumps the pinned sso_bridge version.

The Docker image is pulled by infra at deploy time (sso-bridge:latest).

mattermost-oidc → infra

mattermost-oidc builds a Docker image tagged :latest and :MM_VERSION. infra pulls mattermost-oidc:latest at deploy time. There is no auto-dependency-PR — infra simply pulls the latest image.

infra → staging/production

infra deploys to staging and production. The deployment:

1. Provisions VMs from golden images
2. Runs Ansible roles (including grm and sso-bridge roles)
3. Pulls Docker images (sso-bridge, mattermost-oidc)
4. Configures services

Correct Order for Cross-Repo Changes

When a change spans multiple repos, follow this order:

1. devx first — if the change starts in devx, merge and publish devx first. Wait for the PyPI publish job to complete.
2. Bump devx in consumers — in grm/sso-bridge/infra, bump the pinned devx version, run make setup, verify tests pass, merge.
3. grm/sso-bridge second — merge and publish grm/sso-bridge. Wait for the PyPI publish + Docker image build to complete.
4. Auto-dependency-PRs — grm/sso-bridge post-merge auto-creates infra PRs to bump pinned versions. Wait for these PRs to appear.
5. Merge infra dependency PRs — review and merge the auto-created infra PRs.
6. infra last — deploy to staging, validate, promote to production.

State Verification Before Deployment

Before deploying infra, verify:

1. devx version consistent — all repos pin the same devx version
2. grm published — latest grm tag exists in PyPI
3. sso-bridge published — latest sso_bridge tag exists in PyPI
4. sso-bridge image built — latest sso-bridge Docker image exists
5. mattermost-oidc image built — latest mattermost-oidc image exists
6. infra pins match published versions — no stale pins
7. Nightly gate green — NIGHTLY_STATUS is not failed

Quick Check Commands

# Check latest devx version
curl -sS https://git.oblachno.oblachno.fyi/api/v1/repos/oblachno-oss/devx/releases/latest | python3 -c "import json,sys; print(json.load(sys.stdin).get('tag_name','?'))"

# Check pinned devx version in each repo
for repo in grm sso-bridge infra; do
  echo -n "$repo: "; grep 'devx @' /home/emo/dev/ideas/oblachno/$repo/pyproject.toml | grep -oP 'v[\d.]+'
done

# Check latest sso-bridge image build
curl -sS -H "Authorization: token $DEVELOPER_GITEA_API_TOKEN" \
  "https://git.oblachno.oblachno.fyi/api/v1/repos/oblachno/sso-bridge/actions/runs?per_page=5" \
  | python3 -c "import json,sys; [print(r['id'],r['status'],r['conclusion']) for r in json.load(sys.stdin).get('workflow_runs',[]) if r.get('event')=='push']"