Skip to content
146 changes: 146 additions & 0 deletions .github/actions/push-translations/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
# push-translations

Pushes a plugin's POT file to the shared GlotPress site, translations.stellarwp.com, and imports
its strings into a project. What the import printed comes back as an output.

The Events Calendar, a project at the top level of the site:

```yaml
- uses: stellarwp/plugin-toolbox/.github/actions/push-translations@v1
id: translations
with:
project: the-events-calendar
pot-path: lang/the-events-calendar.pot
remote-folder: tec
host: ${{ secrets.TRANSLATIONS_DEPLOY_HOST }}
user: ${{ secrets.TRANSLATIONS_DEPLOY_USER }}
ssh-key: ${{ secrets.TRANSLATIONS_DEPLOY_SSH_KEY }}
pot-location: ${{ secrets.TRANSLATIONS_DEPLOY_POT_LOCATION }}

- run: echo "$RESULT"
env:
RESULT: ${{ steps.translations.outputs.glotpress-result }}
```

GiveWP, a project under a parent, with a folder of its own on the server:

```yaml
- uses: stellarwp/plugin-toolbox/.github/actions/push-translations@v1
with:
project: givewp/give
pot-path: languages/give.pot
remote-folder: givewp
host: ${{ secrets.TRANSLATIONS_DEPLOY_HOST }}
user: ${{ secrets.TRANSLATIONS_DEPLOY_USER }}
ssh-key: ${{ secrets.TRANSLATIONS_DEPLOY_SSH_KEY }}
pot-location: ${{ secrets.TRANSLATIONS_DEPLOY_POT_LOCATION }}
```

A composite action cannot read secrets, so the caller passes them. Generate the POT before this
step: the action only sends the file.

## One run at a time per project

Every run copies the POT to the same path on the server, `<pot-location>/<remote-folder>/<file>.pot`,
and imports that path into the same project. Two runs at once can import each other's file, or
import an older POT after a newer one. A composite action cannot set `concurrency`, so the job that
uses it does, with a group named after the project:

```yaml
jobs:
translations:
runs-on: ubuntu-latest
concurrency:
group: push-translations-givewp-give
cancel-in-progress: false
```

GitHub runs the jobs of a group one at a time, so two imports never overlap. It does not order them
by commit: a job that reaches the group later runs later, even when it holds an older POT, and of
the jobs waiting only the one that arrived last is kept. Run the push from the commit you release,
after the steps that generate the POT, so the last job to reach the group holds the newest POT. A
group holds jobs of one repository only, so push a project from one repository.

## What it does

1. Checks every input and names the build: a random id of 32 hex characters.
2. Copies the POT to `<pot-location>/<remote-folder>/` with rsync, under the name it has in the
repository.
3. Over ssh, in `site-directory`, runs
`wp glotpress import-originals <project> <pot-location>/<remote-folder>/<file>.pot` and writes
what it prints to `bot-output/<file>-<build id>`.
4. Reads that file back from `result-url` over https, sets it as `glotpress-result` and adds it to
the job summary.
5. Deletes the file from the server. This runs even when the import or the read failed, so the
output does not stay public.

The build id is random, not derived from the commit, so the address of the output cannot be
guessed while the file exists.

## What the server needs

- The `user` can log in with `ssh-key`, and its public key is in `authorized_keys`.
- `rsync` on the server, and `<pot-location>` existing and writable. rsync creates
`<remote-folder>` when it is missing, not the directories above it.
- WP-CLI as `wp` on the path of a non-interactive shell, and the GlotPress site in
`site-directory`, with the `glotpress import-originals` command.
- The project exists in GlotPress. The import does not create one.
- `site-directory/bot-output/` is served at `result-url`. The action creates the directory.

## What it refuses

Before anything is sent, with the input named in the message:

- An empty `project`, `pot-path`, `remote-folder`, `host`, `user`, `ssh-key` or `pot-location`. A
secret the repository does not have arrives empty, so this is how a missing secret shows.
- Any path whose parts are not letters, digits, `.`, `_` and `-`, or that has a part starting with
`.` or `-`. That rules out spaces, quotes, `;`, `|`, `$`, backticks, `..`, `~` and a value that
would be read as a command option.
- `project` or `remote-folder` that starts with `/`.
- `pot-path` that is absolute or does not end in `.pot`.
- `pot-location` that is not absolute.
- `host` that is not a host name or an IPv4 address, and `user` that is not a plain user name.
- `result-url` that is not `https://`, or that has a query, a port or credentials.

