nGitDB

GitHub Actions

The preferred day-0 CI path is the nGitDB GitHub Action. It lets Python or any other generator write a JSON batch file, then nGitDB applies safe patches, commits to a session branch, and creates or updates one pull request.

Required Permissions

permissions:
  contents: write
  pull-requests: write

Expose the default token through normal Actions execution. The Action reads GITHUB_REPOSITORY and GITHUB_TOKEN.

If this repository is private, enable Actions access for same-organization client repositories before using uses: nuanst-gmbh/nGitDB@v0.

Minimal Action Workflow

name: Update company data

on:
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  update:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Build nGitDB batch
        run: python scripts/build_ngitdb_batch.py --output tmp/ngitdb.batch.json

      - name: Publish nGitDB updates
        id: ngitdb
        uses: nuanst-gmbh/nGitDB@v0
        with:
          batch-file: tmp/ngitdb.batch.json
          session-key: company-enrichment
          commit-message: Update generated company data
          pr-title: Update generated company data
          pr-body: Generated by nGitDB.
          resource-config: |
            {
              "baseBranch": "main",
              "resourceRoot": "data",
              "resources": {
                "companies": {
                  "fileName": "company.json",
                  "ownership": {
                    "legalName": "human-owned",
                    "machine": "machine-owned"
                  }
                }
              }
            }

Batch File

Python writes a batch file with patch operations only:

{
  "resources": [
    {
      "resourcePath": "companies/acme-gmbh",
      "patch": {
        "machine.summary": "Industrial supplier with operations in Berlin",
        "machine.lastEnrichedAt": "2026-05-16"
      }
    }
  ]
}

Each resourcePath uses <collection>/<id>. Each patch is passed to db.patch(...), so ownership rules still block human-owned fields.

Inputs

• batch-file: path to the generated batch JSON file.
• resource-config: JSON with baseBranch, resourceRoot, and resources.
• session-key: stable key used to derive the session branch.
• commit-message: commit message for the generated update.
• pr-title: pull request title.
• pr-body: optional pull request body.

resource-config is JSON, so it supports ownership maps but not function validators. Use the TypeScript API route when validators are required in CI.

Outputs

• pull-request-number
• pull-request-url
• head-branch
• committed-resources: JSON array of resource paths.
• created: true when a new PR was opened.
• updated: true when an existing PR was updated.

Existing Resources

The Action patches existing resources. For V1, seed resource files before running automation:

data/companies/acme-gmbh/company.json

If the session branch already exists, nGitDB resumes it. If an open pull request already exists for the same session branch and base branch, nGitDB updates that pull request.

Advanced: Custom Node Integration

Use the TypeScript API directly when the client needs custom validators or richer workflow control.

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: "22"
      cache: npm

  - run: npm ci

  - run: node scripts/apply-ngitdb-update.mjs tmp/company.json
    env:
      GITHUB_TOKEN: $

import { readFile } from "node:fs/promises";
import { createGitDB } from "@nuanst-one/ngitdb";

const merged = JSON.parse(await readFile(process.argv[2], "utf8"));

const db = createGitDB({
  repositoryRoot: process.cwd(),
  backend: { type: "github" },
  baseBranch: "main",
  resources: {
    companies: {
      fileName: "company.json",
      ownership: {
        legalName: "human-owned",
        machine: "machine-owned",
      },
      validate: (document) => {
        const issues = [];
        if (typeof document.legalName !== "string" || document.legalName.length === 0) {
          issues.push("legalName must be a non-empty string");
        }
        return issues;
      },
    },
  },
});

await db.startSession(merged.id);
await db.patch(`companies/${merged.id}`, {
  machine: merged.machine,
});
await db.commit(`Update company data for ${merged.id}`);
await db.createPullRequest({
  title: `Update company data for ${merged.id}`,
  body: "Generated by the nGitDB GitHub Actions workflow.",
});