id: firestore-snapshot-ai-change-review
namespace: company.team
inputs:
- id: repo_url
type: STRING
description: HTTPS URL of the repository that the Firestore snapshot flow pushes to.
- id: branch
type: STRING
defaults: main
- id: snapshot_path
type: STRING
defaults: firestore
description: Folder in the repository that holds the `<collection>.jsonl`
snapshot files, searched recursively.
variables:
# Slack member ID of each collection's owner, mentioned when a change to that collection is rated HIGH.
owners:
feature_flags: U0123456789
settings: U0987654321
tasks:
- id: workspace
type: io.kestra.plugin.core.flow.WorkingDirectory
tasks:
- id: clone
type: io.kestra.plugin.git.Clone
url: "{{ inputs.repo_url }}"
branch: "{{ inputs.branch }}"
depth: 100
username: "{{ secret('GITHUB_USERNAME') }}"
password: "{{ secret('GITHUB_TOKEN') }}"
- id: collect_changes
type: io.kestra.plugin.scripts.python.Script
description: Compares the snapshot files between the last reviewed commit and
HEAD, and lists every document whose data changed.
containerImage: python:3.12
beforeCommands:
- git config --global --add safe.directory '*'
env:
SNAPSHOT_PATH: "{{ inputs.snapshot_path }}"
LAST_SHA: "{{ kv('firestore_review_last_sha', errorOnMissing=false) ?? '' }}"
script: |
import json, os, subprocess
def git(*args):
return subprocess.run(["git", *args], capture_output=True, text=True)
def documents(rev, path):
shown = git("show", f"{rev}:{path}")
if shown.returncode:
return {}
rows = (json.loads(line) for line in shown.stdout.splitlines() if line.strip())
return {row["id"]: row["data"] for row in rows}
head = git("rev-parse", "HEAD").stdout.strip()
base = os.environ["LAST_SHA"]
if not base or git("cat-file", "-e", base + "^{commit}").returncode:
history = git("rev-list", "--max-count=2", "HEAD").stdout.split()
base = history[1] if len(history) > 1 else ""
changes = []
if base and base != head:
changed = git("diff", "--name-only", base, head, "--", os.environ["SNAPSHOT_PATH"]).stdout.split()
for path in (p for p in changed if p.endswith(".jsonl")):
collection = os.path.basename(path).removesuffix(".jsonl")
before, after = documents(base, path), documents(head, path)
for doc_id in sorted(before.keys() | after.keys()):
if before.get(doc_id) != after.get(doc_id):
changes.append({
"collection": collection,
"document": doc_id,
"before": before.get(doc_id),
"after": after.get(doc_id),
})
print("::" + json.dumps({"outputs": {"base": base, "head": head, "changes": changes, "count": len(changes)}}) + "::")
- id: if_changed
type: io.kestra.plugin.core.flow.If
condition: "{{ outputs.collect_changes.vars.count > 0 }}"
then:
- id: review
type: io.kestra.plugin.ai.agent.AIAgent
description: Explains each document change and rates how risky it is for the
running app.
provider:
type: io.kestra.plugin.ai.provider.GoogleGemini
apiKey: "{{ secret('GEMINI_API_KEY') }}"
modelName: gemini-3.5-flash
systemMessage: |
You review changes to production configuration stored in Firestore: feature flags, settings and reference data.
For every change, say in one short sentence what changed, then rate the risk for users of the app:
- HIGH: a feature exposed to many more users at once, a kill switch or safety limit turned off, a document deleted, prices or quotas changed by a large factor, or credentials and URLs changed.
- MEDIUM: a gradual rollout step, a new document, or a value change whose effect is unclear.
- LOW: labels, descriptions or other changes users will not notice.
Base every rating only on the before and after values you are given. A null "before" means the document was added, a null "after" means it was deleted.
prompt: |
Review these Firestore document changes, ordered by collection and document ID:
{{ outputs.collect_changes.vars.changes | toJson }}
configuration:
responseFormat:
type: JSON
jsonSchema:
type: object
required: [ summary, changes ]
properties:
summary:
type: string
description: One or two sentences on the overall change set.
changes:
type: array
items:
type: object
required: [ collection, document, change, risk, reason ]
properties:
collection:
type: string
document:
type: string
change:
type: string
risk:
type: string
enum: [ HIGH, MEDIUM, LOW ]
reason:
type: string
- id: notify
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
url: "{{ secret('SLACK_WEBHOOK') }}"
messageText: |
*Firestore config changed* ({{ outputs.collect_changes.vars.base | slice(0, 7) }}..{{ outputs.collect_changes.vars.head | slice(0, 7) }} in {{ inputs.repo_url }})
{{ outputs.review.jsonOutput.summary }}
{% for c in outputs.review.jsonOutput.changes %}{% set owner = vars.owners[c.collection] ?? '' %}
• *{{ c.risk }}* `{{ c.collection }}/{{ c.document }}`: {{ c.change }} {{ c.reason }}{% if c.risk == 'HIGH' and owner != '' %} <@{{ owner }}>{% endif %}{% endfor %}
- id: remember_head
type: io.kestra.plugin.core.kv.Set
description: Stores the reviewed commit, so the next run only looks at newer snapshots.
key: firestore_review_last_sha
value: "{{ outputs.collect_changes.vars.head }}"
errors:
- id: alert_on_failure
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
url: "{{ secret('SLACK_WEBHOOK') }}"
messageText: "Firestore change review failed in {{ flow.namespace }}.{{ flow.id
}}, execution {{ execution.id }}."
triggers:
- id: after_snapshot
type: io.kestra.plugin.core.trigger.Flow
inputs:
repo_url: https://github.com/my-org/firestore-snapshots
dependsOn:
- namespace: company.team
flowId: firestore-collection-git-snapshot
states: [ SUCCESS ]