Chef Habitat Builder acts as the core of Chef’s Application Delivery Enterprise hub. Chef Habitat Builder was first launched as a cloud service and as the repository of all available plan templates built by Chef and the supporting community. Due to the fact that the application source code is stored alongside the build package, many users expressed a preference for storing packages and running Chef Habitat Builder on-prem. As a result, Chef Habitat Builder can be consumed either as a cloud based or on-premises solution. Plan files are stored in the Chef Habitat Builder SaaS, where they can be viewed and accessed by the Chef Habitat community and then shared with the on-premises version of the builder where they can then be copied and maintained locally.
Chef Habitat Builder Enterprise Components Include:
- Application Manifest - The Application Manifest provides a single application directory, which includes---at a minimum---the compiled app artifact, dynamic links to all direct and transitive runtime dependencies ,and instructions to install and run the app.
- Deployment Channel Management - Pre-canned deployment channels that can be used as-is or a user can custom design their own channels. Apps that are deployed through Chef Habitat can subscribe to a channel and be auto-upgraded whenever the app is promoted.
- Origin Management - Save your application delivery content in uniquely named spaces that you can control.
- Content Library - Hundreds of pre-built application delivery packages and core dependencies, which makes it easy to get started with Chef Habitat.
- Custom Data and Reporting APIs - Rich APIs enable the capability to export to CSV or JSON.
- DevOps Integration APIs - Provides an API so that clients can find and download the necessary packages to run their applications. Additional APIs also enable easy integration with other popular DevOps tools, including Jenkins, Terraform, Artifactory, Hashi Vault, and many others.
- Role Based User Access - Improves your organizations operational safety by letting you assign specific levels of access to each origin member.
For more information on how the SaaS and On-Prem versions of Chef Habitat Builder work together, read the blog - Chef Habitat Builder On-Prem Enhancements that Extend Support to Airgap Environments and Simplify Set-Up
Whether you are looking to leverage the SaaS or on-prem version of Chef Habitat Builder, you will need to create an account on the SaaS version of Chef Habitat Builder. After you have then downloaded the version, you will then sync the two accounts.
This documentation covers everything from creating an account to setting up automated builds and exporting packages to a variety of container registries.
You need to set a few things up before you can get started with Chef Habitat Builder:
Sign-in and Authorize Chef Habitat Builder
Chef Habitat Builder automatically creates your account the first time you sign in using the GitHub authentication process. You'll also need to authorize the Chef Habitat Builder application in Github.
Head over to the Chef Habitat Builder sign-in page at https://bldr.habitat.sh/#/sign-in to get started.
- To sign in with an existing GitHub account, select Sign in with GitHub
- If you need to set up a GitHub account, select the Sign up here link
Signing in with your GitHub account and authorizing the Chef Habitat Builder application the first time you sign in grants you access to the Chef Habitat Builder platform. Once you've completed signing in and authorizing Chef Habitat Builder, you'll arrive at the 'My Origins' view.
Use the Profile tab to:
- See the GitHub account used to sign in
- Add an email to your profile
- Create your personal access token
Access your profile by selecting the round icon at the top right corner of any page. Select the profiles option from the drop-down menu to customize your profile and create your personal access token.
Register an Email Address
Adding an email address to your profile gives the Chef Habitat team permission to contact you directly about important information. If you use an email address associated with a GitHub account, it will also use your GitHub avatar. Save your changes by selecting save.
Chef Habitat Builder uses an access token, called a personal access token or a Habitat authentication token (HAB_AUTH_TOKEN), to give you access to actions that you would like to take on Chef Habitat Builder. The personal access token is the first level of permissions that you need to for any interactions with Chef Habitat Builder, such as uploading packages or checking the status of build jobs.
Create your personal access token at the bottom of the profile page (below the save button), by selecting Generate Token.
Your generated access token will appear in the field. The access token is visible in the tab once, and navigating away from or reloading the page will cause it to vanish from the display. Copy your access token by selecting the icon on the right side of the field and set it as an environment variable before continuing.
You can use your personal access token as a Windows environment variable for a single session by passing it in the command line or save it in your user settings for use across sessions.
Save your personal authorization token as a permanent environment variable in Windows using:
You can also save your personal access token as a permanent environment variable using the Windows user interface. In your Windows help bar, enter
environment and select Edit the system environment variables from the list of suggestions.
This opens the
System Properties window on the
Advanced tab. Select the
Environment Variables button.
In the next window, select the
New button in the top part. This opens a dialog box that lets you set individual user variables.
Create a permanent environment variable by entering
HAB_AUTH_TOKEN as the variable name. Next, paste the authorization token that you copied after you generated a new token on your profile page as the variable value. After you select the
OK, you will see the new token in the user variables field.
To test that your new token works correctly, open the Command Prompt---which you can find by entering command in the Windows search box---and entering
echo %HAB_AUTH_TOKEN%. You should see the value that you pasted into the environment variable.
HAB_AUTH_TOKEN in the CLI with:
<token> with the contents of your generated personal access token.
To use your personal access token across sessions, set it as an environment variable in your interactive shell configuration file, such as your
Then initialize the path from the command line, by running:
An origin is a place on Chef Habitat Builder where you can store, share, and build packages. It is a unique namespace within Chef Habitat Builder, and while you can delete or transfer an origin, you can't rename an origin after it is created. One example of an origin is the "core" origin, which is the set of foundational packages managed and versioned by the core Chef Habitat maintainers.
You can join existing origins by invitation and you can create your own origins. For more on invitations, see origin membership and RBAC.
Create an Origin
To create an origin, select the Create origin button on the My Origins page which opens the Create New Origin form. (Chef Habitat Builder > My Origins )
First, enter a unique name that you want to associate with your packages. Chef Habitat will only let you create an origin with a unique name. Some examples that you'll see in Chef Habitat Builder are team names, user names, and abstract concepts.
Next, choose a privacy setting to set as the default for new packages. You can override this setting when uploading individual packages from the CLI or by connecting a plan file that declares a package as private. The difference between public and private packages is:
- Anyone can find and use public packages
- Only users with origin membership can find and use private packages
When you select Save and Continue, Chef Habitat Builder:
- Creates your origin
- Creates an origin key pair
- Redirects Chef Habitat Builder to the origin page
Create an Origin with the Chef Habitat CLI
Use the hab origin commands to manage your origins from the command line.
Create an origin from the command line with the hab origin create command
The results of this command differ slightly from creating an origin on the Chef Habitat Builder site. The CLI command:
- Creates an origin on the Chef Habitat Builder site
- Does not generate an origin key pair
For more information, see the
hab origin create CLI documentation.
- Download the Chef Habitat CLI
- Create a Chef Habitat Builder account
- Generate a personal access token
- Create an origin or accept an invitation to an existing origin
- Get origin keys
Role-Based Access Control (RBAC) for Chef Habitat Builder (SaaS and on-prem)
New in: 1.6.140
RBAC provides your organization with better operational safety by letting you assign specific levels of access to each user that belongs to an origin. With RBAC in place, existing standard origin 'members' from earlier versions are assigned the 'Maintainer' role. This role has similar permissions of the previous generic 'member' role, and the areas of difference are detailed below. The origin owner role remains unchanged.
When you join or create an origin, Chef Habitat Builder identifies your personal access token and assigns it a membership role for that origin. Your membership role defines the level of access that you have to the resources in an origin. By default, you're assigned the "read-only" role when you join an origin, and you're assigned the 'owner' role when you create an origin.
RBAC Origin Member Roles:
- Read-Only: This user can read an origin's packages, channels, origin membership, jobs, keys, integrations, invitations, roles, settings but cannot add to, change, or delete anything else in the origin, including uploading packages and inviting users to the origin. Read-Only is the default membership role for users joining the origin.
- Member: In addition to read-only access, an origin 'Member' can upload and build packages in the 'unstable' channel, but they cannot promote packages to other channels.
- Maintainer: Existing origin 'members' are now 'Maintainers'. This role has full read and write access to packages, channels, origin membership, jobs, integrations, invitations, settings. However, the 'Maintainer' role is more limited than the past role, in that 'Maintainers' only have read access to packages, channels, origin membership, jobs, keys, integrations, and settings. Origin 'Maintainers' can read origin membership roles and see and send invitations, but they cannot otherwise change origin membership--their own or anybody else's. Finally, 'Maintainers' can neither read nor write origin secrets.
- Administrator: In addition to 'Maintainer' access, the 'Administrator' role adds the missing privileges for writing origin keys and membership roles, as well as for reading and writing origin secrets. Administrators have full read and write access to packages, channels, origin membership, jobs, keys, integrations, invitations, roles, secrets, settings.
- Owner: As in the past, the origin 'Owner' has full read and write access to the origin. Only Owners can delete the origin or transfer ownership to another member.
Comparison of RBAC Member Roles and Actions
|Upload packages to
|Promote packages from
|View build jobs||Y||Y||Y||Y||Y|
|View origin membership||Y||Y||Y||Y||Y|
|View member roles||Y||Y||Y||Y||Y|
|Update member roles||N||N||N||Y||Y|
Manage Origin Membership
In tandem with the changes to the Builder membership roles, we've also updated the
hab CLI to support RBAC. We're working on adding role management to the Chef Habitat Builder site, but in the meantime, you'll need to use the CLI for now.
Manage origin membership with
hab origin invitations
Manage Chef Habitat Builder origin membership with the Chef Habitat CLI, using the hab origin invitations command.
All Chef Habitat Builder users can accept, ignore, and see invitations for their accounts.
View origin invitations:
Accept origin invitations:
Ignore origin invitations:
Send origin membership invitations:
Origin administrators and owners can see all pending origin membership invitations:
Origin administrators and owners can rescind an origin membership invitation:
Origin owners can transfer origin ownership to another member:
Manage membership roles with
You can use role based access control (RBAC) from the command line.
MEMBER_ACCOUNT is the name used to sign in to Chef Habitat builder. You can find the list of user names on an origin's Members Tab. (Builder > Origin > Members)
The RBAC command syntax is:
The syntax for the
show subcommand is:
See an origin member's RBAC role:
The syntax for the
set subcommand is:
Set an origin membership RBAC role with:
- Download the Chef Habitat CLI
- Create a Chef Habitat Builder account
- Generate a personal access token
- Create an origin with
hab origin createor join an origin by invitation
When you create an origin, Chef Habitat Builder automatically generates origin keys. Origin key cryptography is asymmetric: it has a public origin key that you can distribute freely, and a private origin key that you should distribute only to users belonging to the origin. All Chef Habitat Builder users with access to the origin can view the origin public key revisions in the origin key tab (Builder > Origin > Keys) and download the origin public key, but only users with the origin 'administrator' or 'owner' roles can view or download the origin private key, or change the origin key pair.
Chef Habitat uses origin keys:
- When you build an artifact in your local environment, Chef Habitat signs the artifact with a public key
- When you upload an artifact to Chef Habitat Builder or Builder on-prem, Chef Habitat verifies that the artifact was signed with its public key
- When you install an artifact on a Chef Habitat Supervisor, Chef Habitat uses the public origin key to authorize the artifact's installation; Chef Habitat only installs artifacts for which it has the public origin key
- When you download an artifact to your local environment, Chef Habitat uses the public origin key to verify the artifact's integrity before it starts the installation
Chef Habitat Builder origin key names follow the format:
For example, in:
- "testorigin" is the origin's name
- "20190416223046" is the date and time of the key's creation, which was 2019-04-16 22:30:46.
.pubis the file extension for the public key
.sig.keyis the file extension for the private key, which is also called a "signing key"
When you create an origin, Chef Habitat Builder automatically generates an origin key pair and saves both keys. To view your origin keys on Chef Habitat Builder, navigate to your origin and select the Keys tab. (Builder > Origins > Keys) You will always be able to view and download origin public keys, but you will only see the private keys for origins in which you are an "administrator" or "owner".
Download Origin Keys
Download your private or public origin key by selecting the download icon from the right end of the key details, under the Actions heading.
Upload Origin Keys
You can upload origin keys that you generate on the command line to Chef Habitat Builder by selecting either the Upload a private key or Upload a public key icon, and copy your key into the form that appears.
Run Chef Habitat CLI commands from your local environment or from within the Chef Habitat Studio.
See the CLI documentation for more information on the
hab origin key commands.
Find Your Local Origin Keys
Chef Habitat stores your public and private origin keys at
~/.hab/cache/keys on Linux systems,
C:\hab\cache\keys on Windows, and at
/hab/cache/keys inside of the Chef Habitat Studio environment.
To find your origin keys in your local environment:
On Linux or macOS:
To find your existing origin keys from inside of the Chef Habitat Studio:
On Linux or macOS:
Generate Origin Keys with the CLI
When you create an origin through the site, Chef Habitat Builder automatically generates an origin key pair.
The Chef Habitat CLI creates origin key pairs through two different commands, for two different uses:
hab setupto generate your first origin key pair as part of setting up the
- Use the
hab origin key generate <ORIGIN>command to create an key pair for an origin created with the
hab origin createcommand
Create origin keys with the
Download Origin Keys with the CLI
To get your public origin key using the command line, use:
Upload Origin Keys with the CLI
Creating an origin with the
hab origin create command registers the origin on Chef Habitat Builder without creating an origin key pair. The
hab origin key generate command creates the key pair and saves them in your local environment, but it does not upload either origin key to Chef Habitat Builder.
- Only "administrators" and "owners" can upload new keys to an origin.
- Builder requires the public origin key to upload artifacts for that origin, so you'll need to upload it.
- Builder requires the private origin key to enable new artifact builds from packages with plans linked to that origin.
Upload origin keys with the
Upload the origin private key:
Upload both origin keys at the same time:
Import Origin Keys with the CLI
hab origin key import to read the key from a standard input stream into Chef Habitat Builder:
Troubleshoot Origin Key Import
On a macOS, you may encounter an upload failure. To remediate this failure:
- Check that your
HAB_AUTH_TOKENenvironment variable is properly set and initialized
- Add your
SSL_CERT_FILEto the environment variables in your interactive shell configuration file, such as your
Initialize the setting from the command line with:
The Origin Settings tab contains:
- Default Package Settings
- Origin Secrets
Everyone with origin membership can see the Settings tab, but only origin administrators and owners can add, update, or delete settings content.
|Origin Secrets Actions|
The Default Package Settings define the visibility of build artifacts (.hart files). Everyone with origin membership can view the origin settings, but only origin administrators and owners can add, update, or delete settings.
- Public packages are visible in search results and can be used by every Chef Habitat Builder user
- Private artifacts do not appear in search results and are available only to users with origin membership
Change the default setting for the origin by switching from Public Packages to Private Packages. The default setting required for each origin and users with more than one origin can set some as public and others as private. Packages can have different default visibility settings than their origin's. Change the default visibility setting in for individual packages in that package's setting tab (Builder > Origin > Package > Settings).
Everyone with origin membership can view origin secrets, but only origin administrators and owners can add, update, or delete settings. Origin Secrets are located at the bottom of the Settings tab (Builder > Origin > Settings > Origin Secrets) and they let you encrypt and store secrets as environment variables. Origin secrets are useful for plans that require access to protected resources at build time, such as private source-code repositories and cloud storage providers.
Origin secrets are retained by the origin and are available for any of that origin's packages. The origin secrets in your local environment are encrypted with an origin encryption key. Only Chef Habitat Builder can read encrypted origin secrets.
Manage Origin Secrets with the Chef Habitat CLI
You can view the list of origin secrets and delete them in Chef Habitat Builder. However, the primary way of interacting with origin secrets is with the Chef Habitat CLI.
To list all of the secrets in an origin, use:
Set Origin Secrets as Environment Variables
Add your origin secrets as environment variables in your local environment:
Save an Origin Secret
To save an origin secret give the secret a name and the key value:
The output should similar to:
Delete an Origin Secret
To delete an origin secret from an origin with the CLI
See Using Origin Secrets in Plans for guidance on using origin secrets.
hab origin secret CLI documentation for more information on these commands.
Everyone with access to the origin can view origin packages, but only origin members, maintainers, administrators, and owners can upload packages to the 'unstable' channel Origin maintainers, administrators and owners can promote packages from the 'unstable' channel.
While you can build and run Chef Habitat packages without sharing them on Chef Habitat Builder, uploading them there enables greater collaboration and automated package rebuilds as underlying dependencies or your connected GitHub repository are updated.
Note: Chef Habitat Builder can only build Linux based plans (
plan.sh) at this time.
Setting up Chef Habitat Builder is easily done on the website: these steps take you through connecting your local Studio development experience with Builder.
You interact with Chef Habitat Builder by:
- Creating an account.
- Creating an origin, or being invited to join an origin that already exists.
- Setting up
habto authenticate with Builder.
- Uploading the private and public keys for that origin.
- Connecting your Github repositories and opting into rebuilds.
Chef Habitat Builder supports both public and private origins, packages, and Github repositories.
Create a Builder Account
If you haven't created an account yet, see the Create a Builder Account section above.
Create or Join an Existing Origin
You can create your own origin in Builder or be invited to join an existing one. If you already built some Chef Habitat packages on your local computer prior to signing up for an account, you must rename your local packages'
pkg_origin if the origin you want already exists.
Set up Chef Habitat to Authenticate to Builder
When you upload a package to Builder, you are required to supply an auth token as part of the
hab pkg upload subcommand. You can generate a Chef Habitat personal access token via the Builder site Profile page for use with the
hab command-line utility.
Once you have this token, you can set the
HAB_AUTH_TOKEN environment variable to this value, so that any commands requiring authentication will use it.
Create an Origin Key Pair
After finishing the basic account creation steps, you need to create your origin key pair. Habitat will use the private origin key to sign the artifacts (
.hart files) created by building your plan and verify the integrity of your artifacts with the public origin key.
You can create an origin key pair by running
hab cli setup from your host machine, or by running
hab origin key generate <ORIGIN> from either the host machine or from within the studio.
Your public and private origin keys are located at
~/.hab/cache/keys on your host machine and at
/hab/cache/keys inside the studio environment.
Upload Your Origin Keys
If you created a new Habitat origin from your host machine or from the Studio, Builder will not have either of the origin keys corresponding to your artifact. Builder will not accept uploaded artifacts without first having the correct origin public key.
You can upload keys for the origin through the web interface for Builder, or by using the
hab origin key upload command. You must have the access token for authentication, as described earlier, before you can upload keys.
Upload Packages to Builder
As long as you are already a member of the Habitat origin, once Builder possesses at least the public origin key, then you may upload one or more artifacts to that origin with the
hab pkg upload command. After Habitat validates the cryptographic integrity of the artifact, it is then uploaded and stored on Builder. Uploading artifacts is a privileged operation for which you must have the access token.
Chef Habitat supports continuous deployment workflows through the use of channels. A channel is a tag for a package that the Supervisors in a service group can subscribe to. Channels are useful in CI/CD scenarios where you want to gate a package before making it the default version of the package that users should consume. You can think of this split as the difference between test and production, or nightly releases versus stable releases of products.
By default, newly uploaded packages are placed in the
unstable channel. However, the default package that is downloaded is the latest
stable version of a package, unless overridden in commands such as
hab sup run,
hab svc load, and
hab pkg install. If you want to promote your package to the
stable channel, run the
hab pkg promote command as follows:
Note You can also promote packages to the
stablechannel using the promote to stable button in the web app.
For more information on how to use channels, see Continuous Deployment Using Channels.
Running Packages from Builder
Note: When running private packages from Builder, it's necessary to add your Chef Habitat access token to the machine where you intend to deploy the package, via
You can instruct the Supervisor to download and run packages from Builder by using the
hab sup and
hab svc commands, for example:
If the Supervisor does not have the
core/postgresql package in its local cache, it will contact Builder, retrieve the latest version and the public key for the
core origin, verify the cryptographic integrity of the package, and then start it.
You may also supply a
--channel argument to instruct the Supervisor to use a different channel for the purposes of continuous deployment:
Running Packages from Exported Tarballs
An exported tarball package contains the Chef Habitat client/binary as well as dependencies specified by your artifact.
After deploying the tarball to your target server, extract the contents to the root filesystem (
You can instruct the Supervisor to run packages from an exported tarball:
Note: On a clean server, this will download additional packages to satisfy the Supervisor dependencies. You will also require a
hab group and
hab user on the system for most services.
If you have a GitHub repository with multiple components inside, you will most likely also have individual plans for those components that are located inside of component subfolders. By default, Builder will only look for a package plan in either the root of the repository, or in a
habitat subfolder at the root. If it does not find a plan file in those locations, it will not automatically issue builds when it detects file changes in the repository.
In order to tell Builder about the location of the individual plan files, and in order provide more fine-grained control over when component packages are built, you can programmatically customize how and when Builder will build your plans by specifying build behavior in a
.bldr.toml file at the root of the repository that you connect to Builder.
Using this file, Builder only builds packages when source files or directories are updated in paths specified in
.bldr.toml. This allows you to configure the building, publishing, and post-processing phases of a plan build in Builder.
To enable this functionality, do the following:
.bldr.tomlin the root of your repository.
Open it and add an entry for each component package that you want to build.
.bldr.tomlfile is in TOML format, so create a TOML table specifying the
$pkg_namevalue for that plan and then add a
plan_pathfield specifying the path to your
plan.shfile (you do not need to include plan.sh explicitly in the path). If all the files related to the plan are under the plan path, then you are done. Otherwise, you will need an additional 'paths' field specifying Unix-style path globs to files that are associated with the plan you specified in the 'plan_path'. File or directory changes made in these path locations determine which packages will be rebuilt. Basically, when a file is committed, Builder will check to see whether it falls underneath the
plan_pathhierarchy, or matches one of the globs in the
pathsfield if it was specified - if the answer is yes, then Builder will issue a build for that commit.
It's important to note that the entries for
pathsdo not behave the same. If you have something like
plan_path = "habitat", that behaves as if you had written
plan_path = "habitat/*"- that is, it will automatically check every file under the
habitatdirectory. However, if you have something like
paths = [ "src" ], that is not automatically expanded to
src/*. That line will only watch for changes to a file called
src. If you're wanting to watch for changes to any file inside the
srcdirectory, then you must explicitly specify the glob, like so:
paths = [ "src/*" ].
For example, in the Chef Habitat repository itself, this TOML states that the
hab-suppackages will be rebuilt if there are any changes in any of the specified
componentssub-directories. Note that
hab-studiodoes not need to specify a
pathbecause all of it's files are within the
plan_pathhierarchy, but that is not the case for the other projects.
Notice that in order to specify that we're interested in all files inside of the directories in our
pathsentries, we had to add the
/*glob to the end manually.
It's also worth pointing out that there are multiple wildcard characters you can use when specifying path components.
?will match any single character.
*will match any (possibly empty) sequence of characters
**matches the current directory and arbitrary subdirectories. This sequence must form a single path component, so both
b**are invalid. More than two consecutive
*characters is also invalid.
[...]matches any character inside the brackets. You can also specify a range, such as
[0-9]to match any digit or
[a-z]to match any lowercase letter.
[!...]is the negation of
[...]so it will match any character not in the brackets.
Note that while the above set of rules bears a remarkable resemblance to regular expressions, we do not support full regular expression syntax. Only what's shown here is supported. Here is an example.
By connecting a plan file in Chef Habitat Builder, you can trigger both manual (via the web UI, or via the
hab command line) as well as automated package rebuilds whenever a change is merged into the
master branch of the repository containing your Chef Habitat plan, or when a dependent package updates (rebuilds).
Connect a Plan
To connect a plan to Builder, view one of your origins (while signed in), click the Connect a plan file button, and complete the following steps:
- Install the Builder GitHub App
- Choose the GitHub organization and repository containing your Chef Habitat plan
- Choose a privacy setting for the package
- Specify container-registry publishing settings (optional)
- Specify auto-build option (default is off)
The auto-build option controls whether or not your package will get automatically re-built. This option is a useful capability to have - for example, if you have a demo app that doesn’t need to be kept constantly up to date when some underlying dependency updates. Auto-build encompasses both builds that are triggered by Github web hooks (on commits to master), as well as builds that are triggered by a dependency updating.
By default, new plan connections will have auto-build turned off.