This guide walks through connecting a GitHub repository to wxrks: creating a connector configuration, telling wxrks which repository and files to watch, adding the required config file to your repository, and running your first sync. For a high-level explanation of how the connector works, see GitHub Connector Overview.

💡 Who is this for? This guide is for Account Admins and Project Managers with connector-management permissions for the Organizational Unit you're connecting.

Before you start

A GitHub username and a Personal Access Token (PAT) with at least repo scope. We recommend a dedicated service account rather than a personal one — see GitHub's guide to creating a personal access token.
The Organizational Unit in wxrks that the resulting projects should belong to.

Step 1: Create a GitHub Configuration

Go to Integrations in the top navigation, open GitHub, and switch to the Config tab. Click Add Configuration.

GitHub connector page, Config tab, with Add Configuration highlighted

Fill in:

Organizational Unit — which unit owns the projects this configuration creates; new projects inherit that unit's Translation Memories, Glossaries, and other settings.
Name — a label to tell this configuration apart from others. You can create more than one GitHub Configuration — for example, one per team or product.
Workflows — the default workflow(s) applied to projects created from this configuration. Leave empty to use the Organizational Unit's default.
URL — the GitHub API URL. Leave the default (https://api.github.com) unless you use GitHub Enterprise with a custom API endpoint.
Username and GitHub Token — the PAT credentials from "Before you start."

Filled Create GitHub Configuration form, token field masked

Click Create.

Step 2: Add a Repository Configuration

On the configuration's page, switch to the Repository Configurations tab and click Add Configuration. This opens a 3-step wizard:

Repository Configuration wizard step 1: repository name and owner

Repository Name and Repository Owner — the exact repository name and its owner (a GitHub user or organization). For a repository at github.com/your-org/your-repo, the owner is your-org and the name is your-repo.

Repository Configuration wizard step 2: base branch and config path

Base Branch — the branch wxrks watches for source files, and branches from when delivering translations (commonly main, master, or develop). Config Path — the path, inside the repository, to the YAML configuration file described in Step 3.

Repository Configuration wizard step 3: CI tag

CI Tag — a short label that groups projects created from this repository configuration, so you can tell them apart from other continuous integrations in wxrks — for example, ios and android for two repositories of the same app.

Click Create. You can add as many repository configurations as you need under one GitHub Configuration — one per repository, or several per repository pointing at different config paths.

Repository Configurations table with Create Project (Sync) highlighted

Step 3: Add the configuration file to your repository

wxrks reads a YAML file — at the Config Path you set above — that lists which files to translate, from which source language, into which target languages. It can live anywhere in the repository.

github_repo: your-org/your-repo
filenameLanguageSeparator: ~
sourceLocale:
  key: en
  tms: en_us
locales:
  - key: cs
    tms: cs_cz
  - key: da
    tms: da_dk
sources:
  - defaultOutputPathPattern: "{lang}/{filename}"
    sourceFiles:
      - path: en/test.yml
      - path: en/test.json
  - defaultOutputPathPattern: "{lang}/{filename}"
    filenameLanguageSeparator: "."
    sourceFiles:
      - path: en/test.en.yml

github_repo — the repository identifier, as owner/name.
sourceLocale — the source language, with key (the code used in your repository or filenames) and tms (the matching wxrks language code).
filenameLanguageSeparator — the character separating a language code embedded in a filename (the . in test.en.yml, for example). Leave it ~ (null) if your filenames don't embed a language code.
locales — the target languages, in the same key/tms format as sourceLocale.
sources — one entry per group of files that share the same output pattern, each listing its sourceFiles and a defaultOutputPathPattern using {lang} (or {target}) and {filename} placeholders for where translated files get written.

Step 4: Sync and create your first project

Back on the Repository Configurations tab, click Create Project (Sync) on the repository's row.

Sync form: Contact Person, Project Reference, Workflows, Base Branch, CI Tag, Repository, Config Path, Skip Status/Hash Check

Fill in:

Contact Person — who receives notifications about this project.
Project Reference — a name for the resulting project.
Workflows — the workflow(s) this project should follow.
Base Branch, CI Tag, Repository, and Config Path are pre-filled from the repository configuration; CI Tag can still be edited per sync.
Search by files (optional) — restrict this sync to specific filenames.
Skip Status Check — also pull in files whose existing entries are still in a NEW or PENDING state from a previous sync.
Skip Hash Check — re-download every file listed in the config file, even ones whose content hash hasn't changed since the last sync.

Click Sync. wxrks creates the project and starts pulling in the changed files; you can track progress from the requests list on this same page.

How delivery works

Once the project is translated, wxrks creates a new branch off the repository's Base Branch, commits the translated files to it, and opens a pull request back to the base branch for review. Delivering the same project again reuses that same branch and pull request rather than opening a new one each time.

GitHub Connector Overview — what the connector does and how authentication, syncing, and delivery work, at a glance.

Setting Up the GitHub Connector