[CAT-2931] feat: add distributed lock and should-run-integration-tests actions

[dvacca-onfido]

Summary

Adds two new composite actions to prevent SDK integration tests from running in parallel across repositories and to centralise the logic for when tests should run.

New actions

lock/acquire & lock/release

A distributed lock mechanism using a git branch in a dedicated lock repository (onfido/ci-lock) as an atomic mutex.

• Acquire: creates a branch locks/<lock-name> — git ref creation is atomic, so only one workflow succeeds. Others poll until the lock is released or timeout (default: 30 min, polling every 30s).
• Release: deletes the lock branch. Should always run with if: always() to prevent stale locks.
• Lock holder info: after acquiring, pushes a metadata commit so waiting jobs can see which repo/run holds the lock.
• Ownership check: release verifies the current run owns the lock before deleting, preventing a timed-out workflow from releasing another run's lock.
• Auth: uses a GitHub App via actions/create-github-app-token@v2 — short-lived, auto-rotating tokens scoped to the lock repo.

should-run-integration-tests

Determines whether integration tests should run based on the workflow event:

Event	Runs tests?
pull_request (internal branch)	✅ Yes
pull_request (fork)	❌ No (secrets unavailable)
push (merge from fork PR)	✅ Yes (catches what couldn't run pre-merge)
push (internal merge/direct)	❌ No (already tested on pull_request)
release / workflow_dispatch / schedule	✅ Yes

Usage

- name: Should run integration tests
  id: should-run-integration-tests
  if: <per-repo matrix/version check>
  uses: onfido/onfido-actions/should-run-integration-tests@main

- name: Acquire integration test lock
  if: steps.should-run-integration-tests.outputs.result == 'true'
  uses: onfido/onfido-actions/lock/acquire@main
  with:
    app-id: ${{ secrets.ONFIDO_CI_LOCK_APP_ID }}
    app-private-key: ${{ secrets.ONFIDO_CI_LOCK_PRIVATE_KEY }}

# ... run tests ...

- name: Release integration test lock
  if: always() && steps.should-run-integration-tests.outputs.result == 'true'
  uses: onfido/onfido-actions/lock/release@main
  with:
    app-id: ${{ secrets.ONFIDO_CI_LOCK_APP_ID }}
    app-private-key: ${{ secrets.ONFIDO_CI_LOCK_PRIVATE_KEY }}

Setup requirements

1. A GitHub App installed on the org with write access to the ci-lock repository
2. Two org-level secrets: ONFIDO_CI_LOCK_APP_ID and ONFIDO_CI_LOCK_PRIVATE_KEY

Related PRs

• onfido-node#191
• onfido-java#183
• onfido-python#115
• onfido-php#99
• onfido-ruby#106

[miguelvieiraentrust]

LGTM