Orb Tools v12 - Test without publishing

Announcements
1

Orb Tools v12 Release: Enhanced Orb Publication Process & Reduced Contributor Friction

Orb: CircleCI Developer Hub - circleci/orb-tools
Release: Release v12.0.0 - Publish-less testing · CircleCI-Public/orb-tools-orb · GitHub

Key Updates

For a comprehensive list of updates, refer to the full changelog:

Significant Improvements:

  • Development orbs no longer required for testing
    • Introducing dynamic pipeline orb injection for testing
    • Removes the barrier of needing publishing access for contributors to run tests
  • Transition to snake_case
    • Ensures consistency with CircleCI’s native config schema
  • Parameterizable executors
  • Enhanced customization options
    • Customizable orb file names
      • Facilitates publishing multiple orbs simultaneously
    • Simultaneous push of multiple custom development tags
    • Optional checkout step
      • Utilize pre-steps for job customization or to provide a custom checkout

Previously, in order to test your orb, a development version needed to be published prior to running integration/e2e tests for the orb via the dynamic test-deploy workflow. Though the development orb publishing process was automated, it included a lot of friction for those who did not have access to the publishing token, mainly open source contributors. So in the past, if an open source contributor made a PR to an orb that would otherwise build (assuming build forked-prs is enabled), it would stop short of testing due to the lack of access to the private publishing token needed to publish the development version of the orb.

What was needed was a way to test the orb’s changes without requiring access to the publishing token for just development versions of orbs. Because we are already taking advantage of dynamic config, the test-deploy workflow has the ability to be modified before it is executed. Using inline orbs, we now inject the source of the orb directly into the config, rather than referencing a publically accessible development tag.

test-deploy.yaml

version: 2.1
orbs:
  orb-tools: circleci/orb-tools@12.0
  # The orb definition is intentionally not included here. It will be injected into the pipeline.
  <orb-name>: {}
...

Now, rather than referencing a development tag like had had in the past, we reference nothing ({}) and it gets replaced at run-time with the full source of your orb. This functions essentially exactly the same as prior to this update but now the publish job is no longer needed at all in the config.yaml file.

Upgrading

If you have an existing orb you want to upgrade to orb tools 12, due to the major version changes, there will be several adjustments needed. The easiest approach is to take a look at the updated Orb Template used by new orbs as a reference for updating your orb’s config.

You can use the updated migration script for this release to automatically snake_case your orb’s components.

Building a new orb

Building a new orb works the same has it has before, get started with the circleci orb init command. The latest version of the Orb Template with Orb Tools v12 will be pulled.
Docs: Orb Authoring Process - CircleCI

2

Created a ticket here too:

I appreciate the security enhancement, since we’ve had our own challenges with restricted contexts, esp. with Circle requiring some heavy duty GitHub permissions to publish, from what I remember (org owner, maybe?)

but how exactly can we use the old workflow with the new orb, assuming there’s no way to use / test the packed private orb in a different project or workflow? Is there a way to still have it automatically publish / comment on the PR in dev mode.

In our case, we don’t run any tests in CI currently on the orb, and we’re not using the full orb publish / promotion process, since we’re using semantic-release for that, but it is very handy to have that automagic publishing when commits are pushed vs. publishing manually.

I know we can stay on 11.x for quite some time, but eventually, we’ll probably need to update.

3

Hey @wyardley :wave:

how exactly can we use the old workflow with the new orb

We made sure to ensure this was possible, though this is not format the new template follows. Will expand a little below.

assuming there’s no way to use / test the packed private orb in a different project or workflow

This is correct, at least not with dynamically injected orbs, however, this is still completely possible in the way it was previously, by publishing a development version of the orb to a dev tag and testing it just as before.

Is there a way to still have it automatically publish / comment on the PR in dev mode.

Yes! Not only did we not remove this functionality, we improved it! You can now publish multiple development tags at once, anything you want custom.

The publish job has been updated, it is just no longer used for publishing development orbs in the orb tools 12 template

image
image1307×281 20.2 KB

To publish a dev orb, it looks mostly the same:

- orb-tools/publish:
    orb_name: circleci/orb-tools
    vcs_type: <<pipeline.project.type>>
    pub_type: dev

pub_type here is not even necessary as dev is the default, but it is more readable this way in the config. By default, two tags will be produced for the dev version: dev:${CIRCLE_SHA1}, dev:alpha but you can add more now too!

Let me know what you think!

4

Thanks again @KyleTryon - got it - will test.

Also, commented in Major: Orb Tools Version 12 by KyleTryon · Pull Request #181 · CircleCI-Public/orb-tools-orb · GitHub, but is there a way to use orb-tools-orb/default.yml at d82dc2573e58a893284a186bb2895ccceb89857e · CircleCI-Public/orb-tools-orb · GitHub now that the passthrough in the job steps was removed? I am having trouble figuring out how the workaround suggested there would work without completely redefining the executor.

1 Like
5

You can preview what this will look like on the CircleCI Orb Registry at the following link:
https://circleci.com/developer/orbs/orb/?version=dev:dev:${CIRCLE_SHA1}

Also, I’m seeing a literal ${CIRCLE_SHA} in the GH link that gets posted (and maybe a missing orb name / namespace)?

I’ll create a separate ticket for that, unless I see that it’s already been fixed (edit: Dev orb publishing comment missing · Issue #204 · CircleCI-Public/orb-tools-orb · GitHub)

6

Ah, I get it… can do this:

      - orb-tools/lint:
          executor:
            name: orb-tools/python
            resource_class: small

though I think it’s still not possible to do that once at top level and reuse it, right (other than using yaml anchors)?

7

I’m seeing the limitation you are talking about. I have opened an internal ticket to see if there is something we could do to expand a little further but we can get pretty close using anchors and aliases

orbs:
  node: circleci/node@5.1.0

my-executor: &my-executor
  name: node/default
  resource_class: small

jobs:
  example-job:
    executor: *my-executor
    steps:
      - checkout
1 Like
8

Yeah, anchors are where I ended up too.
From previous threads, seems like the way I want to do it is still not possible.