CI/CD Integration

Mergua CLI

Automatically sync translations between your codebase and Mergua via CI/CD — on GitLab, GitHub or Gitea. Use subcommands to push keys, pull translations, detect merges, or run a full sync.

Do you even need the CLI?

The Mergua CLI is a convenience layer for CI/CD pipelines (committing pulled translations, key sync, merge notifications). If you only want to read translations, you don't need it at all — the public REST API lets you pull any locale directly:

curl -H "X-API-Key: $MERGUA_API_KEY" \
  "https://api.mergua.com/v1/$PROJECT_ID/translations/fr?branch=develop&format=nested"

Reach for the CLI when you want a pipeline to commit translations back, push keys, or report merges automatically.

How it works

Your pipeline downloads the Mergua CLI from the Mergua API and runs a command (works on GitLab, GitHub & Gitea — the provider is auto-detected)

The CLI checks if your Git branch has a matching branch in Mergua

push — Uploads translation keys and all locale translations to Mergua

Push

notify — Detects if a Git branch was just merged and notifies Mergua (optionally auto-merges the Mergua branch)

Notify

pull — Downloads translations (based on --mode: always, reviewed, or never)

Pull

If translations changed: commits and pushes directly to your branch (sync command only)

Prerequisites

Before setting up the pipeline sync, you need to prepare a few things.

1. Mergua project

Create a project in Mergua (or use an existing one)
Add at least one locale (e.g. English as source, German as target)
Copy your Project ID from the project header (click the UUID to copy)

2. Mergua API key

