String Catalog Logo
String Catalog
Start Free Log In
Skip to content
Home
Docs
Repository Automation

Getting Started

Repository Automation

Configure repository localization automation with push rules, pull request checks, and manual sync for GitHub, GitLab, and Bitbucket projects.

Repository automation controls when String Catalog watches your repository and how it delivers localization updates for repository projects.

What You Can Automate

Repository automation is split into three user-facing workflows:

  • Push automation: When code is pushed to a matching branch, String Catalog can check supported localization files and open or update a localization pull request.
  • Pull request automation: When a pull request targets a matching branch, String Catalog can check it for missing or needs-review translations. By default, this does not modify the PR branch.
  • Manual sync: Use Sync a Branch to run a one-time sync for a branch without saving a permanent rule.

This lets teams choose how much automation they want without giving every branch the same write behavior.

Where Rules Live

Automation rules are configured from the project's Automation tab.

There you can:

  • Add exact branch names such as main
  • Add wildcard patterns such as release/*
  • Enable or disable rules independently for pushes and pull requests
  • Allow direct writeback for pull request automation on a per-rule basis

Safe Defaults

Repository automation is designed to stay reviewable and scoped:

  • Pull request automation is review-safe by default and does not commit into the PR branch unless you explicitly allow it.
  • Manual sync opens a localization pull request for the selected branch but does not change your tracked branch.
  • Only supported localization files are read and rewritten.
  • If no localization file changes are needed, String Catalog avoids creating unnecessary repository churn.

Tracked Branch vs Branch-Scoped Workflows

Every repository project has one tracked branch. String Catalog treats that branch as the main version of the project shown in the app.

  • Push automation on the tracked branch updates the tracked branch state shown in the UI.
  • Push automation on the tracked branch is also the only automation path that updates the main project snapshot String Catalog uses in the app.
  • Push automation on any other branch is treated as a branch-scoped workflow.
  • Pull request automation is always branch-scoped, whether it is report-only or allowed to write back directly to the PR branch.
  • Manual sync is also branch-scoped unless you run it for the tracked branch itself.

Branch-scoped workflows are useful when developers need automation for work that should stay separate from the main project view.

For example, a team can keep main as the tracked branch while running localization automation on feature/swift-rewrite, release/*, or other temporary branches. Those branches can contain very different files, keys, and localizations without replacing the tracked branch shown in the main project UI.

Common patterns include:

  • Keeping main as the tracked branch for the day-to-day project view in String Catalog
  • Running push automation on release/* when release branches need their own localization pull requests
  • Adding push or pull request automation for large rewrite branches such as feature/swift-rewrite

How To Choose Between Push and Pull Request Automation

Use push automation when:

  • You want a branch such as main or release/* to stay localized continuously.
  • Your team prefers reviewing localization changes in dedicated pull requests.
  • You want predictable localization updates after base-language strings change.

Use pull request automation when:

  • You want an early signal while a feature PR is still under review.
  • You want to check whether a pull request introduced missing translations.
  • You only want direct commits on selected PR targets where automation is acceptable.

Use manual sync when:

  • You need a one-off localization pass for a hotfix, release branch, or temporary branch.
  • You do not want to save an ongoing rule for that branch.

Typical Setup

For most teams, a clean starting point looks like this:

  1. Add a push rule for main or your main release branch.
  2. Add pull request rules for the base branches where reviewers want localization checks.
  3. Leave direct PR writeback off until your team is comfortable with automated commits inside pull requests.
  4. Use manual sync for unusual branches instead of creating temporary rules.

Common Mistakes

  • Treating pull request rules as if they match the source branch instead of the target branch.
  • Enabling direct PR writeback on branches where teammates frequently make manual localization edits.
  • Creating very broad wildcard rules before confirming which branches really need automation.
  • Looking for push and pull request triggers inside project settings instead of the Automation tab.