Request: Can this be used as an Orb SDK or not?

[mschuchard]

Is there an existing issue that is already proposing this?

• [X] I have searched the existing issues

Is your feature request related to a problem? Please describe it

It is unclear to me if this can be used for orb development or not, but it appears that the current answer is: no.

Describe the solution you'd like

Using this SDK for Orb development.

Teachability, documentation, adoption, migration strategy

n/a

What is the motivation / use case for changing the behavior?

Comparable functionality to Jenkins shared libraries, Github Actions actions, Concourse custom resources, and other CI platforms that enable reusable portable library code across pipelines (currently absent from e.g. GitlabCI and TravisCI, but hopefully could exist in CircleCI).

[KyleTryon]

@mschuchard Yes-ish. I will say, it is not purposefully designed to be an Orb SDK, but it absolutely could be done, you would just need to define the reusable config definitions and add them to the config file. I haven't tested this yet, but that should work. We would probably be missing the display and description fields at the moment, but they are optional. However! If you are embracing the Config SDK, you really do not need orbs. You may want to use existing orbs for the sake of not reinventing the wheel, but rather than using orbs, you can simply use javascript. And not using orbs means you get the full benefit of typed code with TypeScript.

Rather than creating an orb from config and uploading it to the CircleCI Orb Registry, you now have the option to instead, package the config as an NPM package and use that package in your SDK built config app.

If you take a look at this blog post, I have created a config template using the SDK and published it as a package. Then, I can use the package in my config app (also using the SDK). This is effectively the same thing as using an Orb, but it uses JavaScript and the NPM registry instead of YAML and the CircleCI Orb Registry.

https://circleci.com/blog/config-sdk/

Our package exports a function named writeNodeConfig which takes in the value of the tag we want for triggering deployments, and the path we want to export the config to. We know the path from earlier in our config.yml, we set to be ./dynamicConfig.yml, because we are in the dynamic directory, we will prepend ... For the tag, we’ll use a generic regex string v.*

import writeNodeConfig from '<your/package>';

writeNodeConfig("v.*", "../dynamicConfig.yml")

Here is another example from a user: https://getlocalci.com/typescript-circleci-configs-only-3-lines/

---

What do you think about this approach instead? We can and probably will make more improvements to specifically focus on Orb development for users who still want to create orbs for the majority of users who are not using the SDK. But especially if this is for yourself, the JS method will give you type information and auto-completion.

[mschuchard]

Then, I can use the package in my config app (also using the SDK). This is effectively the same thing as using an Orb, but it uses JavaScript and the NPM registry instead of YAML and the CircleCI Orb Registry.

LGTM. This was the missing piece of the puzzle for me. I had referenced that blog post and this repo's wiki, but had not been able to connect the dots on the use case extension.

The usage is slightly different across the different CI platforms for sure, but the functionality is still equivalent. Thanks; I will approach from this direction to experiment with implementation.

[mschuchard]

@KyleTryon Never mind: I reviewed the documentation again and cannot locate how to use the NPM as a library i.e. passing arguments to the functions defined within it (I did not see anything about defining them as methods instead of functions, so I assume functions).

Maybe I should just be more straightforward. I am interested in porting my Jenkins Pipeline libraries (https://github.com/mschuchard/jenkins-devops-libs) to other platforms such as Circle, and it is clear how to do this for GH actions with JS and Concourse with any language supported by the SDK (I did Packer for a client earlier this year even). Is this possible given the current state of the Circle Config SDK?

[mschuchard]

I will assume based on feedback that Orb SDK/library functionality analogous to Jenkins, Concourse, and GH Actions is not on the roadmap for this project.

[KyleTryon]

The SDK itself will never be a runtime, it's purpose is to create the YAML that CircleCI config operates from. You will be able to build orbs (which are also YAML) with the SDK. The SDK as it is designed now will not ever run javascript on the platform.

[mschuchard]

I do not have enough insight into Circle internals to know how JS relates here, but thanks for the confirmation. I will wait and hope for eventual library functionality in Circle.