Labeling Cloud Foundry API resources with a git SHA

By: | March 15, 2019


This post was written by the CAPI Product team.


Recently the Cloud Foundry API added the ability to add metadata to a given resource. The metadata feature allows users to add both labels and annotations to their Cloud Foundry resources. One interesting use case is to label your app and related resources with a git commit SHA. This allows you to track which version of your code is running on Cloud Foundry.

When you push an app to Cloud Foundry, the files you push are stored in a resource called a package. Packages are an input into the staging process, along with buildpacks, the output of which is a droplet.

Tracking the version of your code through these various resources can be difficult, so it may help to label them.



The first step is to get the git commit SHA:

git rev-parse --short HEAD


Then, we need to find the GUIDs of the resource we want to label. Here, we’ll label the app, package, and droplet.

To get the app’s guid:

cf app <APP_NAME> --guid


The Cloud Foundry CLI does not yet support labels, so we’ll have to access the Cloud Foundry API directly. Luckily, the Cloud Foundry CLI does include a curl command that takes care of authentication and targeting the appropriate API endpoint.

To get the guid of the current droplet associated with the app:

cf curl "/v3/apps/${APP_GUID}/droplets/current" | jq -r .guid


Droplets are built from packages, so to get the package guid associated with your droplet:

cf curl "/v3/droplets/${DROPLET_GUID}" | jq -r .links.package.href | xargs basename


To add a label to a resource, you must submit a PATCH request. All of the bodies will be the same for each resource, so we can construct it:

jq -nc --arg commit "${COMMIT_SHA}" '{"metadata": { "labels": { "commit": $commit } } }'


Then, PATCH against, say, the app:

cf curl /v3/apps/${APP_GUID} -X PATCH -d "${REQUEST_BODY}"


Once you have labeled the resources, you can then query the Cloud Foundry API using the label_selector query parameter. Here is an example of finding apps with the commit SHA:

cf curl "/v3/apps?label_selector=commit=${COMMIT_SHA}"


This should return all apps that have been tagged with our commit SHA. You can swap out apps for packages and droplets to see those tagged resources.

Here is a script that, when run from the repository of your app, will tag the app, droplet, and package with the commit SHA:

#!/usr/bin/env bash
# Run this from your app's git repo
set -ex
APP_GUID="$(cf app dora --guid)"
DROPLET_GUID="$(cf curl "/v3/apps/${APP_GUID}/droplets/current" | jq -r .guid)"
PACKAGE_GUID="$(cf curl "/v3/droplets/${DROPLET_GUID}" | jq -r .links.package.href | xargs basename)"
# Get a short version of your git SHA
COMMIT_SHA="$(git rev-parse --short HEAD)"
REQUEST_BODY="$(jq -nc --arg commit "${COMMIT_SHA}" '{"metadata": { "labels": { "commit": $commit } } }')"
# Label the app, package, and droplet with the code's current commit SHA.
cf curl "${APP_URI}" -X PATCH -d "${REQUEST_BODY}"
cf curl "${PACKAGE_URI}" -X PATCH -d "${REQUEST_BODY}"
cf curl "${DROPLET_URI}" -X PATCH -d "${REQUEST_BODY}"

Now you are ready to begin labeling your app, package and droplet resources with your git commit SHA to help you better understand what code is running on Cloud Foundry.  This is just one use case for using metadata, but there are many more. We look forward to seeing how the community adopts this new feature and as always, if you have questions or feedback, you can reach the team on the Cloud Foundry Slack under the

#capi channel.

Caitlyn O'Connell Profile Image

Caitlyn O'Connell, AUTHOR

As Senior Marketing Manager of Cloud Foundry Foundation, Caitlyn runs content and manages diversity programming.