Skip to main content

​
Why it matters

  • Prompt text is business logic. Untracked changes can introduce risk or inconsistent behavior.
  • Most compliance frameworks require that production code (including prompts) is:
    • Immutable after deployment
    • Peer‑reviewed before release
    • Traceable with a full audit trail
  • Bundling a prod Prompt Template into an artifact that lives in Git provides these guarantees with almost zero additional tooling.
  • This also protects your application in the unlikely event that you’re application cannot connect to the Freeplay platform

​
Prerequisites for this guide

  • GitHub repository
  • GitHub Actions enabled
  • Freeplay CLI
  • A Prompt Template already promoted to the prodenvironment

​
Step 1  ·  Bundle the production prompt

Run during your release pipeline: 
freeplay download \
  --environment prod \
  --output-dir bundled_prompts \
  --project-id <project-id>
This writes an immutable JSON artifact containing:
  • Prompt text
  • Model/provider selection
  • All request parameters

​
Step 2  ·  Open a pull request if the bundle changes

Add the following workflow file to .github/workflows/prompt-bundle-guard.yml: 
name: Update Bundled Prompts
on:
  push:
    branches: [main]

jobs:
  prompt-bundle-guard:
    runs-on: ubuntu-latest
    permissions:
      contents: write          # push temp branch
      pull-requests: write     # open PR
    steps:
      - uses: actions/checkout@v4

      - name: Install Freeplay CLI
        run: python -m pip install --upgrade freeplay

      - name: Re‑bundle prod prompts
        run: |
					freeplay download \
  					--environment prod \
  					--output-dir bundled_prompts \
  					--project-id <project-id>

      - name: Open PR if bundle changed
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          if git diff --quiet --exit-code -- bundled_prompts; then
            echo "No prompt updates detected." && exit 0
          fi

          git config user.name  "Freeplay Prompt Bundler"
          git config user.email "[privacy@freeplay.ai]"
          branch="auto/prompt-bundle-$(date +%s)"
          git switch -c "$branch"
          git add bundled_prompts
          git commit -m "chore(prompts): update prod bundled prompt"
          git push --set-upstream origin "$branch"

          gh pr create \
            --title "Update production bundled prompts" \
            --body "Automated PR generated by Prompt Bundler workflow." \
            --label "prompt-bundle" \
            --base main \
            --head "$branch" \
            --draft

​
What happens?

  1. Bundle – Regenerates the prod bundle.
  2. Diff – If anything changed inside bundled_prompts/, the workflow:
    • Pushes the change on a new auto/prompt-bundle-* branch.
    • Creates a draft PR that a human must review & merge.
  3. Once merged, the new bundle is locked in Git history.
Tip: Protect main with “Require PR approval” to enforce peer review.

​
Step 3  ·  Pin the Bundled Prompt for production systems at runtime

from pathlib import Path
from freeplay import Freeplay
from freeplay.resources.prompts import FilesystemTemplateResolver

# Point the resolver at your committed bundle directory
fpClientLocal = Freeplay(
    freeplay_api_key=freeplay_key,
    api_base=freeplay_api_base,
    template_resolver=FilesystemTemplateResolver(Path("bundled_prompts"))
)

# Invoke the production template as usual
The SDK reads the local bundle, so the application can only execute prompts that passed the PR gate.

​
Compliance mapping

FrameworkRequirementHow the workflow satisfies it
SOC 2 CC4.1Peer review of production changesPR approval required before merge
ISO 27001 A.14.2.5Secure engineering principles & immutable artifactsBundled Prompt is hashed & version‑controlled
PCI‑DSS 6.4.5Formal approval prior to productionPR review & protected branch policies
HIPAA §164.308(a)(1)(ii)(D)System activity review & audit trailsGit + GitHub Actions logs show who changed what, when

​
FAQ & Troubleshooting

Q : What if we maintain multiple prod environments (e.g., per‑tenant)? A : Run freeplay download --env prod-<tenant> (or similar, given your environment naming conventions) for each environment and store each bundle under its own path. Q : Can I use Bitbucket Pipelines or GitLab CI instead? A : Yes mirror the same logic: re‑bundle, diff, and open a merge request when changes are detected. Q : How do I invalidate a bad prompt quickly? A : Revert the bundle commit or promote a previous prompt template version in the Freeplay dashboard and re‑run the workflow.