Skip to content

GitHub Actions Integration

← Back to CI/CD Overview

Quick Setup

Add the Lingo.dev GitHub Action to your workflow with this simple configuration:

yaml
- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Required Permissions

Your workflow must have these permissions:

yaml
permissions:
  contents: write
  pull-requests: write # Only if using pull request mode

Authentication Setup

  1. Store your Lingo.dev API key as a repository secret named LINGODOTDEV_API_KEY
  2. For pull request mode, provide the GitHub token:
yaml
- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
  1. Enable "Allow GitHub Actions to create and approve pull requests" in repository Settings → Actions → General

Complete Workflow Example

This example automatically translates new content whenever you push to feature branches:

yaml
name: Lingo.dev i18n

on:
  push:
    branches:
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Security for Fork-Based Workflows

When working with external forks, use this selective checkout approach to maintain security:

yaml
jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find apps/web/public/static/locales/** -name "common.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

This approach:

  1. Only checks out translation files from the fork
  2. Prevents exposure of sensitive code
  3. Maintains necessary write permissions

How the Action Works

The GitHub Action follows this process:

  1. Runs the translation engine to process new or changed content
  2. Stages all translation changes
  3. Either commits directly to your branch or creates a pull request
  4. Handles conflicts automatically through rebasing

Customization Options

ParameterDescriptionDefault
versionSpecify CLI version to uselatest
pull-requestCreate PR instead of direct pushfalse
pull-request-titleCustom PR titlefeat: update translations via @lingodotdev
commit-messageCustom commit messagefeat: update translations via @lingodotdev
working-directoryCustom working directory.
process-own-commitsProcess this action's commitsfalse

Example with Custom Options

yaml
- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    pull-request-title: "feat: update translations"
    commit-message: "feat: update translations"
    working-directory: "apps/web"
    process-own-commits: true

Note: When using process-own-commits: true, add persist-credentials: false to your checkout step.

Versioning

You can specify which version of the Lingo.dev CLI to use with the version parameter:

yaml
- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    version: "1.2.3" # Pin to specific version

In most cases, it's not recommended to pin versions, as that would prevent receiving updates and improvements to the CLI.