CI/CD Integration

The nt3 CLI is designed for use in CI/CD pipelines. All commands support non-interactive authentication via a flag or environment variable, and produce machine-readable JSON output with --json.

Recommended pattern

nt3 login -t $NT3_TOKEN   # authenticate non-interactively
nt3 push --json            # push source strings, fail on error
nt3 pull --json            # pull translations, fail on error

The CLI exits with code 1 on any error, making it straightforward to fail a pipeline step when something goes wrong.

GitHub Actions

Push on source file change

This workflow triggers whenever the source translation file is updated on main, pushes the new strings to Entri, triggers AI translation, and pulls the results back as a commit.

name: Sync Translations

on:
  push:
    branches:
      - main
    paths:
      - 'src/locales/en.json'

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

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Entri CLI
        run: npm install -g nt3

      - name: Authenticate
        run: nt3 login -t ${{ secrets.NT3_TOKEN }}

      - name: Push source strings
        run: nt3 push --json

      - name: Translate untranslated keys
        run: nt3 translate --all --json

      - name: Pull translations
        run: nt3 pull --json

      - name: Commit translated files
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update translations [skip ci]"
          file_pattern: "src/locales/*.json"

Pull on demand

A manually triggered workflow for pulling the latest translations without running a full sync:

name: Pull Translations

on:
  workflow_dispatch:

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

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Entri CLI
        run: npm install -g nt3

      - name: Pull translations
        run: |
          nt3 login -t ${{ secrets.NT3_TOKEN }}
          nt3 pull --json

      - name: Open pull request
        uses: peter-evans/create-pull-request@v6
        with:
          commit-message: "chore: pull latest translations"
          title: "Update translations"
          branch: "translations/update"

Environment variables

`NT3_API_TOKEN`

Set this variable instead of running nt3 login. It takes priority over stored credentials and requires no login step:

NT3_API_TOKEN=entri_your_token nt3 push --json

In GitHub Actions, store the token as a repository secret named NT3_TOKEN (or any name you prefer) and reference it with ${{ secrets.NT3_TOKEN }}.

Adding secrets in GitHub

Go to your repository on GitHub
Navigate to Settings > Secrets and variables > Actions
Click New repository secret
Set the name to NT3_TOKEN and paste your Entri API token as the value

Never hard-code your API token in workflow files. Always use secrets or environment variables.

GitLab CI

sync-translations:
  image: node:20
  stage: deploy
  only:
    changes:
      - src/locales/en.json
  script:
    - npm install -g nt3
    - nt3 login -t $NT3_TOKEN
    - nt3 push --json
    - nt3 translate --all --json
    - nt3 pull --json

Store NT3_TOKEN as a CI/CD variable in Settings > CI/CD > Variables.

Exit codes

Code	Meaning
`0`	Success
`1`	One or more errors occurred (authentication failure, file not found, API error, translation failures)

All commands respect these exit codes, so pipeline steps fail automatically on error without any additional scripting.

Parsing JSON output

With --json, commands write structured JSON to stdout. You can pipe this to jq for further processing:

# Count how many keys were created
nt3 push --json | jq '.totals.created'

# List files that had errors
nt3 pull --json | jq '.files[] | select(.error != null) | .path'

# Check overall success
nt3 translate --all --json | jq '.success'

Tips for reliable pipelines

Pin the CLI version to avoid unexpected behavior from updates: npm install -g nt3@1.2.3
Cache the npm install using actions/cache to speed up workflows
Use [skip ci] in auto-commit messages to prevent recursive workflow triggers
Run nt3 status early in a workflow to debug authentication issues before the real commands run

Getting Started

CLI

Integrations

Concepts

Open source

CI/CD Integration

Recommended pattern

GitHub Actions

Push on source file change

Pull on demand

Environment variables

`NT3_API_TOKEN`

Adding secrets in GitHub

GitLab CI

Exit codes

Parsing JSON output

Tips for reliable pipelines

​Recommended pattern

​GitHub Actions

​Push on source file change

​Pull on demand

​Environment variables

​NT3_API_TOKEN

​Adding secrets in GitHub

​GitLab CI

​Exit codes

​Parsing JSON output

​Tips for reliable pipelines

Recommended pattern

GitHub Actions

Push on source file change

Pull on demand

Environment variables

`NT3_API_TOKEN`

Adding secrets in GitHub

GitLab CI

Exit codes

Parsing JSON output

Tips for reliable pipelines