# GitHub Push Event

> GitHub push webhook payload with commits, pusher, and ref tracking.

- Name: `github-push-event`
- Categories: github
- Depends on: `@open-types/github-shared`
- Detail page: https://open-types.dev/types/github-push-event

## Install

```bash
# Types only
npx shadcn add @open-types/github-push-event

# Types + Zod v4 validators
npx shadcn add @open-types/github-push-event-zod

# Types + real-world examples
npx shadcn add @open-types/github-push-event-examples
```

## Types

```typescript
import type {
  GitHubUser,
  GitHubRepository,
  GitHubOrganization,
} from "./github-shared";

export interface GitHubCommitAuthor {
  name: string;
  email: string;
  username?: string;
}

export interface GitHubCommit {
  id: string;
  tree_id: string;
  distinct: boolean;
  message: string;
  timestamp: string;
  url: string;
  author: GitHubCommitAuthor;
  committer: GitHubCommitAuthor;
  added: string[];
  removed: string[];
  modified: string[];
}

export interface GitHubPusher {
  name: string;
  email: string | null;
}

export interface GitHubPushEvent {
  ref: string;
  before: string;
  after: string;
  created: boolean;
  deleted: boolean;
  forced: boolean;
  compare: string;
  commits: GitHubCommit[];
  head_commit: GitHubCommit | null;
  repository: GitHubRepository;
  pusher: GitHubPusher;
  sender: GitHubUser;
  organization?: GitHubOrganization;
}
```

## Zod validator

```typescript
import * as z from "zod";
import type {
  GitHubCommitAuthor,
  GitHubCommit,
  GitHubPusher,
  GitHubPushEvent,
} from "../types/github-push-event";
import {
  githubUserSchema,
  githubRepositorySchema,
  githubOrganizationSchema,
} from "./github-shared";

export const githubCommitAuthorSchema = z.object({
  name: z.string(),
  email: z.string(),
  username: z.string().optional(),
}) satisfies z.ZodType<GitHubCommitAuthor>;

export const githubCommitSchema = z.object({
  id: z.string(),
  tree_id: z.string(),
  distinct: z.boolean(),
  message: z.string(),
  timestamp: z.string(),
  url: z.string(),
  author: githubCommitAuthorSchema,
  committer: githubCommitAuthorSchema,
  added: z.array(z.string()),
  removed: z.array(z.string()),
  modified: z.array(z.string()),
}) satisfies z.ZodType<GitHubCommit>;

export const githubPusherSchema = z.object({
  name: z.string(),
  email: z.string().nullable(),
}) satisfies z.ZodType<GitHubPusher>;

export const githubPushEventSchema = z.object({
  ref: z.string(),
  before: z.string(),
  after: z.string(),
  created: z.boolean(),
  deleted: z.boolean(),
  forced: z.boolean(),
  compare: z.string(),
  commits: z.array(githubCommitSchema),
  head_commit: githubCommitSchema.nullable(),
  repository: githubRepositorySchema,
  pusher: githubPusherSchema,
  sender: githubUserSchema,
  organization: githubOrganizationSchema.optional(),
}) satisfies z.ZodType<GitHubPushEvent>;

export type {
  GitHubCommitAuthor,
  GitHubCommit,
  GitHubPusher,
  GitHubPushEvent,
} from "../types/github-push-event";
```

## Examples

```typescript
// Source: https://docs.github.com/en/webhooks/webhook-events-and-payloads#push
// Captured: 2026-05
import type {
  GitHubCommitAuthor,
  GitHubCommit,
  GitHubPusher,
  GitHubPushEvent,
} from "../types/github-push-event";
import {
  githubUserOctocat,
  githubRepositoryHelloWorld,
  githubOrganizationGitHub,
} from "./shared/github.examples";

const ZERO_SHA = "0000000000000000000000000000000000000000";

const commitAuthorOctocat = {
  name: "Monalisa Octocat",
  email: "octocat@github.com",
  username: "octocat",
} as const satisfies GitHubCommitAuthor;

const commitAuthorDeployBot = {
  name: "deploy-bot",
  email: "bot@example.com",
} as const satisfies GitHubCommitAuthor;

const commitBugfix = {
  id: "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  tree_id: "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  distinct: true,
  message: "Fix all the bugs",
  timestamp: "2011-04-14T16:00:49+02:00",
  url: "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
  author: commitAuthorOctocat,
  committer: commitAuthorOctocat,
  added: ["src/index.ts"],
  removed: [],
  modified: ["README.md"],
} as const satisfies GitHubCommit;

const commitRefactor = {
  id: "7e1f3a2c4d5e6f7081929394a5b6c7d8e9f0a1b2",
  tree_id: "7e1f3a2c4d5e6f7081929394a5b6c7d8e9f0a1b2",
  distinct: true,
  message: "Refactor commit pipeline\n\nExtract helper functions for clarity.",
  timestamp: "2024-09-12T10:15:30Z",
  url: "https://api.github.com/repos/octocat/Hello-World/commits/7e1f3a2c4d5e6f7081929394a5b6c7d8e9f0a1b2",
  author: commitAuthorDeployBot,
  committer: commitAuthorOctocat,
  added: ["lib/pipeline.ts", "lib/util.ts"],
  removed: ["lib/legacy.ts"],
  modified: ["lib/index.ts", "package.json"],
} as const satisfies GitHubCommit;

export const githubCommitAuthorExamples = {
  withUsername: commitAuthorOctocat,
  withoutUsername: commitAuthorDeployBot,
} as const;

export const githubCommitExamples = {
  minimal: commitBugfix,
  full: commitRefactor,
} as const;

export const githubPusherExamples = {
  withEmail: { name: "octocat", email: "octocat@github.com" } satisfies GitHubPusher,
  nullEmail: { name: "deploy-key", email: null } satisfies GitHubPusher,
} as const;

const pushMinimal = {
  ref: "refs/heads/main",
  before: "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
  after: "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  created: false,
  deleted: false,
  forced: false,
  compare: "https://github.com/octocat/Hello-World/compare/6113728f27ae...6dcb09b5b578",
  commits: [commitBugfix],
  head_commit: commitBugfix,
  repository: githubRepositoryHelloWorld,
  pusher: { name: "octocat", email: "octocat@github.com" },
  sender: githubUserOctocat,
} as const satisfies GitHubPushEvent;

export const githubPushEventExamples = {
  minimal: pushMinimal,
  full: {
    ...pushMinimal,
    commits: [commitBugfix, commitRefactor],
    head_commit: commitRefactor,
    organization: githubOrganizationGitHub,
  } satisfies GitHubPushEvent,
  branchCreate: {
    ...pushMinimal,
    created: true,
    before: ZERO_SHA,
  } satisfies GitHubPushEvent,
  branchDelete: {
    ...pushMinimal,
    deleted: true,
    after: ZERO_SHA,
    commits: [],
    head_commit: null,
  } satisfies GitHubPushEvent,
  forced: { ...pushMinimal, forced: true } satisfies GitHubPushEvent,
} as const;
```