agentleFS
MicrosoftKnown publishermicrosoft/fsi-banking-payments-dispute-resolution-accelerator/.squad/skills/azd-seed-hook/SKILL.md

azd-seed-hook

Skill0 starsChanged 3 months agoMITView on GitHub

Category: DevOps / Infrastructure Author: Fenster Date: 2026-07-07 Update (2026-07-09): The top-level postdeploy hook described below was removed from azure.yaml — it fired after every azd deploy <service>, including web/portal on the GitHub-hosted runner, breaking CD once Cosmos went private. Seeding is now handled solely by the deploy-api job in .github/workflows/cd.yml (self-hosted, in-VNet runner). The pattern below (seed script design, upsert idempotency, env var reconciliation) is still accurate for the script itself — only the "wire to azure.yaml" hook step…

  • Installs packages

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After azd up, a freshly provisioned Cosmos container is empty.

    line 21
  2. Very specific:

    Call upsert_dispute(doc) per item

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill: AZD Postdeploy Seed Hook (Python + Cosmos)

Category: DevOps / Infrastructure
Author: Fenster
Date: 2026-07-07

Update (2026-07-09): The top-level postdeploy hook described below was removed from azure.yaml — it fired after every azd deploy <service>, including web/portal on the GitHub-hosted runner, breaking CD once Cosmos went private. Seeding is now handled solely by the deploy-api job in .github/workflows/cd.yml (self-hosted, in-VNet runner). The pattern below (seed script design, upsert idempotency, env var reconciliation) is still accurate for the script itself — only the "wire to azure.yaml" hook step and the "double-run is harmless" claim are now obsolete.


Pattern: Idempotent Cosmos seed wired as an azd postdeploy hook

Problem

After azd up, a freshly provisioned Cosmos container is empty. You want synthetic / seed data automatically inserted on every clean deploy, without re-seeding breaking anything on subsequent runs.

Solution

  1. Add upsert_item helper to cosmos_client.py — one function, always idempotent:
    def upsert_dispute(dispute: dict) -> dict:
        return _get_container("disputes").upsert_item(body=dispute)
  2. Write a seed script at src/api/scripts/seed_cosmos.py:
    • Soft-fail if endpoint is absent (check both COSMOS_ENDPOINT and AZURE_COSMOS_ENDPOINT)
    • Defer import cosmos_client until after env vars are set (preserves testability)
    • Build documents per contract: doc = {**case, "id": caseId, "disputeId": caseId, "networkCode": cardNetwork}
    • Call upsert_dispute(doc) per item
  3. Reconcile env var names — azd exposes Bicep outputs with AZURE_ prefix; the client may expect shorter names. In _resolve_env():
    endpoint = os.environ.get("COSMOS_ENDPOINT") or os.environ.get("AZURE_COSMOS_ENDPOINT", "")
    os.environ["COSMOS_ENDPOINT"] = endpoint  # set before deferred import
  4. Wire to azure.yaml with posix/windows split. Use continueOnError: false once runner deps are installed (see Key rules):
    hooks:
      postdeploy:
        posix:
          shell: sh
          run: cd src/api && PYTHONPATH=. python3 scripts/seed_cosmos.py
          continueOnError: false
        windows:
          shell: pwsh
          run: |
            $env:PYTHONPATH = "src\api"
            python src\api\scripts\seed_cosmos.py
          continueOnError: false

Key rules

RuleWhy
Prefer an explicit CD step over the azd postdeploy hook in CIThe postdeploy hook output is invisible in CD runs (no log capture), and continueOnError: true silently swallows failures. An explicit - name: Seed Cosmos DB step after AZD Deploy shows output in the job log and fails loudly on non-zero exit. Keep the azure.yaml hook only for local azd up convenience — the double-run is harmless (upsert idempotency).
Install app deps on CI runner before azd deployThe postdeploy hook runs on the same runner; ubuntu-latest does NOT have azure-cosmos / azure-identity. Add actions/setup-python@v5 + pip install -r requirements.txt steps before the AZD Deploy step in cd.yml. Without this, imports fail silently.
Use python3 in posix hooks, not pythonBare python is absent on ubuntu-latest; python3 is the reliable alias.
continueOnError: false once deps are installedWith runner deps in place, a non-zero exit means a real problem. Use false so genuine failures (import errors, RBAC 403, upsert exception) fail the deploy visibly. The script's own sys.exit(0) on missing endpoint handles the soft-fail case — no need to swallow all errors at the hook level.
continueOnError: true only during bootstrapAcceptable temporarily if RBAC propagation is known to lag and you have no retry wrapper. Remove as soon as possible.
Defer import cosmos_clientAvoids DefaultAzureCredential construction at import time — critical for test mocking
Soft-fail on missing endpointEnables running azd up from repo without Cosmos (e.g. local-only dev)
Upsert not insertRe-running the hook is always safe; no duplicate-key errors

Testing

Mock cosmos_client before import with sys.modules:

stub = MagicMock()
monkeypatch.setitem(sys.modules, "cosmos_client", stub)
import scripts.seed_cosmos as seed_mod
monkeypatch.setattr(seed_mod, "cosmos_client", stub, raising=False)

Assert stub.upsert_dispute.call_count == len(cases) and verify document shape.

Soft-fail test: confirm SystemExit(0) is raised (not an exception) when endpoint unset.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.