Git sync (export → repo)

Pull translation files from StringPush into your repository for review in Git. StringPush stays the authoring source of truth (overlay, admin, environments); Git holds the deployment artifact via pull request.

Beta quickstart

Status: Git sync is in beta on the hosted platform. Use @stringpush/cli@0.7.0 and @stringpush/sdk@0.7.0 (or newer) from npm.

Path	What you need
CI export → PR	Sync token + `.stringpush/sync.yaml` + `npx @stringpush/cli sync-pr`
Hosted GitHub App + overlay	Admin Application Git sync + GitHub App install + SDK 0.7.0+ on staging
Inbound (Git → platform)	`sync:import` token + `stringpush push` or merge webhook

Admin — Settings → Git sync → create sync token(s) (stp_…; sync:export for CI, sync:import for push).
Repo — add .stringpush/sync.yaml (full example below).
Outbound — CI workflow with sync-pr, or link repo in admin and use overlay Ready for merge.
Publish staging strings, run export, review PR on stringpush/sync-{environment}.

Beta feedback: include API base URL, provider (GitHub/GitLab/custom), and export/PR errors when reporting issues.

Choose your path

Delivery mode	Runtime	Git sync role	Typical use
Hosted	`@stringpush/sdk` loads CDN bundles	Optional — PR export for audit, compliance, or dual delivery	Web apps with in-context overlay
Repo-native	Your app loads locale JSON from Git	Required — PR sync is how strings reach production	i18next / repo-native teams
Enterprise	Either	PR export + optional inbound on merge	Full Git workflow + conflict policies

Choosing a path:

If strings must live in Git for compliance or your deploy pipeline, use repo-native delivery with PR sync (sync-pr or overlay Ready for merge).
If you promote copy when the app deploys (CDN bundles, not locale files in the repo), use environment promote/publish in admin or CI deploy-release — not locale PR as your primary release path.

Outbound: CI vs hosted GitHub App

Option	Status	When to use
`stringpush sync` / `sync-pr` + CI	✅ Shipped	You control when export runs (`workflow_dispatch`, schedule, or after your own publish hook)
Hosted GitHub App	✅ Beta	Admin links repo; overlay Ready for merge or Sync to Git opens PR without maintaining CI
Auto PR on publish	🟡 Beta	Enable `stagingOnPublish: open_pr` in admin Application Git sync (noisy — prefer batch/overlay)

Both outbound paths use the same export API and .stringpush/sync.yaml. The CLI works in any CI with Git; review creation is provider-specific (GitHub, GitLab, custom adapter).

Source of truth

Concern	Source of truth
In-context edits, staging workflow, audit	StringPush
Files your developers review and CI deploys	Git (via PR)
Runtime strings (Hosted)	StringPush CDN bundles (`init`)
Runtime strings (Repo-native)	Git locale files after merge

Full bi-directional sync with conflict resolution policies is available on Enterprise plans. Git sync does not replace in-context overlay as the primary authoring workflow.

Admin: link a repository (hosted path)

Owner/admin — Settings → Git sync:

Config reference — copy projectId, applicationId, and locale codes into .stringpush/sync.yaml in your repo.
Create token — sync:export for CI; optional sync:import for stringpush push.
Application Git sync — select project + application:
- Connect GitHub App — install on the target org/repo; callback records installationId.
- Repository — owner/repo (e.g. acme/web-app).
- Sync config (JSON) — same shape as .stringpush/sync.yaml (export, pr, inbound, …).
- Staging / production on publish — none (default) or open_pr (opens PR on each publish; prefer overlay batch for translators).
- Save — status shows linked when enabled, installation id set, and repo name saved.
Sync to Git (manual) — exports pending changes and opens or updates a pull request.

StringPush provisions the hosted GitHub App for managed environments. CI-only teams can skip repository linking and use sync-pr.

Prerequisites

StringPush project with published staging (or production) values.
Sync token (stp_…) — create in admin (Settings → Git sync) or POST /v1/organization/sync-tokens (owner/admin).
Config file at .stringpush/sync.yaml in your repo root.

Finding setup values

Everything in .stringpush/sync.yaml is non-secret. Use admin Settings → Git sync → Config reference to copy UUIDs.

Value	Where to get it	Commit to Git?	Used for
projectId	Config reference or `GET /v1/projects`	Yes	Export/import API path
applicationId	Config reference or Applications list	Yes	Which app to sync
Locale codes	Projects → Locales	Yes (`export.paths` keys)	Which files to read/write
File paths	Your repo layout	Yes	`export.paths` values
Default branch	Git host (`main`, `master`, …)	Yes (`pr.baseBranch`)	PR target
Sync token `stp_…`	Settings → Git sync → Create token	Never	CI / CLI auth
Runtime API key `trt_…`	Applications → API Keys	Never	SDK only — not Git sync

API and admin URLs

