Understanding Drafts

Understand how Drafts help your prepare changes for deployment

What is a Draft?

A Draft in Humanitec is a set of proposed changes to an App. You can use a Draft to collect together all of the changes you want to make before you make a new deployment of your App into an Environment.

When a draft is deployed, the changes in the draft are applied to what is currently deployed to the Environment. This means that your draft will usually remain valid even if another developer has made a deployment to the environment between you creating your draft and deploying it. As long as the changes in the first draft don't conflict with the second (for example the first draft removes an item which needs to be updated by the second draft,) the second deployment will succeed and apply the changes you had in your draft. This is similar to how patches can be applied to a code base. Multiple patches can be applied as long as they do not conflict with each other.

You can think of a Draft as a place you can make edits. A draft is effectively a list of your edits.

Creating a new Draft

UI
CLI
API
UI

The Humanitec UI ensures that there is always a Draft available for you to start working with. This Draft will have the name Untitled Draft. This means you only need to create a new Draft if you wish to work on an additional set of edits that you wish to deploy independently.

  1. Start in the App Details Screen

  2. Make sure you have selected the Environment you want to add the draft to from the Environment Tabs.

  3. Click the button on the current Draft.

  4. Select "Create new draft" from the menu that appears.

Steps to create a new Draft in the UI

In the UI you can only see your currently active draft at one time. You can switch between Drafts to view your other Drafts.

CLI

Our CLI is currently in closed beta. Please contact us if you want to learn more.

API

Drafts as a concept only exist in the UI and CLI. They are actually just Deployment Deltas which are assigned to a particular environment.

To create a Draft via the API, create a new Delta and set the Environment.

Rename a Draft

If you are working on more than one Draft at a time or you are collaborating on a Draft it can be useful to give a Draft a name. This will help you or your colleague locate the draft in future.

UI
CLI
API
UI
  1. Start in the App Details Screen

  2. Click the button on the current Draft.

  3. Select "Rename draft" from the menu that appears.

Steps to rename a Draft in the UI

CLI

Our CLI is currently in closed beta. Please contact us if you want to learn more.

API

Drafts as a concept only exist in the UI and CLI. They are actually just Deployment Deltas which are assigned to a particular environment.

To rename a draft via the API, you can update the Name.

Switch between Drafts

UI
CLI
API
UI

The Humanitec UI only allows you to work on one Draft at a time. You can change the active Draft you are working on by switching Drafts.

  1. Start in the App Details Screen

  2. Click the button on the current Draft.

  3. Select "Switch drafts" from the menu that appears.

  4. Select the Draft to switch to from the list that appears.

Steps to switch between Drafts
CLI

Our CLI is currently in closed beta. Please contact us if you want to learn more.

API

There is no concept of an "Active Draft" in the API.

Discard a Draft

If you no longer plan to deploy the edits you made in a Draft, you can discard the draft. This will remove the draft from the list of drafts you can switch to.

UI
CLI
API
UI

  1. Start in the App Details Screen

  2. Click the button on the current Draft.

  3. Select "Discard draft" from the menu that appears.

Steps to discard a Draft in the UI

You cannot discard the last remaining Draft in an Environment. To discard the last draft: create a new draft, switch to the old draft and then discard it.

CLI

Our CLI is currently in closed beta. Please contact us if you want to learn more.

API

Discarding a Draft is the equivalent of marking a Delta as archived.