> ## 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.

# GitLab CI

> Automate translation syncing with GitLab CI/CD.

Integrate Entri into your GitLab CI/CD pipelines to automatically push new source strings and pull translations. The `nt3` CLI supports non-interactive authentication and JSON output designed for CI environments.

## Prerequisites

* An Entri API token (generate one in **Settings → API Tokens**)
* A `.nt3.yml` config file committed to your repository
* The `nt3` CLI installed in your pipeline

## Store your API token

Add your Entri API token as a CI/CD variable:

1. Go to your GitLab project → **Settings → CI/CD → Variables**
2. Click **Add variable**
3. Set the key to `NT3_TOKEN`, paste your API token as the value, and mark it as **Masked**

## Basic pipeline: push on source change

This job runs when your source locale file changes and pushes updated strings to Entri.

```yaml theme={null}
sync-translations:
  image: node:22
  rules:
    - changes:
        - src/locales/en.json
  script:
    - npm install -g nt3
    - nt3 login -t $NT3_TOKEN
    - nt3 push --json
```

## Full sync pipeline: push and pull

Push source strings and pull back all translations, then commit the result to the repository.

```yaml theme={null}
sync-translations:
  image: node:22
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - src/locales/en.json
  before_script:
    - npm install -g nt3
    - nt3 login -t $NT3_TOKEN
  script:
    - nt3 push --json
    - nt3 pull --json
    - |
      git config user.email "ci@gitlab.com"
      git config user.name "GitLab CI"
      git add src/locales/
      git diff --staged --quiet || git commit -m "chore: update translations from Entri"
      git push "https://oauth2:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" HEAD:$CI_COMMIT_BRANCH
```

<Note>
  Committing back to the repository requires a `GITLAB_TOKEN` with write access to the repository. Create a project access token with the `write_repository` scope and add it as a CI/CD variable.
</Note>

## Scheduled AI translation

Use a GitLab scheduled pipeline to run AI translation automatically.

```yaml theme={null}
# .gitlab-ci.yml

stages:
  - translate

auto-translate:
  stage: translate
  image: node:22
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  before_script:
    - npm install -g nt3
    - nt3 login -t $NT3_TOKEN
  script:
    - nt3 translate --all --json
    - nt3 pull --json
    - |
      git config user.email "ci@gitlab.com"
      git config user.name "GitLab CI"
      git add src/locales/
      git diff --staged --quiet || git commit -m "chore: AI translations from Entri"
      git push "https://oauth2:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" HEAD:$CI_DEFAULT_BRANCH
```

Configure the schedule under **CI/CD → Schedules** in your GitLab project settings (for example, daily at 2 AM UTC).

## Complete multi-stage example

A production-ready configuration with separate push and pull stages.

```yaml theme={null}
stages:
  - push
  - pull

variables:
  NODE_VERSION: "22"

.entri-setup: &entri-setup
  image: node:${NODE_VERSION}
  before_script:
    - npm install -g nt3
    - nt3 login -t $NT3_TOKEN

push-source-strings:
  <<: *entri-setup
  stage: push
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - src/locales/en.json
  script:
    - nt3 push --json

pull-translations:
  <<: *entri-setup
  stage: pull
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - src/locales/en.json
  script:
    - nt3 pull --json
    - |
      git config user.email "ci@gitlab.com"
      git config user.name "GitLab CI"
      git add src/locales/
      git diff --staged --quiet || git commit -m "chore: update translations from Entri"
      git push "https://oauth2:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" HEAD:$CI_DEFAULT_BRANCH
  needs:
    - push-source-strings
```

## CLI flags reference

| Flag                          | Purpose                                                 |
| ----------------------------- | ------------------------------------------------------- |
| `nt3 login -t <token>`        | Non-interactive authentication for CI                   |
| `nt3 push --json`             | Push source strings; output machine-readable JSON       |
| `nt3 pull --json`             | Pull all target languages; output machine-readable JSON |
| `nt3 pull -l fr --json`       | Pull a specific language only                           |
| `nt3 translate --all --json`  | AI-translate all untranslated keys                      |
| `nt3 push --overwrite --json` | Push and overwrite existing translations                |

## Exit codes

The CLI exits with `0` on success and a non-zero code on failure, causing the pipeline job to fail automatically. Use `--json` for structured output that can be parsed in downstream scripts or notifications.

## Self-hosted Entri

If you are running a self-hosted Entri instance, pass the `--url` flag during login:

```yaml theme={null}
script:
  - nt3 login -t $NT3_TOKEN -u https://entri.your-company.com
  - nt3 push --json
```