GitHub Actions Integration

← Back to CI/CD Overview

Quick Setup

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

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

Required Permissions

Your workflow must have these permissions:

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:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

3. 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:

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:

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

Parameter	Description	Default
version	Specify CLI version to use	latest
pull-request	Create PR instead of direct push	false
pull-request-title	Custom PR title	feat: update translations via @lingodotdev
commit-message	Custom commit message	feat: update translations via @lingodotdev
working-directory	Custom working directory	.
process-own-commits	Process this action's commits	false

Example with Custom Options

- 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:

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