Environment	API (`STRINGPUSH_API_BASE_URL`)	Admin (`STRINGPUSH_ADMIN_BASE_URL`)
Staging	`https://api.staging.stringpush.com`	`https://admin.staging.stringpush.com`
Production	`https://api.platform.stringpush.com`	`https://admin.platform.stringpush.com`

Sync tokens are organization-scoped — match token org to API host.

Minimal checklist

Publish strings for the target environment.
Copy IDs into .stringpush/sync.yaml.
Store STRINGPUSH_SYNC_TOKEN in CI secrets.
Set workflow env vars to the matching API/admin URLs.
Run npx @stringpush/cli@0.7.0 sync-pr --env staging.

Security: sync tokens export published strings only. Revoke on offboarding; rotate after leaks.

Secrets and tokens

Secret / token	Where	Scope	Notes
`stp_…` export	`STRINGPUSH_SYNC_TOKEN` in CI	`sync:export`	Preferred for `sync-pr` / `export`
`stp_…` import	CI vault or local env	`sync:import`	`stringpush push` and inbound API
Admin bearer	Local dev only	Full org admin	Do not store in long-lived CI
`GH_TOKEN` / `GITHUB_TOKEN`	GitHub Actions	`contents: write`, `pull-requests: write`	`github.token` works for same-repo workflows; some orgs need a PAT
API base URL	Workflow env	—	Must match token environment

Example `.stringpush/sync.yaml`

yaml

projectId: "<uuid>"
applicationId: "<uuid>"
export:
  format: json # json | i18next
  paths:
    en: locales/en.json
    de: locales/de.json
pr:
  provider: github # auto | none | github | gitlab | custom
  remote: origin
  baseBranch: main
  branchPrefix: stringpush/sync-
  labels: [] # must already exist in GitHub/GitLab
  reviewers: []
sync:
  staging:
    onPublish: none # none | open_pr — hosted App only; CI ignores
  production:
    onPublish: none
    requireApproval: true
