Using the Pivotal Build Service CLI

Log In to Build Service
Manage Projects
Manage Images

Page last updated:

This topic describes how to use the Pivotal Build Service CLI, pb, to log in to Build Service and manage images, projects, and builds.

Log In to Build Service

After you configure and install Build Service, you can use the pb CLI to target and log in to your Build Service installation.

For more information, see Installing and Configuring Build Service.

To target your Build Service installation and log in:

Target the API for your Build Service installation by running:
```
pb api set YOUR-BUILD-SERVICE-API
```
Where YOUR-BUILD-SERVICE-API is the URL for the API for your Build Service installation. For example, https://build-service.example.com.
Note: Use the --skip-ssl-validation flag if your Build Service installation targets a UAA that has a self-signed CA cert.
Confirm that you targeted the correct Build Service installation by running:
```
pb api get
```
Log in to Build Service by running:
```
pb login
```
When prompted, enter the username and password for UAA.

You can also pass your username and password to Build Service by specifying the environment variables BUILD_SERVICE_USERNAME and BUILD_SERVICE_PASSWORD. The CLI defaults to using them if they exist in the environment.

Manage Projects

The following procedures describe how to manage projects and project members with the pb CLI.

A project is a Build Service entity that uses UAA to provide user access control to images, image configurations, and image builders. For more information, see Build Service Projects.

Create a Project

To create a new project:

Run:
```
pb project create PROJECT-NAME
```
Where PROJECT-NAME is a unique name for the project.

Targeting a Project

Projects map to Kubernetes namespaces. Because of this, you should not create projects with the same name as pre-existing Kubernetes namespaces.

The user who creates the project is added to the project as its first member. Because of this, you cannot access resources produced by Build Service globally across all the namespaces in the cluster.

To target your project:

Run:
```
pb project target PROJECT-NAME
```
Where PROJECT-NAME is the name of your project.

After you have targeted a project, Build Service assumes that the commands you run are for that project.

In order to target a different project, run the command again and specify a different project.

Add and Remove Project Members

All members of a project can add and remove project members.

Add Members to a Project

To add members to a project:

Target your project.
Run:
```
pb project user add UAA-USERNAME
```
Where UAA-USERNAME is the username of the user you want to add.

Remove Members from a Project

To remove members from a project:

Target your project.
Run:
```
pb project user remove UAA-USERNAME
```
Where UAA-USERNAME is the username of the user you want to remove.

Manage Image Registries for a Project

For a project to use an image registry in Build Service, you must associate an image registry and the image registry credentials with the project. If the source code for the image is saved in a repository, you must also associate the Git credentials with the project.

Build Service uses these credentials to deliver container image builds to the specified registry.

Note: The registry credentials must belong to a user with write access on the registry.

Build Service supports the following image registries:

Docker Hub
GCR
Harbor
Artifactory

Associate an Image Registry with a Project

To associate an image registry and image registry credentials with a project:

Target the project with which you want to associate the image by running:
```
pb project target PROJECT-NAME
```
Where PROJECT-NAME is the name of the project that owns the image.
Create a YAML file with the image registry location and credentials. Enter the following variables:
```
registry: REGISTRY-DOMAIN
username: REGISTRY-USERNAME
password: REGISTRY-PASSWORD
```
Where:
- REGISTRY-DOMAIN is the domain for the registry. Use the following guidance to complete the registry field, depending on your image registry:
  - Docker Hub: Enter index.docker.io.
  - GCR: Enter gcr.io.
  - Harbor: Enter the domain that is specific to your deployment of the registry.
  - Artifactory: Enter the domain that is specific to your deployment of the registry
- REGISTRY-USERNAME and REGISTRY-PASSWORD are the username and password of the image registry, respectively. You can include only one password for an image registry in the credentials YAML file.
Apply the image registry YAML file by running:
```
pb secrets registry apply -f PATH-TO-REGISTRY-CREDENTIALS-YAML
```
Where PATH-TO-REGISTRY-CREDENTIALS-YAML is the local path to the YAML file that you created in the previous step.

