Skip to content

docs(workflows): Document workflow sync and patching #763

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nickvergessen merged 2 commits into from
Jul 8, 2026
Merged

docs(workflows): Document workflow sync and patching #763

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fa76c97
docs(workflows): Document workflow sync and patching
nickvergessen Jul 8, 2026
b8c9416
docs: Fix note block
nickvergessen Jul 8, 2026
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
36 changes: 28 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,29 @@ https://github.com/nextcloud/viewer/actions/new

![image](https://raw.githubusercontent.com/nextcloud/.github/master/screenshots/choose-a-workflow.png)

## Auto-update repositories
## Auto-update in a repository

For each template, you can propagate them on all the repos that use it.
1. Go into https://github.com/nextcloud/.github/actions/workflows/dispatch-workflow.yml
2. Enter the name of the workflow you want to dispatch
3. Enter the page you want to execute (100 are done per page, so check the [number of repositories](https://github.com/orgs/nextcloud/repositories), current is 260 so run for page: 1, 2 and 3)
There is a GitHub action for that as well. Simply install
https://github.com/nextcloud/.github/blob/master/workflow-templates/sync-workflow-templates.yml
into your repository and a cron job will update the workflows from the template every sunday morning.

![image](https://raw.githubusercontent.com/nextcloud/.github/master/screenshots/dispatch-a-workflow.png)
> [!NOTE]
> GitHub does not allow pull request that touch workflows to be auto-approved and auto-merged to improve security.
> But it's at least much easier to be aware of the updates and you just need to approve and merge the PRs.

4. Wait for the actions to finish and see the checkout the pull requests
## Patching workflows

## Update workflows with a script
It's also possible to customise workflows by putting a `workflow.yml.patch` file right next to it.
The patch files should be one per workflow and made from the repository root:

Example:
1. Modify `.github/workflows/phpunit-mariadb.yml`
2. Save patch `git diff .github/workflows/phpunit-mariadb.yml > .github/workflows/phpunit-mariadb.yml.patch`

The `sync-workflow-templates.yml` action also supports this and reapplies the patches if possible.
If there was an error it will be outlined in the PR description.

## Update workflows manually

You can also run the following shell script on your machine to update all workflows of an app. It should be run inside the cloned repository of an app and requires rsync to be installed.

Expand Down Expand Up @@ -51,6 +62,15 @@ rsync -vr \
"$temp/workflow-templates/" \
./.github/workflows/

# Reapply patches
for patch in ./.github/workflows/*.yml.patch; do
[ ! -f "$patch" ] && continue
echo "🩹 Applying $patch"
if ! patch -p1 < "$patch"; then
echo "❌ Failed to apply $patch, please resolve manually"
fi
done

# Cleanup
rm -rf "$temp"
```
Loading