A Concourse resource for working with versions of a BOSH release. Specifically focused on support for non-bosh.io releases, private release repositories, version constraints, dev releases, and finalize-release
tasks.
uri
- location of the BOSH release git repositorybranch
- the branch to use (optional unless usingout
; uses default remote branch)dev_releases
- set totrue
to create dev releases from every commitname
- a specific release name to use (default isname
fromconfig/final.yml
)private_config
- a hash of settings which will be serialized toconfig/private.yml
forin
/out
private_key
- a SSH private key when using private git repositoriesversion
- a supported version constraint (e.g.2.x
,>= 2.3.4
,>2.3.2, <3
)
Get the latest versions of the release.
When dev_releases
is enabled, the version will be in the format of ((version))-dev.((commit-date-utc)) commit.((short-commit-hash))
. The version number is an incremented patch from the latest final version (as of the referenced commit), followed by the commit-based, pre-release data. For example, if the last final release was 5.0.0
and the last commit was made on 2018-06-13
in dd7c33e1d
... the version would be 5.0.1-dev.20180613T040837Z.commit.dd7c33e1d
).
Version:
version
- release version
Get a specific version of the release.
Parameters:
tarball
- create a release tarball (defaulttrue
)tarball_name
- file name to use for the tarball (default{{.Name}}-{{.Version}}.tgz
)
Resource:
name
- release namerelease.tgz
- source release tarballversion
- release version
Metadata:
bosh
- version ofbosh
CLI used to create the tarballtime
- timestamp when the tarball was created
Create a new version of the release from an existing tarball or repository checkout.
Parameters:
repository
- path to a repository checkout from which to create a release (one ofrepository
ortarball
must be configured)tarball
- path to an existing release tarball to finalize (one ofrepository
ortarball
must be configured)version
- path to the file with contents of a specific version to usecommit_file
- path to the file with contents of a commit message (default messageVersion {version}
)author_name
- full name to use as commit author (defaultCI Bot
)author_email
- email address to use as commit author (defaultci@localhost
)rebase
- enable automatic rebasing if there are conflicts on push (defaultfalse
)skip_tag
- disable creating an annotated tag pointing to the commit the release tarball was created with (defaultfalse
)
Metadata:
bosh
- version ofbosh
CLI used to finalize the releasecommit
- commit reference where the new version was finalized
The create-dev-release
script may be used to create a release tarball from a clone in the current working directory. See create-dev-release.yml
for an example task config.
Arguments:
- Output directory - for creating the release tarball
The load-release-notes
script may be used to output release notes for a given release version from a clone in the current working directory. See load-release-notes.yml
for an example task config. Release notes are checked in the following order...
- locally-committed release notes in
releases/{name}/{name}-{version}.md
- GitHub release notes for tags
v{version}
or{version}
(based on the clone's remote origin)
Arguments:
- Output path - for writing the release notes contents
- Release version - to lookup release notes (either literal version, or path to a file whose contents is the version)
Environment Variables:
GITHUB_TOKEN
- a GitHub API OAuth authentication tokenmissing_ok
- set totrue
to exit with success even if no release notes are foundskip_github
- set totrue
to skip checking GitHub release notesskip_local
- set totrue
to skip checking local release notes
To use this resource type, you should configure it in the resource_types
section of your pipeline.
- name: bosh-release
type: docker-image
source:
repository: dpb587/bosh-release-resource
The default latest
tag will refer to the current, stable version of this Docker image. For using the latest development version, you can refer to the master
tag. If you need to refer to an older version of this image, you can refer to the appropriate v{version}
tag.
This resource is generally equivalent to the check
/get
behaviors of bosh-io-release
.
If you originally used the bosh-io-release
...
- name: concourse
type: bosh-io-release
source:
repository: concourse/concourse
The equivalent bosh-release
resource would be...
- name: concourse
type: bosh-release
source:
uri: https://github.com/concourse/concourse.git
The release tarball is named {{.Name}}-{{.Version}}.tgz
. If you were not using globs (e.g. release/*.tgz
) you can retain the bosh-io-release
behavior by configuring tarball_name
. For example...
- get: stable-release
params:
tarball_name: release.tgz
Note that url
and sha1
are not provided since tarballs are built locally.
A few examples which may be helpful...
- BOSH Release Notifications - a simple pipeline to send a Slack notification when there is a new release of cloudfoundry/bosh
- dpb587/openvpn-bosh-release - used in the pipeline for building and finalizing releases
- dpb587/caddy-bosh-release - used in the pipeline for building and finalizing releases
Subtle details you might care about...
- This tags the commit from which the release tarball was created (
commit_hash
), not the commit which finalizes the release in thereleases
directory. This is primarily to ensure git tags matchcommit_hash
and refer to the underlying source where changes between versions occur (as opposed to when it was finalized which may have a different set of files). - This uses annotated tags as opposed to lightweight tags. This enables additional metadata to be associated with when the release is published, as opposed to being restricted to when
commit_hash
occurred. - This requires that versions match semver conventions. If your release does not use a semver-compatible version, this may not work. This is primarily to encourage semver-like conventions. For releases where typical 3-tuple version numbers are not meaningful, date-based semver numbers may be a useful alternative.
- This currently requires an externally-provided version file rather than supporting
bosh
's automatic major version-bumping strategy. This is primarily to encourage more explicit version management. If this becomes too burdensome, it may be worth supporting.
Before committing, tests can be run locally with bin/test
. After pushing, Travis CI should automatically run tests for commits and pull requests.