The Assign Action allows you to automatically assign users to pull requests based on validation results or other criteria. This helps ensure PRs get the right attention and establishes clear ownership.

​
Configuration

​
assignees
string | string[]

Username(s) to assign to the PR

​
remove
string | string[]

Username(s) to remove from PR assignees

​
Basic Usage

on_success:
  - assign:
      assignees: ["username1", "username2"]

​
Examples

​
Simple Assignment

Assign specific users to the PR:

on_success:
  - assign:
      assignees: ["project-lead", "qa-engineer"]

​
Self-Assignment

Assign the PR to its author:

on_success:
  - assign:
      assignees: ["@author"]

​
Remove Assignees

Remove specific users from PR assignments:

on_success:
  - assign:
      remove: ["previous-owner"]

​
Combined Assignment

Add and remove assignees in one action:

on_success:
  - assign:
      assignees: ["new-owner"]
      remove: ["previous-owner"]

​
Special Annotations

The Assign Action supports special annotations:

AnnotationDescription
@authorAssigns the PR to its author

​
How It Works

1

Get Current Assignees

The action retrieves the current list of PR assignees

2

Process Special Annotations

It processes any special annotations like @author

3

Add New Assignees

It adds any new assignees specified in assignees

4

Remove Assignees

It removes any assignees specified in remove

​
Practical Use Cases

​
Content Type Assignment

Assign PRs based on the type of content being changed:

ruleset:
  - name: "Documentation Assignment"
    when:
      - "pull_request.opened"
    if:
      - type: "files"
        modified:
          match: "docs/.*"
    on_success:
      - assign:
          assignees: ["docs-maintainer"]
      - label:
          add: ["documentation"]

  - name: "Frontend Assignment"
    when:
      - "pull_request.opened"
    if:
      - type: "files"
        modified:
          match: "src/frontend/.*"
    on_success:
      - assign:
          assignees: ["frontend-lead"]
      - label:
          add: ["frontend"]

  - name: "Backend Assignment"
    when:
      - "pull_request.opened"
    if:
      - type: "files"
        modified:
          match: "src/backend/.*"
    on_success:
      - assign:
          assignees: ["backend-lead"]
      - label:
          add: ["backend"]

​
PR Size-Based Assignment

Assign different reviewers based on PR size:

ruleset:
  - name: "Small PR"
    when:
      - "pull_request.opened"
    if:
      - type: "size"
        files:
          max: 5
    on_success:
      - assign:
          assignees: ["junior-reviewer"]

  - name: "Large PR"
    when:
      - "pull_request.opened"
    if:
      - type: "size"
        files:
          min: 10
    on_success:
      - assign:
          assignees: ["senior-reviewer", "tech-lead"]
      - comment:
          body: "This is a large PR, so both a senior reviewer and tech lead have been assigned."

​
Ownership Transition

Transfer ownership when a PR moves to a new stage:

ruleset:
  - name: "Ready for QA"
    when:
      - "pull_request.labeled"
    if:
      - type: "label"
        match: "ready-for-qa"
    on_success:
      - assign:
          assignees: ["qa-engineer"]
          remove: ["developer"]
      - comment:
          body: "This PR is now ready for QA and has been assigned to @qa-engineer."

​
Custom Assignment by Author

Assign different reviewers based on the PR author:

ruleset:
  - name: "Junior Developer PRs"
    when:
      - "pull_request.opened"
    if:
      - type: "author"
        match: ["junior-dev-1", "junior-dev-2", "intern"]
    on_success:
      - assign:
          assignees: ["senior-mentor"]
      - comment:
          body: "@senior-mentor has been assigned to mentor on this PR."

  - name: "Standard Assignment"
    when:
      - "pull_request.opened"
    if:
      - type: "author"
        ignore: ["junior-dev-1", "junior-dev-2", "intern"]
    on_success:
      - assign:
          assignees: ["team-lead"]

​
Best Practices

Assign PRs based on relevance and expertise
Avoid assigning too many people to one PR
Balance workload across team members
Have clear ownership transitions

Assignments create expectations - make sure assignees know their responsibilities

​
Benefits of Automated Assignment

  • Clear Ownership: Establishes who is responsible for the PR
  • Faster Response: Gets the right eyes on the PR quickly
  • Balanced Workload: Can be used to distribute review work
  • Streamlined Workflow: Reduces manual assignment steps
  • Knowledge Sharing: Can rotate assignees to spread knowledge

​
Assignment vs. Review Requests

GitHub supports both assignees and review requests:

  • Assignees: People responsible for the PR (typically 1-2 people)
  • Reviewers: People asked to review the code (can be multiple)

Consider using the Request Review Action alongside the Assign Action for a complete workflow:

on_success:
  - assign:
      assignees: ["project-owner"] # Overall responsibility
  - requestReview:
      reviewers: ["code-reviewer-1", "code-reviewer-2"] # People to review