12.3 Version Control for Prompts with Git

Version Control for Prompts with Git

Quick Answer: Prompts and flow.dag.yaml live in the same GitHub repository as the app. Pull requests run evaluators. Tags mark the commit that matches a Foundry agent version. Never commit API keys. The exam trap is editing instructions only in the portal with no commit.

The third Domain 3 bullet is implement version control for prompts by using Git repositories. Microsoft Learn’s module Manage prompts for agents in Microsoft Foundry with GitHub is the skill in course form: prompts are production configuration; they take effect immediately; they need the same DevOps treatment as application code.

Why Git, not the portal, is the source of truth

Microsoft’s version-control unit lists what fails without Git: silent degradation (a “harmless” wording change drops accuracy and nobody can diff it), environment drift (dev works, production has a different playground paste), crisis recovery (you cannot restore what was never committed), and lost knowledge (someone deletes a “redundant” safety sentence that was load-bearing). The fix is the same table you already use for Azure Machine Learning jobs in Chapter 4: source control, reviews, environment separation, rollback.

Prompt flow is already files. Each flow folder contains:

• flow.dag.yaml — inputs, outputs, nodes, tools, variants
• .jinja2 / .py — prompt templates and Python tools
• data files for local test

Azure Machine Learning stores a copy under Users/<username>/promptflow on the workspace file share. That share is not Git. Download the folder (or clone a repo onto the compute instance) and check it in. The VS Code Prompt flow extension and pf / pfazure CLI let you author locally, then pfazure run create submits cloud runs from the clone. Foundry agents follow the same idea with a shallower tree: a deployment script plus prompts/vN_instructions.txt.

Microsoft’s recommended layout (adapted for a claims agent) looks like this:

• src/agents/claims_triage/claims_triage.py — reads the instruction file, calls create_version()
• src/agents/claims_triage/prompts/v1_instructions.txt (and v2_, v3_)
• tests/test_claims_triage.py plus an eval dataset
• infra/main.bicep — Foundry/AML resources from Chapter 10
• .github/workflows/eval-prompts.yml — CI
• .env and connection secrets — not committed; listed in .gitignore

File format: .txt or .md for agent instructions (SDK examples read text files), YAML/JSON for metadata, Jinja2 for prompt-flow templates. Name prompt files with incremental versions (v1_instructions.txt) so they line up with Foundry’s agent:1 style versions. Use Git tags (v1, v2) on the commit that deployed that agent version.

Connect GitHub and run CI evaluation on the pull request

Connect GitHub the same way you did for Azure Machine Learning projects: clone with SSH, a scoped PAT, or a GitHub App; store credentials in Key Vault or Actions secrets; do not paste tokens into YAML. Microsoft’s GenAIOps-with-prompt-flow-and-GitHub guide adds the automation contract:

1. Create a service principal (or federated OpenID Connect identity) so GitHub Actions can sign in to Azure.
2. Store the credential as a GitHub secret. Workflows read the secret; the repo does not.
3. Use two branches such as development and main (the template uses main and development) with branch policies.
4. Open a pull request from a feature branch. The PR pipeline runs build validation and experimentation / evaluation flows (pfazure run create plus an evaluation run, or Foundry evaluation APIs).
5. Merge only if evaluators meet the gate (for example groundedness mean ≥ 4.0 and safety pass rate at your threshold).
6. After merge, CI may register the flow in the Azure Machine Learning registry; CD may deploy an online endpoint and run a smoke test. For agents, CI calls create_version() into a dev project; a release workflow promotes the tagged version to production.

Hosted Foundry agents can also use azd pipeline config to generate .github/workflows/azure-dev.yml, a service principal, and repository variables. The exam skill is the pattern: PR → eval → approve → tag → deploy, not a particular YAML filename.

Branch names Microsoft’s prompt-workflow unit suggests: feature/improve-customer-greeting, hotfix/fix-greeting-error, experiment/tone-variations. Lifecycle stages: development → validation → review → production → monitoring. Do not skip validation to “save time.”

Never store API keys in flow.dag.yaml, Jinja2, instruction files, or committed run.yml. Prompt-flow connections (the sample name aoai) live in the workspace. Local .env is for laptops and is gitignored. GitHub Actions uses AZURE_OPENAI_API_KEY or, better, Microsoft Entra ID with DefaultAzureCredential so there is no long-lived key at all.

Code review for a prompt PR is not optional rubber-stamping. Reviewers check: one-factor change, eval report attached, safety sentences still present, no secrets, temperature documented in config not only in chat. Microsoft calls out that prompt changes need team approval because a one-word edit is live behavior.

Exam scenario

A support lead edits the production Foundry agent in the portal to “sound more casual.” Call-center groundedness falls the next morning and nobody can diff the instruction text. You revert by deploying the last Git tag v3 with create_version() from v3_instructions.txt, then you lock portal edits: production instructions deploy only from main after CI evaluation. You add a workflow that, on PRs touching src/agents/**/prompts/**, runs the quality evaluators from Chapter 13 on the changed files. That is version control for prompts.

Common trap

The trap the exam wants: editing prompts only in the portal (or Studio Files) with no commit. You cannot code-review a playground paste, you cannot tag it, and you cannot prove which wording served traffic. A sibling trap is committing aoai API keys in .env. A third is merging prompt PRs without an evaluation job because “it’s just copy.” A fourth is tagging v4 in Git while production still runs an untagged portal version 7 — tags must match the agent version you actually created from that commit.

Prompts are code. Git, PRs, CI evaluators, and tags are how Domain 3 expects you to manage them. Domain 4 then deepens the evaluators your CI already calls.