PR Editor Action

This GitHub Action allows you to automatically edit existing Pull Requests using the flexible power of the GitHub CLI (gh pr edit). It is designed as a composite action for easy reuse in any workflow.

✨ Features

• Full gh pr edit Support: Leverage the official GitHub CLI for robust editing, supporting flags like --title, --base, --add-label, --add-project, and more.
• Flexible Identification: Edit a PR using its number, URL, or the associated branch name.
• Composite Action: Simple integration and high reusability across any GitHub Actions workflow.

🛠️ Requirements

• GitHub CLI (gh): This action requires the GitHub CLI to be available in the runner environment. All official GitHub-hosted Ubuntu runners (ubuntu-latest) already include gh by default.

• Authentication Token: The action uses the GitHub CLI, which requires an authentication token via the GH_TOKEN environment variable. You must ensure the token has adequate permissions (scopes) for the desired operation:

  • General editing requires pull-requests: write.
  • Editing project links (--add-project, --remove-project) requires the project scope.

  Example Authentication:

  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 

Usage Example

Below is a complete workflow example that demonstrates how to use this action:

name: Test PR Editor Action

on:
  workflow_dispatch:
    inputs:
      pr_url:
        description: 'URL or Identifier of the PR to edit'
        required: true

jobs:
  test-edit-pr:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Edit Pull Request
        uses: ws2git/gh-pr-editor-action@v1
        env:
          GH_TOKEN: ${{ github.token }}
        with:
          pr_identifier: ${{ github.event.inputs.pr_url }}
          edit_options: '--title "Test" --body "testing"'

💡 How it works

This action is structured as a composite action running a simple, yet robust, Shell script to execute the editing operation.

1. Input Handling (Action): The action receives two key inputs:

   • pr_identifier: The target Pull Request (PR) identifier (number, URL, or branch name).
   • edit_options: A single string containing all the desired gh pr edit flags and their values (e.g., --title "New Title" --add-label "ready").

2. Script Execution (pr-editor.sh):

   • The composite action executes the bundled Shell script (pr-editor.sh).
   • The action passes the PR Identifier as the first positional argument ($1) and the Edit Options string as the subsequent arguments.
   • Inside the script, the shift command is used to remove the identifier ($1), leaving only the edit options in the remaining positional arguments ($@).

3. GitHub CLI Command:

   • The script constructs and executes the final command using the GitHub CLI:

     gh pr edit "$PR_IDENTIFIER" --repo "$GITHUB_REPOSITORY" "$@"

   • The $GITHUB_REPOSITORY environment variable (automatically set by GitHub Actions) is used to explicitly define the repository context.
   • Crucially, using "$@" (with quotes) ensures that all edit flags, including those containing spaces (like a title: --title "New Title"), are correctly passed as a single set of arguments to the gh pr edit command.

4. Completion: The action logs the result and completes. The operation relies on the GH_TOKEN environment variable for authentication and necessary permissions.

---

📝 Notes

Passing Multiple Edit Options

When defining the edit_options input, ensure you pass the entire set of flags and arguments as a single, properly quoted string. The composite action handles the string as a collection of arguments for the underlying shell script.

✅ Correct format (Recommended):

# Passes all flags as one string
edit_options: '--title "New_Title" --add-project "Roadmap"'

Authentication and Permissions

• The action uses the GH_TOKEN environment variable to authenticate with the GitHub CLI. In most cases, passing the default token is sufficient: GH_TOKEN: ${{ github.token }}.
• Permission Scopes: When running the workflow, you must explicitly grant the necessary write permissions to the token. For example, to edit a PR's title and labels, you need:

  permissions:
    pull-requests: write # Required for editing PR details

• If you need to edit Projects, you may need to use a Personal Access Token (PAT) with the project scope, as the default github.token often has limited project-related permissions.