How to Release a New Version of a Private Orb in CircleCI

Overview

To release a new version of a private orb on CircleCI, you must first ensure the orb was created as private during initialization, then follow a process of updating your source code, publishing the new version using the CircleCI CLI, and optionally tagging releases for production versions. Private orbs remain accessible only to authenticated users within your organization and follow the same publishing workflow as public orbs.

Releasing Your Private Orb Version

Step 1: Verify Private Orb Creation

Ensure the orb was created as private when you first initialized it. You must use the --private flag with the circleci orb init command:

circleci orb init /path/to/my-orb --private

Important: Once an orb is created as private, all future versions will remain private. You cannot change an orb from public to private or vice versa after creation.

Step 2: Update and Commit Your Changes

Make your necessary updates to the orb source code, then commit and push your changes to your repository. This ensures your latest modifications are ready for the new release.

Step 3: Publish the New Version

You can publish a new version of your private orb using the CircleCI CLI with two different approaches:

For Development Releases (expires after 90 days):

circleci orb pack ./src | circleci orb publish - <namespace>/<orb-name>@dev:<tag>

For Production (semantic versioned) Releases:

circleci orb pack ./src | circleci orb publish - <namespace>/<orb-name>@x.y.z

Replace <namespace>, <orb-name>, and x.y.z with your actual values.

Step 4: Tag and Release (for production releases)

If you are using GitHub Releases, create a new release with a semver tag (e.g., v1.2.3). This will trigger your CircleCI pipeline to publish the new orb version automatically.

Validation and Testing

Validating Your Private Orb

To validate your private orb configuration, use the following command:

circleci config validate --org-id <your-org-id> <path/to/config.yml>

This ensures your orb configuration is correct before publishing.

Development vs Production Releases

Development releases are useful for testing and expire after 90 days, making them ideal for experimental features or bug fixes that need validation before production release.

Production releases use semantic versioning and are permanent, making them suitable for stable features that are ready for widespread use within your organization.

Additional Notes

Private Orb Accessibility: Private orbs will not appear in the public Orb Registry, but are accessible via direct URL to authenticated users in your organization. This provides security for proprietary functionality while maintaining ease of use for your team.

Publishing Process Consistency: The process for publishing private orbs is identical to public orbs, except for the initial creation step with the --private flag. This consistency makes it easy to manage both types of orbs using the same tooling.

Organization Scope: Private orbs are scoped to your organization, ensuring that sensitive code or proprietary workflows remain within your team's control.

Automated Publishing: You can integrate orb publishing into your CI/CD pipeline to automatically release new versions when code is pushed to specific branches or when releases are tagged.

Additional Resources