Change Image Registry Association and Credentials

To update the registry association and credentials for a project:

Modify the variables in your image registry YAML file.
- To change the project the registry is associated with, modify project.
- To change the registry associated with the project, modify registry.
- To change the credentials for the registry, modify username and password.
Apply the image registry file by running:
```
pb secrets registry apply -f PATH-TO-REGISTRY-CREDENTIALS-YAML
```
Where PATH-TO-REGISTRY-CREDENTIALS-YAML is the local path to the YAML file that you created in the previous section.

Manage Git Repositories for a Project

To allow Build Service to execute builds against app source code in a private Git repository, you must add the Git username and password to the project that manages the source code.

As you apply YAML files that associate a Git repository and Git repository credentials with a project, the pb CLI provides feedback indicating whether or not the commands succeeded.

Associate a Git Repository with a Project

To associate a Git repository and Git repository credentials with a project:

Note: If your git repository uses an access token, you can specify the token in the below password field. For more information, see Creating a personal access token for the command line in the GitHub documentation.

Create a YAML file with the Git repository location and credentials. Enter the following variables:
```
repository: GIT-REPOSITORY
username: GIT-USERNAME
password: GIT-PASSWORD/TOKEN
```
Where:
- GIT-REPOSITORY is the URL of the GitHub repository.
- GIT-USERNAME is the Git username used to access the GitHub repository.
- GIT-PASSWORD/TOKEN is the password or access token used to access the GitHub repository.
Apply the Git repository file to the project by running:
```
pb secrets git apply -f PATH-TO-REPOSITORY-CREDENTIALS-YAML-FILE
```
Where PATH-TO-REPOSITORY-CREDENTIALS-YAML-FILE is the local path to the YAML file that you created in the previous step.

Change Git Repository Association and Credentials

To update the Git repository and credentials for a project:

Modify the variables in your Git repository YAML file.
- To change the Git repository associated with the project, modify repository.
- To change the credentials for the Git repository, modify username and password.
Apply the Git repository credentials file by running:
```
pb secrets git apply -f PATH-TO-REPOSITORY-CREDENTIALS-YAML-FILE
```
Where PATH-TO-REPOSITORY-CREDENTIALS-YAML-FILE is the local path to the YAML file that you created in the previous step.

Delete Git Repository Credentials from a Project

To delete Git credentials from a project:

Run:
```
pb secrets git delete github.com
```

Delete a Project

This procedure describes how to delete a project using the pb CLI.

Warning: If you delete a project, all registry credentials and Git secrets associated with that project are also deleted.

To delete a project:

Delete all image configurations in Build Service that are owned by the project. You cannot delete a project if the project owns any images on Build Service. To delete image configurations, see Delete an Image.
Run:
```
pb project delete PROJECT-NAME
```
Where PROJECT-NAME is the name of the project to delete.

Manage Images

The following procedures describe how to create and manage images in Build Service.

Image Configurations

To create an image, you must create an image configuration YAML that includes the following properties:

source: Defines the Git location of the code that the image is built against. The revision can be either a branch, tag or a commit sha. When you target the image against a branch, Build Service triggers a build for every new commit.
build: Defines additional configuration for your app such as buildpack version numbers.
- Includes an env property that supplies values to the build by setting environment variables.
- Each env environment variable is an object with a name and a value, for example BP_JAVA_VERSION and 8.*.
image: Defines the destination registry of the builds for the image. You must specify the credentials for the target registry in the registries section of the project configuration. For more information, see Manage Image Registries for a Project. The value for image must match the domain of one of the registries that you provided in the project configuration. Build Service uses the value of image.tag to refer to the image after it is created. If you update the image tag, Build Service creates a new image.

For more information about creating and applying image configurations for apps with source code in GitHub or source code saved locally, see Apply Image Configurations.

Apply Image Configurations

