Skip to content

Backend Deployment - Release Please Setup for GitHub Actions

This guide walks you through integrating Release Please into your existing GitHub Actions deployment pipeline for automated release management, versioning, and changelog generation.

Prerequisites

This guide assumes you've already completed the AWS EC2 GitHub Actions Deployment Setup. If you haven't set up automated deployments yet, complete that guide first.

Overview

Release Please automates the tedious parts of releasing software:

  • Automatic version bumping based on conventional commits
  • Changelog generation from commit messages
  • GitHub release creation with proper prerelease/release targeting
  • Deployment triggering to the correct environments

Current vs. Enhanced Flow

Before Release Please:

Push to main → Build images → Manual release creation → Deploy

After Release Please:

Push to main → Build images → Release Please analysis → Automated release → Deploy

Deployment Strategy

  • Prerelease → Automatically deploys to stage environment
  • Full release → Automatically deploys to production environment
  • Manual promotion from prerelease to full release triggers production deployment

1. Understanding Conventional Commits

Release Please relies on conventional commit messages to determine version bumps and generate changelogs.

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types and Version Impact

Type Description Version Bump Example
feat New feature Minor (0.1.0 → 0.2.0) feat: add user authentication
fix Bug fix Patch (0.1.0 → 0.1.1) fix: resolve database timeout
perf Performance improvement Patch perf: optimize query performance
docs Documentation only None docs: update API documentation
style Code style/formatting None style: fix linting errors
refactor Code refactoring None refactor: simplify auth logic
test Tests only None test: add user registration tests
chore Maintenance tasks None chore: update dependencies
ci CI configuration None ci: update build workflow
build Build system changes None build: update Docker config
revert Revert previous commit Patch revert: undo broken feature

Breaking Changes

To trigger a major version bump (1.0.0 → 2.0.0):

# Option 1: Add ! after type
feat!: redesign authentication system

BREAKING CHANGE: All existing auth tokens will be invalidated.

# Option 2: Include BREAKING CHANGE in footer
feat: update API response format

BREAKING CHANGE: Response structure changed from {data} to {result}.

Commit Examples

# Minor version bump (new features)
git commit -m "feat: add password reset functionality"
git commit -m "feat(auth): implement OAuth2 integration"

# Patch version bump (fixes)
git commit -m "fix: resolve email validation bug"
git commit -m "fix(api): handle null response gracefully"

# No version bump (documentation/chores)
git commit -m "docs: update deployment guide"
git commit -m "chore: update Python dependencies"

# Major version bump (breaking changes)
git commit -m "feat!: migrate to new database schema

BREAKING CHANGE: Database migration required. See upgrade guide."

2. Installation and Setup

2.1 Create Release Please Configuration

Create release-please-config.json in your repository root:

{
  "packages": {
    ".": {
      "package-name": "mow-backend",
      "release-type": "simple",
      "include-component-in-tag": false,
      "include-v-in-tag": true,
      "prerelease": true,
      "initial-version": "1.0.0",
      "changelog-types": [
        {
          "type": "feat",
          "section": "Features"
        },
        {
          "type": "fix",
          "section": "Bug Fixes"
        },
        {
          "type": "perf",
          "section": "Performance Improvements"
        },
        {
          "type": "revert",
          "section": "Reverts"
        },
        {
          "type": "docs",
          "section": "Documentation"
        },
        {
          "type": "style",
          "section": "Styles"
        },
        {
          "type": "chore",
          "section": "Miscellaneous Chores",
          "hidden": true
        },
        {
          "type": "refactor",
          "section": "Code Refactoring"
        },
        {
          "type": "test",
          "section": "Tests"
        },
        {
          "type": "build",
          "section": "Build System"
        },
        {
          "type": "ci",
          "section": "Continuous Integration"
        }
      ]
    }
  }
}

2.2 Create Release Manifest

Create .release-please-manifest.json with your current version:

{
  ".": "1.0.0"
}

Set Your Current Version

Replace "1.0.0" with your actual current release version. This tells Release Please where to start.