A refused `host`, `user` or `pot-location` is named without its value, since it comes from a
secret.

## Inputs

| Input | Required | Default | What it does |
|---|---|---|---|
| `project` | yes | | The GlotPress project path: `the-events-calendar`, `givewp/give` |
| `pot-path` | yes | | The POT file, relative to the workspace |
| `remote-folder` | yes | | The folder under `pot-location` the POT is copied to: `tec`, `givewp` |
| `host` | yes | | The server to connect to |
| `user` | yes | | The user to connect as |
| `ssh-key` | yes | | The private key of `user` |
| `pot-location` | yes | | The directory on the server that holds the POT folders, absolute |
| `site-directory` | no | `translations.stellarwp.com/html/` | The GlotPress site on the server, absolute or relative to the home of `user` |
| `result-url` | no | `https://translations.stellarwp.com/bot-output/` | The public URL of `bot-output/` in `site-directory` |

A trailing `/` on a folder, a directory or the URL is optional.

## Outputs

| Output | Example | What it is |
|---|---|---|
| `glotpress-result` | `1 new strings added, 0 updated, 0 fuzzied, and 0 obsoleted.` | What `wp glotpress import-originals` printed. Text from the server: pass it to a script through `env`, never inside `run:` |
| `project` | `givewp/give` | The project the strings were imported into |

## How it runs

