> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Action drift check

> Run Hyperlocalise localization drift checks in GitHub Actions.

## Overview

Use the repository root action when you want a pull request check that fails on localization drift.

The action runs `hyperlocalise run --dry-run`, streams the CLI output to the workflow log, and uploads two artifacts when enabled:

* `drift-report.json`
* `drift-summary.txt`

## Example workflow

```yaml theme={null}
name: localization-drift

on:
  pull_request:

jobs:
  drift:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: ./
        with:
          check: drift
          config-path: i18n.yml
          hyperlocalise-version: latest
          fail-on-drift: true
          upload-artifact: true
```

For pull request checks, `check` mode can fetch the GitHub pull request diff and pass it to `hyperlocalise check --diff-stdin`. This scopes findings and inline annotations to changed translation keys for supported `.json`, `.jsonc`, and `.arb` files.

```yaml theme={null}
name: localization-check

on:
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
    steps:
      - uses: actions/checkout@v4

      - uses: hyperlocalise/hyperlocalise@v1
        with:
          check: check
          config-path: i18n.yml
          github-diff: true
          fail-on-findings: true
```

When source files use [`extract --prefix-id`](/commands/extract) keys but target files use packed ids from [`pack --prefix-id`](/commands/pack), set `prefix-id: true` so `check` strips source prefixes before comparing keys. This also applies to changed keys when `github-diff` is enabled.

```yaml theme={null}
- uses: hyperlocalise/hyperlocalise@v1
  with:
    check: check
    config-path: i18n.yml
    prefix-id: true
    github-diff: true
    fail-on-findings: true
```

External repositories can use the moving `v1` ref for the latest stable v1 release. Pin an exact tag if you want stricter change control.

```yaml theme={null}
- uses: hyperlocalise/hyperlocalise@v1
  with:
    check: drift
```

## Inputs

* `check`: check name. Supported values are `drift` and `check`.
* `config-path`: path to the config file. Defaults to `i18n.yml`.
* `working-directory`: working directory for the command. Defaults to `.`.
* `hyperlocalise-version`: release version to install. Defaults to `latest`.
* `fail-on-drift`: fail the workflow when drift is detected. Defaults to `true`.
* `fail-on-findings`: fail the workflow when check findings are detected. Defaults to `true`.
* `github-diff`: in `check` mode on pull requests, fetch the GitHub PR diff and pass it to `hyperlocalise check --diff-stdin`. Defaults to `false`.
* `prefix-id`: in `check` mode, pass [`check --prefix-id`](/commands/check) so prefixed source keys are compared against packed target ids. Only supported when `check` is `check`. Defaults to `false`.
* `upload-artifact`: upload the JSON and text artifacts. Defaults to `true`.

## Drift detection

The action treats either of these conditions as drift:

* one or more executable translation tasks in the dry-run report
* one or more prune candidates in the dry-run report

Command failures still fail the action even if drift enforcement is disabled.

## Artifacts

`drift-summary.txt` is the quick triage artifact. It records:

* the config path used
* the CLI exit code
* whether drift was detected
* affected target paths
* affected target locales
* affected entry keys when available

If the CLI fails before it writes JSON, the action still writes a minimal text artifact when possible.