Create release notes and versioning with the release workflow

Ever wondered what a release workflow should look like and how to create release notes and do versioning automatically? Read this guide.

Ever wondered what a release workflow should look like and how to create release notes and do versioning automatically? Read on.

release workflow

Branches, branches

For our test project, we use GitHub as the code source provider and use the relevant steps for it on Bitrise.

Let's assume that the main code base is on the master branch, and one or more developer will want to develop a new feature and thus push code to the main code base. As it is important to keep the main code base bug free and clean, the developers should work on different branches, for example feature/new-login-screen-design, and they should create a pull request to merge new code. This will open a well-designed comparison page, which is a good interface to start a discussion about the new changes on, and it also helps track changes made in the pull request after it has been opened, that is the changes resulted by the discussion.

Using branches we'll hopefully have a bug-free code base and go on releasing our app. 😎

Follow the versions

When the main code base has a couple of those pull requests merged, you might want to keep track of the versions as well. App versions can be handled easily by using git tags and as Bitrise can handle your tag events, a new build can be started by using the new tag as a trigger.

For this you'll need to configure your app to handle tags on the Triggers tab like this:

add triggers to run builds

Generating a changelog

As soon as you have the tag trigger event set to use a workflow, you can generate a changelog automatically, moreover, creating a GitHub release is only a step away. 🙂

Just add a Generate Changelog and a Github Release step to your release workflow.

bitrise workflow

The Generate Changelog step will automatically collect your commit messages since the last tag event (you are using meaningful commit messages, right? 🤔) and it will export the list into the environment variable called $BITRISE_CHANGELOG. It is also exported into the deploy dir as a file called

Create a Release

GitHub Release will require your GitHub username and an access token for that user. In our example, I set $BITRISE_CHANGELOG as the release body and $BITRISE_GIT_TAG as the title. I also set draft to no so the release will automatically be published.

So now if you tag the right commit and push it into your repository, it will look something like this on GitHub:

github release note

This event has already started the workflow matching the git tag you specified earlier. After the build has run successfully, you will see your release created with the changelog:

github release notes

Opening a PR, fixing an issue and merging it to the master will look like this on Bitrise:

bitrise build list

Of course, by tagging a code state and triggering a build you can deploy the actual tagged version to the app stores in one go, so managing app versions can be as easy as to have them versioned by git tags.

Check out the sample workflow we've used:

format_version: '5'

- pull_request_source_branch: "*"
  workflow: run-tests
- tag: "*.*.*"
  workflow: create-release

    - activate-ssh-key@4.0.2: {}
    - git-clone@4.0.11: {}
    - generate-changelog@0.9.0: {}
    - github-release@0.9.3:
        - body: "$BITRISE_CHANGELOG"
        - draft: "no"
        - username: "$MY_GITHUB_USERNAME"
        - api_token: "$MY_GITHUB_ACCESS_TOKEN"
        - name: "$BITRISE_GIT_TAG"
    - activate-ssh-key@3.1.1:
        run_if: '{{getenv "SSH_RSA_PRIVATE_KEY" | ne ""}}'
    - git-clone@4.0.11: {}
    - script@1.1.5:
        title: Do anything with Script step
    - deploy-to-bitrise-io@1.3.12: {}
Copy code

Share your best practices or experience with us in the comments!

Happy building!

No items found.

Explore more topics

App development

Best practices from engineers on how to use Bitrise to build better apps, faster.


Meet other Bitrise engineers, technology experts, power users, partners and join our BUGs.


All the updates about Bitrise events, sponsorships, employees, and more.


Mobile development, latest tech, industry insights, and interviews with experts.

Mobile DevOps

Learn why mobile development is unique and requires a set of unique practices.


Stay tuned for the last updates, new features, and product improvements.

Get the latest from Bitrise

Join other Mobile DevOps engineers who receive regular emails from Bitrise, filled with tips, news, and best practices.