Keep AI Context Up to Date with GitHub Actions
Last updated November 15, 2026 · By the SaturnSQL team
Schemas change with every release, and the context AI tools read should change with them. Keep a connection’s context as an Apache Ossie model next to your code, review it in the same pull request as the change, and a GitHub Actions workflow updates SaturnSQL Context on merge.
On a pull request the workflow only previews: it comments what would change and saves nothing. On a push to main it imports.
1. Create an API key
In Settings → API keys, create a key with Access: Context sync only. It can import and export context and nothing else: no schema, no queries, no SQL. In your GitHub repository, add it under Settings → Secrets and variables → Actions as a secret named SATURNSQL_API_KEY.
2. Add the model to the repository
In SaturnSQL, open Context, pick the connection and choose Export → Apache Ossie (YAML). Commit the file, for example as context/shop.ossie.yaml. If you already have an Ossie model, use that instead.
3. Add the workflow
The quickest way: in Context, choose Export → GitHub Actions workflow. It copies the workflow with your connection filled in. Save it as .github/workflows/saturnsql-context.yml. Or copy it from here and replace YOUR_CONNECTION_ID with the ID after connection= in the Context page address.
name: SaturnSQL Context
on:
pull_request:
paths: ['context/shop.ossie.yaml', '.github/workflows/saturnsql-context.yml']
push:
branches: [main]
paths: ['context/shop.ossie.yaml', '.github/workflows/saturnsql-context.yml']
permissions:
contents: read
pull-requests: write
jobs:
context:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Preview on pull requests, import on main
env:
SATURNSQL_URL: https://saturnsql.com
SATURNSQL_API_KEY: ${{ secrets.SATURNSQL_API_KEY }}
CONNECTION_ID: YOUR_CONNECTION_ID
MODEL: context/shop.ossie.yaml
PR: ${{ github.event.pull_request.number }}
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
run: |
set -euo pipefail
apply=false
if [ "$GITHUB_EVENT_NAME" = "push" ]; then apply=true; fi
jq -n --rawfile yaml "$MODEL" --argjson apply "$apply" '{yaml: $yaml, apply: $apply}' > request.json
status=$(curl -sS -o response.json -w '%{http_code}' -X POST \
"$SATURNSQL_URL/api/context/$CONNECTION_ID/import" \
-H "Authorization: Bearer $SATURNSQL_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @request.json)
if [ "$status" != "200" ]; then
echo "::error::SaturnSQL import failed ($status): $(jq -r '.error // .' response.json)"
exit 1
fi
jq -r --argjson apply "$apply" '
def changed(b): if b then "Updated" else "No change" end;
"<!-- saturnsql-context:YOUR_CONNECTION_ID -->",
"### SaturnSQL Context: \(.model)",
"",
(if .applied then "Imported into SaturnSQL Context."
elif $apply then "Nothing to import. SaturnSQL Context already matches this model."
else "Preview. Nothing is saved until this is merged." end),
"",
"| | |",
"|---|---|",
"| Table descriptions | \(.summary.tables) |",
"| Column descriptions | \(.summary.columns) |",
"| Definitions | \(.summary.definitions) |",
"| Context files | \(changed(.summary.instructions)) |",
(((.unmatched.tables + .unmatched.columns) | map("`" + . + "`") | join(", ")) as $missing
| if $missing == "" then empty else "", "Not found in the database: \($missing)" end)
' response.json > report.md
cat report.md >> "$GITHUB_STEP_SUMMARY"
if [ -n "$PR" ]; then
id=$(gh api "repos/$GH_REPO/issues/$PR/comments" --paginate \
--jq '.[] | select(.body | startswith("<!-- saturnsql-context:YOUR_CONNECTION_ID -->")) | .id' | tail -n 1)
if [ -n "$id" ]; then
gh api -X PATCH "repos/$GH_REPO/issues/comments/$id" -F [email protected] > /dev/null
else
gh api "repos/$GH_REPO/issues/$PR/comments" -F [email protected] > /dev/null
fi
fi
4. Open a pull request
Change a description in the model and open a pull request. The workflow comments how many table descriptions, column descriptions and definitions would change, and lists anything in the file the database doesn’t have. Push more commits and it updates the same comment. Merge, and the change is in SaturnSQL Context, where every AI tool reads it.
Frequently asked questions
Does the import delete context that is not in the file?
No. Descriptions, synonyms and definitions the file leaves out stay as they are, so edits made in SaturnSQL or by an AI tool are not wiped by the next merge. Tables in the file that the database doesn’t have are listed in the comment and skipped.
Who can import context from GitHub?
The API key acts for the person who created it. They need to own the connection or be an admin, the key needs the context sync or write scope, and the workspace needs a plan with SaturnSQL Context.
Can one repository hold models for several connections?
Yes. Keep one Ossie file per connection and copy the step for each one, with its own connection ID and model path. Each connection gets its own comment on the pull request.
More on the format in Apache Ossie import and export.