Public Access
136 lines
5.3 KiB
Markdown
136 lines
5.3 KiB
Markdown
# 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`:
|
|
```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
|
|
|
|
```bash
|
|
# 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']"
|
|
```
|