Reviewing Core Plans


Ready to review some core plans? This can seem a bit scary, but it’s certainly doable- here is how!

Reviewing a New Plan

If someone is adding a new plan to

  • Check whether the new plan fits the requirements outlined in
  • Check the plan out locally and ensure that it builds in a local studio. If it does not build, put the error in a comment in the PR and ask the person submitting the PR to look into it.
  • If the plan builds, go ahead and merge the PR.
  • Next, head to, login, navigate to Builder, find the core origin, and click the “Connect a plan file” button
  • Select habitat-sh, then core plans, then paste in the path to the new core-plan’s file (probably core-plan-name/
  • Click “Build Latest Version”
  • After the build completes, promote the build to the stable branch.

Reviewing a Change to an Existing Plan

NOTE - these steps will change when we have completed adding in CI/CD tests, as outlined here. But you can still test them manually until that is ready!

First, identify whether a change is a low risk or high risk change. Generally, I consider a minor version bump of the software being packaged to be a low risk change.

Reviewing a Low Risk Change

If the PR is a low risk change - still check out the PR locally and ensure that it builds. Then merge the pull request and navigate to the page for the core plan on Builder. Merging the pull request should automatically kick off a new build in Builder. If for some reason it does not, click the “Build Latest Version” button.

If the new version builds successfully, you should be good to bulk promote everything built in that builder job to stable (NOTE - you will need to do more extensive testing with a high risk or hell dive change).

Now, it’s time to check whether other plans that are dependent on the edited plan have built successfully, then bulk promote those that have.

The ‘hab bldr job promote’ command can be used for bulk promotion of group packages.

Note: You MUST update to hab 0.39.1 or later in order to properly use the promote command.

The best way to run the promote is to use the new ‘–interactive’ flag to check the list of successful builds, and weed out any packages that should not be promoted.

To get your group id:

Check out the builder output for the most recent build for your package on

Look for this line (the number will vary)

hab-studio: Exported: HAB_BLDR_CHANNEL=bldr-832040326113607680

Copy the number after “bldr-” - this is your job group id

Make sure to set your preferred EDITOR before issuing the commands, eg:

export EDITOR=vi
hab bldr job promote --origin core -i <GROUP ID> <CHANNEL>

After exiting the editor, you will be prompted one more time for whether you want to promote the package list. If you want, you can include a ‘–verbose’ flag in the command above, and you will be shown the final list of promotable packages before the prompt.

If you receive an error that the build job is still in progress, you can check its status with:

hab bldr job status -s <GROUP ID>

A simple but useful command to get a visual of a large tree of jobs is

$ hab bldr job status -s <id> | egrep "(Failure|InProgress|NotStarted)"

You can watch the above command’s progress with the watch command, if you desire.


$ watch -n 10 hab bldr job status -s <id> | egrep "(Failure|InProgress|NotStarted)"

Reviewing a Medium Risk Change

I consider any change which adds new behavior to a plan to be a medium risk change. The testing process for these is more extensive. If the person who opened the pull request has not including testing steps for the changes, I always ask them to add those in a comment on the PR. When they do, check out the branch locally, do a local build, and then run the tests (I often spin up an instance of the new plan in a local Docker container).

When these tests are successfully complete, go ahead and merge the PR, then make sure a build gets kicked off on Builder. When the build completes, I usually check out the new package locally and test the behavior again to vet it. If all looks good, I will go ahead and promote it to stable. Then follow the same process as for the low risk change in order to build promote dependencies.

Reviewing a Major Version Update Change

To be added

Reviewing a Hell Dive Change

A “Hell Dive” change is anyone that will affect a significant (i.e. more than 20) other plans.

More to come on how to review/merge/promote these soon.

Useful Sample Apps for testing

If you are testing packages related to node, ruby, or go, here are some useful sample apps to use for testing (please feel free to add more as you discover them!)

For examples of reviewing different types of core plans, check out the articles labeled “Reviewing Core Plans example”, including