Using YAML anchors in a destructured orb?


I’ve recently started working on my first orb (zzamboni/leanpub, feedback welcome). I have several jobs and commands which share the same base set of parameters, so I have declared them as a YAML anchor near the top of my single-file orb.

I was thinking of destructuring the orb, but it seems that in YAML references cannot be used across multiple files (I guess each .yml file in the tree gets validated separately?). This is what I get:

> circleci config pack src

Error: Failed trying to marshal the tree to YAML : yaml: unknown anchor 'base-leanpub-params' referenced

Is this possible, or should I just stay with a single-file orb due to this?


1 Like

Hi @zzamboni!

Right, I think you’d have to keep your anchors isolated to particular YAML files within your destructured /src directory in order for this to work :slightly_smiling_face:

Hi @rose - thanks for the quick reply! That’s what I suspected. I’ll destructure only the parts that can be cleanly separated then :slight_smile:

Can I ask what you were trying to use YAML anchors for across multiple files within your orb source directory? @zzamboni

I suspect it likely indicates a gap in our orb schema (like, for example, a lack of support for top-level parameter declarations)…

Hi @rose,

In the orb I’m writing most commands and jobs take the same two parameters (book-slug and api-key) with the same default values. To avoid repeating their declarations in every block, I put them at the top with an anchor, and use it in commands and jobs as needed. You can see this in Github:

Since this is my first orb (and I only recently started using CircleCI at all), maybe I’m going about it the wrong way? Maybe there is some other way to pass this information around without using parameters. I’d appreciate any feedback about the structure and code in my orb as well :slight_smile:

Thanks in advance!

Yup, my thoughts exactly @zzamboni!

You’ve definitely got the right idea! Parameters are the best way to pass values around between your jobs and commands, and it’s definitely a best practice to keep those parameter names consistent. What you’re exposing here is a feature we should support—and likely will at some point: top-level parameter declarations for an orb. So thank you!

In the interim, you could either:

  • Keep your orb structured the way it is, and accept that your code will have to be a bit less DRY than ideal
  • Stop using the destructured format, so your orb is all a single file, and use YAML anchors to DRY up your parameters syntax

I’d recommend the former, personally, as I think the destructured syntax is useful enough to make lack of YAML anchor support an acceptable cost.

But we should provide the support to make this kind of thing unnecessary! I think users have filed requests for this feature already at—please vote for it so we can prioritize the development work accordingly :slightly_smiling_face:

Hi @rose - thanks for your feedback.

I couldn’t find a relevant entry for this at - I may file a new one.

I would like to semi-hijack the thread to ask about your sentence:

I think the destructured syntax is useful enough to make lack of YAML anchor support an acceptable cost.

Could you help me understand what is so useful about destructured syntax? I understand that you get smaller, hopefully easier-to-understand files, but on the other hand, if you want to make a global change (e.g. rename a parameter all over the place) you have to edit many files, whereas in a single file you can do this very easily. Plus, you lose the ability to use features such as YAML anchors and references. Furthermore, trying to read a destructured orb becomes harder by having to traverse multiple files.

Maybe I’m missing something because the orb I’ve worked with so far is relatively small - maybe destructuring becomes more useful for larger, more complex orbs.

Thanks for helping me understand :slight_smile:

1 Like

@zzamboni Totally :slightly_smiling_face:

It may be a matter of preference, for sure!

I’m coming at this as a maintainer of many circleci orbs, many of which are large/complex. In our case, what the destructured syntax does is make the entire development process more modular. Say you create a command in one orb, but decide it’s a better fit for another orb. You can just drop the command’s YAML file into the other orb.

You can also do things like automatically decide how major/minor of a release to publish based on which orb files were edited in a particular commit, which is the basis of a lot of the automated publishing set up for CircleCI’s various orb repositories.

But for developers working on a smaller, singular orb, the single-file structure may certainly win out, for reasons that also make sense. Personally, even for a small orb, I find the destructured directory/file tree structure easier to parse as a developer. But others may feel otherwise.

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.