Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions actions/update-submodule/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
# SPDX-License-Identifier: AGPL-3.0-or-later

name: Update a linked submodule from a merged pull request
description: Updates a gitlink through the GitHub API without checking out PR code.

inputs:
token:
description: Token limited to the parent and source repository operations
required: true
source-repository:
description: Repository containing the already merged source pull request
required: true
submodule-path:
description: Gitlink path within the parent repository
required: true

runs:
using: composite
steps:
- name: Verify and update submodule gitlink
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
SUBMODULE_PATH: ${{ inputs.submodule-path }}
SOURCE_REPOSITORY: ${{ inputs.source-repository }}
with:
github-token: ${{ inputs.token }}
script: |
const run = require('${{ github.action_path }}/update.js')
await run({ github, context, core, env: process.env })
96 changes: 96 additions & 0 deletions actions/update-submodule/update.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
// SPDX-License-Identifier: AGPL-3.0-or-later

'use strict'

const BOT = {
name: 'github-actions[bot]',
email: '41898282+github-actions[bot]@users.noreply.github.com',
}

function validatePath(path) {
return /^[a-zA-Z0-9_.-]+(\/[a-zA-Z0-9_.-]+)*$/.test(path) &&
!path.split('/').some(part => part === '.' || part === '..')
}

async function updateSubmodule({ github, context, core, env }) {
const owner = context.repo.owner
const repo = context.repo.repo
const submodule = env.SUBMODULE_PATH
const sourceRepository = env.SOURCE_REPOSITORY
if (!validatePath(submodule) ||
!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(sourceRepository)) {
throw new Error('Invalid submodule path or source repository configuration')
}

const { data: pr } = await github.rest.pulls.get({
owner, repo, pull_number: context.issue.number,
})
if (pr.state !== 'open' ||
pr.head.repo?.full_name !== owner + '/' + repo ||
!/^(main|stable\d+)$/.test(pr.base.ref)) {
throw new Error('Only open, same-repository PRs targeting main or stable are supported')
}

const prefix = submodule + ': https://github.com/' + sourceRepository + '/pull/'
const matches = (pr.body || '').split(/\r?\n/)
.map(line => line.match(/^\s*-\s*\[[ xX]\]\s*(.*)$/))
.filter(Boolean)
.map(match => match[1].trim())
.filter(text => text.startsWith(prefix))
if (matches.length !== 1) {
throw new Error('Expected exactly one linked submodule PR')
}
const sourceNumber = matches[0].slice(prefix.length).trim()
if (!/^[1-9]\d*$/.test(sourceNumber)) {
throw new Error('Invalid linked submodule PR number')
}
const [sourceOwner, sourceName] = sourceRepository.split('/')
const { data: source } = await github.rest.pulls.get({
owner: sourceOwner, repo: sourceName, pull_number: Number(sourceNumber),
})
if (!source.merged_at || !/^[a-f0-9]{40}$/.test(source.merge_commit_sha || '') ||
source.base.ref !== pr.base.ref) {
throw new Error('The linked dependency PR must be merged into the same target branch')
}

const { data: commit } = await github.rest.git.getCommit({
owner, repo, commit_sha: pr.head.sha,
})
const { data: currentTree } = await github.rest.git.getTree({
owner, repo, tree_sha: commit.tree.sha,
})
const gitlink = currentTree.tree.find(entry =>
entry.path === submodule && entry.mode === '160000')
if (!gitlink) {
throw new Error('The configured path is not a git submodule')
}
if (gitlink.sha === source.merge_commit_sha) {
core.notice('Submodule already references the merged dependency')
return
}

const { data: tree } = await github.rest.git.createTree({
owner, repo, base_tree: commit.tree.sha,
tree: [{ path: submodule, mode: '160000', type: 'commit',
sha: source.merge_commit_sha }],
})
const subject = 'chore(deps): update ' + submodule +
' from merged PR #' + sourceNumber
const message = subject + '\n\nSigned-off-by: ' +
BOT.name + ' <' + BOT.email + '>'
const { data: updated } = await github.rest.git.createCommit({
owner, repo, message, tree: tree.sha, parents: [pr.head.sha],
author: BOT, committer: BOT,
})
await github.rest.git.updateRef({
owner, repo, ref: 'heads/' + pr.head.ref, sha: updated.sha, force: false,
})
await github.rest.issues.createComment({
owner, repo, issue_number: context.issue.number,
body: 'Updated ' + submodule + ' to ' + sourceRepository + '#' +
sourceNumber + ' (' + source.merge_commit_sha + ').',
})
}

