CI/CD Integration

Automate your translation sync with three recurring steps: push new source strings when code is merged, audit key parity on pull requests, and pull finished translations before deploying.

Add your token as a secret

In your repository settings, add a secret named STRINGHIVE_TOKEN with a token scoped to Write (for push) and Read (for pull and audit). Never hardcode the token in workflow files.

For read-only steps, a Read-only token is sufficient — consider using separate secrets with the minimum required ability.

GitHub Actions

Push on merge

When a branch lands on main, push any new or updated source strings to Stringhive. --conflict-strategy=keep leaves existing translations intact so only genuinely new strings start empty.

name: Stringhive Sync

on:
  push:
    branches: [main]

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

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.5'

      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader

      - name: Push source strings
        run: php artisan stringhive:push my-app --conflict-strategy=keep
        env:
          STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

Audit on pull requests

Check key parity on every PR before it merges. --format=github emits ::warning annotations that appear inline in the PR diff, so reviewers see missing or orphaned keys directly on the changed files.

name: Translation Audit

on:
  pull_request:
    branches: [main]

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

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.5'

      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader

      - name: Audit translation keys
        run: php artisan stringhive:audit my-app --format=github --fail-on-missing
        env:
          STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

--fail-on-missing exits with code 1 if any keys used in your code are absent from the hive, failing the check. Drop it if you want annotations without blocking the PR.

Pull before deploy

Pull all finished translations before you build or package a release:

- name: Pull translations
  run: php artisan stringhive:pull my-app
  env:
    STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

Place this step before any npm run build or deployment step so the bundle always includes the latest strings.

Complete workflow

A single file that pushes on merge and audits on PRs:

name: Stringhive

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  push-strings:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.5'
      - run: composer install --no-dev --optimize-autoloader
      - run: php artisan stringhive:push my-app --conflict-strategy=keep
        env:
          STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

  audit:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.5'
      - run: composer install --no-dev --optimize-autoloader
      - run: php artisan stringhive:audit my-app --format=github --fail-on-missing
        env:
          STRINGHIVE_TOKEN: ${{ secrets.STRINGHIVE_TOKEN }}

GitLab CI

stringhive-push:
  stage: deploy
  only:
    - main
  script:
    - composer install --no-dev --optimize-autoloader
    - php artisan stringhive:push my-app --conflict-strategy=keep
  variables:
    STRINGHIVE_TOKEN: $STRINGHIVE_TOKEN

stringhive-audit:
  stage: test
  only:
    - merge_requests
  script:
    - composer install --no-dev --optimize-autoloader
    - php artisan stringhive:audit my-app --fail-on-missing
  variables:
    STRINGHIVE_TOKEN: $STRINGHIVE_TOKEN

Set STRINGHIVE_TOKEN in Settings > CI/CD > Variables with the Masked flag so it never appears in job logs.

Token scoping

Use a Write token for the push job and a separate Read token for pull and audit. This limits the blast radius if a secret leaks — a compromised Read token can't modify your source strings.