KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#codex #developer-tools #typescript #ai-agents #claude-code #ai-agent #cli #deepseek-harness #dsh-plugin #python #mcp #react

pr-conventional-commits

★ 84 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Conventional Commit In Pull Requests GitHub Action

## Features

- Conventional Commit Validation: Checks that the PR title adheres to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
- Automatic Labeling: Labels the PR based on the task type mentioned in the title. Can be disabled.
- Title Pattern Validation: Optionally validates PR titles against custom regex (issue tickets, title formats, etc.).

## Overview

Conventional Commits is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

This GitHub Action checks that the PR title adheres to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. If the PR title contains a valid task type and optionally a task number, it labels the PR based on the task type.

### Why PR Conventional Commits?

- **Automatic Generation of CHANGELOGs**: With Conventional Commits, CHANGELOGs can be automatically generated, making it easier for users to find what's changed between releases.
- **Explicitly Communicate Nature of Changes**: Conventional commits establish a clear guideline, making it easier for people to contribute to your projects.
- **Simple Navigation through Git History**: Conventional commits make it easy to identify the nature of changes (fix, feat, chore, etc.) when searching through the git commit history.
- **Compatibility with Semantic Versioning (SemVer)**: Conventional Commits provides a structured format for commit messages, which aligns with SemVer and helps understand version changes without reading the code.
- **Labeling PRs**: By labeling PRs based on the task type, it provides a visual indication of the nature of changes and helps in organizing and prioritizing PR reviews.
- **Breaking Change**: Adding a `!` in the PR title will automatically assign the breaking change label to the PR.
- **Filtering by labels**: You can filter out specific labels in GitHub Pull Requests UI

### Inputs

- `task_types` (required): An array of task types. Example: `["feat","fix","docs","test","ci","refactor","perf","chore","revert"]`.
- `title_regex` (optional): Regular expression for custom title validation; disabled by default. Example: `''PROJECT-\d{2,5}$''` for trailing issue ticket; `''^[^:]+: [A-Z]''`  for capitalized title.
- `add_label` (optional): Whether to add labels. Default is `'true'`.
- `custom_labels` (optional): A JSON string mapping task types to custom label names. Example: `{"feat": "feature", "fix": "fix", "docs": "documentation", "test": "test", "ci": "CI/CD", "refactor": "refactor", "perf": "performance", "chore": "chore", "revert": "revert", "wip": "WIP"}`.

### Labeling Pull Requests
When a pull request title adheres to the Conventional Commits specification, this action can automatically label the pull request based on the task type. Labels provide filtering PRs by a label, a visual indication of the nature of changes, aiding in organizing and prioritizing PR reviews.

By default, this action adds labels based on the task type. For example, a pull request with a task type of `ci` will be labeled as `CI/CD`. You can customize the label names by providing a `custom_labels` input.

Adding a `!` in the PR title will automatically assign the `breaking change` label to the PR.

If you prefer not to add labels, you can disable the labeling functionality by setting the `add_label` input to `'false'` or remove the flag, by default is disabled.
In such cases, the action will still validate the PR title against the Conventional Commits specification but will not add any labels.

You can also control adding labels for `scope`, this is disabled by default, to enable it, add `add_scope_label: true` in the action's configuration