Build Service supports builds against apps with source code that is saved in a Git repository or saved on your local machine. You can specify only one location for app source code.

The procedures in this section describe how to apply image configurations in Build Service that have source code saved in a Git repository or source code saved locally.

Apply an Image With Source Code in a Git Repository

To apply an image configuration to Build Service:

Create an image configuration YAML file. For example:
```
source:
  git:
    url: https://github.com/PATH-TO-EXAMPLE-APP
    revision: main
build:
  env:
  - name: ENV-NAME
    value: ENV-VALUE
image:
  tag: REGISTRY-DOMAIN/PATH-TO-EXAMPLE-APP-IMAGE
```
Where:
- PATH-TO-EXAMPLE-APP is the path to an app on GitHub.
- ENV-NAME is the name of your build environment.
- ENV-VALUE is the value of your build environment.
- REGISTRY-DOMAIN is the domain for the registry. Use the following guidance to complete the registry field, depending on your image registry:
  - Docker Hub: Enter index.docker.io.
  - GCR: Enter gcr.io.
  - Harbor: Enter the domain that is specific to your deployment of the registry.
  - Artifactory: Enter the domain that is specific to your deployment of the registry
- PATH-TO-EXAMPLE-APP-IMAGE is the local path to the image registry.
Apply the image configuration by running:
```
pb image apply -f PATH-TO-IMAGE-CONFIGURATION
```
Where PATH-TO-IMAGE-CONFIGURATION is the local path where you saved the image configuration YAML file.

Apply an Image With Local Source Code

To apply an image configuration that uses local source code:

Create an image configuration file that has no Git properties. For example:
```
build:
  env:
  - name: ENV-NAME
    value: ENV-VALUE
image:
  tag: REGISTRY-DOMAIN/PATH-TO-EXAMPLE-APP
```
Where:
- PATH-TO-EXAMPLE-APP is the local path to an app.
- ENV-NAME is the name of your build environment.
- ENV-VALUE is the value of your build environment.
- REGISTRY-DOMAIN is the domain for the registry. Use the following guidance to complete the registry field, depending on your image registry:
  - Docker Hub: Enter index.docker.io.
  - GCR: Enter gcr.io.
  - Harbor: Enter the domain that is specific to your deployment of the registry.
  - Artifactory: Enter the domain that is specific to your deployment of the registry
Apply the image configuration by running:
```
pb image apply -f /PATH-TO-IMAGE-CONFIGURATION/IMAGE-CONFIGURATION.yaml -p /PATH-TO-APP-DIRECTORY
```
Where:
- PATH-TO-IMAGE-CONFIGURATION is the local path to the image configuration YAML file.
- IMAGE-CONFIGURATION is the name of the image configuration YAML file.
- PATH-TO-APP-DIRECTORY is the local path to the app directory.

Apply an Image With Source Code In A Blob Store

To apply an image and reference source code that lives in a blobstore:

Create an image configuration file that has no Git properties. For example:
```
build:
  source:
    blob:
      url: https://storage.blob.com/my-org/myapp.jar
  env:
  - name: ENV-NAME
    value: ENV-VALUE
image:
  tag: REGISTRY-DOMAIN/PATH-TO-EXAMPLE-APP
```
Where:
- PATH-TO-EXAMPLE-APP is the local path to an app.
- ENV-NAME is the name of your build environment.
- ENV-VALUE is the value of your build environment.
- REGISTRY-DOMAIN is the domain for the registry. Use the following guidance to complete the registry field, depending on your image registry:
  - Docker Hub: Enter index.docker.io.
  - GCR: Enter gcr.io.
  - Harbor: Enter the domain that is specific to your deployment of the registry.
  - Artifactory: Enter the domain that is specific to your deployment of the registry
Apply the image configuration by running:
```
pb image apply -f /PATH-TO-IMAGE-CONFIGURATION/IMAGE-CONFIGURATION.yaml
```
Where:
- PATH-TO-IMAGE-CONFIGURATION is the local path to the image configuration YAML file.
- IMAGE-CONFIGURATION is the name of the image configuration YAML file.

