pr-list-action

List Pull Requests Action

list-pull-requests-action is a GitHub Action that lists merged pull requests between the latest tag and the current head. You can customize which pull requests to include based on labels, define the order of the list, and apply regex-based replacements using a configuration file.

Usage

Add the following step to your GitHub Actions workflow:

- name: List Pull Requests
  uses: SPHTech/list-pull-requests-action@v1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    config_file: '.github/list-pull-requests.yml' # Optional: Define a custom path to your config file
    head_ref: 'HEAD' # Optional: the workflow will read PR until this ref, default is HEAD.

Inputs

Name	Description	Required	Default
github_token	GitHub token for authentication.	Yes	N/A
config_file	Path to the configuration file to customize PR listing behavior.	No	.github/list-pull-requests.yml
head_ref	The reference to the head commit for comparing commits. If not provided, defaults to HEAD.	No	HEAD

Outputs

{
  number: number;
  title: string;
  labels: string[];
}

Name	Description
pr_list	A list of pull request information.

Configuration File Format

The configuration file should be a YAML file (e.g., pr-list-config.yml) with the following structure:

skip_labels:
  - documentation
  - skip-release-note
order: ascending
title_format: '- $TITLE @$AUTHOR (#$NUMBER)'
replacers:
  - search: '/\[([A-Z0-9]+-\d+)\]/g'
    replace: '[[$1]](https://sph.atlassian.net/browse/$1) -'

Configuration Parameters

Parameter	Description	Type	Default
skip_labels	A list of labels. PRs with any of these labels will be skipped.	Array of strings	[] (No labels skipped)
order	The order in which to list the PR titles. Options are ascending or descending.	String	descending
title_format	A customizable format for displaying PR details. Available placeholders: $TITLE, $AUTHOR, $NUMBER. Use @$AUTHOR to include the author only if present.	String	'- $TITLE @$AUTHOR (#$NUMBER)'
replacers	An array of objects for regex-based replacements. Each object should contain search and replace keys, where search is the regex pattern and replace is the replacement string.	Array of objects	[] (No replacements)

Example Configuration File

Below is an example configuration file that you can use in your repository:

skip_labels:
  - documentation
  - skip-release-note
order: descending
title_format: '- $TITLE @$AUTHOR (#$NUMBER)'
replacers:
  - search: '/\[([A-Z0-9]+-\d+)\]/g'
    replace: '[[$1]](https://sph.atlassian.net/browse/$1) -'

• skip_labels: This list specifies labels for PRs that should not be included in the output list. In the example, any PRs labeled with "documentation" or "skip-changelog" will be skipped.
• order: Specifies the order in which the PR titles are listed, based on PR numbers.
• title_format: A customizable format for displaying PR details.
  • $TITLE: The title of the pull request.
  • $AUTHOR: The username of the author of the pull request. If the author is not available, the @$AUTHOR part will be removed from the output.
  • $NUMBER: The number of the pull request.
  • Example Usage:
    • '$TITLE @$AUTHOR (#$NUMBER)' outputs: Fix issue @username (#123).
    • '$TITLE (#$NUMBER)' outputs: Fix issue (#123).
    • '$TITLE - PR: #$NUMBER by @$AUTHOR' outputs: Fix issue - PR: #123 by @username.
• replacers: An array of regex-based replacements for transforming PR titles.
  • search: A regex pattern to search for in the PR title.
  • replace: A string that replaces the match found by the regex.
  • Example Usage:
    • If a PR title contains [PROJECT-123], it will be converted to a clickable link: [[PROJECT-123]](https://sph.atlassian.net/browse/PROJECT-123) -.

Full Workflow Example

Here's how you can use the list-pull-requests-action in a GitHub Actions workflow:

name: List Pull Requests

on:
  push:
    branches:
      - main

jobs:
  list_prs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: List Pull Requests
        id: list-pull-requests
        uses: SPHTech/list-pull-requests-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          config_file: 'custom/path/to/your-config.yml' # optional
          head_ref: 'CPR' # optional

      - name: Print PR Titles
        run: |
            pr_list="${{ steps.list-pull-requests.outputs.pr_list }}"
            pr_titles=$(echo "$pr_list" | jq -r '.[].title')

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue to improve the action.

---

This README.md provides an overview of how to use the list-pull-requests-action, including input and output details, configuration options, and examples to help users get started quickly.