GitHub Action Event Payload

Overview

The event payload module provides tools to work with GitHub Actions event data, including:

• Raw event payload access

• Strongly typed event models using Pydantic

• Convenience helper functions for common event operations

More details: GitHub Actions Event Payload

Raw Event Payload

event_payload()

Get GitHub Event payload that triggered the workflow as a dictionary.

example:

from github_action_toolkit import event_payload

payload = event_payload()
# Output:
# {"action": "opened", "number": 1, "pull_request": {...}, "repository": {...}, "sender": {...}}

get_event_name()

Get the name of the event that triggered the workflow.

example:

from github_action_toolkit import get_event_name

event_name = get_event_name()
# Returns: "push", "pull_request", "issue_comment", etc.

Typed Event Models

get_typed_event()

Parse the event payload into a strongly typed Pydantic model based on the event type.

Supported event types:

• push → PushEvent

• pull_request / pull_request_target → PullRequestEvent

• issue_comment → IssueCommentEvent

• workflow_run → WorkflowRunEvent

example:

from github_action_toolkit import get_typed_event, PushEvent, PullRequestEvent

event = get_typed_event()

if isinstance(event, PushEvent):
    print(f"Push to {event.ref}")
    print(f"Commits: {len(event.commits)}")
elif isinstance(event, PullRequestEvent):
    print(f"PR #{event.number}: {event.pull_request.title}")
    print(f"Action: {event.action}")

Event Model Classes

The following typed models are available:

• PushEvent - Push events with commits, refs, and change information

• PullRequestEvent - Pull request events with PR details, labels, reviewers

• IssueCommentEvent - Issue and PR comment events

• WorkflowRunEvent - Workflow run events

Supporting models:

• Actor - GitHub user or organization

• Repository - Repository information

• Commit - Git commit details

• Label - Issue/PR labels

• PullRequest - Pull request details

• Issue - Issue details

• Comment - Comment on issue or PR

• WorkflowRun - Workflow run details

Convenience Helpers

is_pr()

Check if the current event is a pull request event.

example:

from github_action_toolkit import is_pr

if is_pr():
    print("This is a pull request event")

get_pr_number()

Get the pull request number for PR events.

example:

from github_action_toolkit import get_pr_number

pr_number = get_pr_number()
if pr_number:
    print(f"PR number: {pr_number}")

head_ref()

Get the head reference for the event.

• For push events: returns the ref being pushed to

• For pull request events: returns the head branch

example:

from github_action_toolkit import head_ref

ref = head_ref()
print(f"Head ref: {ref}")

base_ref()

Get the base reference for pull request events.

example:

from github_action_toolkit import base_ref

ref = base_ref()
if ref:
    print(f"Base ref: {ref}")

get_changed_files()

Get the list of changed files for push events.

example:

from github_action_toolkit import get_changed_files

files = get_changed_files()
for file in files:
    print(f"Changed: {file}")

get_labels()

Get the list of labels for pull request or issue events.

example:

from github_action_toolkit import get_labels

labels = get_labels()
if "bug" in labels:
    print("This is a bug fix")

Complete Example

from github_action_toolkit import (
    get_event_name,
    get_typed_event,
    is_pr,
    get_pr_number,
    head_ref,
    base_ref,
    get_labels,
    get_changed_files,
    PushEvent,
    PullRequestEvent,
)

# Get event information
event_name = get_event_name()
print(f"Event: {event_name}")

# Use typed event models
event = get_typed_event()

if isinstance(event, PushEvent):
    print(f"Push to {event.ref}")
    print(f"Before: {event.before}")
    print(f"After: {event.after}")
    
    files = get_changed_files()
    print(f"Changed files: {', '.join(files)}")

elif isinstance(event, PullRequestEvent):
    print(f"PR #{event.number}: {event.pull_request.title}")
    print(f"Action: {event.action}")
    print(f"Head: {head_ref()}")
    print(f"Base: {base_ref()}")
    
    labels = get_labels()
    print(f"Labels: {', '.join(labels)}")

# Use helper functions
if is_pr():
    pr_num = get_pr_number()
    print(f"Working on PR #{pr_num}")