Note: Build Service v0.0.4 does not support polling functionality for source code that is stored in a blobstore. When you push new source code to the specified blobstore URL, Build Service cannot rebuild your app.

List Images

To list all the image configurations for the currently targeted project:

Run:
```
pb image list
```

The following is an example of the output for this command:

Project: some-project

Images
------
first/image:tag
second/image:tag
third/image:tag

Image Rebuilds

Rebuilds happen in two ways. An imperative rebuild occurs when you make edits to the image configuration and run pb image apply. An automatic rebuild occurs when build inputs change, without you editing the image configuration itself.

You can initiate an imperative rebuild in these ways:

You update the commit, branch, Git repository, or build fields on the image’s configuration file and re-apply it by running pb image apply.
You upload a new copy of the local source code by running pb image apply -p PATH-TO-SOURCE, where PATH-TO-SOURCE is the source code path.

For more information, see Apply Image Configurations.

Build Service auto-rebuilds images when one or more of the following build inputs change:

New buildpack versions are made available through an updated builder image.
- The Build Service Bundle on Pivotal Network includes the latest buildpacks contained in a builder image.
- When upgrading PBS, you must relocate new buildpack versions over to your container registry.
There is a new commit on a branch or tag Build Service is tracking.
There is a new base OS image available, such as cflinuxfs3.

Monitor Builds for an Image

The procedures in this section describe how to view information and logs for image builds.

Build Service stores the ten most recent successful builds and the ten most recent failed builds.

To view logs for a build, you must provide the build number. You cannot view logs for a build by referencing the image digest.

View All Builds for an Image

To list all the builds created for an image:

Run:
```
pb image builds IMAGE-TAG
```
Where IMAGE-TAG is the value of the field image.tag in the image configuration YAML file.

The following is an example of the output for this command:

Build    Status    Started Time           Finished Time          Reason    Digest
-----    ------    ------------           -------------          ------    ------
    1    SUCCESS   2019-09-09 21:55:27    2019-07-08 21:55:54    CONFIG    *************************************************
    2    SUCCESS   2019-09-09 21:56:55    2019-07-08 21:57:40    COMMIT    *************************************************
    3    SUCCESS   2019-09-09 21:57:55    2019-07-08 21:58:40    STACK     *************************************************
    4    FAILED    2019-09-09 21:58:55    2019-07-08 21:59:40    CONFIG+   --
    5    BUILDING  2019-09-09 21:59:55    --                     BUILDER   --
    -    PENDING   --                     --                     UNKNOWN   --

The following describes the fields in the example output:

Build: Describes the index of builds in the order that they were built.
Status: Describes the status of a previous or pending build image.
Started Time: Describes when a build started.
Finished Time: Describes when a build finished.
Reason: Describes why an image rebuild occured. These reasons include:
- CONFIG: Occurs when a change is made to commit, branch, Git repository, or build fields on the image’s configuration file and you run pb image apply.
- COMMIT: Occurs when new source code is committed to a branch or tag build service is monitoring for changes.
- BUILDER: Occurs when new buildpack versions are made available through an updated builder image.
  Note: A rebuild can occur for more than one reason. When there are multiple reasons for a rebuild, the pb CLI output shows the primary Reason and appends a + sign to the Reason field. The priority rank for the Reason, from highest to lowest, is CONFIG, COMMIT, and BUILDER.
- STACK: Occurs when a new base OS image, called a run image, is available.
Digest: Contains the SHA256 of the successfully built image. You can reference this SHA to run Docker commands such as pull and inspect.

View Build Details for an Image

To display detailed information about a build:

Run:
```
pb image build IMAGE-TAG -b BUILD-NUMBER
```
Where:
- IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.
- BUILD-NUMBER is the number of the build you want to inspect.

The following is an example of the output for this command:

