Releasing a New Buildpack Version

Page last updated:

This topic describes how to update and release a new version of a Cloud Foundry (CF) buildpack through the CF Buildpacks Team Concourse pipeline. Concourse is a continuous integration (CI) tool for software development teams. This is the process used by the CF Buildpacks Team and other CF buildpack development teams. You can use this process as a model for using Concourse to build and release new versions of your own buildpacks.

The Concourse pipelines for Cloud Foundry buildpacks are located in the buildpacks-ci GitHub repository.

Release a New Buildpack Version

To release a new buildpack version, perform the following:

  1. Ensure you have downloaded the buildpacks-ci repository: 

    $ git clone https://github.com/cloudfoundry/buildpacks-ci.git

  2. From the buildpack directory, check out the develop branch of the buildpack: 

    $ cd /system/path/to/buildpack
$ git checkout develop

  3. Ensure you have the most current version of the repository: 

    $ git pull -r

  4. Run bump to update the version in the buildpack repository: 

    $ /system/path/to/buildpacks-ci/scripts/bump

  5. Modify the CHANGELOG file manually to condense recent commits into relevant changes. For more information, see Modify Changelogs.

  6. Add and commit your changes: 

    $ git add VERSION CHANGELOG
$ git commit -m "Bump version to $(cat VERSION) [{insert story #}]"

  7. Push your changes to the develop branch: 

    $ git push origin develop

Concourse Buildpack Workflow

If buildpacks-ci is not deployed to Concourse, manually add a Git tag to the buildpack and mark the tag as a release on GitHub.

If buildpacks-ci is deployed to Concourse, the buildpack update passes through the following life cycle:

  1. Concourse triggers the buildpack-to-master job in the pipeline for the updated buildpack. This job merges develop onto the master or main branch of the buildpack.

  2. The detect-new-buildpack-and-upload-artifacts job triggers in the pipeline for the updated buildpack. This job creates a cached and uncached buildpack and uploads them to an AWS S3 bucket.

  3. The specs-lts-master and specs-edge-master jobs trigger and run the buildpack test suite and the buildpack-specific tests of the Buildpack Runtime Acceptance Tests (BRATS).

  4. If you are using Pivotal Tracker, paste the links for the specs-edge-master and specs-lts-master builds in the related buildpack release story and deliver that story.

  5. Your project manager can manually trigger the buildpack-to-github job on Concourse as part of the acceptance process. This releases the buildpack to GitHub.

  6. After the buildpack has been released to GitHub, the cf-release pipeline is triggered using the manual trigger of the recreate-bosh-lite job on that pipeline. If the new buildpack has been released to GitHub, the CF that is deployed for testing in the cf-release pipeline is tested against that new buildpack.

  7. After the cats job has successfully completed, your project manager can ship the new buildpacks to the cf-release repository and create the new buildpack BOSH release by manually triggering the ship-it job.

Note: If errors occur during this workflow, you may need to remove unwanted tags. For more information, see Handle Unwanted Tags.

Modify Changelogs

The Ruby Buildpack changelog shows an example layout and content of a changelog. In general, changelogs follow these conventions:

  • Reference public tracker stories whenever possible.
  • Exclude unnecessary files
  • Combine and condense commit statements into individual stories containing valuable changes.

Handle Unwanted Tags

If you encounter problems with the commit that contains the new version, change the target of the release tag by performing the following:

  1. Ensure the repository is in a valid state and is building successfully.
  2. Remove the tag from your local repository and from GitHub.
  3. Start a build. The pipeline build script should re-tag the build if it is successful.