Migrating pull requests originating from forks#

The ansys/actions/hk-migrate-fork-pr action migrates pull requests opened from forks into branches inside the main repository. This is sometimes necessary because GitHub does not expose repository secrets to workflows triggered by fork PRs, so CI pipelines that require secrets cannot run successfully.

The action creates a migration/pr-<N> branch in the main repository that is a mirror of the fork’s branch, then opens a new pull request targeting main. Subsequent syncs keep the migration branch up to date with the contributor’s fork.

Important

Required token scopes and workflow permissions

The github-token input must be a token with the following permissions:

  • contents: write - push migration branches

  • pull-requests: write - create PRs, manage comments and reactions

Additionally, the provided github-token must have read:org scope to check team membership for authorization.

The workflow job must declare:

permissions:
  contents: write
  pull-requests: write

Setup#

The action listens for issue_comment events on pull requests and triggers when a team member posts @pyansys-ci-bot migrate (first migration) or @pyansys-ci-bot sync (subsequent sync).

Typical setup might involve creating or updating a .github/workflows/migrate-fork-pr.yml workflow with the following content:

name: Migrate fork PR

on:
  issue_comment:
    types: [created]

jobs:
  hk-migrate-fork-pr:
    name: "Migrate fork PR to main repository"
    runs-on: ubuntu-latest
    if: |
      github.event_name == 'issue_comment' &&
      github.event.issue.pull_request != null &&
      (contains(github.event.comment.body, '@pyansys-ci-bot migrate') ||
       contains(github.event.comment.body, '@pyansys-ci-bot sync'))
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: "Migrate fork PR"
        uses: ansys/actions/hk-migrate-fork-pr@{{ version }}
        with:
          pr-number: ${{ github.event.issue.number }}
          comment-id: ${{ github.event.comment.id }}
          user-triggering: ${{ github.event.comment.user.login }}
          github-token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
          bot-username: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
          team-slug: 'pyansys-maintainers'

Note

Replace team-slug with the slug of the GitHub team whose members are authorised to trigger migrations (for example, pymapdl-maintainers).

How the action works#

The following describes the end-to-end flow from the perspective of both the contributor and the maintainer.

First migration

  1. An external contributor opens a pull request from their fork.

  2. A maintainer comments @pyansys-ci-bot migrate on the fork PR.

  3. The action verifies that the commenter is a member of the configured team.

  4. A migration/pr-<N> branch is created in the main repository as an exact mirror of the fork branch.

  5. A new pull request targeting main is opened automatically.

  6. A success comment is posted on the fork PR explaining the workflow to the contributor (see Contributor workflow below).

Subsequent syncs

  1. The contributor pushes new commits to their fork branch as normal.

  2. When CI needs to run against the latest changes, a maintainer comments @pyansys-ci-bot sync on the fork PR.

  3. The action mirrors the fork branch onto the migration branch again, and CI triggers on the migration PR.

At no point does the contributor need write access to the main repository.

Contributor workflow#

After the first migration, contributors should:

  • Continue pushing commits to their own fork branch exactly as they would for any pull request.

  • When they want their latest changes reflected in the migration PR, leave a comment on the fork PR tagging a member of the maintainer team and asking for a sync.

  • Not push directly to the migration/pr-<N> branch — they do not have access to it, and a subsequent sync would overwrite any such changes anyway.

Note

If a maintainer merged main into the migration branch directly, and the fork branch has not received that same merge, a sync would silently discard those commits. The action detects this situation and blocks the sync with an explanatory comment on the fork PR.

When this happens, the contributor must first merge main into their fork branch. Once the fork branch is up to date, the maintainer can trigger the sync again.