------------------
Retrieving information for image "gcr.io/myapp" - build 1
------------------
STATUS
     Status:     SUCCESS
     Reasons:    Config
     Image:      gcr.io/myapp@sha256:f87b614257af05c3301c1554c4f15131793caec3adf55e45d2c612e90445765a
------------------
BUILD DETAILS
     Run Image:  cloudfoundry/cnb:run@sha256:asdas098asdas
     Builder:    cloudfoundry/cnb:bionic@sha256:grtewwads0asdvf09asdf

     Source:
         Git:        http://github.com/myapp
         Revision:   ad123ad
     Buildpacks:
         Id:         io.java.etc
         Version:    123

         Id:         io.kotlin.etc
         Version:    321

------------------

The following describes the fields in the example output:

Status: Describes the status of a previous or pending build image.
Reason: Describes why an image rebuild occured. These reasons include:
- CONFIG: Occurs when a change is made to commit, branch, Git repository, or build fields on the image’s configuration file and you run pb image apply.
- COMMIT: Occurs when new source code is committed to a branch or tag build service is monitoring for changes.
- BUILDER: Occurs when new buildpack versions are made available through an updated builder image.
  Note: A rebuild can occur for more than one reason. When there are multiple reasons for a rebuild, the pb CLI output shows the primary Reason and appends a + sign to the Reason field. The priority rank for the Reason, from highest to lowest, is CONFIG, COMMIT, and BUILDER.
- STACK: Occurs when a new base OS image (called a run image) is available.
Image: The full image tag for the app image produced by the build.
Run Image: The full image tag for the run image used by the app.
Builder: The full image tag for the builder image used by the build.
Source: This field contains one of the following:
- For a build created from a Git commit:
  - Git: The Git repository URL.
  - Revision: The commit SHA.
- For a build created from local source code:
  - Local Source: Indicates that the source code was pushed from a development workstation.
- For a build created from a blob:
  - Blob: The blob URL.
Buildpacks: A list of buildpacks the build used.

View Logs for a Build

To view logs for a build:

Run:
```
pb image logs IMAGE-TAG -b BUILD-NUMBER
```
Where:
- IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.
- BUILD-NUMBER is the number of the build with the logs you want to view.

The following is an example of the output of the command:

