{"id":19259246,"url":"https://github.com/concourse/semver-resource","last_synced_at":"2026-01-06T23:22:44.702Z","repository":{"id":19344260,"uuid":"22583401","full_name":"concourse/semver-resource","owner":"concourse","description":"automated semantic version bumping","archived":false,"fork":false,"pushed_at":"2025-03-31T04:10:26.000Z","size":2281,"stargazers_count":96,"open_issues_count":19,"forks_count":105,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-06T18:08:44.349Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/concourse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-03T20:53:55.000Z","updated_at":"2025-03-24T13:48:42.000Z","dependencies_parsed_at":"2023-02-12T03:15:33.886Z","dependency_job_id":"f3e47ab6-9e3b-4c49-829a-dfef0eea7fc1","html_url":"https://github.com/concourse/semver-resource","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fsemver-resource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fsemver-resource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fsemver-resource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fsemver-resource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/concourse","download_url":"https://codeload.github.com/concourse/semver-resource/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248775187,"owners_count":21159565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T19:15:50.708Z","updated_at":"2026-01-06T23:22:44.696Z","avatar_url":"https://github.com/concourse.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Semver Resource\n\nA resource for managing a version number. Persists the version number in one of several backing stores.\n\n\u003ca href=\"https://ci.concourse-ci.org/teams/main/pipelines/resource/jobs/build?vars.type=%22semver%22\"\u003e\n  \u003cimg src=\"https://ci.concourse-ci.org/api/v1/teams/main/pipelines/resource/jobs/build/badge?vars.type=%22semver%22\" alt=\"Build Status\"\u003e\n\u003c/a\u003e\n\n\n## Source Configuration\n\n* `initial_version`: *Optional.* The version number to use when\nbootstrapping, i.e. when there is not a version number present in the source.\n\n* `driver`: *Optional. Default `s3`.* The driver to use for tracking the\n  version. Determines where the version is stored.\n\nThere are four supported drivers, with their own sets of properties for\nconfiguring them.\n\n\n### `git` Driver\n\nThe `git` driver works by modifying a file in a repository with every bump. The\n`git` driver has the advantage of being able to do atomic updates.\n\n* `uri`: *Required.* The repository URL.\n\n* `branch`: *Required.* The branch the file lives on.\n\n* `file`: *Required.* The name of the file in the repository.\n\n* `private_key`: *Optional.* The SSH private key to use when pulling from/pushing to to the repository.\n\n* `username`: *Optional.* Username for HTTP(S) auth when pulling/pushing.\n   This is needed when only HTTP/HTTPS protocol for git is available (which does not support private key auth)\n   and auth is required.\n\n* `password`: *Optional.* Password for HTTP(S) auth when pulling/pushing.\n\n* `git_user`: *Optional.* The git identity to use when pushing to the\n  repository support RFC 5322 address of the form \"Gogh Fir \\\u003cgf@example.com\\\u003e\" or \"foo@example.com\".\n\n* `skip_ssl_verification`: *Optional.* Skip SSL verification for git endpoint. Useful for git compatible providers using self-signed SSL certificates.\n\n* `commit_message`: *Optional.* If specified overides the default commit message with the one provided. The user can use %version% and %file% to get them replaced automatically with the correct values.\n\n### `s3` Driver\n\nThe `s3` driver works by modifying a file in an S3 compatible bucket.\n\n* `bucket`: *Required.* The name of the bucket.\n\n* `key`: *Required.* The key to use for the object in the bucket tracking\nthe version.\n\n* `access_key_id`: *Optional.* The AWS access key to use when accessing the\nbucket.\n\n* `secret_access_key`: *Optional.* The AWS secret key to use when accessing\nthe bucket.\n\n* `assume_role_arn`: *Optional.* The AWS role to assume.\n    Role be assumed using the AWS SDK's default authentication chain. If\n    `access_key_id` and `secret_access_key` are provided, then those\n    credentials will be used to assume the role.\n\n* `session_token`: *Optional.* The AWS session token to use when accessing\nthe bucket.\n\n* `region_name`: *Optional. Default `us-east-1`.* The region the bucket is in.\n\n* `endpoint`: *Optional.* Custom endpoint for using S3 compatible provider. Can be a hostname or URL. (e.g. `https://my-endpoint.com` or `my-endpoint.com`)\n\n* `disable_ssl`: *Optional.* Disable SSL for the endpoint, useful for S3 compatible providers without SSL. Only used when `endpoint` is set.\n\n* `skip_ssl_verification`: *Optional.* Skip SSL verification for S3 endpoint. Useful for S3 compatible providers using self-signed SSL certificates.\n\n* `server_side_encryption`: *Optional.* The server-side encryption algorithm\nused when storing the version object (e.g. `AES256`, `aws:kms`, `aws:kms:dsse`).\n\nThe following IAM permissions are required with a resource ARN like\n`\"arn:aws:s3:::BUCKET_NAME/*\"`. You could use the exact key instead of `/*` if\nyou wish:\n\n* `s3:PutObject`\n* `s3:GetObject`\n\n### `swift` Driver\n\nThe `swift` driver works by modifying a file in a container.\n\n* `openstack` *Required.* All openstack configuration must go under this key.\n\n  * `container`: *Required.* The name of the container.\n\n  * `item_name`: *Required.* The item name to use for the object in the container tracking\nthe version.\n\n  * `region`: *Required.* The region the container is in.\n\n  * `identity_endpoint`, `username`, `user_id`, `password`, `api_key`, `domain_id`, `domain_name`, `tenant_id`, `tenant_name`, `allow_reauth`, `token_id`: See below\nThe swift driver uses [gophercloud](http://gophercloud.io/docs/) to handle interacting\nwith OpenStack. All OpenStack Identity versions are supported through this library. The\nAuthentication properties will pass through to it. For detailed information about the\nindividual parameters, see https://github.com/rackspace/gophercloud/blob/master/auth_options.go\n\n### `gcs` Driver\n\nThe `gcs` driver works by modifying a file in a Google Cloud Storage bucket.\n\n* `bucket`: *Required.* The name of the bucket.\n\n* `key`: *Required.* The key to use for the object in the bucket tracking the version.\n\n* `json_key`: *Required.* The contents of your GCP Account JSON Key. Example:\n\n  ```yaml\n  json_key: |\n    {\n      \"private_key_id\": \"...\",\n      \"private_key\": \"...\",\n      \"client_email\": \"...\",\n      \"client_id\": \"...\",\n      \"type\": \"service_account\"\n    }\n  ```\n\n### Example\n\nWith the following resource configuration:\n\n``` yaml\nresources:\n- name: version\n  type: semver\n  source:\n    driver: git\n    uri: git@github.com:concourse/concourse.git\n    branch: version\n    file: version\n    private_key: {{concourse-repo-private-key}}\n```\n\nBumping with a `get` and then a `put`:\n\n``` yaml\nplan:\n- get: version\n  params: {bump: minor}\n- task: a-thing-that-needs-a-version\n- put: version\n  params: {file: version/version}\n```\n\nOr, bumping with an atomic `put`:\n\n``` yaml\nplan:\n- put: version\n  params: {bump: minor}\n- task: a-thing-that-needs-a-version\n```\n\n## Behavior\n\n### `check`: Report the current version number.\n\nDetects new versions by reading the file from the specified source. If the\nfile is empty, it returns the `initial_version`. If the file is not empty, it\nreturns the version specified in the file.\n\n### `in`: Provide the version as a file, optionally bumping it.\n\nProvides the version number to the build as a `version` file in the destination.\n\nCan be configured to bump the version locally, which can be useful for getting\nthe `final` version ahead of time when building artifacts.\n\n#### Parameters\n\n* `bump` and `pre`: *Optional.* See [Version Bumping\n  Semantics](#version-bumping-semantics).\n\nNote that `bump` and `pre` don't update the version resource - they just\nmodify the version that gets provided to the build. An output must be\nexplicitly specified to actually update the version.\n\n* `pre_without_version`: *Optional.* By default `false`, once it's set to `true`\nthen PreRelease will be bumped without a version number.\n\n\n### `out`: Set the version or bump the current one.\n\nGiven a file, use its contents to update the version. Or, given a bump\nstrategy, bump whatever the current version is. If there is no current version,\nthe bump will be based on `initial_version`.\n\nThe `file` parameter should be used if you have a particular version that you\nwant to force the current version to be. This can be used in combination with\n`in`, but it's probably better to use the `bump` and `pre` params as they'll\nperform an atomic in-place bump if possible with the driver.\n\n#### Parameters\n\nOne of the following must be specified:\n\n* `file`: *Optional.* Path to a file containing the version number to set.\n\n* `bump` and `pre`: *Optional.* See [Version Bumping\n  Semantics](#version-bumping-semantics).\n\nWhen `bump` and/or `pre` are used, the version bump will be applied atomically,\nif the driver supports it. That is, if we pull down version `N`, and bump to\n`N+1`, the driver can then compare-and-swap. If the compare-and-swap fails\nbecause there's some new version `M`, the driver will re-apply the bump to get\n`M+1`, and try again (in a loop).\n\n* `pre_without_version`: *Optional.* By default `false`, once it's set to `true`\nthen PreRelease will be bumped without a version number.\n\n* `get_latest`: *Optional.* See [Check-less Usage](#check-less-usage).\n\n## Version Bumping Semantics\n\nBoth `in` and `out` support bumping the version semantically via two params:\n`bump` and `pre`:\n\n* `bump`: *Optional.* Bump the version number semantically. The value must\nbe one of:\n\n  * `major`: Bump the major version number, e.g. `1.0.0` -\u003e `2.0.0`.\n  * `minor`: Bump the minor version number, e.g. `0.1.0` -\u003e `0.2.0`.\n  * `patch`: Bump the patch version number, e.g. `0.0.1` -\u003e `0.0.2`.\n  * `final`: Promote the version to a final version, e.g. `1.0.0-rc.1` -\u003e `1.0.0`.\n\n\n* `pre`: *Optional.* When bumping, bump to a prerelease (e.g. `rc` or\n`alpha`), or bump an existing prerelease.\n\n  If present, and the version is already a prerelease matching this value,\n  its number is bumped. If the version is already a prerelease of another\n  type, (e.g. `alpha` vs. `beta`), the type is switched and the prerelease\n  version is reset to `1`. If the version is *not* already a pre-release, then\n  `pre` is added, starting at `1`.\n\n  The value of `pre` can be anything you like; the value will be `pre`-pended (_hah_)\n  to a numeric value. For example, `pre: foo` will result in a semver of\n  `x.y.z-foo.\u003cnumber\u003e`, `pre: alpha` becomes `x.y.z-alpha.\u003cnumber\u003e`, and\n  `pre: my-preferred-naming-convention` becomes `x.y.z-my-preferred-naming-convention.\u003cnumber\u003e`\n\n* `build`: *Optional.* Same as `pre` but for build labels (e.g. `build: foo`\n  will result in a semver of `x.y.z+foo.\u003cnumber\u003e`, `build: alpha` becomes\n  `x.y.z+alpha.\u003cnumber\u003e`.\n\n  It is valid for a semver to be both a prerelease and a build, for example,\n  `pre: alpha, build: test` results in `x.y.z-alpha.\u003cnumber\u003e+test.\u003cnumber\u003e`\n* `pre_without_version`: *Optional.* When bumping to a prerelease, drop the\n  version if set to `true`.\n  Examples:\n    * Major version bump: version file = 1.2.4-SNAPSHOT, release version = 2.0.0\n    * Minor version bump: version file = 1.2.4-SNAPSHOT, release version = 1.3.0\n    * Promote snapshot: version file = 1.2.4-SNAPSHOT, release version = 1.2.4\n* `build_without_version`: *Optional.* Same as `pre_without_version` but for\n  build labels.\n\n## Check-less Usage\n\nA classic usage of semver resource is like:\n\n```yaml\nresources:\n- name: version\n  type: semver\n  source:\n    driver: git\n    uri: git@github.com:concourse/concourse.git\n    branch: version\n    file: version\n    private_key: {{concourse-repo-private-key}}\n\njobs:\n- name: some-job\n  plan:\n  - get: trigger-resource\n    trigger: true\n  - get: version\n    param: {bump: major}\n  - task: a-thing-that-needs-a-version\n  - put: version\n    params: {file: version/version}\n```\n\nIn above classic mode, Concourse will run periodic checks against the `semver`\nresource `version`. Each check will do a `git clone` as the driver is `git`.\nWhen there are a lot of `semver` resources, checks on `semver` resources may\nalso bring burden to the git system as each check will invoke a `git clone`.\n\nGiven each `semver` resource requires a parameter `file` in `source`, `semver`\nresources are hard to enjoy [benefits of global resources](https://concourse-ci.org/global-resources.html#benefits-of-global-resources).\n\nTo mitigate the burden of checks, if a `semver` resource is not a job trigger,\ncheck-less mode can be used. The above sample then can be rewritten as:\n\n```yaml\njobs:\n- name: some-job\n  plan:\n  - get: trigger-resource\n    trigger: true\n  - put: version # change `get` to `put`\n    params:\n      get_latest: true # and set `get_latest: true`\n      bump: major\n  - task: a-thing-that-needs-a-version\n  - put: version\n    params: {file: version/version}\n```\n\nYou may have noticed that, original `get: version` is changed to `put: version`.\nNow resource `version` is put-only, then Concourse will no longer run check on\nit. Param `get_latest: true` tells the `put` step to only fetch the latest version\nwithout bumping anything. Then the implied `get` will fetch a version as a typical\n`get` step.\n\nIf your Concourse or Git (e.g. Gitlab) systems are exhausted by `semver` resources'\nchecks, you may consider reforming pipelines to use this check-less usage.\n\nThe cons of check-less usage are:\n\n* you cannot use `put` step as a job trigger.\n* you cannot use `passed` in a `put` step\n* `put` step with `get_latest: true` will always fetch the latest version, thus\n  you are not able to pin an old version.\n\n## Running the tests\n\nThe tests have been embedded with the `Dockerfile`; ensuring that the testing\nenvironment is consistent across any `docker` enabled platform. When the docker\nimage builds, the test are run inside the docker container, on failure they\nwill stop the build.\n\nRun the tests with the following command:\n\n```sh\ndocker build -t semver-resource --target tests .\n```\n\n### Integration tests\n\nThe integration requires two AWS S3 buckets, one without versioning and another\nwith. The `docker build` step requires setting `--build-args` so the\nintegration will run.\n\nYou will need:\n* AWS key and secret\n* An S3 bucket\n* The region you are in (i.e. `us-east-1`, `us-west-2`)\n\nRun the tests with the following command, replacing each `build-arg` value with your own values:\n\n```sh\ndocker build . -t semver-resource --target tests -f dockerfiles/alpine/Dockerfile \\\n  --build-arg SEMVER_TESTING_ACCESS_KEY_ID=\"some-key\" \\\n  --build-arg SEMVER_TESTING_SECRET_ACCESS_KEY=\"some-secret\" \\\n  --build-arg SEMVER_TESTING_BUCKET=\"some-bucket\" \\\n  --build-arg SEMVER_TESTING_REGION=\"some-region\"\n\ndocker build . -t semver-resource --target tests -f dockerfiles/ubuntu/Dockerfile \\\n  --build-arg SEMVER_TESTING_ACCESS_KEY_ID=\"some-key\" \\\n  --build-arg SEMVER_TESTING_SECRET_ACCESS_KEY=\"some-secret\" \\\n  --build-arg SEMVER_TESTING_BUCKET=\"some-bucket\" \\\n  --build-arg SEMVER_TESTING_REGION=\"some-region\"\n```\n\n## Contributing\n\nPlease make all pull requests to the `master` branch and ensure tests pass\nlocally.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconcourse%2Fsemver-resource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconcourse%2Fsemver-resource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconcourse%2Fsemver-resource/lists"}