Two [actions/github-script](https://github.com/actions/github-script) steps run
[`push-translations.js`](./push-translations.js). The first checks the inputs and sets the values
the later steps use. The second reads the import output back over https and sets it as the
`glotpress-result` output. Inputs reach both through `process.env`, never by being interpolated.

The copy and the two ssh steps are third-party actions,
[burnett01/rsync-deployments](https://github.com/Burnett01/rsync-deployments) and
[appleboy/ssh-action](https://github.com/appleboy/ssh-action), pinned to a full commit SHA because
they receive the deploy key. The rsync action builds a shell command from the paths, the host and
the user, which is why all of them are checked. The remote script holds no value: the checked
values reach the remote shell as environment variables, through the ssh action's `envs`.

`tests/actions/push-translations/push-translations.test.js` covers the check, with the two shapes
above and the refusals, and the read of the import output. Run `npm install` once, then `node --test`.
148 changes: 148 additions & 0 deletions .github/actions/push-translations/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
# Pushes a plugin's POT file to the shared GlotPress site, translations.stellarwp.com: rsync copies
# the POT to the server, `wp glotpress import-originals` imports it over ssh, and what the import
# printed comes back as an output.
#
# This action handles a deploy key and builds remote shell commands. The first step checks every
# input against an allow-list, in push-translations.js run by actions/github-script, and fails
# before anything is sent. The later steps use the values it checked. No input is interpolated into
# a script: the remote `script:` reads its values from the environment.
#
# Every run copies the POT to the same path on the server, so the calling job sets a `concurrency`
# group for the project; the README shows one.
name: Push translations
description: Pushes a POT file to the GlotPress site and imports its strings into a project

inputs:
project:
description: >-
The GlotPress project the strings are imported into, as its path on the site:
`the-events-calendar`, or `givewp/give` for a project under a parent.
required: true
pot-path:
description: >-
The POT file, relative to the workspace, e.g. `languages/give.pot`. Its name is the name it
has on the server.
required: true
remote-folder:
description: >-
The folder under `pot-location` the POT is copied to, one per product line: `tec`, `givewp`.
required: true
host:
description: 'The server to connect to. Pass a secret.'
required: true
user:
description: 'The user to connect as. Pass a secret.'
required: true
ssh-key:
description: 'The private key of `user`. Pass a secret.'
required: true
pot-location:
description: >-
The directory on the server that holds the POT folders, as an absolute path, e.g.
`/home/user/pots/`. Pass a secret.
required: true
site-directory:
description: >-
The directory of the GlotPress site on the server, where `wp` runs: absolute, or relative to
the home of `user`.
required: false
default: 'translations.stellarwp.com/html/'
result-url:
description: >-
The public https URL of the `bot-output/` folder in `site-directory`, where the import output
is read back from.
required: false
default: 'https://translations.stellarwp.com/bot-output/'

outputs:
glotpress-result:
description: 'What `wp glotpress import-originals` printed.'
value: ${{ steps.fetch.outputs.glotpress-result }}
project:
description: 'The GlotPress project the strings were imported into.'
value: ${{ steps.check.outputs.project }}

runs:
using: 'composite'
steps:
- name: Check the inputs and name the build
id: check
uses: actions/github-script@v9
env:
# github-script's require() resolves against the workspace of the repository being built,
# not this action's directory, so the path has to be passed in. github.action_path is the
# documented expression for it.
ACTION_PATH: ${{ github.action_path }}
# Read from process.env rather than interpolated into the script, so an input is data and
# never part of the program.
INPUT_PROJECT: ${{ inputs.project }}
INPUT_POT_PATH: ${{ inputs.pot-path }}
INPUT_REMOTE_FOLDER: ${{ inputs.remote-folder }}
INPUT_HOST: ${{ inputs.host }}
INPUT_USER: ${{ inputs.user }}
INPUT_SSH_KEY: ${{ inputs.ssh-key }}
INPUT_POT_LOCATION: ${{ inputs.pot-location }}
INPUT_SITE_DIRECTORY: ${{ inputs.site-directory }}
INPUT_RESULT_URL: ${{ inputs.result-url }}
with:
script: |
const { runPushTranslations } = require(`${process.env.ACTION_PATH}/push-translations.js`)
await runPushTranslations({ core, env: process.env })

# SHA-pinned: these two actions receive the deploy key. Bump the SHA to pick up a new release.
# The rsync action builds a shell command from path, remote_path, remote_host and remote_user,
# which is why the first step checks all four.
- name: Copy the POT file to the server
uses: burnett01/rsync-deployments@796cf0d5e4b535745ce49d7429f77cf39e25ef39 # 7.0.1
with:
switches: -avz --omit-dir-times --no-perms
path: ${{ steps.check.outputs.pot-path }}
remote_path: ${{ steps.check.outputs.remote-path }}
remote_host: ${{ steps.check.outputs.host }}
remote_user: ${{ steps.check.outputs.user }}
remote_key: ${{ inputs.ssh-key }}

- name: Import the strings into GlotPress
uses: appleboy/ssh-action@25ce8cbbcb08177468c7ff7ec5cbfa236f9341e1 # v1.1.0
env:
SITE_DIRECTORY: ${{ steps.check.outputs.site-directory }}
PROJECT: ${{ steps.check.outputs.project }}
REMOTE_POT: ${{ steps.check.outputs.remote-pot }}
RESULT_FILE: ${{ steps.check.outputs.result-file }}
with:
host: ${{ steps.check.outputs.host }}
username: ${{ steps.check.outputs.user }}
key: ${{ inputs.ssh-key }}
# The checked values reach the remote shell as variables, not as text of the script.
envs: SITE_DIRECTORY,PROJECT,REMOTE_POT,RESULT_FILE
script: |
set -e
cd "$SITE_DIRECTORY"
mkdir -p bot-output
wp glotpress import-originals "$PROJECT" "$REMOTE_POT" > "bot-output/$RESULT_FILE"

- name: Read the import output
id: fetch
uses: actions/github-script@v9
env:
ACTION_PATH: ${{ github.action_path }}
RESULT_URL: ${{ steps.check.outputs.result-url }}
with:
script: |
const { runReadResult } = require(`${process.env.ACTION_PATH}/push-translations.js`)
await runReadResult({ core, env: process.env })

# Also when the import or the read failed, so the output file does not stay public.
- name: Delete the import output from the server
if: ${{ always() && steps.check.outcome == 'success' }}
uses: appleboy/ssh-action@25ce8cbbcb08177468c7ff7ec5cbfa236f9341e1 # v1.1.0
env:
SITE_DIRECTORY: ${{ steps.check.outputs.site-directory }}
RESULT_FILE: ${{ steps.check.outputs.result-file }}
with:
host: ${{ steps.check.outputs.host }}
username: ${{ steps.check.outputs.user }}
key: ${{ inputs.ssh-key }}
envs: SITE_DIRECTORY,RESULT_FILE
script: |
rm -f -- "$SITE_DIRECTORY/bot-output/$RESULT_FILE"
Loading
Loading