revisions.html.md.erb

---
title: Cloud Foundry API app revisions
owner: CAPI
---

A revision represents code and configuration used by an app at a specific time. It is a Cloud Foundry API (CAPI) object that can contain references to a droplet, a custom start command, and environment variables. The most recent revision for a running app represents code and configuration running in <%= vars.platform_name %>.
App revisions do not include any tasks run on the app.

For additional information about app revisions, see [Revisions](http://v3-apidocs.cloudfoundry.org/version/release-candidate/#revisions) in the Cloud Foundry API (CAPI) documentation.

<p class="note important">
CAPI v3 is the recommended API version for revisions. While revisions work with CAPI v2, there are several inconsistencies. For example, revision descriptions for apps with multiple processes can be inaccurate because CAPI v2 does not support apps with multiple processes. Additionally, pushing an app for the first time with revisions in CAPI v2 creates two revisions.</p>

<p class="note caution">
The app revisions API is experimental, and future releases might have breaking changes.</p>

## <a id="overview"></a> Revisions use cases

Some use cases for revisions include:

* **Viewing revisions for an app:** This can help you understand how your app has changed over time.

* **Rolling back to a previous revision:** This allows you to deploy a version of the app that you had running previously without needing to track that previous state yourself or have multiple apps running. When you create a deployment and reference a revision, the revision deploys as the current version of your app.

### <a id="events"></a> Events that trigger revisions

Revisions are generated through these events:

* A new droplet is deployed for an app.
* An app is deployed with new environment variables.
* An app is deployed with a new or changed custom start command.
* An app rolls back to a prior revision.

By default, CAPI retains a maximum of 100 revisions per app.

### <a id="revision-description"></a> Revision descriptions

Each revision includes a description of what changed in your app at the time the revision was created. The description includes one or more of these descriptions:

* `Process type removed`
* `New process type added`
* `Rolled back to revision X`
* `Custom start command removed`
* `Custom start command updated`
* `Custom start command added`
* `New environment variables deployed`
* `New droplet deployed`

### <a id="droplets"></a> Droplet storage considerations

By default, <%= vars.platform_name %> retains the five most recent staged droplets in its droplets bucket. This means that you can roll back to revisions as long as they are using one of those five droplets. Not all revisions include a change in droplet.

<% if vars.platform_code == "CF" || vars.platform_code == "PCF" %>
Operators can configure <%= vars.platform_name %> to retain more droplets if necessary using the <%= vars.droplet_config %>
<% end %>


## <a id="view"></a> View revisions

This section describes how to use CAPI endpoints for viewing revisions.

### <a id="list"></a> List revisions for an app

To list revisions for an app:

* Using the `revisions` command:
	 
	```
	cf revisions APP-NAME
	```
	Where `APP-NAME` is the name of your app.

* Using the `curl` command
	
	1. Retrieve the GUID of the app by running:

		```
		cf app APP-NAME --guid
		```
		Where `APP-NAME` is the name of your app.

	1. Run:

		```
		cf curl /v3/apps/GUID/revisions
		```
		Where `GUID` is the GUID you retrieved in an earlier step.

### <a id="list-deployed"></a> List deployed revisions for an app

Deployed revisions are revisions linked to started processes in an app. To list deployed revisions:

* Using the `revision` command:

	```
	cf revision APP-NAME
	```
	Where `APP-NAME` is the name of your app.

* Using the `curl` command

	1. Retrieve the GUID of the app by running:

		```
		cf app APP-NAME --guid
		```
		Where `APP-NAME` is the name of your app.

	1. Run:

		```
		cf curl /v3/apps/GUID/revisions/deployed
		```
		Where `GUID` is the GUID you retrieved in an earlier step.

### <a id="get"></a> Retrieve a revision

To retrieve a revision:

* Using the `revision` command:

	```
	cf revision APP-NAME --version VERSION
	```
	Where `APP-NAME` is the name of your APP and `VERSION` is the revision version.

* Using the `curl` command:

	1. Run:

	```
	cf curl /v3/revisions/GUID
	```
	Where `GUID` is the GUID of the revision.


## <a id="push-app"></a> Roll back to a previous revision

To roll back to a previous revision:

* Using the `rollback` command:

	```
	cf rollback APP-NAME --version VERSION
	```
	Where `APP-NAME` is the name of your APP and `VERSION` is the revision version you want to rollback to.

* Using `curl` command:

	1. Retrieve the GUID of the app:

			```
			cf app APP-NAME --guid
			```
			Where `APP-NAME` is the name of your app.

	1. Retrieve the GUID of the revision. See [Retrieve a revision](#get).

	1. Create a deployment using CAPI by running:

	    ```
	    cf curl v3/deployments \
	    -X POST \
	    -d '{
	      "revision": {
	        "guid": "REVISION-GUID"
	      },
	      "relationships": {
	        "app": {
	          "data": {
	            "guid": "APP-GUID"
	          }
	        }
	      }
	    }'
	    ```

	    Where:
	    <ul>
	      <li><code>REVISION-GUID</code> is the GUID of the revision.</li>
	      <li><code>APP-GUID</code> is the GUID of the app.</li>
	    </ul>

## <a id="metadata"></a> Add metadata to a revision

<% if vars.platform_code == "CF" || vars.platform_code == "PCF" %>

To add metadata to a revision, see [Add metadata to an object](../adminguide/metadata.html).
<% else %>
To add metadata to a revision, see [Cloud Foundry documentation](https://docs.cloudfoundry.org/adminguide/metadata.html).
<% end %>

## <a id="disable"></a> Deactivate revisions for an app

CAPI activates app revisions by default. To deactivate revisions for an app, you must manually turn them off.

To deactivate revisions for an app:

1. Retrieve the GUID of the app by running:

	```
	cf app APP-NAME --guid
	```
	Where `APP-NAME` is the name of your app.

1. Run:

	```
	cf curl /v3/apps/GUID/features/revisions -X PATCH -d '{ "enabled": false }'
	```
	Where `GUID` is the GUID you retrieved in an earlier step.