module.exports = updateSubmodule
103 changes: 103 additions & 0 deletions actions/update-submodule/update.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
// SPDX-License-Identifier: AGPL-3.0-or-later

'use strict'

const test = require('node:test')
const assert = require('node:assert/strict')
const update = require('./update.js')

const sha = chr => chr.repeat(40)

function fixture(change = () => {}, envChange = {}) {
const parent = {
state: 'open',
head: { repo: {full_name: 'LibreSign/libresign'}, ref: 'deps/upgrade', sha: sha('a') },
base: {ref: 'main'},
body: '- [ ] 3rdparty: https://github.com/LibreSign/3rdparty/pull/17',
}
const source = {
merged_at: '2026-11-17T12:00:00Z',
merge_commit_sha: sha('b'),
base: {ref: 'main'},
}
const gitlink = {path: '3rdparty', mode: '160000', type: 'commit', sha: sha('c')}
change({parent, source, gitlink})
const calls = []
const wrap = (name, fn) => async args => {
calls.push({name, args})
return {data: await fn(args)}
}
const github = {rest: {
pulls: {get: wrap('pulls.get', args => args.repo === '3rdparty' ? source : parent)},
git: {
getCommit: wrap('git.getCommit', () => ({tree: {sha: sha('d')}})),
getTree: wrap('git.getTree', () => ({tree: [gitlink]})),
createTree: wrap('git.createTree', () => ({sha: sha('e')})),
createCommit: wrap('git.createCommit', () => ({sha: sha('f')})),
updateRef: wrap('git.updateRef', () => ({})),
},
issues: {createComment: wrap('issues.createComment', () => ({}))},
}}
const notices = []
const context = {repo: {owner: 'LibreSign', repo: 'libresign'}, issue: {number: 42}}
const core = {notice: text => notices.push(text)}
const env = {SUBMODULE_PATH: '3rdparty', SOURCE_REPOSITORY: 'LibreSign/3rdparty', ...envChange}
return {github, context, core, env, calls, notices}
}

test('updates only the gitlink at the exact merged SHA, with DCO and no force push', async () => {
const f = fixture()
await update(f)
const tree = f.calls.find(x => x.name === 'git.createTree').args
assert.deepEqual(tree.tree, [{path: '3rdparty', mode: '160000', type: 'commit', sha: sha('b')}])
assert.equal(tree.base_tree, sha('d'))
const commit = f.calls.find(x => x.name === 'git.createCommit').args
assert.deepEqual(commit.parents, [sha('a')])
assert.match(commit.message, /Signed-off-by: github-actions\[bot\]/)
const pushed = f.calls.find(x => x.name === 'git.updateRef').args
assert.equal(pushed.force, false)
assert.equal(pushed.ref, 'heads/deps/upgrade')
assert.equal(f.calls.at(-1).name, 'issues.createComment')
})

const cases = [
['fork is rejected', ({parent}) => {parent.head.repo.full_name = 'fork/libresign'}],
['closed target is rejected', ({parent}) => {parent.state = 'closed'}],
['unsupported target branch is rejected', ({parent}) => {parent.base.ref = 'feature'}],
['missing linked source PR is rejected', ({parent}) => {parent.body = ''}],
['duplicate linked source PRs are rejected', ({parent}) => {parent.body += '\n' + parent.body}],
['unmerged source is rejected', ({source}) => {source.merged_at = null}],
['mismatched source branch is rejected', ({source}) => {source.base.ref = 'stable35'}],
['unrecognized submodule is rejected', ({gitlink}) => {gitlink.path = 'other'}],
]
for (const [name, change] of cases) {
test(name, async () => {
const f = fixture(change)
await assert.rejects(update(f))
assert.equal(f.calls.some(x => x.name === 'git.createCommit'), false)
})
}

test('path traversal is rejected before any API access', async () => {
const f = fixture(() => {}, {SUBMODULE_PATH: '../3rdparty'})
await assert.rejects(update(f), /Invalid submodule path/)
assert.equal(f.calls.length, 0)
})

