Skip to content

CI CD templates

Jump to bottom
Pavel Tkachenko edited this page Jul 30, 2026 · 2 revisions

CI/CD templates

./ptc-cli.sh init prints the right one of these for your project, already pinned to the CLI version you ran it with. The copies below are for reference.

Both recipes are loop-safe: the translation result lands on a stable ptc/translations branch as a pull/merge request, and that branch is not a trigger branch, so a translation commit cannot start another translation run.

GitHub Actions

Use the action — OnTheGoSystems/ptc-action. It vendors ptc-cli inside itself, so nothing is downloaded at job time, and it SHA-pins the action that opens the PR.

Before the first run

  1. Settings → Secrets and variables → Actions → add PTC_API_TOKEN.
  2. Settings → Actions → General → Workflow permissions → enable "Allow GitHub Actions to create and approve pull requests". Skipping this is the single most common first-run failure.

.github/workflows/translate.yml:

name: Translate
on:
  push:
    branches: [main]
    paths: ['locales/en.json']   # your SOURCE files — this is the loop guard
  workflow_dispatch: {}

permissions:
  contents: write
  pull-requests: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: OnTheGoSystems/ptc-action@v1
        with:
          api-token: ${{ secrets.PTC_API_TOKEN }}
          create-pr: true

api-token is the only input you must pass. A .ptc-config.yml committed at the repository root is picked up on its own; with no config at all the action runs ptc init and translates what it detects.

Worth adding: pr-token: ${{ secrets.PTC_PR_TOKEN }}, a PAT or GitHub App token, so the translation PR triggers your own checks — a PR opened with the default GITHUB_TOKEN does not.

Full input list: action README.

GitLab CI

There is no CI/CD Catalog component, and there cannot be one: include: component: is resolved against your GitLab instance, so a component published on someone else's server can never be included from yours. Paste the job instead.

Before the first run

  1. Settings → CI/CD → Variables → add PTC_API_TOKEN as a masked variable. It is read from the environment and never appears on the command line.
  2. Give the job a way to push — see the note under the snippet.

Append to .gitlab-ci.yml:

ptc-translate:
  stage: deploy
  image: alpine:3.22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  before_script:
    - apk add --no-cache bash curl git jq
  script:
    - curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/v1.0.3/ptc-cli.sh -o ptc-cli.sh
    - echo "87efed00bd9345b9a4d5fb1972d8d53525246f6a2a4e6a48ae7d20d67e41362a  ptc-cli.sh" | sha256sum -c -
    - chmod +x ptc-cli.sh
    - ./ptc-cli.sh --config-file .ptc-config.yml
    - |
      if ! git diff --quiet; then
        git config user.email "ci@ptc"
        git config user.name "PTC Translate"
        git checkout -B ptc/translations
        git add -A
        git commit -m "chore(i18n): update translations via PTC [skip ci]"
        git push -o merge_request.create \
                 -o merge_request.target="$CI_DEFAULT_BRANCH" \
                 -o merge_request.title="Update translations from PTC" \
                 -f "https://gitlab-ci-token:${PTC_GIT_PUSH_TOKEN:-$CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" HEAD:ptc/translations
      fi

The push needs a token that may write to the repository. Two routes, pick whichever your instance and plan allow:

  • CI_JOB_TOKEN — works only if a maintainer enables Settings → CI/CD → Job token permissions → "Allow Git push requests to the repository". GitLab 18.4 or later; off by default. Not possible at all before 18.4.
  • PTC_GIT_PUSH_TOKEN — a project access token with the write_repository scope, stored as a masked CI/CD variable. Project access tokens are not available on gitlab.com Free.

The snippet reads PTC_GIT_PUSH_TOKEN and falls back to CI_JOB_TOKEN, so the same job works either way.

The commit carries [skip ci] — the only skip token GitLab honours. [skip translations] and similar do nothing here.

Alpine note: the CLI needs bash, curl, git and jq; a bare alpine image has none of them, which is what the before_script is for.

Pinning and verification
Latest release v1.0.3
sha256 of ptc-cli.sh 87efed00bd9345b9a4d5fb1972d8d53525246f6a2a4e6a48ae7d20d67e41362a

Pin an exact tag (v1.0.3) for a build that never changes, or the floating v1 tag to pick up backward-compatible updates. Never fetch from refs/heads/main — that is a moving branch, and a push to it would change what your build runs.

Checksums for every release are on the releases page.

Clone this wiki locally