inbound:
  enabled: false
  branch: main # branch that triggers webhook import
  paths:
    - locales/**
  onMerge: upsert_draft # upsert_draft | upsert_published

sync.staging.onPublish / admin staging on publish apply when the hosted GitHub App opens PRs on publish. Overlay Ready for merge batches saves into one PR instead (preferred for translators).

Environment variables

Variable	Required	Description
`STRINGPUSH_API_TOKEN`	Yes	Sync token (`stp_…`) or admin bearer
`STRINGPUSH_API_BASE_URL`	Yes	API origin
`STRINGPUSH_ADMIN_BASE_URL`	No	Admin origin for PR body links
`GH_TOKEN` / `GITHUB_TOKEN`	GitHub PR	Push branch + open PR
`GITLAB_TOKEN` / `CI_JOB_TOKEN`	GitLab MR	GitLab API or job token

Install CLI

bash

npx @stringpush/cli@0.7.0 --help

Commands

Export / pull / sync-pr

bash

export STRINGPUSH_API_TOKEN="stp_…"
export STRINGPUSH_API_BASE_URL="https://api.staging.stringpush.com"

stringpush export --env staging --out ./locales
stringpush pull --env staging
stringpush sync-pr --env staging --provider github

sync-pr checks out stringpush/sync-{environment}, writes locale files, commits, pushes, and opens or reuses one open PR per branch.

Provider-aware entrypoint:

bash

stringpush sync --env staging --review-request --provider github
stringpush sync --env staging --provider none --json  # bring your own PR step

Push (inbound — Git → platform)

Import locale files from export.paths into StringPush:

bash

export STRINGPUSH_API_TOKEN="stp_…"  # sync:import scope
stringpush push --env staging
stringpush push --dry-run --env staging

Uses POST /v1/projects/:projectId/import. Default onMerge comes from inbound.onMerge in sync.yaml (upsert_draft writes staging drafts; upsert_published requires owner/admin or import token rules).

Custom review adapter

bash

stringpush sync --env staging --review-request --provider custom \
  --adapter-command ./scripts/stringpush-review-request

Adapter stdin: branch, base, title, body, files, labels, reviewers. Stdout: { "status": "created", "url": "…", "id": "…" }.

Overlay: Ready for merge

When the application is Git-linked in admin and the site runs @stringpush/sdk@0.7.0+ on staging (0.3.8+ minimum for overlay queue):

Each overlay Save enqueues that key/locale for the next batch.
The edit panel shows a pending count and Ready for merge.
Ready for merge opens or updates a pull request on stringpush/sync-{environment}.

Requires the hosted GitHub App linked in admin. CI-only teams can skip linking and use sync-pr instead.

Details: Staging overlay — Git sync.

GitHub Actions

yaml

name: StringPush locale sync

on:
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * *"

permissions:
  contents: write
  pull-requests: write

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Sync staging locales to PR
        env:
          STRINGPUSH_API_TOKEN: ${{ secrets.STRINGPUSH_SYNC_TOKEN }}
          STRINGPUSH_API_BASE_URL: https://api.staging.stringpush.com
          STRINGPUSH_ADMIN_BASE_URL: https://admin.staging.stringpush.com
          GH_TOKEN: ${{ github.token }}
        run: |
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config user.name "github-actions[bot]"
          npx @stringpush/cli@0.7.0 sync-pr --provider github --env staging

Configure pr.labels in sync.yaml only if those labels already exist in GitHub.

Typical flow: publish in admin → run workflow → review PR → merge → app CI deploys locale files.

Verify Git sync

Use this checklist after setup.

Path A — CI `sync-pr`

Publish at least one string to staging.
Run the GitHub Actions workflow (or sync-pr locally with gh auth).
Expect PR on stringpush/sync-staging targeting pr.baseBranch.
Diff shows export.paths files with expected JSON.
Re-run with no changes → exit unchanged (success, no empty commit).

Path B — Hosted overlay

Link repo in Application Git sync; confirm installation id + owner/repo saved.
Deploy app with SDK 0.7.0+; open staging with ?translation_edit=1.
Save a string → pending Git count increases.
Ready for merge → PR URL in panel; queue clears.
PR diff contains batched keys only.

Path C — Inbound (optional)

Create sync:import token.
Edit a locale file locally → stringpush push --env staging (or merge PR with inbound.enabled: true).
Confirm value updated in admin Keys (staging).

CLI smoke

For a non-mutating check, run sync-pr against a test branch with --provider none --json, then inspect the generated files before enabling PR creation in CI.

Troubleshooting

Problem	Likely cause	Fix
Export 401	Wrong/missing token or API host mismatch	Token from same environment as `STRINGPUSH_API_BASE_URL`
Export 404	Wrong `projectId` / `applicationId`	Copy from Config reference
Workflow cannot open PR	`GITHUB_TOKEN` lacks permissions	Add `contents: write`, `pull-requests: write`; or use PAT secret
`gh` PR fails on org repo	`GITHUB_TOKEN` cannot cross repos	Use PAT with `contents` + `pull_requests`
Ready for merge missing	App not linked or SDK < 0.3.8	Link in admin; upgrade to SDK 0.7.0+
Queue stays after merge click	Hosted Git sync job did not complete	Retry once, then contact StringPush support with the project, application, and environment
Installation id empty	Install callback interrupted	Re-run Connect GitHub App or paste id from GitHub App settings
Inbound ignored	`inbound.enabled: false` or wrong branch	Set `inbound.branch` to merge target; enable in sync config
Label errors	Label missing in GitHub	Create label or remove from `pr.labels` (CLI skips missing labels with warning)

FAQ

Can I sync production?
Yes — --env production and matching published values. Use separate branches (stringpush/sync-staging vs stringpush/sync-production).

Does sync include drafts?
Sync tokens: published only. Admin export can use includeDrafts=true.

What if nothing changed?
sync-pr exits 0 with unchanged.

CI and hosted App together?
Yes — same sync.yaml and PR branch naming; avoid running both on every save unless intentional.

Webhook events?
Enterprise webhook automation can notify your systems when a batch PR is queued. Contact StringPush support to enable and document the event contract for your account.

Exit codes

Code	Meaning
0	Success
1	Validation, config, or API error
2	Missing/invalid token

Rate limits

Export: 60 requests/minute per organization or sync token.

Staging overlay — edit mode + Ready for merge
Environment release — promote staging → production
Getting started — first init() and publish

Git sync (export → repo) ​

Beta quickstart ​

Choose your path ​

Outbound: CI vs hosted GitHub App ​

Source of truth ​

Admin: link a repository (hosted path) ​

Prerequisites ​

Finding setup values ​

API and admin URLs ​

Minimal checklist ​

Secrets and tokens ​

Example .stringpush/sync.yaml ​

Environment variables ​

Install CLI ​

Commands ​

Export / pull / sync-pr ​

Push (inbound — Git → platform) ​

Custom review adapter ​

Overlay: Ready for merge ​

GitHub Actions ​

Verify Git sync ​

Path A — CI sync-pr ​

Path B — Hosted overlay ​

Path C — Inbound (optional) ​

CLI smoke ​

Troubleshooting ​

FAQ ​

Exit codes ​

Rate limits ​

Related ​

Git sync (export → repo)

Beta quickstart

Choose your path

Outbound: CI vs hosted GitHub App

Source of truth

Admin: link a repository (hosted path)

Prerequisites

Finding setup values

API and admin URLs

Minimal checklist

Secrets and tokens

Example `.stringpush/sync.yaml`

Environment variables

Install CLI

Commands

Export / pull / sync-pr

Push (inbound — Git → platform)

Custom review adapter

Overlay: Ready for merge

GitHub Actions

Verify Git sync

Path A — CI `sync-pr`

Path B — Hosted overlay

Path C — Inbound (optional)

CLI smoke

Troubleshooting

FAQ

Exit codes

Rate limits

Related