semantic_release plugin for fastlane

• Getting Started
• About
• Commit Format
• Quick Start
• Available Actions
  • analyze_commits
  • conventional_changelog
• Examples
• Development
• Questions

fastlane add_plugin semantic_release

Automated version management and generator of release notes. Inspired by semantic-release for npm packages. Based on conventional commits.

Semantic Release for Fastlane @ Medium - By Jiri Otahal

This plugin expects commits to follow the Conventional Commits specification:

<type>(<scope>): <subject>

Examples:

fix(auth): resolve login crash on Android
feat: add dark mode support
feat(api)!: change response format
docs: update installation guide

Breaking changes are detected in two ways:

• Adding ! after the type/scope: feat(api)!: change response format
• Including BREAKING CHANGE: in the commit body

Other types (docs, chore, refactor, perf, test, style) do not trigger a version bump by default, but will appear in the changelog. You can customize this mapping with the releases parameter.

Two built-in commit format patterns are available via the commit_format parameter:

• default — Matches: docs, fix, feat, chore, style, refactor, perf, test
• angular — Matches any word as a type (more permissive)

You can also pass a custom Regexp with 4 capture groups: type, scope, breaking indicator (!), and subject.

Here is a minimal Fastfile showing the typical workflow — analyze commits, then generate a changelog:

lane :release do
  # 1. Analyze commits to determine next version
  is_releasable = analyze_commits(match: 'v*')

  if is_releasable
    next_version = lane_context[SharedValues::RELEASE_NEXT_VERSION]

    # 2. Generate changelog from commits
    notes = conventional_changelog(
      format: 'markdown',
      commit_url: 'https://github.com/user/repo/commit'
    )

    # 3. Use the version and notes however you need
    # For example: tag, push, create GitHub release, etc.
    add_git_tag(tag: "v#{next_version}")
    push_git_tags

    set_github_release(
      repository_name: 'user/repo',
      tag_name: "v#{next_version}",
      description: notes
    )
  end
end

Analyzes your git history since the last matching tag, determines the next semantic version, and returns true if a release is recommended.

How it works:

1. Finds the last tag matching your pattern (e.g., v*, ios/beta*)
2. Parses the version number from that tag
3. Gets all commits since the tag
4. Analyzes each commit subject against conventional commit rules
5. Calculates the next version based on commit types
6. Returns true if the next version is higher than the last

Example:

is_releasable = analyze_commits(match: 'ios/beta*')

After running, the following values are available via lane_context[SharedValues::KEY]:

Access them like this:

next_version = lane_context[SharedValues::RELEASE_NEXT_VERSION]

Generates formatted release notes from commits since the last version. Must run after analyze_commits.

• Parses all commits since the last version
• Groups commits by type (feat, fix, docs, refactor, etc.)
• Creates formatted release notes in markdown, slack, or plain text

Example:

notes = conventional_changelog(format: 'slack', title: 'Android Alpha')

Build separate changelogs for different platforms:

# Only analyze iOS-scoped commits
analyze_commits(match: 'ios/v*', include_scopes: ['ios'])

# Ignore Android-specific commits
analyze_commits(match: 'v*', ignore_scopes: ['android', 'windows'])

Map additional commit types to version bumps:

analyze_commits(
  match: 'v*',
  releases: { fix: 'patch', feat: 'minor', refactor: 'patch' }
)

Prevent breaking change markers from triggering major version bumps. The ! suffix and BREAKING CHANGE: in the commit body will be ignored for both version bumping and changelog output:

analyze_commits(match: 'v*', ignore_breaking_changes: true)
notes = conventional_changelog(format: 'markdown')

notes = conventional_changelog(format: 'plain', display_links: false)
upload_to_testflight(changelog: notes)

# Run all tests and linting
bundle exec rake

# Run only tests
bundle exec rake spec

# Run only linting
bundle exec rake rubocop

If you have any issues or feature requests, please open an issue on GitHub.

Jiri Otahal