Skip to content

README.md

Latest commit

 

History

History
120 lines (81 loc) · 5.13 KB

README.md

File metadata and controls

120 lines (81 loc) · 5.13 KB

@yuki-no/plugin-batch-pr

NPM Version

Collects opened Yuki-no translation issues and creates a single pull request to consolidate changes.

Usage

- uses: Gumball12/yuki-no@v1
  env:
    # [optional]
    # Specifies the root directory path in the `head-repo`
    # that should be stripped when applying changes to `upstream-repo`
    YUKI_NO_BATCH_PR_ROOT_DIR: head-repo-dirname

    # [optional]
    # file patterns that should be excluded from batch PR
    YUKI_NO_BATCH_PR_EXCLUDE: |
      head-repo-patterns
  with:
    plugins: |
      @yuki-no/plugin-batch-pr@latest

Configuration

This plugin reads configuration from environment variables:

  • YUKI_NO_BATCH_PR_ROOT_DIR (optional): Specifies the root directory path in the head-repo that should be stripped from file paths when applying changes to the upstream-repo. When set, this prefix will be removed from head-repo file paths before applying changes. If not specified, files will be applied with their original paths.
  • YUKI_NO_BATCH_PR_EXCLUDE (optional): Specifies file patterns to exclude from batch PR processing. Supports glob patterns and multiple patterns separated by newlines.

YUKI_NO_BATCH_PR_ROOT_DIR

The YUKI_NO_BATCH_PR_ROOT_DIR option allows you to specify a root directory path in the head repository that should be stripped when applying changes to the upstream repository. This is particularly useful when your head repository has a different directory structure than your upstream repository.

For example, if your head repository has documentation in a docs/ folder, but your upstream repository expects the files at the root level, you can configure:

env:
  YUKI_NO_BATCH_PR_ROOT_DIR: docs

This will ensure that when applying changes from docs/README.md in your head repository, they will be applied to README.md in the upstream repository (the docs/ prefix is stripped).

YUKI_NO_BATCH_PR_EXCLUDE

The YUKI_NO_BATCH_PR_EXCLUDE option allows you to specify head-repo file patterns that should be excluded from batch PR processing. This is useful when you want to exclude certain files like build artifacts, temporary files, or sensitive files from being included in the batch PR.

The option supports glob patterns and can accept multiple patterns, each on a separate line:

env:
  # Specify `head-repo` file patterns
  YUKI_NO_BATCH_PR_EXCLUDE: |
    *.log
    temp/**
    build/*
    .env*
    **/*.tmp

Files matched by YUKI_NO_BATCH_PR_EXCLUDE are intentionally NOT applied by the plugin. They will be listed in the batch PR body under "Excluded Files (manual changes required)", so you can quickly see what to update manually.

Note that this behaves slightly differently from Yuki-no's exclude option. The exclude option is used when creating issues from head-repo changes. For more details, please refer to the Yuki-no Configuration section.

Permissions

This plugin requires additional permissions beyond the default yuki-no setup:

permissions:
  # Default yuki-no permissions
  issues: write
  actions: read

  # Required for branch creation and push operations
  contents: write

  # Required for batch PR creation
  pull-requests: write

Additionally, you need to enable "Allow GitHub Actions to create and approve pull requests" in your repository settings:

Set workflow permissions

  1. Go to Settings → Actions → General
  2. Under Workflow permissions, check "Allow GitHub Actions to create and approve pull requests"
  3. Click "Save"

These permissions are required because the plugin needs to create pull requests.

Configuration

This plugin uses yuki-no's built-in include and exclude options to determine which files to track.

How It Works

  1. Collects all opened yuki-no translation issues
  2. Extracts file changes from each issue's commits
  3. Applies changes to a unified branch
  4. Creates or updates a single pull request with all changes
  5. Links all related issues in the PR description

Important Notes

Closed Issue Handling

When an issue tracked in a batch PR is closed, the plugin does not automatically revert its changes from the batch PR. This behavior is intentional for the following reasons:

  • Preserves manual edits: Prevents accidental removal of changes you may have made directly in the batch PR
  • Avoids complex conflicts: Reduces the risk of merge conflicts with other tracked issues
  • Maintains stability: Ensures predictable behavior and file states

If you need to remove changes from closed issues, close the current batch PR and re-run the yuki-no action to create a fresh batch PR with only the currently open issues.

Release Tracking Integration

When using @yuki-no/plugin-release-tracking, not released issues are automatically excluded from batch PR collection. If release tracking is not installed, all opened translation issues will be included in the batch as normal.