2.3 Create Personal Access Token

Release Please needs a Personal Access Token (PAT) to trigger deployment workflows:

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Generate new token with these permissions:
  3. Repository access: Select your repository
  4. Contents: Read and write
  5. Pull requests: Write
  6. Metadata: Read
  7. Copy the token and save it securely
  8. Add as repository secret:
  9. Go to your repository → Settings → Secrets and variables → Actions
  10. New repository secret
  11. Name: RELEASE_PLEASE_TOKEN
  12. Value: Your token

2.4 Set Up Conventional Commit Validation (Optional)

Create a git hook to validate commit messages locally:

# Create the validation script
cat > scripts/validate-commit.sh << 'EOF'
#!/bin/bash
# Conventional Commit Message Validator

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Read commit message from file
commit_msg_file=$1
if [ -f "$commit_msg_file" ]; then
    commit_message=$(cat "$commit_msg_file")
else
    echo -e "${RED}Error: No commit message file provided${NC}"
    exit 1
fi

# Skip validation for merge commits
if echo "$commit_message" | grep -q "^Merge "; then
    exit 0
fi

# Skip validation for revert commits (GitHub format)
if echo "$commit_message" | grep -q "^Revert "; then
    exit 0
fi

# Valid conventional commit types
valid_types="feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert"

# Conventional commit regex
conventional_regex="^($valid_types)(\(.+\))?\!?:\s.{1,72}"

if echo "$commit_message" | grep -qE "$conventional_regex"; then
    echo -e "${GREEN}✓ Commit message follows conventional commit format${NC}"

    # Check for breaking change indicators
    if echo "$commit_message" | grep -q "BREAKING CHANGE:\|!:"; then
        echo -e "${YELLOW}⚠ Breaking change detected - will trigger major version bump${NC}"
    fi

    exit 0
else
    echo -e "${RED}✗ Commit message does not follow conventional commit format${NC}"
    echo ""
    echo -e "${YELLOW}Expected format:${NC}"
    echo "  <type>[optional scope]: <description>"
    echo ""
    echo -e "${YELLOW}Valid types:${NC}"
    echo "  feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert"
    echo ""
    echo -e "${YELLOW}Examples:${NC}"
    echo "  feat: add user authentication"
    echo "  fix: resolve database connection issue"
    echo "  feat(api): add new endpoint for user profiles"
    echo "  fix!: change API response format"
    echo ""
    echo -e "${YELLOW}Your commit message:${NC}"
    echo "  $commit_message"

    exit 1
fi

exit 0
EOF

# Make it executable
chmod +x scripts/validate-commit.sh

# Install as git hook (optional)
cp scripts/validate-commit.sh .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

3. Update GitHub Actions Workflows

3.1 Create Release Please Workflow

Create .github/workflows/release-please.yml:

name: Release Please

on:
  workflow_run:
    workflows: ["Build & Push Images"]
    types: [completed]
    branches: [main]
  workflow_dispatch: {}

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-24.04
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    outputs:
      release-created: ${{ steps.release.outputs.release_created }}
      tag-name: ${{ steps.release.outputs.tag_name }}
      prerelease: ${{ steps.release.outputs.prerelease }}
    steps:
      - name: Release Please
        uses: googleapis/release-please-action@v4
        id: release
        with:
          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

3.2 Update Build Workflow

Your existing build-images.yml should already be set up correctly to trigger on pushes to main. No changes needed.

3.3 Update Deploy Workflows

Your existing deploy-stage.yml and deploy-prod.yml should already be configured to trigger on:

  • Stage: types: [prereleased]
  • Production: types: [released]

If they're not set up this way, update the triggers:

# In deploy-stage.yml
on:
  release:
    types: [prereleased]  # Only prereleases
  workflow_dispatch:
    inputs:
      tag:
        description: 'Release tag to deploy'
        required: true
        type: string

# In deploy-prod.yml  
on:
  release:
    types: [released]  # Only full releases (not prereleases)
  workflow_dispatch:
    inputs:
      tag:
        description: 'Release tag to deploy'
        required: true
        type: string