test('idempotent update does not create commits or comments', async () => {
const f = fixture(({source, gitlink}) => {gitlink.sha = source.merge_commit_sha})
await update(f)
assert.equal(f.calls.some(x => x.name === 'git.createCommit'), false)
assert.equal(f.calls.some(x => x.name === 'issues.createComment'), false)
assert.equal(f.notices.length, 1)
})

test('concurrent ref movement rejects without reporting success', async () => {
const f = fixture()
f.github.rest.git.updateRef = async () => {
throw new Error('Reference changed')
}
await assert.rejects(update(f), /Reference changed/)
assert.equal(f.calls.some(x => x.name === 'issues.createComment'), false)
})
26 changes: 26 additions & 0 deletions docs/cross-repository-automation.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,32 @@ Consumer-specific changes belong in `.github/workflows/<workflow>.patch`. Do not

The catalog updater targets only the consumer's default branch by default. Projects with maintained long-lived release branches should declare those branches through a consumer-local patch to `sync-workflow-templates.yml`; branch lifecycle is consumer policy and must not be hard-coded in the organization template.

## Submodule dependency commands

`command-submodule-pr.yml` tracks a pinned upstream workflow from
`nextcloud/3rdparty`; its generic changes live in `patches/nextcloud/`
and are verified against immutable upstream checksums.

`command-update-submodule.yml` is LibreCode-owned. It delegates to the
version-pinned, tested `actions/update-submodule` Action: the Nextcloud Server
command is a conceptual reference, but its implementation is intentionally
not copied because it updates a moving branch tip and can rewrite commits.

A consumer must install each workflow and configure its parameters using
Actions variables or a consumer-local `.github/workflows/<name>.yml.patch`:

- `command-submodule-pr.yml`: `SUBMODULE_PR_COMMAND`,
`SUBMODULE_TARGET_REPOSITORY` and `SUBMODULE_PATH`.
- `command-update-submodule.yml`: `SUBMODULE_UPDATE_COMMAND`,
`SUBMODULE_SOURCE_REPOSITORY` and `SUBMODULE_PATH`.

The creation command expects a Composer lockfile in the source PR. The update
command requires a linked source PR already merged into the same target branch
and uses its exact merged SHA. Both commands require maintainer authorization,
repository-hosted PR branches and a scoped publishing credential. No force
push is performed. Publishing credentials are not available to dependency
analysis or staging steps.

## Publishing templates

`LibreCodeCoop/.github` is the source of truth for LibreCode-managed workflow templates and the distribution catalog consumed by repository updaters. Templates derived from external upstream sources are refreshed through the pinned upstream/patch pipeline rather than edited as independent downstream implementations.
Expand Down
132 changes: 132 additions & 0 deletions patches/nextcloud/command-submodule-pr.yml.patch
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
--- upstream/vendor/nextcloud/command-submodule-pr.yml
+++ workflow-templates/command-submodule-pr.yml
@@ -1,6 +1,6 @@
# SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
# SPDX-License-Identifier: MIT
+name: Open submodule pull request
-name: Server PR comment

on:
issue_comment: # zizmor: ignore[dangerous-triggers]
@@ -13,8 +13,8 @@
init:
runs-on: ubuntu-latest-low

+ # A consumer patch or repository variable configures the command.
+ if: github.event.issue.pull_request != '' && vars.SUBMODULE_PR_COMMAND != '' && github.event.comment.body == vars.SUBMODULE_PR_COMMAND
- # On pull requests and if the comment starts with `/server-pr`
- if: github.event.issue.pull_request != '' && startsWith(github.event.comment.body, '/server-pr')

outputs:
head_ref: ${{ steps.comment-branch.outputs.head_ref }}
@@ -75,19 +75,26 @@
needs: init

env:
+ TARGET_REPOSITORY: ${{ vars.SUBMODULE_TARGET_REPOSITORY }}
+ SUBMODULE_PATH: ${{ vars.SUBMODULE_PATH }}
HEAD_REF: ${{ needs.init.outputs.head_ref }}
HEAD_SHA: ${{ needs.init.outputs.head_sha }}
BASE_REF: ${{ needs.init.outputs.base_ref }}
PR_NUMBER: ${{ github.event.issue.number }}
PR_TITLE: ${{ github.event.issue.title }}
- REVIEWER: ${{ github.event.comment.user.login }}
- GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }} # zizmor: ignore[secrets-outside-env]