Example
![img.png](https://raw.githubusercontent.com/ytanikin/pr-conventional-commits/main/labels.png)

### Configuring Squash Merging

When merging pull requests, you can configure the merge behavior, including the option for squashing. Follow these steps (or [Github's guide](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests)):

1. Go to your repository's `Settings` tab.
2. Select the `General` menu on the left sidebar.
3. Under `Pull Requests`, select `Allow squash merging`. This allows contributors to merge a pull request by squashing all commits into a single commit.
4. Select PR title as a default message for squashed commit.

![squash_config.png](https://raw.githubusercontent.com/ytanikin/pr-conventional-commits/main/squash_config.png)

When using the squash merge option, all commits from the head branch will be combined into a single commit in the base branch. The default commit message presented when merging a pull request with squash will be the PR title.

Note: Make sure that at least one merge option is enabled (merge commits, squashing, or rebasing).

## Examples

### Basic Usage, no label, no title validation

This configuration checks for conventional commits using the specified `task_types` but doesn't add any labels or validate title patterns.

Add a step that uses this action in your workflow file:

```yaml
name: PR Conventional Commit Validation

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  validate-pr-title:
    runs-on: ubuntu-latest
    steps:
      - name: PR Conventional Commit Validation
        uses:  ytanikin/pr-conventional-commits@1.4.0
        with:
          task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'
          add_label: 'false'
```

For this configuration, the following PR title is valid: `feat: add new feature`

### Usage, with title validation, no labeling

This configuration checks for conventional commits using the specified `task_types` and validates title patterns, but doesn't add any labels.

Add a step that uses this action in your workflow file:

```yaml
name: PR Conventional Commit Validation

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  validate-pr-title:
    runs-on: ubuntu-latest
    steps:
      - name: PR Conventional Commit Validation
        uses:  ytanikin/pr-conventional-commits@1.4.0
        with:
         task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'
         add_label: 'false'
         title_regex: 'PROJECT-\d{2,5}'
```

For this configuration, the following PR title is valid: `feat: PROJECT-12345 add new feature`

## Usage with labeling, where label is just a task type

This configuration checks for conventional commits using the specified `task_types` and adds labels according to the task type.

Add a step that uses this action in your workflow file:

```yaml
name: PR Conventional Commit Validation

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  validate-pr-title:
    runs-on: ubuntu-latest
    steps:
      - name: PR Conventional Commit Validation
        uses:  ytanikin/pr-conventional-commits@1.4.0
        with:
          task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'
```

For this configuration, the following PR title is valid: `feat: add new feature`. **The PR will be labeled as** `feat`.

## Example Usage with title validation, custom labeling and scope labeling

This configuration checks for conventional commits using the specified `task_types`, validates title patterns, and adds custom labels.

Add a step that uses this action in your workflow file:

```yaml
name: PR Conventional Commit Validation

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  validate-pr-title:
    runs-on: ubuntu-latest
    steps:
      - name: PR Conventional Commit Validation
        uses:  ytanikin/pr-conventional-commits@1.4.0
        with:
         task_types: '["feat","fix","docs","test","ci","refactor","perf","chore","revert"]'
         title_regex: 'PROJECT-\\d{2,5}'
         custom_labels: '{"feat": "feature", "fix": "fix", "docs": "documentation", "test": "test", "ci": "CI/CD", "refactor": "refactor", "perf": "performance", "chore": "chore", "revert": "revert", "wip": "WIP"}'
         add_scope_label: 'true'
```

For this configuration, the following PR title is valid: `feat: PROJECT-12345 add new feature`.
**The PR will be labeled as `feature`.**

### Troubleshooting

- If you encounter an error message: `Error: Resource not accessible by integration`, adjust your repository settings. Go to your repository's settings, navigate to the "Actions" tab, and under the "General" section, update the "Workflow permissions" setting to "Read and Write Permission". This grants the necessary permissions for the action to function correctly.

- If you need to use a different GitHub token instead of the default `GITHUB_TOKEN`, you can provide your own token as the `token` input to the action.

### Contributing

After modifying the code, please:
1. Run `npm test` to run tests and ensure your changes work correctly
1. Open a PR

#### Optional: Local Docker Testing
```bash
# Test the Docker build locally (optional)
docker build -t pr-conventional-commits-test .

# Run tests inside container (optional)
docker run --rm pr-conventional-commits-test npm test
```

You can verify your changes by editing the title of your PR. The PR uses an action located in the root directory of the branch associated with your PR, and GitHub will automatically build the Docker container with your changes.

## Author

👤 **YTanikin**

- Website: https://medium.com/@ytanikin
- Github: [@ytanikin](https://github.com/ytanikin)

## 🤝 Contributing

Contributions, issues and feature requests are welcome!<br />Feel free to check [issues page](https://github.com/ytanikin/pr-conventional-commits/issues).

pr-conventional-commits

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README