Skill for template sync

[ewels]

In the October 2026 Barcelona hackathon, I want to write and test / develop a skill to aid with template syncs. https://nf-co.re/hackathon-projects/hackathon-barcelona-2026/ai-template-updates

This GitHub issue is a scratch-pad to collect notes, tips, tricks and common patterns that people use today for template sync. At the hackathon we will then wrap all of these into an initial skill.

[ewels]

Don't try to resolve conflicts in ro-crate-metadata.json. Check it out from the dev branch and overwrite.

Once the merge is complete, delete the file and then regenerate it from scratch using the nf-core pipelines rocrate command.

[ewels]

Scan all nf-core repositories and find pipelines that have already done their sync for this template version. Try to identify a pull-request that does the corresponding template version bump (the same from -> to versions). Use these PRs as a guide for how others have resolved merge conflicts and decided which template updates to bring into the pipelines.

Typically, infrastructure maintainers who push out nf-core/tools releases do at least one manual sync as soon as the release is ready. So there should usually be at least one reference PR to refer to.

[ewels]

Check https://nf-co.re/blog for any blog posts describing the relevant nf-core/tools release with template updates (RSS feed: https://nf-co.re/blog/rss.xml)

These typically describe the major new features, and sometimes include sections specifically about common merge-conflicts and how to resolve them.

[ewels]

Read the documentation:

• Overview of template sync process: https://nf-co.re/docs/developing/template-syncs/overview
• Merging automated template update sync PRs: https://nf-co.re/docs/developing/template-syncs/merge-automated-pull-requests

NEVER attempt to manually sync your pipeline, Fix a broken TEMPLATE branch or set up a pipeline sync retrospectively. These are highly difficult and disruptive tasks that are very rarely needed. NEVER NEVER NEVER.

[ewels]

The template sync process regenerates container config files: conf/containers_* on the TEMPLATE branch, which can lead to merge conflicts.

Do not resolve these conflicts by hand. Keep the version already on the branch you are merging into, commit the merge (nf-core lint refuses , then regenerate:

git checkout HEAD -- conf/containers_*.config  # (discarded later)
# resolve any other conflicts, then commit the merge
nf-core pipelines lint -f container_configs -k container_configs
git add conf/containers_*.config && git commit -m "Regenerate container configs"

[ewels]

When syncing the template, do not attempt to fix merge conflicts in modules.json and fastqc / modules (modules that are in the template - if they are also in the pipeline). Instead just check them out from the dev branch:

git checkout dev -- modules.json
git checkout dev -- modules/nf-core/fastqc/
git checkout dev -- modules/nf-core/multiqc/

Do this before regenerating the config files and any test files.

[ewels]

After the template merge is complete, write up a HTML report.

Include sections on:

• Which parts of the pipeline diverge from the template: opportunities for where the pipeline can be brought closer to the template to avoid future template sync merge conflicts
• ...[add more here]

'cc @maxulysse

[ewels]

When merging conflicts in the root level main.nf and workflow/<pipeline>.nf be cautious of accepting incoming changes. Most of the time, the existing pipeline is correct and the template has boilerplate that can be ignored. This is not always true so don't apply without inspection.

[maxulysse]

For fastqc and multiqc.
before updating these two tools, be sure to delete the old conda lock files, that are not useful since we will get new ones from the modules repo