steps:
+ - name: Validate target configuration
+ shell: bash
+ run: |
+ set -euo pipefail
+ [[ "$TARGET_REPOSITORY" =~ ^[[:alnum:]_.-]+/[[:alnum:]_.-]+$ ]] || exit 1
+ [[ "$SUBMODULE_PATH" =~ ^[[:alnum:]_.-]+(/[[:alnum:]_.-]+)*$ ]] || exit 1
+
- name: Checkout 3rdparty ${{ needs.init.outputs.head_ref }}
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
+ path: source
- path: 3rdparty
persist-credentials: false
fetch-depth: 0
ref: ${{ needs.init.outputs.head_sha }}
@@ -99,57 +106,56 @@
coverage: none

- name: Generate composer diff
+ working-directory: source
- working-directory: 3rdparty
run: |
composer global config --no-interaction allow-plugins.ion-bazan/composer-diff true
composer global require --no-interaction ion-bazan/composer-diff
{
+ echo "- [ ] $SUBMODULE_PATH: ${{ github.server_url }}/${{ github.repository }}/pull/$PR_NUMBER"
- echo "- [ ] 3rdparty: ${{ github.server_url }}/${{ github.repository }}/pull/$PR_NUMBER"
echo
composer diff --with-links --base "origin/$BASE_REF:composer.lock" --target composer.lock
} > "$RUNNER_TEMP/pr-body.md"
cat "$RUNNER_TEMP/pr-body.md"

+ - name: Checkout target repository ${{ needs.init.outputs.base_ref }}
- - name: Checkout server ${{ needs.init.outputs.base_ref }}
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
+ repository: ${{ env.TARGET_REPOSITORY }}
+ path: parent
+ persist-credentials: false
- repository: nextcloud/server
- path: server
- persist-credentials: true
- # Pushing a new branch to server needs the `workflow` scope, as GitHub can not always verify in time that no workflow is changed
- token: ${{ secrets.COMMAND_BOT_WORKFLOWS }} # zizmor: ignore[secrets-outside-env]
ref: ${{ needs.init.outputs.base_ref }}

+ - name: Fail if target branch already exists
+ working-directory: parent
- - name: Fail if branch already exists on server
- working-directory: server
run: |
if git ls-remote --exit-code --heads origin "refs/heads/$HEAD_REF"; then
+ echo "Branch $HEAD_REF already exists on $TARGET_REPOSITORY, not overwriting it"
- echo "Branch $HEAD_REF already exists on nextcloud/server, not overwriting it"
exit 1
fi

- name: Setup git
+ working-directory: parent
- working-directory: server
run: |
+ git config --local user.email '41898282+github-actions[bot]@users.noreply.github.com'
+ git config --local user.name 'github-actions[bot]'
- git config --local user.email 'nextcloud-command@users.noreply.github.com'
- git config --local user.name 'nextcloud-command'

+ - name: Commit submodule reference
+ working-directory: parent
- - name: Commit 3rdparty update and push
- working-directory: server
run: |
git checkout -b "$HEAD_REF"
+ git update-index --cacheinfo "160000,$HEAD_SHA,$SUBMODULE_PATH"
- git update-index --cacheinfo "160000,$HEAD_SHA,3rdparty"
git commit --signoff -m "$(sed -E 's/^\[stable[0-9.]*\] *//' <<< "$PR_TITLE")"
+ - name: Push branch and create target pull request
+ env:
+ GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }} # zizmor: ignore[secrets-outside-env]
- git push origin "$HEAD_REF"
-
- - name: Create server pull request
run: |
+ set -euo pipefail
+ gh auth setup-git
+ git -C parent push origin "$HEAD_REF"
+ url=$(gh pr create --repo "$TARGET_REPOSITORY" --base "$BASE_REF" --head "$HEAD_REF" \
- url=$(gh pr create --repo nextcloud/server --base "$BASE_REF" --head "$HEAD_REF" \
--title "$PR_TITLE" \
- --label dependencies --label '3. to review' \
- --reviewer "$REVIEWER" \
--body-file "$RUNNER_TEMP/pr-body.md")
+ gh pr comment "$PR_NUMBER" --repo '${{ github.repository }}' --body "- Parent PR: $url"
- gh pr comment "$PR_NUMBER" --repo '${{ github.repository }}' --body "- Server PR: $url"

- name: Add reaction on failure
uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
Loading
Loading