ghsummon detects @copilot <prompt> directives in files (primarily Markdown), then automatically creates a Pull Request and summons GitHub Copilot Coding Agent to work on it — all driven by a simple git push.

1. Write @copilot <prompt> in a Markdown file and push
2. GitHub Actions runs ghsummon
3. ghsummon detects the @copilot directive in the git diff
4. A new branch and PR are created automatically (base = the pushed branch)
5. Copilot Coding Agent is assigned and triggered via @copilot comment
6. Copilot replaces the @copilot prompt with research results directly on the PR branch
7. Review and merge the PR — the branch is deleted, allowing re-use

Add an @copilot directive at the beginning of a line in a Markdown file:

@copilot Investigate the latest best practices for Go error handling

Multi-line prompts are supported using indentation (tab or 2+ spaces):

@copilot Research GitHub Copilot Coding Agent trigger methods
  Compare REST API, GraphQL, and GitHub CLI approaches
  Include best practices and recommendations

name: ghsummon
on:
  push:
    branches: [main]
    paths: ['**.md']

permissions:
  contents: write
  pull-requests: write

jobs:
  research:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: Songmu/ghsummon@v0
        with:
          token: ${{ secrets.GHSUMMON_TOKEN }}

• Copilot license (Pro, Pro+, Business, or Enterprise) — works with personal accounts, no Org required
• Coding Agent enabled (Settings > Copilot for personal accounts, or Org policy)
• .github/workflows/copilot-setup-steps.yml must exist in the repository (docs)
• GitHub Actions enabled

Copilot Coding Agent assignment via the API requires a user token (personal access token or GitHub App user-to-server token). GitHub App installation tokens and GITHUB_TOKEN cannot assign Copilot to PRs.

See: Assigning an issue to Copilot via the GitHub API

Make sure you're authenticating with the API using a user token, for example a personal access token or a GitHub App user-to-server token.

For GitHub Actions, create a fine-grained PAT with these repository permissions:

• Contents: Read and Write
• Pull requests: Read and Write

Store it as secrets.GHSUMMON_TOKEN in your repository settings.

Copilot Coding Agent requires this workflow to exist in the repository. See docs.

name: "Copilot Setup Steps"
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5

ghsummon uses branch-name-based exclusion. For each file with an @copilot directive, a branch named ghsummon-<filepath> is created. If the branch already exists, the file is skipped (work already in progress). Once the PR is merged and the branch is deleted, the same file can be processed again.

Songmu