[build-step-credential-initializer] {"level":"info","ts":1562684107.3441668,"logger":"fallback-logger","caller":"creds-init/main.go:40","msg":"Credentials initialized.","commit":"002a41a"}
[build-step-credential-initializer]
[build-step-git-source-0] git-init:main.go:81: Successfully cloned "https://github.com/buildpack/sample-java-app" @ "abde24efc17802b7e2b3814e0ead63a460e66f5f" in path "/workspace"
[build-step-git-source-0]
[build-step-prepare]
[build-step-detect] Trying group 1 out of 3 with 27 buildpacks...
[build-step-detect] ======== Results ========
[build-step-detect] skip: Cloud Foundry Archive Expanding Buildpack
[build-step-detect] pass: Pivotal OpenJDK Buildpack
[build-step-detect] pass: Pivotal Build System Buildpack
[build-step-detect] pass: Cloud Foundry Spring Boot Buildpack
[build-step-detect] pass: Cloud Foundry Apache Tomcat Buildpack
...
[build-step-detect] skip: Cloud Foundry JMX Buildpack
[build-step-detect] pass: Cloud Foundry Spring Auto-reconfiguration Buildpack
[build-step-detect]
[build-step-restore] Restoring cached layer 'io.pivotal.openjdk:openjdk-jdk'
...
[build-step-restore] Restoring cached layer 'org.cloudfoundry.springboot:spring-boot'
[build-step-restore]
[build-step-analyze] Analyzing image 'registry.com/sample/demo@sha256:8ff708081ee10f7039f77275f1e6eb6359cae8d90028c79a5c493ced0dc63f68'
[build-step-analyze] Using cached layer 'io.pivotal.openjdk:openjdk-jdk'
...
[build-step-analyze] Rewriting metadata for layer 'org.cloudfoundry.springboot:spring-boot'
[build-step-analyze] Writing metadata for uncached layer 'io.pivotal.clientcertificatemapper:client-certificate-mapper'
[build-step-analyze] Writing metadata for uncached layer 'org.cloudfoundry.springautoreconfiguration:auto-reconfiguration'
[build-step-analyze]
[build-step-build]
[build-step-build] Pivotal OpenJDK Buildpack 1.0.0-M9
[build-step-build]   OpenJDK JDK 11.0.3: Reusing cached layer
[build-step-build]   OpenJDK JRE 11.0.3: Reusing cached layer
[build-step-build]   JVMKill Agent 1.16.0: Reusing cached layer
[build-step-build]   Class Counter 1.0.0-M9: Reusing cached layer
[build-step-build]   Memory Calculator 4.0.0: Reusing cached layer
[build-step-build]
...
[build-step-build]     task:        java -cp $CLASSPATH $JAVA_OPTS io.buildpacks.example.sample.SampleApplication
[build-step-build]     web:         java -cp $CLASSPATH $JAVA_OPTS io.buildpacks.example.sample.SampleApplication
[build-step-build]
[build-step-build] Pivotal Client Certificate Mapper Buildpack 1.0.0-M9
[build-step-build] Cloud Foundry Spring Auto-reconfiguration Buildpack 1.0.0-M9
[build-step-build]   Spring Auto-reconfiguration 2.7.0: Reusing cached layer
[build-step-build]
[build-step-export] Reusing layers from image 'index.docker.io/matthewmcnew/demo@sha256:8ff708081ee10f7039f77275f1e6eb6359cae8d90028c79a5c493ced0dc63f68'
[build-step-export] Reusing layer 'app' with SHA sha256:02e0070ce11bac1829174ec1296dcb1f3f04a4c30a958e2c41ad5498f78898fe
...
[build-step-export] Reusing layer 'org.cloudfoundry.springautoreconfiguration:auto-reconfiguration' with SHA sha256:93d94baf6d0dfc4981eb7d8ddfc4ae51f5c13cf87789b64ae8c4b015318a1b43
[build-step-export] *** Images:
[build-step-export]       registry.com/sample/demo:latest - succeeded
[build-step-export]       registry.com/sample/demo:b2.20190709.145448 - succeeded
[build-step-export]
[build-step-export] *** Digest: sha256:48a4ca8e4d8e8a9af26437588d0ce0e9d5c09b53aeb3ef64230a3d58d4b0dc90
[build-step-export]
[build-step-cache] Reusing layer 'io.pivotal.openjdk:openjdk-jdk' with SHA sha256:5554c7c06a266eb44a7cbdf0ecfaa14070e21af2b0bdfd1edd3b96f5168cd511
[build-step-cache] Reusing layer 'io.pivotal.buildsystem:build-system-cache' with SHA sha256:3b03fdd870a2dc1e924a040b604c25b76efafc1324ceb08eae8eae686fc3a940
...
[build-step-cache] Reusing layer 'org.cloudfoundry.springboot:spring-boot' with SHA sha256:effa8b80729cafa9f9a01b21a4badb5203510de0bb2e6b309ffd2593b0a28de7
[build-step-cache]

View Logs for a Running Build

You can stream logs that show the progress of a build. The logs terminate when the build completes.

To view logs for a running build:

Run:
```
pb image logs IMAGE-TAG -b BUILD-NUMBER -f
```
Where:
- IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.
- BUILD-NUMBER is the number of the build with the logs you want to view.

Delete an Image

This procedure describes how to delete a Build Service image.

Warning: Deleting an image also deletes all the builds that the image owns. It does not delete the images generated by those builds.

To delete an image:

Run:
```
pb image delete IMAGE-TAG
```
Where IMAGE-TAG is the value of the image.tag field in the image configuration YAML file.

When you successfully delete an image, you see this message:

Successfully deleted image IMAGE-TAG

Create a pull request or raise an issue on the source for this page in GitHub