From 635c53da8b7abf8136c3471e6bf8d522a2662762 Mon Sep 17 00:00:00 2001 From: Anmol Nagpal Date: Fri, 19 Sep 2025 12:16:11 -0400 Subject: [PATCH] =?UTF-8?q?feat(GH)=20adding=20new=20workflow=20for=20?= =?UTF-8?q?=F0=9F=9A=80=20CloudDrove=E2=80=93Conventional-Commits-Standard?= =?UTF-8?q?L?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../conventional-commits-example.yml | 47 +++ .../workflows/conventional-commits-lint.yml | 54 +++ .../conventional-commits-pr-title.yml | 47 +++ .../conventional-commits-release.yml | 124 ++++++ README.md | 1 + ....1.conventional-commits-quick-reference.md | 165 ++++++++ docs/30.conventional-commits.md | 356 ++++++++++++++++++ 7 files changed, 794 insertions(+) create mode 100644 .github/workflows/conventional-commits-example.yml create mode 100644 .github/workflows/conventional-commits-lint.yml create mode 100644 .github/workflows/conventional-commits-pr-title.yml create mode 100644 .github/workflows/conventional-commits-release.yml create mode 100644 docs/30.1.conventional-commits-quick-reference.md create mode 100644 docs/30.conventional-commits.md diff --git a/.github/workflows/conventional-commits-example.yml b/.github/workflows/conventional-commits-example.yml new file mode 100644 index 00000000..e4406c6f --- /dev/null +++ b/.github/workflows/conventional-commits-example.yml @@ -0,0 +1,47 @@ +--- +name: 📋 Conventional Commits Example + +# This is an example workflow showing how to use all three conventional commits workflows +# Copy this to your repository and customize as needed + +on: + pull_request: + branches: [ main, master ] + types: [opened, edited, reopened, synchronize] + push: + branches: [ main, master ] + +jobs: + # Validate commit messages in PRs + validate-commits: + if: github.event_name == 'pull_request' + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-lint.yml@master + with: + allowed_types: "feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert" + scopes: "api,ui,docs,config,deploy,infra" + breaking_change_token: "BREAKING CHANGE" + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # Validate PR titles + validate-pr-title: + if: github.event_name == 'pull_request' + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-pr-title.yml@master + with: + allowed_types: "feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert" + scopes: "api,ui,docs,config,deploy,infra" + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # Create releases on push to main/master + release: + if: github.event_name == 'push' + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-release.yml@master + with: + target_branch: master + initial_version: "1.0.0" + prerelease: false + changelog_file: "CHANGELOG.md" + version_prefix: "v" + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/conventional-commits-lint.yml b/.github/workflows/conventional-commits-lint.yml new file mode 100644 index 00000000..cb2d8e41 --- /dev/null +++ b/.github/workflows/conventional-commits-lint.yml @@ -0,0 +1,54 @@ +--- +name: 🔍 Conventional Commits Lint + +on: + workflow_call: + inputs: + allowed_types: + required: false + type: string + default: "feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert" + description: 'Comma-separated list of allowed commit types' + scopes: + required: false + type: string + default: "" + description: 'Comma-separated list of allowed scopes (optional)' + breaking_change_token: + required: false + type: string + default: "BREAKING CHANGE" + description: 'Token to identify breaking changes' + secrets: + GITHUB_TOKEN: + required: false + description: 'GitHub token for private repositories' + +jobs: + conventional-commits-check: + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + + steps: + - name: đŸ“Ļ Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 0 + token: ${{ secrets.GITHUB_TOKEN }} + + - name: 🔍 Validate Conventional Commits + uses: webiny/action-conventional-commits@v1.3.0 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + allowed-commit-types: ${{ inputs.allowed_types }} + scopes: ${{ inputs.scopes }} + breaking-change-token: ${{ inputs.breaking_change_token }} + + - name: 📋 Summary + run: | + echo "✅ All commit messages follow Conventional Commits specification" + echo "📝 Allowed types: ${{ inputs.allowed_types }}" + if [ -n "${{ inputs.scopes }}" ]; then + echo "đŸŽ¯ Allowed scopes: ${{ inputs.scopes }}" + fi + echo "đŸ’Ĩ Breaking change token: ${{ inputs.breaking_change_token }}" diff --git a/.github/workflows/conventional-commits-pr-title.yml b/.github/workflows/conventional-commits-pr-title.yml new file mode 100644 index 00000000..f073a74b --- /dev/null +++ b/.github/workflows/conventional-commits-pr-title.yml @@ -0,0 +1,47 @@ +--- +name: 📝 PR Title Conventional Commits Check + +on: + workflow_call: + inputs: + allowed_types: + required: false + type: string + default: "feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert" + description: 'Comma-separated list of allowed commit types' + scopes: + required: false + type: string + default: "" + description: 'Comma-separated list of allowed scopes (optional)' + secrets: + GITHUB_TOKEN: + required: false + description: 'GitHub token for private repositories' + +jobs: + pr-title-check: + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + + steps: + - name: đŸ“Ļ Checkout repository + uses: actions/checkout@v5 + with: + token: ${{ secrets.GITHUB_TOKEN }} + + - name: 🔍 Validate PR Title + uses: Namchee/conventional-pr@v0.6.0 + with: + access_token: ${{ secrets.GITHUB_TOKEN }} + allowed_types: ${{ inputs.allowed_types }} + scopes: ${{ inputs.scopes }} + + - name: 📋 Summary + run: | + echo "✅ PR title follows Conventional Commits specification" + echo "📝 Allowed types: ${{ inputs.allowed_types }}" + if [ -n "${{ inputs.scopes }}" ]; then + echo "đŸŽ¯ Allowed scopes: ${{ inputs.scopes }}" + fi + echo "📄 PR Title: ${{ github.event.pull_request.title }}" diff --git a/.github/workflows/conventional-commits-release.yml b/.github/workflows/conventional-commits-release.yml new file mode 100644 index 00000000..ef6c0e9b --- /dev/null +++ b/.github/workflows/conventional-commits-release.yml @@ -0,0 +1,124 @@ +--- +name: 🚀 Conventional Commits Release + +on: + workflow_call: + inputs: + target_branch: + required: true + type: string + default: master + description: 'Target branch for releases' + initial_version: + required: false + type: string + default: "1.0.0" + description: 'Initial version if no tags exist' + prerelease: + required: false + type: boolean + default: false + description: 'Create prerelease versions' + changelog_file: + required: false + type: string + default: "CHANGELOG.md" + description: 'Changelog file path' + version_prefix: + required: false + type: string + default: "v" + description: 'Version prefix (e.g., v for v1.0.0)' + secrets: + GITHUB_TOKEN: + required: true + description: 'GitHub token for creating releases and tags' + +jobs: + conventional-release: + runs-on: ubuntu-latest + if: github.event_name == 'push' && github.ref == format('refs/heads/{0}', inputs.target_branch) + + steps: + - name: đŸ“Ļ Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 0 + token: ${{ secrets.GITHUB_TOKEN }} + + - name: 🧩 Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y jq + + - name: 🔍 Determine next version + id: version + uses: smlx/ccv@v0.9.0 + with: + write-tag: false + initial-version: ${{ inputs.initial_version }} + prerelease: ${{ inputs.prerelease }} + version-prefix: ${{ inputs.version_prefix }} + + - name: 📝 Generate changelog + id: changelog + uses: requarks/changelog-action@v1 + with: + token: ${{ secrets.GITHUB_TOKEN }} + tag: ${{ steps.version.outputs.version }} + includeInvalidCommits: false + writeToFile: true + changelogFilePath: ${{ inputs.changelog_file }} + includeRefIssues: true + useGitmojis: true + reverseOrder: false + + - name: 🏷ī¸ Create and push tag + if: steps.version.outputs.version != '' + run: | + git config user.name "clouddrove-ci" + git config user.email "84795582+clouddrove-ci@users.noreply.github.com" + git tag ${{ steps.version.outputs.version }} + git push origin ${{ steps.version.outputs.version }} + + - name: 🚀 Create GitHub release + if: steps.version.outputs.version != '' + uses: ncipollo/release-action@v1 + with: + token: ${{ secrets.GITHUB_TOKEN }} + tag: ${{ steps.version.outputs.version }} + name: ${{ steps.version.outputs.version }} + allowUpdates: true + draft: false + prerelease: ${{ inputs.prerelease }} + makeLatest: true + body: | + ${{ steps.changelog.outputs.changes }} + + **Release Type:** ${{ steps.version.outputs.version_type }} + + [Compare changes](https://github.com/${{ github.repository }}/compare/${{ steps.version.outputs.previous_version }}...${{ steps.version.outputs.version }}) + + - name: 💾 Commit changelog + if: steps.version.outputs.version != '' + uses: stefanzweifel/git-auto-commit-action@v6 + with: + branch: ${{ inputs.target_branch }} + commit_user_name: clouddrove-ci + commit_user_email: 84795582+clouddrove-ci@users.noreply.github.com + commit_author: "CloudDrove CI <84795582+clouddrove-ci@users.noreply.github.com>" + commit_message: 'docs: update ${{ inputs.changelog_file }} for ${{ steps.version.outputs.version }}' + file_pattern: ${{ inputs.changelog_file }} + + - name: 📋 Release summary + run: | + if [ -n "${{ steps.version.outputs.version }}" ]; then + echo "✅ Released ${{ steps.version.outputs.version }} successfully" + echo "🏷ī¸ Version type: ${{ steps.version.outputs.version_type }}" + echo "📝 Changelog updated: ${{ inputs.changelog_file }}" + if [ "${{ inputs.prerelease }}" == "true" ]; then + echo "🔖 This is a prerelease" + fi + else + echo "ℹī¸ No new version to release" + fi diff --git a/README.md b/README.md index e29ae16d..25d59a0e 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,7 @@ Above example is just a simple example to call workflow from github shared workf 27. [Terraform Workflow](./docs/27.terraform_workflow.md) 28. [Terraform Module Tag Release Workflow (Shared)](./docs/28.tf-monorepo-tag-release.md) 29. [Terraform PR Plan Diff workflow](./docs/29.tf-pr-checks.md) +30. [Conventional Commits Workflows](./docs/30.conventional-commits.md) ## Feedback If you come accross a bug or have any feedback, please log it in our [issue tracker](https://github.com/clouddrove/github-shared-workflows/issues), or feel free to drop us an email at [hello@clouddrove.com](mailto:hello@clouddrove.com). diff --git a/docs/30.1.conventional-commits-quick-reference.md b/docs/30.1.conventional-commits-quick-reference.md new file mode 100644 index 00000000..3aa85c8c --- /dev/null +++ b/docs/30.1.conventional-commits-quick-reference.md @@ -0,0 +1,165 @@ +# Conventional Commits Quick Reference + +A quick reference guide for developers using Conventional Commits in CloudDrove projects. + +## Commit Message Format + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +## Commit Types + +| Type | Description | Version Bump | +|------|-------------|--------------| +| `feat` | New feature | Minor | +| `fix` | Bug fix | Patch | +| `docs` | Documentation | Patch | +| `style` | Code style (formatting, etc.) | Patch | +| `refactor` | Code refactoring | Patch | +| `perf` | Performance improvement | Patch | +| `test` | Adding/updating tests | Patch | +| `chore` | Maintenance tasks | Patch | +| `ci` | CI/CD changes | Patch | +| `build` | Build system changes | Patch | +| `revert` | Reverting changes | Patch | + +## Breaking Changes + +Use `!` after type/scope or include `BREAKING CHANGE:` in footer: + +``` +feat!: redesign API +# or +feat: redesign API + +BREAKING CHANGE: API endpoints have changed +``` + +## Examples + +### Basic Commits +```bash +feat: add user authentication +fix: resolve memory leak in cache +docs: update API documentation +style: format code with prettier +refactor: simplify user service +perf: optimize database queries +test: add unit tests for auth +chore: update dependencies +ci: add automated testing +build: update webpack config +``` + +### With Scopes +```bash +feat(api): add user authentication +fix(ui): resolve button click issue +docs(readme): update installation guide +style(components): format with prettier +refactor(services): simplify user service +perf(database): optimize queries +test(auth): add unit tests +chore(deps): update dependencies +ci(github): add automated testing +build(webpack): update configuration +``` + +### With Body and Footer +```bash +feat(api): add user authentication + +Implement JWT-based authentication with login and registration endpoints. +Includes password hashing and token validation. + +Closes #123 +``` + +### Breaking Changes +```bash +feat!: redesign user API + +BREAKING CHANGE: The user API endpoints have been completely redesigned. +All existing API calls will need to be updated. + +Migration guide: https://docs.example.com/migration +``` + +## PR Title Format + +PR titles should follow the same format as commit messages: + +``` +feat: add user authentication system +fix(ui): resolve button click issue +docs: update API documentation +``` + +## Common Scopes + +- `api` - API changes +- `ui` - User interface changes +- `docs` - Documentation changes +- `config` - Configuration changes +- `deploy` - Deployment changes +- `infra` - Infrastructure changes +- `test` - Test-related changes +- `build` - Build system changes + +## Best Practices + +1. **Use imperative mood**: "add feature" not "added feature" +2. **Keep description under 50 characters** +3. **Capitalize first letter of description** +4. **Don't end description with period** +5. **Use body to explain what and why, not how** +6. **Reference issues in footer** +7. **Be consistent with scopes across the project** + +## Quick Commands + +### Check commit format +```bash +# Validate your commit message +echo "feat: add new feature" | npx commitlint +``` + +### Generate changelog +```bash +# Generate changelog from commits +npx conventional-changelog -p angular -i CHANGELOG.md -s +``` + +### Bump version +```bash +# Bump version based on commits +npx standard-version +``` + +## Troubleshooting + +### Commit validation fails +- Check format: `type: description` +- Ensure type is allowed +- Verify scope is allowed (if configured) + +### PR title validation fails +- Use same format as commits +- Check type and scope are allowed + +### Release not created +- Ensure commits are conventional format +- Check GitHub token permissions +- Verify commits since last release + +## Resources + +- [Conventional Commits Specification](https://www.conventionalcommits.org/) +- [Commitizen](https://github.com/commitizen/cz-cli) - Interactive commit tool +- [Commitlint](https://github.com/conventional-changelog/commitlint) - Commit message linter +- [Standard Version](https://github.com/conventional-changelog/standard-version) - Version bumping tool diff --git a/docs/30.conventional-commits.md b/docs/30.conventional-commits.md new file mode 100644 index 00000000..834baa12 --- /dev/null +++ b/docs/30.conventional-commits.md @@ -0,0 +1,356 @@ +# Conventional Commits Workflows + +This document describes the GitHub workflows for implementing [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification in CloudDrove projects. These workflows help maintain consistent commit messages, automate versioning, and generate changelogs based on commit conventions. + +## Overview + +The Conventional Commits specification provides a standardized format for commit messages that enables automated tooling and clear communication about changes. Our workflows implement three key aspects: + +1. **Commit Message Validation** - Ensures all commits follow the conventional format +2. **PR Title Validation** - Validates pull request titles follow conventional format +3. **Automated Release Management** - Generates versions and changelogs based on commit types + +## Workflows + +### 1. Conventional Commits Lint + +**File:** `.github/workflows/conventional-commits-lint.yml` + +Validates that all commit messages in a pull request follow the Conventional Commits specification. + +#### Features + +- ✅ Validates commit message format +- đŸŽ¯ Configurable allowed commit types +- 🔍 Optional scope validation +- đŸ’Ĩ Breaking change detection +- 📋 Detailed validation feedback + +#### Usage + +```yaml +name: Validate Commits + +on: + pull_request: + branches: [ main, master ] + +jobs: + conventional-commits: + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-lint.yml@master + with: + allowed_types: "feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert" + scopes: "api,ui,docs,config" # Optional + breaking_change_token: "BREAKING CHANGE" + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +#### Inputs + +| Input | Required | Default | Description | +|-------|----------|---------|-------------| +| `allowed_types` | No | `feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert` | Comma-separated list of allowed commit types | +| `scopes` | No | `""` | Comma-separated list of allowed scopes (optional) | +| `breaking_change_token` | No | `BREAKING CHANGE` | Token to identify breaking changes | + +#### Commit Types + +| Type | Description | Example | +|------|-------------|---------| +| `feat` | A new feature | `feat: add user authentication` | +| `fix` | A bug fix | `fix: resolve memory leak in cache` | +| `docs` | Documentation changes | `docs: update API documentation` | +| `style` | Code style changes | `style: format code with prettier` | +| `refactor` | Code refactoring | `refactor: simplify user service` | +| `perf` | Performance improvements | `perf: optimize database queries` | +| `test` | Adding or updating tests | `test: add unit tests for auth service` | +| `chore` | Maintenance tasks | `chore: update dependencies` | +| `ci` | CI/CD changes | `ci: add automated testing` | +| `build` | Build system changes | `build: update webpack configuration` | +| `revert` | Reverting changes | `revert: revert "feat: add new feature"` | + +### 2. PR Title Conventional Commits Check + +**File:** `.github/workflows/conventional-commits-pr-title.yml` + +Validates that pull request titles follow the Conventional Commits format. + +#### Features + +- ✅ Validates PR title format +- đŸŽ¯ Configurable allowed commit types +- 🔍 Optional scope validation +- 📋 Clear validation feedback + +#### Usage + +```yaml +name: Validate PR Title + +on: + pull_request: + types: [opened, edited, reopened, synchronize] + +jobs: + pr-title-check: + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-pr-title.yml@master + with: + allowed_types: "feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert" + scopes: "api,ui,docs,config" # Optional + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +#### Inputs + +| Input | Required | Default | Description | +|-------|----------|---------|-------------| +| `allowed_types` | No | `feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert` | Comma-separated list of allowed commit types | +| `scopes` | No | `""` | Comma-separated list of allowed scopes (optional) | + +### 3. Conventional Commits Release + +**File:** `.github/workflows/conventional-commits-release.yml` + +Automatically creates releases and generates changelogs based on conventional commits. + +#### Features + +- 🚀 Automatic version bumping based on commit types +- 📝 Automated changelog generation +- 🏷ī¸ Git tag creation +- đŸ“Ļ GitHub release creation +- 💾 Automatic changelog commits + +#### Usage + +```yaml +name: Release + +on: + push: + branches: [ main, master ] + +jobs: + release: + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-release.yml@master + with: + target_branch: master + initial_version: "1.0.0" + prerelease: false + changelog_file: "CHANGELOG.md" + version_prefix: "v" + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +#### Inputs + +| Input | Required | Default | Description | +|-------|----------|---------|-------------| +| `target_branch` | Yes | `master` | Target branch for releases | +| `initial_version` | No | `1.0.0` | Initial version if no tags exist | +| `prerelease` | No | `false` | Create prerelease versions | +| `changelog_file` | No | `CHANGELOG.md` | Changelog file path | +| `version_prefix` | No | `v` | Version prefix (e.g., v for v1.0.0) | + +#### Version Bumping Rules + +| Commit Type | Version Bump | Example | +|-------------|--------------|---------| +| `feat` | Minor | `1.0.0` → `1.1.0` | +| `fix` | Patch | `1.0.0` → `1.0.1` | +| `feat!` or `BREAKING CHANGE` | Major | `1.0.0` → `2.0.0` | +| `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build` | Patch | `1.0.0` → `1.0.1` | + +## Complete Example + +Here's a complete example of how to implement all three workflows in your repository: + +### 1. Create `.github/workflows/validate-commits.yml` + +```yaml +name: Validate Conventional Commits + +on: + pull_request: + branches: [ main, master ] + +jobs: + validate-commits: + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-lint.yml@master + with: + allowed_types: "feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert" + scopes: "api,ui,docs,config,deploy" + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + validate-pr-title: + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-pr-title.yml@master + with: + allowed_types: "feat,fix,docs,style,refactor,perf,test,chore,ci,build,revert" + scopes: "api,ui,docs,config,deploy" + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +### 2. Create `.github/workflows/release.yml` + +```yaml +name: Release + +on: + push: + branches: [ main, master ] + +jobs: + release: + uses: clouddrove/github-shared-workflows/.github/workflows/conventional-commits-release.yml@master + with: + target_branch: master + initial_version: "1.0.0" + prerelease: false + changelog_file: "CHANGELOG.md" + version_prefix: "v" + secrets: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +## Commit Message Examples + +### Basic Format +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +### Examples + +#### Feature +``` +feat: add user authentication system + +Implement JWT-based authentication with login and registration endpoints. +Includes password hashing and token validation. + +Closes #123 +``` + +#### Bug Fix +``` +fix(api): resolve memory leak in user service + +The user service was not properly cleaning up database connections, +causing memory leaks during high load periods. + +Fixes #456 +``` + +#### Breaking Change +``` +feat!: redesign user API + +BREAKING CHANGE: The user API endpoints have been completely redesigned. +All existing API calls will need to be updated to use the new format. + +Migration guide: https://docs.example.com/migration +``` + +#### With Scope +``` +feat(ui): add dark mode toggle + +Add a toggle button in the header to switch between light and dark themes. +Includes theme persistence in localStorage. + +Closes #789 +``` + +## Best Practices + +### 1. Commit Message Guidelines + +- Use the imperative mood ("add feature" not "added feature") +- Keep the description under 50 characters +- Capitalize the first letter of the description +- Don't end the description with a period +- Use the body to explain what and why, not how +- Reference issues and pull requests in the footer + +### 2. Scope Guidelines + +- Use lowercase for scopes +- Use kebab-case for multi-word scopes +- Keep scopes consistent across the project +- Common scopes: `api`, `ui`, `docs`, `config`, `deploy`, `test` + +### 3. Breaking Changes + +- Use `!` after the type/scope for breaking changes +- Include `BREAKING CHANGE:` in the footer +- Provide migration instructions when possible +- Consider creating a separate migration guide + +### 4. Workflow Configuration + +- Start with basic types and add more as needed +- Define project-specific scopes +- Use consistent version prefixes +- Consider using prereleases for development branches + +## Troubleshooting + +### Common Issues + +1. **Commit validation fails** + - Check that commit messages follow the format: `type: description` + - Ensure the type is in the allowed list + - Verify scope is allowed (if scopes are configured) + +2. **PR title validation fails** + - Ensure PR title follows conventional format + - Check that the type is allowed + - Verify scope is allowed (if scopes are configured) + +3. **Release not created** + - Check that commits are on the target branch + - Verify GitHub token has necessary permissions + - Ensure there are conventional commits since the last release + +### Debugging + +Enable debug logging by adding this to your workflow: + +```yaml +- name: Debug + run: | + echo "Event: ${{ github.event_name }}" + echo "Ref: ${{ github.ref }}" + echo "Target branch: ${{ inputs.target_branch }}" +``` + +## Migration from Existing Workflows + +If you're migrating from the existing tag-release workflow: + +1. **Replace label-based versioning** with commit-based versioning +2. **Update commit messages** to follow conventional format +3. **Configure allowed types and scopes** for your project +4. **Test the workflows** in a development branch first + +## Support + +For issues or questions about these workflows: + +- Create an issue in the [github-shared-workflows repository](https://github.com/clouddrove/github-shared-workflows/issues) +- Contact CloudDrove support at [hello@clouddrove.com](mailto:hello@clouddrove.com) + +## References + +- [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/) +- [Semantic Versioning](https://semver.org/) +- [GitHub Actions Documentation](https://docs.github.com/en/actions)