Thanks for your interest in contributing to the Conjur Buildpack! Here are some guidelines on how to get started.
For general contribution and community guidelines, including our pull request workflow, please see the community repo.
The following prerequisites and all sections below pertain to building and running the Conjur Buildpack locally, unless otherwise specified.
Before getting started, you should install some developer tools. These are not required to deploy the Conjur Buildpack but they will let you develop using a standardized, expertly configured environment.
- git to manage source code
- Docker to manage dependencies and runtime environments
- Docker Compose to orchestrate Docker environments
In addition, if you will be making changes to the conjur-env
binary, you should
ensure you have Go installed locally.
Our project uses Go modules, so you will want to install version 1.12+.
The conjur-env
binary uses Go modules to manage dependencies.
To update the versions of summon
/ conjur-api-go
that are included in the conjur-env
binary in the buildpack,
make sure you have Go installed locally (at least version 1.12) and run:
$ cd conjur-env/
$ go get github.com/cyberark/[repo]@v[version]
This will automatically update go.mod and go.sum.
Commit your changes, and the next time ./conjur-env/build.sh
is run the
vendor/conjur-env
directory will be created with updated dependencies.
When upgrading the version of Go for conjur-env
, the value needs to be updated
in a few places:
- Update the base image in
./conjur-env/Dockerfile
- Update the Go version in
./conjur-env/go.mod
- Update the version and file hashes in
manifest.yml
- available versions and hashes can be found here, or see the manifest for the official Go Buildpack. (This is for the offline version of the buildpack, which is built with buildpack-packager.) - Update the version and SHA hash in
lib/install_go.sh
-- you can find the available versions and hashes on the CF dependencies page.
The buildpack has a cucumber test suite. This validates the functionality and
also offers great insight into the intended functionality of the buildpack.
Please see ./tests/features
.
To test the usage of the Conjur Service Broker within a CF deployment, you can follow the demo scripts in the Cloud Foundry demo repo.
To test your changes within a running instance of Cloud Foundry Stack and Conjur, run:
./ci/start_dev_environment
This starts Conjur and Cloud Foundry Stack containers, and provides terminal access to the Cloud Foundry container. You do not need to restart the container after you make changes to the project.
To run the local cucumber
tests within the development environment, run the following
command from the tests/integration
directory, within the container:
cucumber \
--format pretty \
--format junit \
--out ./features/reports \
--tags 'not @integration'
Unit tests are comprised of two categories:
- Unit tests, linting, and code coverage for
conjur-env
Golang module - Unit tests for
lib/0001_retrieve-secrets.sh
To run all tests for the conjur-env
Golang module and for
lib/0001_retrieve-secrets.sh
, you can run:
./ci/test_unit
To run all tests for only the conjur-env
Golang module, run:
./ci/test_conjur-env
To run all tests for only 0001_retrieve-secrets.sh
, run:
./tests/retrieve-secrets/start
See the README.md for more information.
To run the set of features marked with not @integration
,
which are the subset of cucumber
integration tests not dependent
on a remote PCF instance or privileged credentials. Run:
./ci/test_integration
This starts Conjur and Cloud Foundry Stack containers, and
runs the cucumber
tests within.
To run the Buildpack end-to-end tests, the test script needs to be given the API endpoint and admin credentials for a CloudFoundry installation. These are provided as environment variables to the script:
export CF_API_ENDPOINT=https://api.sys.cloudfoundry.net
CF_ADMIN_PASSWORD=... ./ci/test_e2e
These variables may also be provided using Summon
by updating the ci/secrets.yml
file as needed and running:
summon -f ./ci/secrets.yml ./ci/test_e2e
This requires access to privileged credentials.
If integration tests fail, it's possible that some artifacts may not be cleaned up properly. To clean up leftover components from running integration tests on a remote PCF environment, run:
./ci/clear_ci_artifacts
-
Based on the unreleased content, determine the new version number and update the VERSION file. This project uses semantic versioning.
-
Ensure the changelog is up to date with the changes included in the release.
-
Ensure the open source acknowledgements are up to date with the dependencies in the conjur-env binary, and update the file if there have been any new or changed dependencies since the last release.
-
Commit these changes -
Bump version to x.y.z
is an acceptable commit message. -
Once your changes have been reviewed and merged into master, tag the version using
git tag -s v0.1.1
. Note this requires you to be able to sign releases. Consult the github documentation on signing commits on how to set this up.vx.y.z
is an acceptable tag message. -
Push the tag:
git push vx.y.z
(orgit push origin vx.y.z
if you are working from your local machine). -
Retrieve the archived release ZIP from the Jenkins build. Upload this ZIP file to the GitHub release.
IMPORTANT Do not upload any artifacts besides the ZIP to the GitHub release. At this time, the tile build assumes the project ZIP is the only artifact.