From Commit to Release: Automating GitHub Workflows

This documentation describes an automated GitHub workflow system that handles pull request labelling and automated releases for both development and production environments. The system uses branch naming conventions to automatically label PRs, generates release notes, and manages versioning.

How It Works

PR Labeling System

• Monitors for new pull requests
• Analyses branch names to apply appropriate labels
• Uses configured patterns in pr-labeler.yml
• Labels determine how changes are categorised in releases

Release Management

1. Development Releases
   1. Triggered by pushes to dev branch
   2. Creates draft releases
   3. Maintains development version tracking
2. Production Releases:
   1. Triggered by pushes to main branch
   2. Automatically publishes releases
   3. Includes hotfix detection
3. Version Resolution : Automatically determines version numbers based on PR labels
   1. breaking → Major version bump
   2. feature, fix → Minor version bump
   3. chore, etc. → Patch version bump

Setup Instructions

Prerequisites

• GitHub Personal Access Token (classic) or Organisation Token
• Token Must have private repository read, write and workflow permissions

Required Files Structure

📦root
┣📦.github
┣ 📂workflows
┃ ┣ 📜pr-labeler.yml # PR labeling workflow
┃ ┣ 📜release-dev.yml # Development release workflow
┃ ┗ 📜release-prod.yml # Production release workflow
┣ 📜pr-labeler.yml # Label configuration
┗ 📜release-drafter.yml # Release configuration

Customising Templates

Modifying PR Labels

To add or modify label patterns, edit .github/pr-labeler.yml:

# Add new label
enhancement: ["enhance/*", "improvement/*"]

# Modify existing label
feature:
  - "feature/*"
  - "feat/*"
  - "new/*"

Customising Release Notes

Edit .github/release-drafter.yml:

1. Change Categories:

categories:
- title: '🚀 New Features' # Modified emoji and title

labels:
- 'feature'
- 'enhancement'
- title: '🔧 Improvements' # New category

labels:
- 'improvement'

2. Modify Change Format:

# Add commit details
change-template: '- $TITLE (#$NUMBER)\n $COMMIT_MESSAGES'

3. Custom Release Template:

template: |

## Release v$RESOLVED_VERSION
### What's Changed
$CHANGES

### Contributors
$CONTRIBUTORS

### Additional Notes
_Released on: $RELEASE_DATE_

Branch Naming Convention

<type>/<description>

Types:

feature/ → New features (minor version)

fix/ → Bug fixes (minor version)

chore/ → Maintenance (patch version)

breaking/ → Breaking changes (major version)

Examples:

feature/user-authentication

fix/login-timeout

chore/update-dependencies

breaking/api-v2

Development Flow

1. Create Feature Branch:

git checkout -b feature/new-login

2. Make Changes and Commit:

git commit -m "feat: Add OAuth login"

git commit -m "Add password reset"

3. Create Pull Request:

• Title: "Add new authentication system"
• Branch will automatically be labeled as "feature"

4. Merge Process:

• Dev: Creates draft release
• Main: Publishes release automatically

Troubleshooting

Common Issues

1. PR Labels Not Applied

• Verify branch name matches patterns in pr-labeler.yml
• Check workflow permissions in GitHub
• Verify TOKEN secret is configured

2. Release Not Generated

• Check branch matches workflow trigger (dev or main)
• Review workflow run logs for errors
• .github dir with all files needs to be in both (dev and main)

3. Incorrect Version Numbers

• Check PR labels match version-resolver configuration
• Verify label application in PR
• Review version resolution rules

Support & Future Improvements

• Review GitHub Actions logs
• https://help.shortcut.com/hc/en-us/articles/207540323-Using-Branches-and-Pull-Requests-with-the-Shortcut-VCS-Integrations

Thank You