> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nt3.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD Integration

> Automate translation syncing in your CI/CD pipeline.

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

```bash theme={null}
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.

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
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

1. Go to your repository on GitHub
2. Navigate to **Settings > Secrets and variables > Actions**
3. Click **New repository secret**
4. Set the name to `NT3_TOKEN` and paste your Entri API token as the value

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

## GitLab CI

```yaml theme={null}
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:

```bash theme={null}
# 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