4. Enhanced Release Flow

4.1 Development Process

  1. Develop features using conventional commits:
   git checkout -b feature/user-profiles
   # Make changes
   git commit -m "feat: add user profile management"
   git commit -m "test: add user profile tests"
   git commit -m "docs: update API documentation"

  1. Create pull request to main branch

  2. Merge pull request (rebase merge):

   # GitHub will rebase individual commits maintaining their messages:
   # "feat: add user profile management"
   # "test: add user profile tests" 
   # "docs: update API documentation"

4.2 Automated Release Process

  1. Push to main triggers:
  2. Build & Push Images workflow

  3. Release Please workflow (after build completes)

  4. Release Please analyzes commits and either:

  5. Creates new release PR (if there are releasable changes)
  6. Updates existing release PR (if one exists)

  7. Does nothing (if only docs/chores since last release)

  8. Release PR contains:

  9. Version bump based on conventional commits
  10. Auto-generated changelog
  11. Updated manifest file

4.3 Stage Deployment

  1. Review the release PR created by Release Please
  2. Merge the release PR:
  3. This creates a GitHub prerelease (due to "prerelease": true config)

  4. Prerelease automatically triggers stage deployment

  5. Monitor deployment in GitHub Actions

  6. Test in stage environment

4.4 Production Deployment

When you're ready to deploy to production:

  1. Go to GitHub Releases
  2. Find your prerelease (e.g., v1.2.0)
  3. Click "Edit release"
  4. Uncheck "This is a pre-release"
  5. Click "Update release"

This converts the prerelease to a full release, which automatically triggers production deployment.

5. Release Types and Strategies

5.1 Regular Releases

# Example commit sequence leading to v1.2.0
git commit -m "feat: add export functionality"      # Minor bump
git commit -m "fix: resolve pagination bug"        # Patch bump  
git commit -m "docs: update export guide"          # No bump

# Release Please creates: v1.2.0
# (previous version was v1.1.3)

5.2 Breaking Changes

For major version bumps:

git commit -m "feat!: redesign API authentication

BREAKING CHANGE: All existing API keys will be invalidated. 
Users must regenerate keys after upgrade."

# This creates v2.0.0 (from v1.x.x)

6. Troubleshooting

6.1 Release Please Not Creating PR

Symptoms: No release PR appears after pushing conventional commits

Causes & Solutions:

  1. No releasable commits: Only docs, chore, etc. since last release

  2. Solution: Add a feat or fix commit

  3. Workflow not triggering: Release Please didn't run after build

  4. Check: GitHub Actions tab for failed/skipped workflows

  5. Solution: Ensure build workflow completed successfully

  6. Configuration errors: Invalid config files

  7. Check: JSON syntax in config files

  8. Solution: Validate JSON and fix syntax errors

  9. Token permissions: PAT doesn't have required permissions

  10. Solution: Recreate token with Contents: Write and Pull requests: Write

6.2 Deployment Not Triggering

Symptoms: Release created but no deployment workflow runs

Causes & Solutions:

  1. Wrong release type: Full release created instead of prerelease
  2. Check: GitHub release page shows "Latest" not "Pre-release"

  3. Solution: Edit release and check "This is a pre-release"

  4. Workflow trigger mismatch: Deploy workflows expect different event types

  5. Check: Workflow on: triggers match release types

  6. Solution: Update triggers to prereleased and released

  7. Token limitations: Default GITHUB_TOKEN can't trigger workflows

  8. Solution: Ensure Release Please uses PAT (RELEASE_PLEASE_TOKEN)

6.3 Wrong Version Generated

Symptoms: Release Please creates unexpected version number

Causes & Solutions:

  1. Commit type confusion: Using wrong conventional commit types

  2. Solution: Review commit types and their version impact

  3. Manifest out of sync: .release-please-manifest.json has wrong version

  4. Solution: Update manifest to match actual latest release

  5. Missing breaking change syntax: Major changes not properly marked

  6. Solution: Use ! or BREAKING CHANGE: for breaking changes

