Semantic Pull Request Composer

This action automatically composes the pull request title and body based on the branch name, which follows a semantic convention. Optional AI autocompletion using OpenAI completions API is also available.

Inspiration

Development teams often use a convention to name their branches. For example, they might use a prefix to indicate the type of change, and a ticket number to indicate the ticket that the change is related to.

For example, a branch name might look like this:

feat/TEAM-1234-add-new-feature

This action automatically composes the pull request title and body based on the branch name, which follows a semantic convention.

Features

• Automatically compose the pull request title and body based on the branch name
• Optional AI autocompletion using OpenAI
• Supports custom prefixes and tickets
• Supports custom project base URL
• Supports custom templates (partially done, more improvements for advanced templates coming soon)

Usage

name: Semantic Pull Request Composer
on:
  pull_request:
    types: [opened, edited, reopened, synchronize]
jobs:
  pr-compose:
    runs-on: ubuntu-latest
    steps:
      - uses: mateoguzmana/semantic-pr-composer@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          title-format: 'prefix(ticket): description'
          template-type: 'conventional'
          project-base-url: 'https://<yourprojectdomain>/issues'

You can see a demo pull request, and its result below:

---

Options

Option	Description	Default
github-token	GitHub token to use for the API calls.	${{ secrets.GITHUB_TOKEN }}
title-format	The title format to use	'prefix(ticket): description'
project-base-url	Base URL for the project/task/ticket system	'https://example.com'
template-type	The template type to use	'basic'
custom-template	If set, template-type is ignored
prefixes	The prefixes to use	Default prefixes
tickets	The tickets to use	Default tickets
openai-token	See OpenAI Token
project-context	Project context. Used for the AI autocompletion

Title Format

Used to determine how to format the pull request title.

The title format is a string that can contain the following placeholders:

• prefix - The prefix of the branch name
• ticket - The ticket number of the branch name
• description - The description of the branch name

Example:

- uses: mateoguzmana/semantic-pr-composer@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    title-format: 'prefix(ticket): description'

The default title format is based on conventional commits. If you are using a different convention, you can pass your own title format.

Project Base URL

Used to determine the base URL for the project/task/ticket system.

Example:

- uses: mateoguzmana/semantic-pr-composer@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    project-base-url: 'https://<yourprojectdomain>/issues'

Template Type

Used to determine which template to use for the pull request title and body.

Choose one of the following template types:

• basic
• conventional
• custom (see Custom Template)

Custom Template

Can be used to customize the pull request title and body.

The template is a string that can contain the following placeholders:

• prefix - The prefix of the branch name
• ticket - The ticket number of the branch name
• projectBaseUrl - The project base URL
• description - The description of the branch name

Example:

### My custom title

[ticket](projectBaseUrl/ticket)

### Amazing changes - custom format

prefix

### Description

> description

### Checklist

- [ ] I have added/updated unit tests

- [ ] I have added/updated documentation

- [ ] I have updated the [CHANGELOG.md](./CHANGELOG.md) file

Note: Currently, the custom template will only replace the values above. If you are looking for a more advanced template, please open an issue. I am still investigating how to do something smarter where you can add conditional logic to the template.

Prefixes

Used to determine which prefix to use for the pull request title and body.

The prefixes are an array of strings. Default prefixes are:

• feat
• fix
• docs
• style
• refactor
• perf
• test
• chore
• revert
• build
• ci

Note: The default prefixes are based on conventional commits. If you are using a different convention, you can pass your own prefixes.

You can pass them as an array of strings:

- uses: mateoguzmana/semantic-pr-composer@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    prefixes: |
      ["feat", "fix", "chore", "docs", "refactor", "test", "style", "ci", "perf", "build"]

Tickets

Used to determine which ticket to use for the pull request title and body.

The tickets are an array of strings. Default tickets are:

• test

You can pass them as an array of strings:

- uses: mateoguzmana/semantic-pr-composer@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    tickets: |
      ["test", "test2"]

OpenAI Token

OpenAI token. If set, the action will try to generate a pull request description using the OpenAI completions API.

Note: This is experimental.

---

Contributing

Contributions are welcome! Please read the Contributing Guide for more information.

License

MIT