From 330cca53b90535a8f738aa459851a8c639a4ccc9 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Tue, 10 Nov 2026 22:08:16 -0300 Subject: [PATCH 1/7] Add push-translations: a POT file to GlotPress, with the project and the server folder as inputs --- .github/actions/push-translations/README.md | 126 ++++++++++++++ .github/actions/push-translations/action.yml | 151 +++++++++++++++++ .../push-translations/push-translations.js | 158 ++++++++++++++++++ .../push-translations.test.js | 156 +++++++++++++++++ 4 files changed, 591 insertions(+) create mode 100644 .github/actions/push-translations/README.md create mode 100644 .github/actions/push-translations/action.yml create mode 100644 .github/actions/push-translations/push-translations.js create mode 100644 tests/actions/push-translations/push-translations.test.js diff --git a/.github/actions/push-translations/README.md b/.github/actions/push-translations/README.md new file mode 100644 index 0000000..3c70c7d --- /dev/null +++ b/.github/actions/push-translations/README.md @@ -0,0 +1,126 @@ +# 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. + +## What it does + +1. Checks every input and names the build: a random id of 32 hex characters. +2. Copies the POT to `//` with rsync, under the name it has in the + repository. +3. Over ssh, in `site-directory`, runs + `wp glotpress import-originals //.pot` and writes + what it prints to `bot-output/-`. +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 `` existing and writable. rsync creates + `` 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 + +One [actions/github-script](https://github.com/actions/github-script) step runs +[`push-translations.js`](./push-translations.js), which checks the inputs and sets the values the +later steps use. Inputs reach it through `process.env`, never by being interpolated into it. + +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`. + +The output is written to `GITHUB_OUTPUT` as a heredoc with a random delimiter, so a result of +several lines cannot add or override an output. + +`tests/actions/push-translations/push-translations.test.js` covers the check: the two shapes +above, and the refusals. Run `npm install` once, then `node --test`. diff --git a/.github/actions/push-translations/action.yml b/.github/actions/push-translations/action.yml new file mode 100644 index 0000000..ee4988c --- /dev/null +++ b/.github/actions/push-translations/action.yml @@ -0,0 +1,151 @@ +# 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: a `run:` step and the remote `script:` read their values from the environment. +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: ${{ inputs.host }} + remote_user: ${{ inputs.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: ${{ inputs.host }} + username: ${{ inputs.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 + shell: bash + env: + RESULT_URL: ${{ steps.check.outputs.result-url }} + run: | + result=$(curl -fsS --proto '=https' --max-time 60 "$RESULT_URL") + + # A heredoc with a random delimiter: a multi-line result cannot add or override outputs. + delimiter="glotpress-$RANDOM$RANDOM$RANDOM$RANDOM" + if grep -qxF "$delimiter" <<< "$result"; then + echo "The import output holds the output delimiter. Run the job again." >&2 + exit 1 + fi + printf 'glotpress-result<<%s\n%s\n%s\n' "$delimiter" "$result" "$delimiter" >> "$GITHUB_OUTPUT" + printf '## Results from GlotPress\n\n```\n%s\n```\n' "$result" >> "$GITHUB_STEP_SUMMARY" + + # 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: ${{ inputs.host }} + username: ${{ inputs.user }} + key: ${{ inputs.ssh-key }} + envs: SITE_DIRECTORY,RESULT_FILE + script: | + rm -f -- "$SITE_DIRECTORY/bot-output/$RESULT_FILE" diff --git a/.github/actions/push-translations/push-translations.js b/.github/actions/push-translations/push-translations.js new file mode 100644 index 0000000..9ea2c22 --- /dev/null +++ b/.github/actions/push-translations/push-translations.js @@ -0,0 +1,158 @@ +'use strict' + +/** + * Checks what the push-translations action was given, before anything is sent to the translations + * server, and names the file the import output is written to. + * + * The later steps of action.yml copy the POT with rsync and run `wp glotpress import-originals` + * over ssh. The rsync action builds a shell command from its inputs, and the import is a remote + * shell command, so every value that reaches either one has to match an allow-list first. Those + * steps use the outputs set here, never the raw inputs. + * + * readInputs is pure, so a test can call it with an environment. + */ + +const crypto = require('node:crypto') + +/** What was not done, to close every error message. */ +const WHAT = 'Nothing was sent to the translations server.' + +/** + * One part of a path: letters, digits, `.`, `_` and `-`, not starting with `.` or `-`. So no part + * is `..`, a hidden file or a command option, and none holds a space or a shell metacharacter. + */ +const PART = '[A-Za-z0-9_][A-Za-z0-9._-]*' + +/** One or more parts joined by `/`. */ +const PARTS = `${PART}(?:/${PART})*` + +/** + * What each input has to match, and how to say what it is. The first capture group is the value + * the action uses, so a trailing `/` is dropped. `secret` keeps the value out of the message. + */ +const RULES = { + project: { + pattern: new RegExp(`^(${PARTS})$`), + shape: 'a GlotPress project path, such as the-events-calendar or givewp/give', + }, + 'pot-path': { + pattern: new RegExp(`^((?:${PART}/)*${PART}\\.pot)$`), + shape: 'the path of a .pot file relative to the workspace, such as languages/give.pot', + }, + 'remote-folder': { + pattern: new RegExp(`^(${PARTS})/?$`), + shape: 'a folder name under pot-location, such as tec or givewp', + }, + 'site-directory': { + pattern: new RegExp(`^(/?${PARTS})/?$`), + shape: 'a directory on the server, absolute or relative to the home of user, such as translations.stellarwp.com/html/', + }, + 'result-url': { + pattern: new RegExp(`^(https://[A-Za-z0-9][A-Za-z0-9.-]*(?:/${PART})*)/?$`), + shape: 'an https URL of a folder, with no query, such as https://translations.stellarwp.com/bot-output/', + }, + host: { + pattern: /^([A-Za-z0-9][A-Za-z0-9.-]*)$/, + shape: 'a host name or an IPv4 address', + secret: true, + }, + user: { + pattern: new RegExp(`^(${PART})$`), + shape: 'a user name', + secret: true, + }, + 'pot-location': { + pattern: new RegExp(`^(/${PARTS})/?$`), + shape: 'an absolute directory on the server, such as /home/user/pots/', + secret: true, + }, + // Only handed to the rsync and ssh actions as a key, never part of a command: any text will do. + 'ssh-key': { pattern: /^([\s\S]+)$/, shape: 'a private key', secret: true }, +} + +/** A build id: 32 lowercase hex characters. */ +const BUILD_ID = /^[a-f0-9]{32}$/ + +/** + * Reads one input and checks it against its rule. + * + * @param {object} env The environment, holding the inputs as `INPUT_*`. + * @param {string} name The input's name, as action.yml spells it. + * + * @throws {Error} When the value is empty or does not match. + * + * @returns {string} The value the action uses. + */ +function readInput(env, name) { + const { pattern, shape, secret } = RULES[name] + const value = String(env[`INPUT_${name.toUpperCase().replace(/-/g, '_')}`] ?? '').trim() + + if (value === '') { + throw new Error(`${name} is empty. Pass ${shape}. ${WHAT}`) + } + + const match = pattern.exec(value) + if (!match) { + // A value from a secret is masked in the log anyway, but is not repeated here either. + throw new Error(`${name} ${secret ? '' : `'${value}' `}is not ${shape}. ${WHAT}`) + } + + return match[1] +} + +/** + * Checks every input and builds the values the later steps use. + * + * @param {object} env The environment, holding the inputs as `INPUT_*`. + * @param {string} buildId What makes the output file's name unique and hard to guess. Random by + * default; a test passes its own. + * + * @throws {Error} When an input, or the build id, is refused. + * + * @returns {Object} The step's outputs, by name. + */ +function readInputs(env, buildId = crypto.randomBytes(16).toString('hex')) { + const read = Object.fromEntries(Object.keys(RULES).map((name) => [name, readInput(env, name)])) + + if (!BUILD_ID.test(buildId)) { + throw new Error(`The build id is not 32 hex characters. ${WHAT}`) + } + + const potFile = read['pot-path'].split('/').pop() + const remotePath = `${read['pot-location']}/${read['remote-folder']}/` + const resultFile = `${potFile.slice(0, -'.pot'.length)}-${buildId}` + + // host, user and ssh-key are checked but not returned: the later steps take them from the inputs. + return { + project: read.project, + 'pot-path': read['pot-path'], + 'remote-path': remotePath, + 'remote-pot': `${remotePath}${potFile}`, + 'site-directory': read['site-directory'], + 'result-file': resultFile, + 'result-url': `${read['result-url']}/${resultFile}`, + } +} + +/** + * Runs the check and sets the outputs. + * + * @param {object} options + * @param {object} options.core The @actions/core toolkit, for the outputs and the summary. + * @param {object} options.env The environment, holding the inputs as `INPUT_*`. + * + * @throws {Error} When an input is refused. + * + * @returns {Promise} + */ +async function runPushTranslations({ core, env }) { + const outputs = readInputs(env) + + for (const [name, value] of Object.entries(outputs)) { + core.setOutput(name, value) + } + + await core.summary.addRaw(`## Translations build: \`${outputs['result-file']}\``, true).write() +} + +module.exports = { runPushTranslations, readInputs } diff --git a/tests/actions/push-translations/push-translations.test.js b/tests/actions/push-translations/push-translations.test.js new file mode 100644 index 0000000..0f09ecf --- /dev/null +++ b/tests/actions/push-translations/push-translations.test.js @@ -0,0 +1,156 @@ +'use strict' + +const { describe, it } = require('node:test') +const assert = require('node:assert') + +const { + runPushTranslations, + readInputs, +} = require('../../../.github/actions/push-translations/push-translations.js') +const { coreWithOutputs } = require('../../support/actions.js') + +const BUILD_ID = '0123456789abcdef0123456789abcdef' + +/** What The Events Calendar passes, with the defaults of action.yml filled in. */ +const TEC = { + INPUT_PROJECT: 'the-events-calendar', + INPUT_POT_PATH: 'lang/the-events-calendar.pot', + INPUT_REMOTE_FOLDER: 'tec/', + INPUT_SITE_DIRECTORY: 'translations.stellarwp.com/html/', + INPUT_RESULT_URL: 'https://translations.stellarwp.com/bot-output/', + INPUT_HOST: 'ssh.example.com', + INPUT_USER: 'deploy', + INPUT_SSH_KEY: '-----BEGIN OPENSSH PRIVATE KEY-----\nabc\n-----END OPENSSH PRIVATE KEY-----', + INPUT_POT_LOCATION: '/home/deploy/pots/', +} + +/** What GiveWP passes: a project under a parent, and its own remote folder. */ +const GIVE = { + ...TEC, + INPUT_PROJECT: 'givewp/give', + INPUT_POT_PATH: 'languages/give.pot', + INPUT_REMOTE_FOLDER: 'givewp', +} + +describe('push-translations', () => { + it('accepts the TEC shape', () => { + assert.deepStrictEqual(readInputs(TEC, BUILD_ID), { + project: 'the-events-calendar', + 'pot-path': 'lang/the-events-calendar.pot', + 'remote-path': '/home/deploy/pots/tec/', + 'remote-pot': '/home/deploy/pots/tec/the-events-calendar.pot', + 'site-directory': 'translations.stellarwp.com/html', + 'result-file': `the-events-calendar-${BUILD_ID}`, + 'result-url': `https://translations.stellarwp.com/bot-output/the-events-calendar-${BUILD_ID}`, + }) + }) + + it('accepts the Give shape', () => { + assert.deepStrictEqual(readInputs(GIVE, BUILD_ID), { + project: 'givewp/give', + 'pot-path': 'languages/give.pot', + 'remote-path': '/home/deploy/pots/givewp/', + 'remote-pot': '/home/deploy/pots/givewp/give.pot', + 'site-directory': 'translations.stellarwp.com/html', + 'result-file': `give-${BUILD_ID}`, + 'result-url': `https://translations.stellarwp.com/bot-output/give-${BUILD_ID}`, + }) + }) + + it('trims the values, and takes a POT at the root and an absolute site directory', () => { + const read = readInputs( + { ...TEC, INPUT_POT_PATH: ' give.pot\n', INPUT_SITE_DIRECTORY: '/var/www/site', INPUT_HOST: '10.0.0.1\n' }, + BUILD_ID + ) + + assert.strictEqual(read['pot-path'], 'give.pot') + assert.strictEqual(read['site-directory'], '/var/www/site') + }) + + it('gives each run a build id of its own, 32 hex characters', () => { + const [first, second] = [readInputs(TEC), readInputs(TEC)] + + assert.match(first['result-file'], /^the-events-calendar-[a-f0-9]{32}$/) + assert.notStrictEqual(first['result-file'], second['result-file']) + }) + + it('refuses a build id that is not 32 hex characters', () => { + assert.throws(() => readInputs(TEC, 'abc; rm -rf ~'), /build id/) + }) + + const refused = { + 'a shell metacharacter in project': { INPUT_PROJECT: 'give; rm -rf ~' }, + 'a command substitution in project': { INPUT_PROJECT: 'give$(id)' }, + 'a backtick in project': { INPUT_PROJECT: 'give`id`' }, + 'a space in project': { INPUT_PROJECT: 'give wp' }, + 'a parent directory in project': { INPUT_PROJECT: '../give' }, + 'an option as project': { INPUT_PROJECT: '--path=/tmp' }, + 'an absolute project': { INPUT_PROJECT: '/givewp/give' }, + 'an empty project': { INPUT_PROJECT: '' }, + 'a pipe in remote-folder': { INPUT_REMOTE_FOLDER: 'tec|cat' }, + 'a parent directory in remote-folder': { INPUT_REMOTE_FOLDER: 'tec/../..' }, + 'an absolute remote-folder': { INPUT_REMOTE_FOLDER: '/tec' }, + 'an empty remote-folder': { INPUT_REMOTE_FOLDER: ' ' }, + 'a quote in site-directory': { INPUT_SITE_DIRECTORY: "html' && id '" }, + 'a parent directory in site-directory': { INPUT_SITE_DIRECTORY: '../html' }, + 'a home shorthand in site-directory': { INPUT_SITE_DIRECTORY: '~/html' }, + 'an empty site-directory': { INPUT_SITE_DIRECTORY: '' }, + 'a pot-path that is not a .pot': { INPUT_POT_PATH: 'languages/give.php' }, + 'a space in pot-path': { INPUT_POT_PATH: 'languages/give wp.pot' }, + 'a parent directory in pot-path': { INPUT_POT_PATH: '../../etc/give.pot' }, + 'an absolute pot-path': { INPUT_POT_PATH: '/etc/give.pot' }, + 'a metacharacter in pot-path': { INPUT_POT_PATH: 'languages/$(id).pot' }, + 'a newline inside pot-path': { INPUT_POT_PATH: 'languages/give.pot\nid.pot' }, + 'an empty pot-path': { INPUT_POT_PATH: '' }, + 'a result-url that is not https': { INPUT_RESULT_URL: 'http://translations.stellarwp.com/bot-output/' }, + 'a file result-url': { INPUT_RESULT_URL: 'file:///etc/passwd' }, + 'a result-url with a query': { INPUT_RESULT_URL: 'https://translations.stellarwp.com/bot-output/?a=b' }, + 'a result-url with credentials': { INPUT_RESULT_URL: 'https://user:pass@translations.stellarwp.com/' }, + 'an empty result-url': { INPUT_RESULT_URL: '' }, + 'a metacharacter in host': { INPUT_HOST: 'example.com;id' }, + 'an option as host': { INPUT_HOST: '-oProxyCommand=id' }, + 'an empty host': { INPUT_HOST: '' }, + 'a space in user': { INPUT_USER: 'deploy -o x' }, + 'an empty user': { INPUT_USER: undefined }, + 'an empty ssh-key': { INPUT_SSH_KEY: ' \n' }, + 'a relative pot-location': { INPUT_POT_LOCATION: 'pots/' }, + 'a parent directory in pot-location': { INPUT_POT_LOCATION: '/home/deploy/../root/' }, + 'a metacharacter in pot-location': { INPUT_POT_LOCATION: '/home/deploy/pots/ && id' }, + 'an empty pot-location': { INPUT_POT_LOCATION: '' }, + } + + for (const [name, inputs] of Object.entries(refused)) { + it(`refuses ${name}`, () => { + const input = Object.keys(inputs)[0].replace('INPUT_', '').toLowerCase().replace(/_/g, '-') + + assert.throws( + () => readInputs({ ...TEC, ...inputs }, BUILD_ID), + new RegExp(`^Error: ${input} .*Nothing was sent to the translations server\\.$`, 's') + ) + }) + } + + it('does not repeat a value that comes from a secret in the message', () => { + for (const input of ['INPUT_HOST', 'INPUT_USER', 'INPUT_POT_LOCATION']) { + assert.throws( + () => readInputs({ ...TEC, [input]: 's3cret value' }, BUILD_ID), + (error) => !error.message.includes('s3cret') + ) + } + }) + + it('sets the validated values as outputs and names the build in the summary', async (t) => { + const { core, outputs, summary } = await coreWithOutputs(t) + + await runPushTranslations({ core, env: GIVE }) + + const set = outputs() + assert.strictEqual(set.project, 'givewp/give') + assert.strictEqual(set['remote-pot'], '/home/deploy/pots/givewp/give.pot') + assert.match(set['result-file'], /^give-[a-f0-9]{32}$/) + assert.strictEqual(set['result-url'], `https://translations.stellarwp.com/bot-output/${set['result-file']}`) + assert.ok(summary().includes(set['result-file'])) + // The key and the host are never outputs: the later steps take them from the inputs. + assert.ok(!Object.values(set).some((value) => value.includes('PRIVATE KEY') || value.includes('ssh.example.com'))) + }) +}) From 01dcf6505c8e335cd39fc27318457bbf4695c3e7 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Tue, 10 Nov 2026 22:12:20 -0300 Subject: [PATCH 2/7] push-translations reads the import output in its script, not in a bash step --- .github/actions/push-translations/action.yml | 20 ++++------ .../push-translations/push-translations.js | 38 +++++++++++++++++- .../push-translations.test.js | 39 +++++++++++++++++++ 3 files changed, 83 insertions(+), 14 deletions(-) diff --git a/.github/actions/push-translations/action.yml b/.github/actions/push-translations/action.yml index ee4988c..684d716 100644 --- a/.github/actions/push-translations/action.yml +++ b/.github/actions/push-translations/action.yml @@ -5,7 +5,7 @@ # 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: a `run:` step and the remote `script:` read their values from the environment. +# a script: the remote `script:` reads its values from the environment. name: Push translations description: Pushes a POT file to the GlotPress site and imports its strings into a project @@ -120,20 +120,14 @@ runs: - name: Read the import output id: fetch - shell: bash + uses: actions/github-script@v9 env: + ACTION_PATH: ${{ github.action_path }} RESULT_URL: ${{ steps.check.outputs.result-url }} - run: | - result=$(curl -fsS --proto '=https' --max-time 60 "$RESULT_URL") - - # A heredoc with a random delimiter: a multi-line result cannot add or override outputs. - delimiter="glotpress-$RANDOM$RANDOM$RANDOM$RANDOM" - if grep -qxF "$delimiter" <<< "$result"; then - echo "The import output holds the output delimiter. Run the job again." >&2 - exit 1 - fi - printf 'glotpress-result<<%s\n%s\n%s\n' "$delimiter" "$result" "$delimiter" >> "$GITHUB_OUTPUT" - printf '## Results from GlotPress\n\n```\n%s\n```\n' "$result" >> "$GITHUB_STEP_SUMMARY" + 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 diff --git a/.github/actions/push-translations/push-translations.js b/.github/actions/push-translations/push-translations.js index 9ea2c22..fdf3ef4 100644 --- a/.github/actions/push-translations/push-translations.js +++ b/.github/actions/push-translations/push-translations.js @@ -155,4 +155,40 @@ async function runPushTranslations({ core, env }) { await core.summary.addRaw(`## Translations build: \`${outputs['result-file']}\``, true).write() } -module.exports = { runPushTranslations, readInputs } +/** + * Reads what the import printed back from the site, and sets it as the `glotpress-result` output. + * + * The URL was built by the check step from checked values. It is checked again for https here, + * since the request is made with whatever this step is handed. + * + * @param {object} options + * @param {object} options.core The @actions/core toolkit, for the output and the summary. + * @param {object} options.env The environment, holding `RESULT_URL`. + * @param {Function} options.fetchImpl The fetch to use, the runtime's by default. + * + * @throws {Error} When the URL is not https, or the site does not answer 200. + * + * @returns {Promise} + */ +async function runReadResult({ core, env, fetchImpl = globalThis.fetch }) { + const url = String(env.RESULT_URL ?? '') + + if (!url.startsWith('https://')) { + throw new Error('The import output has no https URL to be read from. The import ran, and its output was not read.') + } + + const response = await fetchImpl(url, { redirect: 'error', signal: AbortSignal.timeout(60000) }) + + if (!response.ok) { + throw new Error( + `Reading the import output answered ${response.status}. The import ran, and its output was not read.` + ) + } + + const result = (await response.text()).trim() + + core.setOutput('glotpress-result', result) + await core.summary.addHeading('Results from GlotPress', 2).addCodeBlock(result).write() +} + +module.exports = { runPushTranslations, runReadResult, readInputs } diff --git a/tests/actions/push-translations/push-translations.test.js b/tests/actions/push-translations/push-translations.test.js index 0f09ecf..4013c73 100644 --- a/tests/actions/push-translations/push-translations.test.js +++ b/tests/actions/push-translations/push-translations.test.js @@ -5,6 +5,7 @@ const assert = require('node:assert') const { runPushTranslations, + runReadResult, readInputs, } = require('../../../.github/actions/push-translations/push-translations.js') const { coreWithOutputs } = require('../../support/actions.js') @@ -154,3 +155,41 @@ describe('push-translations', () => { assert.ok(!Object.values(set).some((value) => value.includes('PRIVATE KEY') || value.includes('ssh.example.com'))) }) }) + +describe('runReadResult', () => { + /** A fetch that answers once and records the URL it was asked for. */ + const fetchOf = (status, body) => { + const urls = [] + + return { urls, fetchImpl: async (url) => (urls.push(url), new Response(body, { status })) } + } + + it('sets what the import printed as the output, several lines included', async (t) => { + const { core, outputs, summary } = await coreWithOutputs(t) + const { urls, fetchImpl } = fetchOf(200, '3 new strings added\n1 string obsoleted\n') + + await runReadResult({ core, env: { RESULT_URL: 'https://example.com/bot-output/give-abc' }, fetchImpl }) + + assert.deepStrictEqual(urls, ['https://example.com/bot-output/give-abc']) + assert.strictEqual(outputs()['glotpress-result'], '3 new strings added\n1 string obsoleted') + assert.match(summary(), /3 new strings added/) + }) + + it('fails when the site does not answer 200, and sets no output', async (t) => { + const { core, outputs } = await coreWithOutputs(t) + + await assert.rejects( + runReadResult({ core, env: { RESULT_URL: 'https://example.com/x' }, fetchImpl: fetchOf(404, 'no').fetchImpl }), + /answered 404/ + ) + assert.deepStrictEqual(outputs(), {}) + }) + + it('refuses a URL that is not https before any request', async (t) => { + const { core } = await coreWithOutputs(t) + const { urls, fetchImpl } = fetchOf(200, 'x') + + await assert.rejects(runReadResult({ core, env: { RESULT_URL: 'http://example.com/x' }, fetchImpl }), /no https URL/) + assert.deepStrictEqual(urls, []) + }) +}) From 4b852f656bd6168a4bcd903da71bd26c2ba80a98 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Tue, 10 Nov 2026 22:12:36 -0300 Subject: [PATCH 3/7] push-translations README: the second script step reads the import output --- .github/actions/push-translations/README.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/.github/actions/push-translations/README.md b/.github/actions/push-translations/README.md index 3c70c7d..e298138 100644 --- a/.github/actions/push-translations/README.md +++ b/.github/actions/push-translations/README.md @@ -108,9 +108,10 @@ A trailing `/` on a folder, a directory or the URL is optional. ## How it runs -One [actions/github-script](https://github.com/actions/github-script) step runs -[`push-translations.js`](./push-translations.js), which checks the inputs and sets the values the -later steps use. Inputs reach it through `process.env`, never by being interpolated into it. +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 @@ -119,8 +120,5 @@ they receive the deploy key. The rsync action builds a shell command from the pa 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`. -The output is written to `GITHUB_OUTPUT` as a heredoc with a random delimiter, so a result of -several lines cannot add or override an output. - -`tests/actions/push-translations/push-translations.test.js` covers the check: the two shapes -above, and the refusals. Run `npm install` once, then `node --test`. +`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`. From 3f3c495c5191175b7b6338d74d5db5771929f800 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 13:00:20 -0300 Subject: [PATCH 4/7] README lists the ported release actions --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ed72fd7..0729503 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ Three drawers in the toolbox. You can use any one without the others. | Layer | Lives in | What's in it | |---|---|---| -| Composite actions | `.github/actions/` | Small single-purpose steps with no opinions: `setup-slic`, `setup-bun`, `setup-node`, `prepare-matrix`, `check-php-changes`, `smart-checkout`, `process-changelog`, `generate-pot`, `zip-name`, `release-zip` | +| Composite actions | `.github/actions/` | Small single-purpose steps with no opinions: `setup-slic`, `setup-bun`, `setup-node`, `prepare-matrix`, `check-php-changes`, `smart-checkout`, `analyze-hooks`, `update-wp-version`, `generate-pot`, `push-translations`, `zip-name`, `release-zip` | | Reusable workflows | `.github/workflows/` | Full jobs built from the actions (standards, analysis, tests, zip, release prep). Most repos will only touch this layer. | | File sync | `templates/` + `.github/sync.yml` | Files that must exist in the target repo, grouped by brand and repo type | @@ -165,7 +165,8 @@ Each phase ends with something people can actually use. ### Phase 2: actions - [ ] Port `setup-slic`, `prepare-matrix`, `setup-bun` from LearnDash. -- [ ] Port `check-php-changes`, `smart-checkout`, `process-changelog`, `add-changelog`, `generate-pot` from TEC. +- [ ] Port `check-php-changes` and `smart-checkout` from TEC. +- [x] Port `update-wp-version`, `generate-pot` and `push-translations` from TEC, with the paths, the GlotPress project, the server folder and the POT headers as inputs. `process-changelog` and `add-changelog` are not ported: `release-prep` writes the changelog, and `stellarwp/changelogger`'s `add` command files an entry under a name. - [x] Port `analyze-hooks` from TEC: the actions and filters a release adds, updates, deprecates or removes and the views it adds, changes or removes, as pending changelog entries. The search paths, the views paths and the changelog types are inputs, and a `v` on the release tag is accepted. - [ ] Add `setup-node` for the npm crowd. - [x] Add `release-prep`: version bump, TBD replacement and changelog through pup and the changelogger action, committed to the release branch through the GitHub API. A caller to copy is in `templates/workflows/release-prep.yml`. From 37e2d724258c518e869c3a52d83ad64bde7648ae Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:20:14 -0300 Subject: [PATCH 5/7] push-translations connects with the host and user its check step trimmed and checked --- .github/actions/push-translations/action.yml | 12 +++++----- .../push-translations/push-translations.js | 7 ++++-- .../push-translations.test.js | 23 +++++++++++++++++-- 3 files changed, 32 insertions(+), 10 deletions(-) diff --git a/.github/actions/push-translations/action.yml b/.github/actions/push-translations/action.yml index 684d716..be21c8d 100644 --- a/.github/actions/push-translations/action.yml +++ b/.github/actions/push-translations/action.yml @@ -95,8 +95,8 @@ runs: switches: -avz --omit-dir-times --no-perms path: ${{ steps.check.outputs.pot-path }} remote_path: ${{ steps.check.outputs.remote-path }} - remote_host: ${{ inputs.host }} - remote_user: ${{ inputs.user }} + remote_host: ${{ steps.check.outputs.host }} + remote_user: ${{ steps.check.outputs.user }} remote_key: ${{ inputs.ssh-key }} - name: Import the strings into GlotPress @@ -107,8 +107,8 @@ runs: REMOTE_POT: ${{ steps.check.outputs.remote-pot }} RESULT_FILE: ${{ steps.check.outputs.result-file }} with: - host: ${{ inputs.host }} - username: ${{ inputs.user }} + 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 @@ -137,8 +137,8 @@ runs: SITE_DIRECTORY: ${{ steps.check.outputs.site-directory }} RESULT_FILE: ${{ steps.check.outputs.result-file }} with: - host: ${{ inputs.host }} - username: ${{ inputs.user }} + host: ${{ steps.check.outputs.host }} + username: ${{ steps.check.outputs.user }} key: ${{ inputs.ssh-key }} envs: SITE_DIRECTORY,RESULT_FILE script: | diff --git a/.github/actions/push-translations/push-translations.js b/.github/actions/push-translations/push-translations.js index fdf3ef4..bc67240 100644 --- a/.github/actions/push-translations/push-translations.js +++ b/.github/actions/push-translations/push-translations.js @@ -7,7 +7,7 @@ * The later steps of action.yml copy the POT with rsync and run `wp glotpress import-originals` * over ssh. The rsync action builds a shell command from its inputs, and the import is a remote * shell command, so every value that reaches either one has to match an allow-list first. Those - * steps use the outputs set here, never the raw inputs. + * steps use the outputs set here, never the raw inputs, except ssh-key, which is only ever a key. * * readInputs is pure, so a test can call it with an environment. */ @@ -122,10 +122,13 @@ function readInputs(env, buildId = crypto.randomBytes(16).toString('hex')) { const remotePath = `${read['pot-location']}/${read['remote-folder']}/` const resultFile = `${potFile.slice(0, -'.pot'.length)}-${buildId}` - // host, user and ssh-key are checked but not returned: the later steps take them from the inputs. + // The later steps connect with host and user as checked here, trimmed. ssh-key is not returned: + // it is handed to those steps as a key, never placed in a command. return { project: read.project, 'pot-path': read['pot-path'], + host: read.host, + user: read.user, 'remote-path': remotePath, 'remote-pot': `${remotePath}${potFile}`, 'site-directory': read['site-directory'], diff --git a/tests/actions/push-translations/push-translations.test.js b/tests/actions/push-translations/push-translations.test.js index 4013c73..4bc5a07 100644 --- a/tests/actions/push-translations/push-translations.test.js +++ b/tests/actions/push-translations/push-translations.test.js @@ -38,6 +38,8 @@ describe('push-translations', () => { assert.deepStrictEqual(readInputs(TEC, BUILD_ID), { project: 'the-events-calendar', 'pot-path': 'lang/the-events-calendar.pot', + host: 'ssh.example.com', + user: 'deploy', 'remote-path': '/home/deploy/pots/tec/', 'remote-pot': '/home/deploy/pots/tec/the-events-calendar.pot', 'site-directory': 'translations.stellarwp.com/html', @@ -50,6 +52,8 @@ describe('push-translations', () => { assert.deepStrictEqual(readInputs(GIVE, BUILD_ID), { project: 'givewp/give', 'pot-path': 'languages/give.pot', + host: 'ssh.example.com', + user: 'deploy', 'remote-path': '/home/deploy/pots/givewp/', 'remote-pot': '/home/deploy/pots/givewp/give.pot', 'site-directory': 'translations.stellarwp.com/html', @@ -68,6 +72,19 @@ describe('push-translations', () => { assert.strictEqual(read['site-directory'], '/var/www/site') }) + it('returns host and user without the newlines around them, which the later steps connect with', () => { + const read = readInputs({ ...TEC, INPUT_HOST: '\nssh.example.com\n', INPUT_USER: ' deploy\n' }, BUILD_ID) + + assert.strictEqual(read.host, 'ssh.example.com') + assert.strictEqual(read.user, 'deploy') + }) + + it('refuses a newline inside host or user', () => { + for (const input of ['INPUT_HOST', 'INPUT_USER']) { + assert.throws(() => readInputs({ ...TEC, [input]: 'example\nid' }, BUILD_ID), /Nothing was sent/) + } + }) + it('gives each run a build id of its own, 32 hex characters', () => { const [first, second] = [readInputs(TEC), readInputs(TEC)] @@ -151,8 +168,10 @@ describe('push-translations', () => { assert.match(set['result-file'], /^give-[a-f0-9]{32}$/) assert.strictEqual(set['result-url'], `https://translations.stellarwp.com/bot-output/${set['result-file']}`) assert.ok(summary().includes(set['result-file'])) - // The key and the host are never outputs: the later steps take them from the inputs. - assert.ok(!Object.values(set).some((value) => value.includes('PRIVATE KEY') || value.includes('ssh.example.com'))) + assert.strictEqual(set.host, 'ssh.example.com') + assert.strictEqual(set.user, 'deploy') + // The key is never an output: the later steps take it from the input. + assert.ok(!Object.values(set).some((value) => value.includes('PRIVATE KEY'))) }) }) From 10cb282a759ea45eeeb1bd969efc0af572746dfb Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:20:29 -0300 Subject: [PATCH 6/7] push-translations README: the calling job runs one push per project at a time with a concurrency group --- .github/actions/push-translations/README.md | 20 ++++++++++++++++++++ .github/actions/push-translations/action.yml | 3 +++ 2 files changed, 23 insertions(+) diff --git a/.github/actions/push-translations/README.md b/.github/actions/push-translations/README.md index e298138..8e90ec6 100644 --- a/.github/actions/push-translations/README.md +++ b/.github/actions/push-translations/README.md @@ -39,6 +39,26 @@ GiveWP, a project under a parent, with a folder of its own on the server: 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`, +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 and keeps only the newest waiting one, so the last +import is from the newest run. 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. diff --git a/.github/actions/push-translations/action.yml b/.github/actions/push-translations/action.yml index be21c8d..699705a 100644 --- a/.github/actions/push-translations/action.yml +++ b/.github/actions/push-translations/action.yml @@ -6,6 +6,9 @@ # 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 From 5741a0dfc4efa5c74e879e0a5541438e41bbaf3f Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 21:29:30 -0300 Subject: [PATCH 7/7] push-translations README: a concurrency group stops imports overlapping, not an older POT importing last --- .github/actions/push-translations/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/actions/push-translations/README.md b/.github/actions/push-translations/README.md index 8e90ec6..31c5e2e 100644 --- a/.github/actions/push-translations/README.md +++ b/.github/actions/push-translations/README.md @@ -55,9 +55,11 @@ jobs: cancel-in-progress: false ``` -GitHub runs the jobs of a group one at a time and keeps only the newest waiting one, so the last -import is from the newest run. A group holds jobs of one repository only, so push a project -from one repository. +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