6.4 Changelog Issues

Symptoms: Changelog missing or incorrectly formatted

Causes & Solutions:

  1. Hidden commit types: Some commit types marked as hidden
  2. Check: changelog-types configuration

  3. Solution: Remove "hidden": true for types you want visible

  4. Commit message format: Commits don't follow conventional format

  5. Solution: Use commit validation hook to catch formatting errors

7. Best Practices

7.1 Commit Message Guidelines

  • Be descriptive but concise: feat: add user authentication not feat: stuff
  • Use imperative mood: fix: resolve bug not fixed bug
  • Include scope when helpful: feat(api): add new endpoint
  • Explain breaking changes: Always include BREAKING CHANGE: details

7.2 Release Management

  • Review release PRs carefully: Check version bump and changelog
  • Test prereleases thoroughly: Use stage environment validation
  • Coordinate major releases: Plan breaking changes with team
  • Keep releases small: Frequent small releases over large ones

7.3 Emergency Procedures

Hotfix Process: 1. Create hotfix branch from release tag 2. Make minimal fix with conventional commit
3. Fast-track PR review and merge 4. Release Please creates patch release 5. Monitor deployment closely

Rollback Process: 1. Create new release pointing to previous working commit 2. Use revert: commit message format 3. Deploy as normal release process

8. Monitoring and Maintenance

8.1 Regular Tasks

  • Monitor release PRs: Check for stale or conflicting PRs
  • Update dependencies: Keep Release Please action up to date
  • Review commit patterns: Ensure team follows conventional commits
  • Validate deployments: Confirm stage/prod targeting works correctly

8.2 Metrics to Track

  • Release frequency: How often are you releasing?
  • Lead time: Time from commit to production
  • Deployment success rate: Percentage of successful deployments
  • Rollback frequency: How often do you need to rollback?

8.3 Team Education

  • Conventional commits training: Ensure all developers understand format
  • Release process documentation: Keep this guide up to date
  • Deployment troubleshooting: Share common issues and solutions

9. Advanced Configuration

9.1 Multiple Release Strategies

For different release cadences:

{
  "packages": {
    ".": {
      "release-type": "simple",
      "prerelease": true,
      "versioning-strategy": "default"
    }
  }
}

9.2 Custom Changelog Sections

Add custom commit types:

{
  "changelog-types": [
    {
      "type": "security",
      "section": "Security Fixes"
    },
    {
      "type": "deps", 
      "section": "Dependencies"
    }
  ]
}

9.3 Release Branch Strategy

For maintaining multiple versions:

{
  "release-search-depth": 400,
  "separate-pull-requests": true
}

10. Migration from Manual Releases

If you're migrating from manual release creation:

10.1 Audit Current Releases

  1. Review existing releases for version numbering consistency
  2. Update manifest to match latest actual release
  3. Clean up any draft releases that might confuse Release Please

10.2 Transition Plan

  1. Week 1: Install Release Please, create first automated release PR
  2. Week 2: Test prerelease → stage deployment flow
  3. Week 3: Test full release → production deployment flow
  4. Week 4: Full team adoption of conventional commits

10.3 Team Training

  • Conventional commits workshop: Hands-on training session
  • Release process walkthrough: Demonstrate new workflow
  • Git hook installation: Help developers set up commit validation

Conclusion

Release Please integration transforms your deployment pipeline from manual to fully automated:

  • Developers focus on code: No more manual version bumping or changelog writing
  • Consistent releases: Automated versioning based on conventional commits
  • Safe deployments: Prerelease testing before production
  • Clear history: Auto-generated changelogs provide release visibility
  • Flexible promotion: Easy stage-to-production promotion workflow

The combination of conventional commits, automated releases, and environment-specific deployments creates a robust, scalable release management system that grows with your team and project complexity.

For questions or issues, refer to the Release Please documentation or review the troubleshooting section above.

< Backend Deployment - Verify Dev Deployment

Next: Backend Operations - AWS Inventory and Cleanup >