{"id":15055539,"url":"https://github.com/sanjp10/release","last_synced_at":"2025-04-10T03:53:37.354Z","repository":{"id":37410360,"uuid":"332223252","full_name":"sanjP10/release","owner":"sanjP10","description":"Tag verification and creation using your changelog file. All Git providers supported for public and self-hosted instances. Designed to help automated release creations in CI/CD workflows.","archived":false,"fork":false,"pushed_at":"2025-03-13T02:02:05.000Z","size":812,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T03:53:08.703Z","etag":null,"topics":["bitbucket","cd","ci","ci-cd","cicd","continuous-delivery","continuous-deployment","continuous-integration","git","github","gitlab","pipelines","release","release-automation","release-management","release-notes","tagger","tagging","tags","validation"],"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/sanjP10.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-23T13:58:53.000Z","updated_at":"2025-02-28T09:06:38.000Z","dependencies_parsed_at":"2023-02-05T04:31:38.397Z","dependency_job_id":"d7a4b214-c6e1-46ad-8ec0-6dfd01c8d5d9","html_url":"https://github.com/sanjP10/release","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanjP10%2Frelease","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanjP10%2Frelease/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanjP10%2Frelease/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanjP10%2Frelease/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sanjP10","download_url":"https://codeload.github.com/sanjP10/release/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154998,"owners_count":21056542,"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":["bitbucket","cd","ci","ci-cd","cicd","continuous-delivery","continuous-deployment","continuous-integration","git","github","gitlab","pipelines","release","release-automation","release-management","release-notes","tagger","tagging","tags","validation"],"created_at":"2024-09-24T21:44:16.763Z","updated_at":"2025-04-10T03:53:37.334Z","avatar_url":"https://github.com/sanjP10.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Release\n\n\n![Unit and Integration Tests](https://github.com/sanjP10/release/actions/workflows/ci.yml/badge.svg)\n![CodeQL](https://github.com/sanjP10/release/workflows/CodeQL/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/sanjP10/release)](https://goreportcard.com/report/github.com/sanjP10/release)\n\nRelease is a tool that validates and creates tags against git repos by reading your changelog file.\n\nIt is supported for the following git repository providers via their respective REST APIs:\n\n* GitHub\n* Gitlab\n* Bitbucket\n\nIf a provider isn't provided to the command it will default to the in built git tagging functionality.\n\nIt requires a markdown formatted changelog, with the most recent changes at the top.\n\nThe that consists of a version must start with a `h2` markup and have a number afterward.\n\nAn example changelog would be \n\n```\n# Changelog\n\n[//]: \u003c\u003e (Spaces an no spaces on version number lines are for checking regex in unit tests)\n## 1.1.0\n\n### Updated\n* An update happened\n\n## 1.0.0\n\n### Added\n\n* Initial release\n\n```\n\nthe version numbers can be of a format with decimals separating them.\n\nExample formats tha can be used are\n\n```\nmajor\nmajor.minor\nmajor.minor.patch\nmajor.minor.patch.micro\n```\n\n***Note: the format must be consistent within the changelog***\n\n# Validation/Release Flows\n\n### Require version bumps\n![Release Require version bump](./drawio/Release-Flows-Require-Version-Bump.png)\n\n### Valid release\n![Valid Release](./drawio/Release-Flows-Valid-Release.png)\n\n### Create Release\n![Create Release](./drawio/Release-Flows-Creation-Flow.png)\n\n# Installation\n\n#### **With Go installed**\n\nIf you have go installed, you can install `release` by running the following.\n\n```bash\ngo install github.com/sanjP10/release@latest\n```\nTo find out where `release` was installed you can run `go list -f {{.Target}} github.com/sanjP10/release`\n\n#### **Without Go installed**\n\nYou can go to the [releases page](https://github.com/sanjP10/release/releases) and download the binary for your desired operating system and architecture.\n\nFor `release` to be used globally add that directory to the `$PATH` environment setting.\n\n# Usage\n\nThe two subcommands for release are `validate` and `create`\n* `validate` will interrogate the latest version on the changelog file and if it exists for the repository.\nIf it does exist, and the commit hash provided is the same it will return a successful exit code. Ideally you put this\n  as part of your testing phase within your CI/CD.\n* `create` will do the same as `validate` and if the tag does not exist it will create the tag for the commit hash provided. You\nuse this when you want to create a tag for your repo.\n\nThese are the flags when a provider is present\n\n```\n-username \u003cusername\u003e\n-password \u003cpassword/authroization token\u003e \n-repo \u003cowner/org/project\u003e/\u003crepo name\u003e\n-changelog \u003cchangelog md file\u003e\n-hash \u003ccommit sha\u003e\n-host \u003chost dns\u003e (optional) (default is bitbucket.org, gitlab.com, github.com)\n-provider \u003cgit provider of choice from gitlab, github and bitbucket\u003e\n```\n\nThese are the flags when using the default git functionality\n```\n-username \u003cusername for https authentication, optional for ssh key - defaults to git\u003e\n-password \u003cpassword/authroization token for https authentication, optional for ssh key password\u003e \n-changelog \u003cchangelog md file\u003e\n-hash \u003ccommit sha\u003e\n-email \u003cemail address for tag\u003e\n-origin \u003cgit https/ssh origin\u003e\n-ssh \u003cpath to private ssh key, will require ssh to be part of known hosts and regitered with ssh-agent, optional field\u003e\n```\n\n## Changelog Notes\nThe **GitHub** and **Gitlab** APIs also takes the markdown between the version numbers and creates a release with the changelog notes you created.\nIf you use the default **git** provided or a self-hosted **bitbucket** the release notes are added as annotations to the tag, so if you run `git show \u003cdesired tag\u003e` you can see the notes associated.\n**Bitbucket** api does not process any release notes as it is not supported.\n\n\n## Examples\nThis is an example `validate` command via bitbucket\n\n```\nrelease validate -username $USER -password $ACCESS_TOKEN -repo owner/repo_name -changelog changelog.md -hash $COMMIT_HASH -provider bitbucket\n```\nThis is an example `validate` command using default git\n```\n# HTTPS\nrelease validate -username $USER -password $ACCESS_TOKEN -email user@domain.com -origin https://$USER@bitbucket.org/$BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG.git -changelog CHANGELOG.md -hash $COMMIT_HASH\n\n# SSH\nrelease validate -ssh $PATH_TO_PRIVATEKEY -password $ACCESS_TOKEN -email user@domain.com -origin git@bitbucket.org/$BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG.git -changelog CHANGELOG.md -hash $COMMIT_HASH\n```\n\nThis is an example `create` command via bitbucket\n\n```\nrelease create -username $USER -password $ACCESS_TOKEN -repo owner/repo_name -changelog changelog.md -hash $COMMIT_HASH -provider bitbucket\n```\nThis is an example `create` command using default git\n```\n# HTTPS\nrelease create -username $USER -password $ACCESS_TOKEN -email user@domain.com -origin https://$USER@bitbucket.org/$BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG.git -changelog CHANGELOG.md -hash $COMMIT_HASH\n\n# SSH\nrelease create -ssh $PATH_TO_PRIVATEKEY -password $ACCESS_TOKEN -email user@domain.com -origin git@bitbucket.org/$BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG.git -changelog CHANGELOG.md -hash $COMMIT_HASH\n\n```\n\nThis is an example of `validate` command against a self-hosted bitbucket\n```\nrelease validate -username $USER -password $ACCESS_TOKEN -repo owner/repo_name -changelog changelog.md -hash $COMMIT_HASH -host api.mybitbucket.com -provider bitbucket\n```\n\n# Outputs\n\nRelease when returning with a successful exit code will write the desired or created tag as stdout.\n\nYou can in turn take that output and use it with other tag based services such as Docker.\n\nAn example script would be\n```bash\nversion=$(release create -username $USER -password $ACCESS_TOKEN -repo owner/repo -changelog CHANGELOG.md -hash $COMMIT_HASH -provider github) || exit $?\ndocker build -t myContainer:$version .\ndocker push myContainer:$version\n```\n\n# CI/CD Integrations\n\n## Bitbucket Pipeline example\nTo integrate the `validate` use this in bitbucket pipelines you can use the following as steps\n\n```yaml\n- step:\n    name: validate version\n    image: golang\n    script:\n      - go install github.com/sanjP10/release@latest\n      # Test version does not exist\n      - release validate -username $USER -password $ACCESS_TOKEN -repo $BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG -changelog CHANGELOG.md -hash $BITBUCKET_COMMIT -provider bitbucket\n```\n\nTo integrate the `create` use this in the bitbucket pipeline after you merge to master\n\nTo integrate this into bitbucket pipelines you can use the following as steps\n\n```yaml\n- step:\n    name: create version\n    image: golang\n    script:\n      - go install github.com/sanjP10/release@latest\n      - release create -username $USER -password $ACCESS_TOKEN -repo $BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG -changelog CHANGELOG.md -hash $BITBUCKET_COMMIT -provider bitbucket\n```\n\n## GitHub Actions Example\n\n### Using release-action GitHub action\n\nFor GitHub actions you can use the [release-action](https://github.com/sanjP10/release-action).\n\n### Directly installing the tool into your job\n\nTo integrate the `validate` use this in GitHub actions you can use the following as steps\n\n```yaml\n  validate:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v3\n      - name: Setup Go\n        uses: actions/setup-go@v3\n        with:\n          go-version: '^1.18'\n      - run: go install github.com/sanjP10/release@latest\n      - run: release validate -username ${{ github.actor }} -password ${{ secrets.GITHUB_TOKEN }} -repo ${{ github.repository }} -changelog CHANGELOG.md -hash ${{ github.sha }} -provider github\n```\n\nTo integrate the `create` use this in the bitbucket pipeline after you merge to master\n\nTo integrate this into GitHub actions you can use the following as steps\n\n```yaml\n  create:\n    runs-on: ubuntu-latest\n    needs: \u003cA STEP\u003e\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v3\n      - name: Setup Go\n        uses: actions/setup-go@v3\n        with:\n          go-version: '^1.18'\n      - run: go install github.com/sanjP10/release@latest\n      - run: release create -username ${{ github.actor }} -password ${{ secrets.GITHUB_TOKEN }} -repo ${{ github.repository }} -changelog CHANGELOG.md -hash ${{ github.sha }} -provider github\n```\n\n## Circle CI Orb\n\n### Using release circle ci orb\n\nFor GitHub actions you can use the [release](https://circleci.com/developer/orbs/orb/sanjp10/release) orb.\n\n### Directly installing the tool into your job (requires golang executor)\n\n```yaml\njobs:\n  # Define one or more jobs which will utilize your orb's commands and parameters to validate your changes.\n  validate:\n    executor: release/default\n    steps:\n      - checkout\n      - run:\n          name: Create tag\n          command: |\n            go install github.com/sanjP10/release@latest\n            release validate -username \u003c\u003c parameters.username \u003e\u003e -password \u003c\u003c parameters.password \u003e\u003e -repo \u003c\u003c parameters.repo \u003e\u003e -changelog \u003c\u003c parameters.changelog-file-location \u003e\u003e -hash $CIRCLE_SHA1 -provider \u003c\u003c parameters.provider \u003e\u003e\n  create:\n    executor: release/default\n    steps:\n      - checkout\n      - run:\n          name: Create tag\n          command: |\n            go install github.com/sanjP10/release@latest\n            release create -username \u003c\u003c parameters.username \u003e\u003e -password \u003c\u003c parameters.password \u003e\u003e -repo \u003c\u003c parameters.repo \u003e\u003e -changelog \u003c\u003c parameters.changelog-file-location \u003e\u003e -hash $CIRCLE_SHA1 -provider \u003c\u003c parameters.provider \u003e\u003e\n```\n\n# Cloud Service Provider Implementations\n\n## CodeCommit\nCodeCommit only supports SSH\n\nAs code commit uses credential-helper to create a username and password it is not possible to get\nthe username and password for use with HTTPs.\n\nIt's required that you use SSH which is only available via IAM Users.\n\nAfter following the steps in the AWS Documentation of setting up an ssh key as documented [here](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-ssh-unixes.html#setting-up-ssh-unixes-keys)\n\nYou will need to get the SSH Key ID which can be found in the IAM User console.\n\nThis would be the command for using the tool when using SSH.\n```\nrelease validate -ssh $PATH_TO_PRIVATEKEY -email user@domain.com -origin ssh://$AWS_SSH_KEY_ID@git-codecommit.eu-west-1.amazonaws.com/v1/repos/$REPO_NAME -username $AWS_SSH_KEY_ID -changelog CHANGELOG.md -hash $COMMIT_HASH\n```\n\n## GCP Source Repositories\nCloud Source Repositories only supports SSH\n\nAs source repositories uses git-cookies to create a username and password it is not possible to get\nthe username and password for use with HTTPs.\n\nOnce you have registered the ssh key within cloud source repositories, the command  would be as follows\n```\nrelease validate -ssh $PATH_TO_PRIVATEKEY -email user@domain.com -origin ssh://$ACCOUNT_EMAIL@source.developers.google.com/p/$PROJECT_ID/r/$REPO_NAME -username $ACCOUNT_EMAIL -changelog CHANGELOG.md -hash $COMMIT_HASH\n```\n\n# Known Issues\n\n## Git provider\n* Azure - Unfortunately neither HTTPs nor SSH due to this [issue](https://github.com/go-git/go-git/issues/64)\n* GitHub - Unfortunately neither HTTPs nor SSH due to this [issue](https://github.com/go-git/go-git/issues/122), so as an alternative please use `-provider github` which utilises GitHub's REST API\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanjp10%2Frelease","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsanjp10%2Frelease","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanjp10%2Frelease/lists"}