[Feature Request] YAML merge keys support

[polarathene]

Why are you starting this discussion?

Product Feedback

What GitHub Actions topic or product is this about?

General

Discussion Details

Context

It was suggested to create a new issue/discussion and I haven't come across one raised since for YAML merge keys support.

From the original 2021 YAML anchor + alias feature request (which opens with an example snippet using merge keys):

• April 2025

  I also talked with the engineer working on YAML anchors about merge key support and unfortunately merge keys are not natively supported in the updated parser.

  • Supporting merge keys would require significantly more work since we would have to build custom code to support it instead of using native capabilities in the parser (like there is for YAML anchors).
  • While we won't be supporting merge keys at this time if there is sufficient interest in merge keys, we can consider it in the future. I would recommend creating a separate feature request for merge keys here, that is where we are tracking new feature requests going forward.

• Aug 2025

  Merge keys are part of YAML 1.1 but not YAML 1.2.
  A separate issue would be more appropriate to request merge key functionality.

Related: YAML anchor + alias support:

• Aug 2025 feature request comment announcing support had arrived in 2025.
• Associated blog announcement.

---

Feature Request

In the YAML spec 1.2.0 changelog (2009) merge keys was dropped:

The merge << and value = special mapping keys have been removed.

However, in the wild there are various YAML 1.2 compliant parsers which can be found to still have support for merge keys (treating it as an extension that is sometimes opt-in or always supported):

• https://docs.deno.com/runtime/reference/std/yaml/
• https://stackoverflow.com/a/77374664 (PyYaml, Docker Compose)
• Merge keys shouldn’t be supported by default nodeca/js-yaml#646 (comment) (js-yaml)
• https://yamlscript.org/blog/2025-06-02/yaml-variables/ (YS/yamlscript is marked as officially supported by the YAML company)
• https://eemeli.org/yaml/#schema-options (doesn't actually have a 1.2 spec parser that allows merge keys, but rather reverts to full YAML 1.1 schema via opt-in, this project also offers a separate yaml 1.1 types extension which this comment is presumably referring to)

---

NOTE: Despite the YAML 1.2.0 changelog regarding removal of the << merge key operator, it had been communicated since about plans for explicit removal of the merge keys feature and apparently an RFC associated to that (now no longer present at the current iteration of the wiki unless going through revision history). As the main wiki page notes, the original team ran out of steam after the 2009 1.2.1 spec release, and while activity did pick up again with the 2021 1.2.2 spec release, progress seems to have stalled? (unclear if there will be a YAML 1.3, or what progress since 1.2.2)

[polarathene]

FWIW: nektos/act added related support at the end of 2025. That project had a different implementation originally, but it raises the question... could GHA workflows could be processed through a separate YAML 1.2 parser that already has support for merge keys, then process that document with the aliases + merge already resolved?

• Overhead of doing that shouldn't be costly? (and is language agnostic)
• The only other concern might be for error/debug messaging, which should not be too tricky to implement a sourcemap to correct source lines referenced?

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[dotsystemsdevs]

This is a great write-up and a much-needed discussion. Since GitHub switched to the new parser and enabled anchors/aliases in 2025, the lack of merge keys (<<) has definitely become the "missing piece" for keeping GHA workflows DRY.

While we wait for native support, have you considered using a pre-processor step in the meantime? Many teams are now using tools like yq or a simple Jsonnet/CUE setup to compile their "templated" YAMLs into standard GitHub-compatible YAML before pushing.

Also, as you mentioned nektos/act adding support, it proves there is a clear demand for the local DX to match the cloud runner's capabilities. If GitHub won't build a custom resolver for the 1.2 parser, perhaps a "Compatibility Mode" flag in the workflow settings could be a middle ground?

In the meantime, I’ll definitely upvote this. It’s the most logical next step after the 2025 anchor update.

[polarathene]

Also, as you mentioned nektos/act adding support

I haven't said that Act supports using <<, just that they updated to also support anchors + aliases.

I don't use that project so I'm unfamiliar if it actually has YAML merge keys support.

have you considered using a pre-processor step in the meantime?

I could leverage some form of templating/generation yes. I can't as easily get third-party projects that I contribute to be comfortable with the burden of additional complexity supporting that indirection.

My contributions tend not to be large enough to justify such a workaround, but merge keys support in some workflows would be helpful where a step is repeated with a slight change (as opposed to creating a separate workflow/action to call, especially with the existing GHA file layout constraints that a separate feature request is tracking for better organization via subdirs).

When piecing together this feature request, I did come across true-yaml-actions at the actions marketplace which is intended to automate the workflow template workaround for merge keys support 😓