Go to your project in Mergua
Scroll down to API Keys
Create a new key and copy it immediately (it won't be shown again)

3. Git host access token

GitLab: Preferences > Access Tokens with api scope
GitHub: Use GITHUB_TOKEN (automatic) or a PAT
Gitea: Token with repo + API scope
Only needed for the sync and notify commands — pull / push work without it. See Git Providers.

4. CI/CD variables

Add these as masked variables in your CI/CD settings:

Variable	Value	Options
MERGUA_API_KEY	Your Mergua API key	Masked
MERGUA_GIT_TOKEN	Git host token (for sync/notify)	Masked

Important: Secrets must be set as masked variables in your CI settings, not in your pipeline file. Secrets in YAML are visible to everyone with repo access.

Quickstart

After completing the prerequisites above, add this to your .gitlab-ci.yml:

# MERGUA_API_KEY and MERGUA_GIT_TOKEN must be set as masked CI/CD variables
# (Settings > CI/CD > Variables) — never put secrets in this file.
variables:
  MERGUA_PROJECT_ID: "your-project-uuid"

stages:
  - .pre
  - build
  # ... your other stages

mergua-sync:
  stage: .pre
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq git
  script:
    - curl -sf https://api.mergua.com/v1/mergua.sh | sh -s -- sync
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - if: $CI_COMMIT_BRANCH
      when: always
  allow_failure: false

Commit and push. The mergua-sync job appears in the .pre stage of your pipeline.

Commands

The Mergua CLI uses subcommands to select which operation to run. Each command can be customised with flags — run any command with --help for details.

curl -sf https://api.mergua.com/v1/mergua.sh | sh -s -- <command> [flags]

Command	Push keys	Notify merge	Pull	Commit & push	Git token
`sync`
`pull`				you commit
`push`
`notify`

MERGUA_API_KEY (your Mergua project key) is always required — every command talks to the Mergua API. MERGUA_GIT_TOKEN (your Git host token) is only needed for sync and notify, because those push commits or query the Git host API. pull and push never need MERGUA_GIT_TOKEN.

Just need the files once, without any pipeline? Download translations directly from the REST API — Import & Export › API access.

The sync command triggers a second pipeline

The sync command commits and pushes translation changes to your branch. This push triggers a second pipeline run on your CI. The CLI detects its own commits (starting with Mergua: sync translations) and skips automatically — no infinite loops. But the second pipeline still shows up in your CI history.

Alternatives to avoid the second pipeline:

Pull + own commit step: Use the pull command and add your own git commit / git push step with [skip ci] in the commit message.
GitLab workflow rules: Exclude pipelines when the commit message starts with Mergua::

workflow:
  rules:
    - if: $CI_COMMIT_MESSAGE =~ /^Mergua:/
      when: never
    - when: always

GitHub: skip push events from Mergua: Add a condition:

jobs:
  mergua-sync:
    if: ${{ !startsWith(github.event.head_commit.message, 'Mergua:') }}
    runs-on: ubuntu-latest

Precedence: CLI flag > env var > default

Every option can be passed as a CLI flag or set as an environment variable. CLI flags always take precedence over environment variables. Environment variables are useful for CI/CD pipeline defaults, while flags let you override per-run.

# All equivalent:
curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- pull --path src/locale --format flat
MERGUA_LOCALE_PATH=src/locale MERGUA_FILE_FORMAT=flat curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- pull

Git Providers

The same CLI runs on GitLab, GitHub and Gitea. The provider is auto-detected from the CI environment (GITLAB_CI, GITEA_ACTIONS, GITHUB_ACTIONS — Gitea is checked before GitHub because it sets both). Override with --provider if detection is wrong.

What	GitLab CI	GitHub / Gitea Actions
Branch	CI_COMMIT_REF_NAME	GITHUB_REF_NAME
Commit SHA	CI_COMMIT_SHA	GITHUB_SHA
Repo (owner/repo)	CI_PROJECT_PATH	GITHUB_REPOSITORY
Merge detection	Merge Requests API	Pull Requests API

GitHub Actions

MERGUA_GIT_TOKEN is the host access token (only needed for sync / notify commands).

name: Mergua Sync
on:
  push:
    branches: ['**']
jobs:
  mergua-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: sudo apt-get update && sudo apt-get install -y jq
      - run: curl -sf https://api.mergua.com/v1/mergua.sh | sh -s -- sync
        env:
          MERGUA_API_KEY: ${{ secrets.MERGUA_API_KEY }}
          MERGUA_PROJECT_ID: ${{ secrets.MERGUA_PROJECT_ID }}
          MERGUA_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Gitea Actions

The same workflow works unchanged — --provider auto-detects gitea, and the API base is derived from GITHUB_SERVER_URL. Pass a token with repo + API scope as MERGUA_GIT_TOKEN.

Branch Matching

The CLI automatically matches your Git branch to a Mergua branch by name. This keeps translation work isolated per feature — just like Mergua branches isolate translation changes from main. Override with --branch.

Feature branches

When you push a branch like feature/login, the CLI looks for a Mergua branch with the same name.

Branch exists: Translations are pulled from that branch, keys are synced to it
Branch doesn't exist: Translations fall back to --fallback-branch (default: main). Key Sync auto-creates the branch (enabled by default, disable with --no-auto-create).

Main / master

On main or master, translations are always pulled from Mergua's main branch. Key Sync is skipped — keys reach main via branch merges, not direct pushes.

Git branch	Mergua branch exists?	Pull	Key Sync
feature/login	Yes	Uses `feature/login`	Syncs to `feature/login`
feature/login	No	Falls back to `--fallback-branch`	Creates `feature/login` branch
develop	Yes	Uses `develop`	Syncs to `develop`
main	—	Uses `main`	Skipped

Configuration Examples

Common setups for different use cases. Pass options as CLI flags or set them as environment variables (flags take precedence).

Minimal — Translation pull only

Downloads translations on every push. Good for projects where keys are managed in Mergua directly.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- pull

Custom path and format

Override the locale path and JSON format via CLI flags.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- pull --path src/locale --format flat

Without Key Sync

Key Sync is enabled by default in the sync and push commands. Disable it if keys are managed in Mergua directly.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- sync --no-key-sync

Full setup — with Auto-Merge

Fully automated: keys and translations are synced, and when you merge your Git branch, the matching Mergua branch is auto-merged too.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- sync --auto-merge

Key Manifest File

If your project uses a separate key structure file (e.g. main.json) instead of a source locale file, point the manifest path directly to it.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- sync --key-manifest src/assets/i18n/main.json

The CLI extracts all string leaf nodes as keys, regardless of what the values contain.

Two-way Key Sync (Key Pull)

When your team also creates keys directly in Mergua, enable Key Pull to keep your manifest file in sync. Without it, keys added in Mergua would be deleted on the next pipeline run.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- sync --key-manifest src/assets/i18n/main.json --key-pull

Requires --key-manifest to point to a file (not a directory).

Reviewed pull mode

Only pull translations when all locales are fully reviewed and conflict-free.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- pull --mode reviewed

Available modes: always (default), reviewed, never.

Debian/Ubuntu CI image

If your CI image is Debian-based instead of Alpine, use apt-get to install dependencies:

mergua-sync:
  stage: .pre
  image: node:22
  before_script:
    - apt-get update && apt-get install -y jq
  script:
    - curl -sf https://api.mergua.com/v1/mergua.sh | sh -s -- sync
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - if: $CI_COMMIT_BRANCH
      when: always

Most Debian/Ubuntu images already include curl and git. Only jq typically needs to be installed.

Pull-only — commit it yourself

Writes translation files and stops. No MERGUA_GIT_TOKEN needed — your own steps commit and push.

curl -sf https://api.mergua.com
                        /api/v1/mergua.sh | sh -s -- pull --path src/assets/i18n

Push-only — keys up, nothing back

Uploads keys/translations to Mergua without pulling or committing.

curl -sf https://api.mergua.com
                        /api/v1/mergua.sh | sh -s -- push

Notify-only — react to merges

A main-branch job that only tells Mergua a branch was merged (and optionally auto-merges it), without pushing or pulling.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- notify --auto-merge

JSON output

Pass --json before the command for machine-readable output. Human-readable logs go to stderr, JSON result to stdout.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- --json pull

Continue on errors

Pass --no-fail to continue the pipeline even when the Mergua API returns an error.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- --no-fail sync

Key Sync (Push)

Automatically push translation keys from your source code to Mergua. New keys appear for translators immediately, deleted keys are tracked as branch operations.

Enabled by default

Key Sync is enabled by default in the sync and push commands. No extra configuration needed — keys are pushed automatically.

The source locale and locale folder are auto-detected from your Mergua project settings. Override with --source and --key-manifest if needed.

To disable Key Sync, pass --no-key-sync.

How it works

Reads all locale files from your locale folder (e.g. en.json, de.json) and syncs them to Mergua
Keys are determined from the source locale file — new keys are created with translations from all locale files
Removed keys are tracked as DELETE_KEY branch operations
Existing keys and translations are left untouched

Branch behavior

Keys are synced to a Mergua branch matching your Git branch name
With --auto-create (default), the branch is created automatically
Key sync is skipped on main/master branches (keys reach main via merge)

Pipeline order

In the sync command, Key Sync runs before the translation download. This means newly pushed keys are immediately available when translations are pulled back.

Key Pull (Two-way Sync)

By default, Key Sync is one-way: code → Mergua. Enable --key-pull to also update your manifest file with keys added in Mergua. Without it, keys created via the dashboard are deleted on the next sync because they're missing from your manifest.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- sync --key-manifest src/assets/i18n/main.json --key-pull

Requires --key-manifest to point to a file, not a directory. Enable when translators or PMs add keys directly in Mergua.

Workflows

End-to-end scenarios showing what happens at each step and what you configure where. Pick the one closest to your setup.

Feature branch → review → merge (sync command)

The default, fully automated flow. Keys flow from code to Mergua per branch, translators work in isolation, and translations flow back when the branch merges.

Configure

# .gitlab-ci.yml
variables:
  MERGUA_PROJECT_ID: "your-project-uuid"

mergua-sync:
  stage: .pre
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq git
  script:
    - curl -sf $MERGUA_API_URL/mergua.sh | sh -s -- sync --auto-merge

MERGUA_API_KEY and MERGUA_GIT_TOKEN as masked CI/CD variables; MERGUA_PROJECT_ID in the variables: block.

Flow

YouPush a feature branch
e.g. feature/login, with new i18n keys added in your source locale.
CIPipeline runs "sync" command
Provider auto-detected; branch resolved from the CI environment.
MerguaBranch auto-created, keys pushed
A matching Mergua branch is created and the new keys appear for translators.
CIExisting translations pulled & committed
Any translations already in Mergua are written back to your branch.
TeamTranslators work in Mergua
They translate and review on the feature branch, isolated from main.
GitYou merge the MR/PR into main
The next pipeline on main detects which branch was merged.
MerguaMergua branch auto-merged
--auto-merge triggers automatic merging of the Mergua branch.
CImain pipeline replaces the locale files
The final, merged translations are committed to main.

Monorepo / multi-locale folder

Point the manifest at a folder to sync keys from the source locale and push every locale file in one run — handy for repos that keep all languages side by side.

Configure

# .gitlab-ci.yml
mergua-sync:
  script:
    - curl -sf $MERGUA_API_URL/mergua.sh | sh -s -- sync --path libs/i18n/src/assets --key-manifest libs/i18n/src/assets

--key-manifest points to the locale folder; the source locale is auto-detected and all other locale files are pushed as translations.

Flow

YouPush with changed locale files
e.g. en.json gains keys, de.json gains some translations.
MerguaKeys synced from the source locale
Folder mode reads {folder}/{sourceLocale}.json as the key manifest.
MerguaAll other locales pushed as translations
de.json, fr.json, … are uploaded for their respective languages.
CITranslations pulled & merged into each file
Every locale file in the folder is refreshed and committed.

Pull-only — you own the commit (any provider)

The pipeline only writes translation files; your own steps commit and push. No git token required, so it works with the most restricted CI tokens.

Configure

# .gitlab-ci.yml
mergua-sync:
  script:
    - curl -sf $MERGUA_API_URL/mergua.sh | sh -s -- pull

Only MERGUA_API_KEY is needed (no MERGUA_GIT_TOKEN). Add your own git add/commit/push (or open a PR) after the script runs.

Flow

CIPipeline runs the "pull" command
Branch resolved from CI; no commits are made by the CLI.
MerguaTranslations downloaded
Locale files are written to --path (default: src/assets/i18n).
CIFiles left in the working tree
The CLI prints a hand-off message and exits.
YouCommit & push your way
Custom message, signing, formatters, or open a dedicated PR — your call.

Sync Behavior

Understanding when keys get created, updated, deleted, or left unchanged. The push and sync commands compare your manifest file against the keys in Mergua and apply the difference.

Example: First sync

You push this manifest file for the first time:

en.json

{
  "home": {
    "title": "Welcome",
    "subtitle": "Get started"
  },
  "auth": {
    "login": "Log in"
  }
}

Result:+3 created — All three keys (home.title, home.subtitle, auth.login) are new.

Example: Key added and removed

On the next push, you added a key and removed another:

en.json (updated)

{
  "home": {
    "title": "Welcome",
    "subtitle": "Get started",
    "cta": "Try it free"
  }
}

+1 createdhome.cta is new · -1 deletedauth.login is missing from the manifest · =2 unchanged

Example: Value changed

If the source value of an existing key changes:

en.json (value changed)

{
  "home": {
    "title": "Welcome back",
    "subtitle": "Get started",
    "cta": "Try it free"
  }
}

~1 updatedhome.title changed from "Welcome" to "Welcome back" — tracked as a MODIFY_VALUE branch operation · =2 unchanged

When are keys deleted?

A key is marked for deletion when it exists in Mergua but is missing from your manifest
Deletions are tracked as DELETE_KEY branch operations — they are not permanent until the branch is merged
If you re-add the key to your manifest, the deletion is automatically undone on the next sync
The Sync Dashboard shows which keys were deleted in each sync run

When are keys updated?

A key is updated when its source locale value changes between syncs
Updates are tracked as MODIFY_VALUE branch operations with the new value
Other locale translations are not affected — only the source value is compared

Who is shown as "created by"?

When the CI pipeline creates branches, adds keys, or edits translations, the API key owner's name is shown as the creator. This is the team member who generated the API key in the project settings.

Pipeline-created items are marked with a via CI Pipeline badge so you can distinguish manual edits from automated syncs.

API response

The sync endpoint returns the affected key names. Pass --json for machine-readable output:

{
  "created": ["home.cta"],
  "deleted": ["auth.login"],
  "updated": ["home.title"],
  "unchanged": 2,
  "summary": {
    "created": 1, "deleted": 1,
    "updated": 1, "unchanged": 2
  },
  "branch": "feature/redesign",
  "branchCreated": false
}

Translation Pull

The pull command downloads translations from Mergua. In sync, translations are also committed directly to your branch. Control when translations are pulled with --mode.

Pull modes (--mode)

Mode	Behavior
always	Downloads translations on every pipeline run, even if some locales are incomplete. This is the default.
reviewed	Checks branch readiness first. Only downloads if all translations are reviewed and no conflicts exist.
never	Skips translation download entirely. Useful when you only want Key Sync and Merge Notifications (via `sync`).

Smart merge

Translations from Mergua are merged with your local files, not overwritten. Mergua values take precedence where they exist, but local values are preserved for keys that Mergua doesn't have translations for yet.

Direct commit (sync command)

In the sync command, translations are committed and pushed directly to your branch — no separate merge request. The CLI automatically skips itself when it detects its own sync commits, so there are no infinite pipeline loops.

Pull command — where do the files go?

The pull command only writes translation files to disk — it does not commit or push. Where the files end up depends on how you run the CLI:

In CI/CD: The files are written to the runner's working directory. Add a subsequent step to commit and push them.
Locally: Run the command in your project folder and the files are written directly into your working tree.

Example CI step to commit after pull:

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- pull

git add src/assets/i18n/

git diff --cached --quiet || git commit -m "chore: update translations [skip ci]"

git push origin HEAD

Token requirements

Downloading translations only needs your MERGUA_API_KEY. Committing the pulled translations back to your repo (sync command) additionally needs MERGUA_GIT_TOKEN with write access.

Readiness Check (--mode reviewed)

With --mode reviewed, the CLI checks branch readiness before downloading. Translations are only pulled when all locales are fully reviewed and conflict-free. hasConflicts signals that translations on main were modified after the branch operations were created.

Git Merge Notification

When a Git branch is merged, the notify command (also part of sync) detects the merge and notifies Mergua. A banner appears on the matching Mergua branch card.

How it works

Runs on the target branch after a merge — checks whether the current commit was a merge
Asks your git host which PR/MR produced this commit
If a merge is found, calls the Mergua notification endpoint
The Mergua branch is marked as "git-merged" and a readiness summary is printed

What Mergua records about the merge

When — the merged_at from the host
Where — the target branch name
Branch existence — whether the source branch was deleted after the merge

When it's not clean

Merge notification is best-effort — it never fails your pipeline (independent of --no-fail). You may see:

Nothing — the commit wasn't a merge, or no PR/MR was found (expected on normal commits)
No matching Mergua branch — merge detected but no Mergua branch matches
Status: NOT READY — marked git-merged, but translations still need review

Auto-Merge

With --auto-merge, the CLI automatically merges the Mergua branch when the Git branch is merged. If all operations are reviewed, a full merge is performed. If only some locales are ready, a partial merge is attempted.

curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- notify --auto-merge
# or as part of full sync:
curl -sf https://api.mergua.com/api/v1/mergua.sh | sh -s -- sync --auto-merge

Command Reference

Complete flag reference for each command. Global flags (before the command) work with all commands.

Global Flags

Place before the command name. Apply to all commands.

--api-key <key>Env: MERGUA_API_KEY

Mergua project API key

--project <uuid>Env: MERGUA_PROJECT_ID

Mergua project UUID

--provider <name>Env: MERGUA_GIT_PROVIDER

Git provider: gitlab, github, or gitea (auto-detected)

--branch <name>Env: MERGUA_GIT_BRANCH

Git branch (auto-detected from CI)

--json

Machine-readable JSON output (result on stdout, logs on stderr)

--no-color

Disable colored output

--no-failEnv: MERGUA_FAIL_ON_ERROR=false

Continue on errors instead of failing the pipeline

--version, -v

Print version and exit

pull

Download translations from Mergua

--format nested|flatDefault: nested

JSON format for translation files

--path <dir>Default: src/assets/i18n

Where translation files are written

--mode always|reviewed|neverDefault: always

When to download translations

--fallback-branch <name>Default: main

Fallback when no matching Mergua branch exists

--auto-create / --no-auto-createDefault: auto-create

Auto-create Mergua branch if it does not exist

--key-pullDefault: off

Update manifest file with keys from Mergua

--key-manifest <path>Default: same as --path

Path to key manifest file (required for --key-pull)

push

Upload keys/translations to Mergua

--source <locale>Default: auto-detected

Source locale code (e.g. "en")

--key-manifest <path>Default: same as --path

Path to locale folder or single manifest file

--path <dir>Default: src/assets/i18n

Where locale files are read from

--no-key-sync

Skip key sync entirely

--auto-create / --no-auto-createDefault: auto-create

Auto-create Mergua branch if it does not exist

notify

Report git merges to Mergua

--git-token <token>Env: MERGUA_GIT_TOKEN

Git host token (required — used to query merge status)

--auto-merge / --no-auto-mergeDefault: no auto-merge

Automatically merge the Mergua branch when the Git branch is merged

sync

Full sync: push + notify + pull + commit. Combines all flags from pull, push, and notify.

Accepts all flags from pull (--format, --path, --mode, --fallback-branch, --key-pull, --key-manifest, --auto-create), push (--source, --no-key-sync), and notify (--git-token, --auto-merge).

version

Print the CLI version. With --json, outputs as JSON.

Environment Variables

All environment variables are fallbacks for CLI flags. Precedence: CLI flag > env var > built-in default. Secrets should always be passed as env vars in CI/CD pipelines.

At a glance

Variable	Used for	Default	Required
MERGUA_API_KEY	Authenticates the CLI with your Mergua project	—	required	Read more
MERGUA_GIT_TOKEN	Lets the CLI push commits & query the Git host	—	conditional	Read more
MERGUA_PROJECT_ID	Selects which Mergua project to sync	—	required	Read more
MERGUA_API_URL	Points the CLI at the right Mergua server	auto (from server)	optional	Read more
MERGUA_LOCALE_PATH	Where translation files are read & written	src/assets/i18n	optional	Read more
MERGUA_FILE_FORMAT	Shape of the JSON output (nested vs flat)	nested	optional	Read more
MERGUA_FALLBACK_BRANCH	Source branch when no matching Mergua branch exists	main	optional	Read more
MERGUA_GIT_PROVIDER	Which Git host integration to use	auto-detected	optional	Read more
MERGUA_GIT_BRANCH	Which branch to sync	auto (CI var / git)	optional	Read more
MERGUA_GIT_REMOTE	Where translation commits are pushed	auto (per provider)	optional	Read more
MERGUA_GIT_REPO	Identifies the repo to the host API	auto (CI var)	optional	Read more
MERGUA_KEY_SYNC	Turns on pushing keys from code to Mergua	true	optional	Read more
MERGUA_KEY_MANIFEST_PATH	Where keys & locale files are discovered	MERGUA_LOCALE_PATH	optional	Read more
MERGUA_SOURCE_LOCALE	Which locale holds the canonical keys	auto-detected	optional	Read more
MERGUA_AUTO_CREATE_BRANCH	Creates the Mergua branch on first sync	true	optional	Read more
MERGUA_KEY_PULL	Writes new keys back into your manifest	false	optional	Read more
MERGUA_PULL_MODE	When translations get pulled	always	optional	Read more
MERGUA_FAIL_ON_ERROR	Whether API errors fail the pipeline	true	optional	Read more
MERGUA_AUTO_MERGE_BRANCH	Merges translations when the Git branch merges	false	optional	Read more

Full details by category:

Secrets (CI/CD Variables)

Set these in GitLab > Settings > CI/CD > Variables. Never put them in .gitlab-ci.yml. Secrets are always passed as env vars, never as CLI flags.

MERGUA_API_KEYRequired

Mergua project API key — must be masked in GitLab. Also available as --api-key flag for non-CI usage.

MERGUA_GIT_TOKENConditional

Git host token with api + write scope. Only required for sync and notify commands — pull and push do not need it. Must be masked. Also available as --git-token flag.

Project Configuration

Set these in the variables block or pass them as CLI flags (flags take precedence).

MERGUA_PROJECT_IDRequired

Mergua project UUID (copy from the project header). CLI flag: --project

MERGUA_API_URLDefault: auto (from server)

Mergua API base URL. Automatically set by the server that delivers the script.

MERGUA_LOCALE_PATHDefault: src/assets/i18n

Path where translation files are written. CLI flag: --path

MERGUA_FILE_FORMATDefault: nested

JSON format: nested or flat. CLI flag: --format

MERGUA_FALLBACK_BRANCHDefault: main

Fallback branch when no matching Mergua branch exists. CLI flag: --fallback-branch

Git Provider

Auto-detected from the CI environment — set these only when running outside CI or overriding detection.

MERGUA_GIT_PROVIDERDefault: auto-detected

Git host: gitlab, github, or gitea. CLI flag: --provider

MERGUA_GIT_BRANCHDefault: auto (CI var / git)

Branch to sync. Falls back to the CI branch variable, then `git rev-parse`. CLI flag: --branch

MERGUA_GIT_REMOTEDefault: auto (per provider)

Full authenticated push remote URL. Derived per provider by default; set on unusual hosting.

MERGUA_GIT_REPODefault: auto (CI var)

Repository path owner/repo. Derived from CI_PROJECT_PATH (GitLab) or GITHUB_REPOSITORY (GitHub/Gitea).

Key Sync

These env vars are fallbacks for CLI flags on push and sync commands.

MERGUA_KEY_SYNCDefault: true

Key Sync — push keys from code to Mergua. Enabled by default. CLI flag: --no-key-sync (to disable)

MERGUA_KEY_MANIFEST_PATHDefault: MERGUA_LOCALE_PATH

Path to locale folder or single file. CLI flag: --key-manifest

MERGUA_SOURCE_LOCALEDefault: auto-detected

Source locale code, e.g. "en". Auto-detected from your Mergua project settings. CLI flag: --source

MERGUA_AUTO_CREATE_BRANCHDefault: true

Auto-create Mergua branch if it does not exist. CLI flags: --auto-create / --no-auto-create

MERGUA_KEY_PULLDefault: false

Update the manifest file with keys from Mergua after each translation pull. CLI flag: --key-pull

Pipeline Behavior

These env vars are fallbacks for CLI flags and command selection.

MERGUA_PULL_MODEDefault: always

When to pull translations: always (every run), reviewed (only when fully reviewed), never (skip pull). CLI flag: --mode

MERGUA_FAIL_ON_ERRORDefault: true

Fail pipeline on Mergua API errors. CLI flag: --no-fail (to disable)

MERGUA_AUTO_MERGE_BRANCHDefault: false

Auto-merge Mergua branch when Git branch is merged. CLI flags: --auto-merge / --no-auto-merge

Mergua CLI

Do you even need the CLI?

How it works

Prerequisites

1. Mergua project

2. Mergua API key

3. Git host access token

4. CI/CD variables

Quickstart

Commands

The sync command triggers a second pipeline

Precedence: CLI flag > env var > default

Git Providers

GitHub Actions

Gitea Actions

Branch Matching

Feature branches

Main / master

Configuration Examples

Minimal — Translation pull only

Custom path and format

Without Key Sync

Full setup — with Auto-Merge

Key Manifest File

Two-way Key Sync (Key Pull)

Reviewed pull mode

Debian/Ubuntu CI image

Pull-only — commit it yourself

Push-only — keys up, nothing back

Notify-only — react to merges

JSON output

Continue on errors

Key Sync (Push)

Enabled by default

How it works

Branch behavior

Pipeline order

Key Pull (Two-way Sync)

Workflows

Feature branch → review → merge (sync command)

Monorepo / multi-locale folder

Pull-only — you own the commit (any provider)

Sync Behavior

Example: First sync

Example: Key added and removed

Example: Value changed

When are keys deleted?

When are keys updated?

Who is shown as "created by"?

API response

Translation Pull

Pull modes (--mode)

Smart merge

Direct commit (sync command)

Pull command — where do the files go?

Token requirements

Readiness Check (--mode reviewed)

Git Merge Notification

How it works

What Mergua records about the merge

When it's not clean

Auto-Merge

Command Reference

Global Flags

pull

push

notify

sync

version

Environment Variables

At a glance

Secrets (CI/CD Variables)

Project Configuration

Git Provider

Key Sync

Pipeline Behavior

Troubleshooting

Setup & Configuration

Authentication & Access

Key Sync