Skip to main content
The GitHub integration turns Entri into the source of truth that delivers translations to your codebase. Connect the Entri GitHub App once per organization, point each project at a repository and branch, then click Sync now — Entri exports your translations server-side, writes the files to the paths declared in the repo’s .nt3.yml, and either commits to the branch or opens a pull request. This removes the “a developer has to run the CLI” step. The same .nt3.yml that powers nt3 pull drives the server-side sync, so the files Entri writes are identical to what the CLI produces.

​
How it works

1

Connect the GitHub App (once per organization)

In Settings → Organization → GitHub, an owner or admin clicks Connect GitHub and installs the Entri GitHub App on the repositories you choose. We recommend installing on selected repositories rather than all repos.
2

Configure a repository (per project)

In Settings → Project → GitHub Sync, pick one of the installed repositories, set the target branch (e.g. main), and choose a sync mode.
3

Sync

Click Sync now. Entri reads .nt3.yml from the chosen branch, exports each language × file pattern, and writes the result to GitHub.

​
Sync modes

Open a pull request

Entri pushes to a dedicated nt3/sync-… branch and opens a pull request against your target branch. Re-running Sync now updates the same pull request rather than opening a new one. Recommended for protected branches and review workflows.

Commit to branch

Entri commits the translations directly to the target branch. If the branch is protected and rejects the push, Entri reports a clear error asking you to switch to pull request mode.

​
Configuration source of truth

Entri reads paths and formats from the .nt3.yml on the connected branch — exactly like the CLI. It does not duplicate path configuration in the UI.
.nt3.yml
project_id: <your-project-id>
source_language: en
file_patterns:
  - path: locales/{lang}/messages.po
    format: po
  - path: src/i18n/{lang}.json
    format: json-nested
The {lang} placeholder is replaced with each language code. The source language comes from .nt3.yml; the target languages come from your project settings. If source_language in .nt3.yml disagrees with the project’s source language, the sync fails with a config drift error rather than silently diverging.

​
Behavior and limits

  • Additive / overwrite-only. Entri creates or overwrites the managed translation files. It does not delete files from the repo, even if a language is removed. Deleting stale files is planned for a later release.
  • Commits appear as nt3[bot] and are shown as Unverified in GitHub — this is normal for GitHub App tokens.
  • No empty syncs. If nothing changed since the last sync, Entri reports “Up to date — no changes” and creates no commit or pull request.
  • Path safety. Paths are validated before any write: absolute paths, .. traversal, and anything under .github/ are rejected.
  • Required App permissions (least privilege): Contents: Read & Write, Pull requests: Read & Write, Metadata: Read. The App does not request Workflows, Actions, Administration, or Secrets.

​
Permissions

ActionRequired role
Connect / disconnect the GitHub AppOwner or Admin
Configure a project’s repository, branch, and modeOwner or Admin
Trigger a sync (Sync now)Developer or higher
See Roles & Permissions for the full role matrix.

​
Troubleshooting

Entri could not find or parse .nt3.yml on the configured branch. Add one (run nt3 init locally and commit it) and try again. The error message names the file, branch, and the invalid field.
The GitHub App was removed or suspended for your organization. Reconnect it from Settings → Organization → GitHub.
In commit mode, a protected branch will reject a direct push. Switch the project to pull request mode.
The App is installed but no repositories were granted. Adjust the installation on GitHub to grant access to the repository you want to sync.