# GitHub Workflow Run Event

> GitHub workflow_run webhook payload with run status, conclusion, and workflow tracking.

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

## Install

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

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

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

## Types

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

export interface GitHubWorkflowRun {
  id: number;
  node_id: string;
  name: string;
  head_branch: string;
  head_sha: string;
  run_number: number;
  event: string;
  status: string | null;
  conclusion: string | null;
  workflow_id: number;
  url: string;
  html_url: string;
  created_at: string;
  updated_at: string;
  run_attempt: number;
  run_started_at: string;
}

export interface GitHubWorkflow {
  id: number;
  node_id: string;
  name: string;
  path: string;
  state: string;
  created_at: string;
  updated_at: string;
}

export type GitHubWorkflowRunEventAction =
  | "requested"
  | "completed"
  | "in_progress";

export interface GitHubWorkflowRunEvent {
  action: GitHubWorkflowRunEventAction;
  workflow_run: GitHubWorkflowRun;
  workflow: GitHubWorkflow;
  repository: GitHubRepository;
  sender: GitHubUser;
  organization?: GitHubOrganization;
}
```

## Zod validator

```typescript
import * as z from "zod";
import type {
  GitHubWorkflowRun,
  GitHubWorkflow,
  GitHubWorkflowRunEventAction,
  GitHubWorkflowRunEvent,
} from "../types/github-workflow-run-event";
import {
  githubUserSchema,
  githubRepositorySchema,
  githubOrganizationSchema,
} from "./github-shared";

export const githubWorkflowRunSchema = z.object({
  id: z.number().int(),
  node_id: z.string(),
  name: z.string(),
  head_branch: z.string(),
  head_sha: z.string(),
  run_number: z.number().int(),
  event: z.string(),
  status: z.string().nullable(),
  conclusion: z.string().nullable(),
  workflow_id: z.number().int(),
  url: z.string(),
  html_url: z.string(),
  created_at: z.string(),
  updated_at: z.string(),
  run_attempt: z.number().int(),
  run_started_at: z.string(),
}) satisfies z.ZodType<GitHubWorkflowRun>;

export const githubWorkflowSchema = z.object({
  id: z.number().int(),
  node_id: z.string(),
  name: z.string(),
  path: z.string(),
  state: z.string(),
  created_at: z.string(),
  updated_at: z.string(),
}) satisfies z.ZodType<GitHubWorkflow>;

export const githubWorkflowRunEventActionSchema = z.enum([
  "requested",
  "completed",
  "in_progress",
]) satisfies z.ZodType<GitHubWorkflowRunEventAction>;

export const githubWorkflowRunEventSchema = z.object({
  action: githubWorkflowRunEventActionSchema,
  workflow_run: githubWorkflowRunSchema,
  workflow: githubWorkflowSchema,
  repository: githubRepositorySchema,
  sender: githubUserSchema,
  organization: githubOrganizationSchema.optional(),
}) satisfies z.ZodType<GitHubWorkflowRunEvent>;

export type {
  GitHubWorkflowRun,
  GitHubWorkflow,
  GitHubWorkflowRunEventAction,
  GitHubWorkflowRunEvent,
} from "../types/github-workflow-run-event";
```

## Examples

```typescript
// Source: https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_run
// Captured: 2026-05
import type {
  GitHubWorkflowRun,
  GitHubWorkflow,
  GitHubWorkflowRunEvent,
} from "../types/github-workflow-run-event";
import {
  githubUserOctocat,
  githubRepositoryHelloWorld,
  githubOrganizationGitHub,
} from "./shared/github.examples";

const workflowRunInProgress = {
  id: 9876543210,
  node_id: "WFR_kwLOABCDEF",
  name: "CI",
  head_branch: "main",
  head_sha: "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  run_number: 42,
  event: "push",
  status: "in_progress",
  conclusion: null,
  workflow_id: 161335,
  url: "https://api.github.com/repos/octocat/Hello-World/actions/runs/9876543210",
  html_url: "https://github.com/octocat/Hello-World/actions/runs/9876543210",
  created_at: "2024-09-12T10:15:30Z",
  updated_at: "2024-09-12T10:15:35Z",
  run_attempt: 1,
  run_started_at: "2024-09-12T10:15:32Z",
} as const satisfies GitHubWorkflowRun;

const workflowRunSuccess = {
  ...workflowRunInProgress,
  status: "completed",
  conclusion: "success",
  updated_at: "2024-09-12T10:20:10Z",
} as const satisfies GitHubWorkflowRun;

export const githubWorkflowRunExamples = {
  inProgress: workflowRunInProgress,
  success: workflowRunSuccess,
  failure: {
    ...workflowRunSuccess,
    conclusion: "failure",
  } satisfies GitHubWorkflowRun,
  retry: { ...workflowRunSuccess, run_attempt: 2 } satisfies GitHubWorkflowRun,
} as const;

const workflow = {
  id: 161335,
  node_id: "MDg6V29ya2Zsb3cxNjEzMzU=",
  name: "CI",
  path: ".github/workflows/ci.yml",
  state: "active",
  created_at: "2020-01-08T23:48:37.000Z",
  updated_at: "2020-01-08T23:50:21.000Z",
} as const satisfies GitHubWorkflow;

export const githubWorkflowExamples = {
  active: workflow,
  disabled: { ...workflow, state: "disabled_manually" } satisfies GitHubWorkflow,
} as const;

const minimal = {
  action: "requested",
  workflow_run: workflowRunInProgress,
  workflow,
  repository: githubRepositoryHelloWorld,
  sender: githubUserOctocat,
} as const satisfies GitHubWorkflowRunEvent;

export const githubWorkflowRunEventExamples = {
  minimal,
  inProgress: {
    ...minimal,
    action: "in_progress",
  } satisfies GitHubWorkflowRunEvent,
  completed: {
    ...minimal,
    action: "completed",
    workflow_run: workflowRunSuccess,
  } satisfies GitHubWorkflowRunEvent,
  full: {
    ...minimal,
    action: "completed",
    workflow_run: workflowRunSuccess,
    organization: githubOrganizationGitHub,
  } satisfies GitHubWorkflowRunEvent,
} as const;
```