Skip to main content

​
Overview

The GitHub Subscriptions API allows you to subscribe channels to GitHub repository events. When events occur (like pushes, pull requests, or issues), notifications are automatically posted to the subscribed channel. Your organization must have GitHub connected before creating subscriptions.

​
Supported Event Types

The following GitHub events can be subscribed to:
  • push - Code pushes to repository
  • pull_request - Pull request opened, closed, merged, etc.
  • issues - Issues created, updated, closed, etc.
  • release - New releases published
  • deployment_status - Deployment status changes
  • workflow_run - GitHub Actions workflow runs
  • star - Repository starred or unstarred
  • milestone - Milestones created, updated, or completed

​
githubSubscription.create

Subscribe a channel to a GitHub repository’s events.
​
channelId
ChannelId
required
Channel to receive GitHub notifications
​
repositoryId
number
required
GitHub’s numeric repository ID (stable across renames)
​
repositoryFullName
string
required
Repository full name in “owner/repo” format (for display)
​
repositoryOwner
string
required
Repository owner (user or organization)
​
repositoryName
string
required
Repository name
​
enabledEvents
GitHubEventType[]
required
Array of event types to subscribe to
​
branchFilter
string | null
Optional branch filter for push events (e.g., “main”, null = all branches)
​
data
GitHubSubscription
The created subscription
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • ChannelNotFoundError - Channel doesn’t exist
  • GitHubNotConnectedError - Organization hasn’t connected GitHub
  • GitHubSubscriptionExistsError - Channel is already subscribed to this repository
  • UnauthorizedError - User is not authorized
  • InternalServerError - Server error
const result = await client.rpc("githubSubscription.create", {
  channelId: "channel_123",
  repositoryId: 12345678,
  repositoryFullName: "hazelchat/hazel",
  repositoryOwner: "hazelchat",
  repositoryName: "hazel",
  enabledEvents: ["push", "pull_request", "issues"],
  branchFilter: "main" // Only notify for main branch pushes
})

console.log("Subscribed to:", result.data.repositoryFullName)

​
githubSubscription.list

List all GitHub subscriptions for a specific channel.
​
channelId
ChannelId
required
Channel identifier
​
data
GitHubSubscription[]
Array of subscriptions for the channel
Errors:
  • ChannelNotFoundError - Channel doesn’t exist
  • UnauthorizedError - User is not authorized
  • InternalServerError - Server error
const result = await client.rpc("githubSubscription.list", {
  channelId: "channel_123"
})

for (const sub of result.data) {
  console.log(`Subscribed to: ${sub.repositoryFullName}`)
  console.log(`Events: ${sub.enabledEvents.join(", ")}`)
}

​
githubSubscription.listByOrganization

List all GitHub subscriptions across all channels in your organization. Useful for organization-level integration settings.
​
data
GitHubSubscription[]
Array of all subscriptions in the organization
Errors:
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Server error
const result = await client.rpc("githubSubscription.listByOrganization", {})

console.log(`Total subscriptions: ${result.data.length}`)

// Group by repository
const byRepo = result.data.reduce((acc, sub) => {
  const repo = sub.repositoryFullName
  acc[repo] = (acc[repo] || 0) + 1
  return acc
}, {})

console.log("Subscriptions by repository:", byRepo)

​
githubSubscription.update

Update a GitHub subscription’s settings.
​
id
GitHubSubscriptionId
required
Subscription identifier
​
enabledEvents
GitHubEventType[]
New array of event types to subscribe to
​
branchFilter
string | null
New branch filter (null = all branches)
​
isEnabled
boolean
Enable or disable the subscription
​
data
GitHubSubscription
Updated subscription object
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • GitHubSubscriptionNotFoundError - Subscription doesn’t exist
  • UnauthorizedError - User is not authorized
  • InternalServerError - Server error
const result = await client.rpc("githubSubscription.update", {
  id: "ghsub_abc123",
  enabledEvents: [
    "push",
    "pull_request",
    "issues",
    "release", // Added
    "workflow_run" // Added
  ]
})

​
githubSubscription.delete

Delete a GitHub subscription (soft delete). The channel will stop receiving notifications from the repository.
​
id
GitHubSubscriptionId
required
Subscription identifier
​
transactionId
TransactionId
Transaction ID for optimistic updates
Errors:
  • GitHubSubscriptionNotFoundError - Subscription doesn’t exist
  • UnauthorizedError - User is not authorized
  • InternalServerError - Server error
await client.rpc("githubSubscription.delete", {
  id: "ghsub_abc123"
})

console.log("Subscription removed")

​
Event Filtering Examples

​
Development Channel (All Activity)

await client.rpc("githubSubscription.create", {
  channelId: "dev_channel",
  repositoryId: 12345678,
  repositoryFullName: "myorg/myrepo",
  repositoryOwner: "myorg",
  repositoryName: "myrepo",
  enabledEvents: [
    "push",
    "pull_request",
    "issues",
    "release",
    "deployment_status",
    "workflow_run",
    "star",
    "milestone"
  ],
  branchFilter: null // All branches
})

​
Production Channel (Releases Only)

await client.rpc("githubSubscription.create", {
  channelId: "production_channel",
  repositoryId: 12345678,
  repositoryFullName: "myorg/myrepo",
  repositoryOwner: "myorg",
  repositoryName: "myrepo",
  enabledEvents: ["release", "deployment_status"],
  branchFilter: "main"
})

​
CI/CD Channel (Workflows and Deployments)

await client.rpc("githubSubscription.create", {
  channelId: "cicd_channel",
  repositoryId: 12345678,
  repositoryFullName: "myorg/myrepo",
  repositoryOwner: "myorg",
  repositoryName: "myrepo",
  enabledEvents: ["workflow_run", "deployment_status"],
  branchFilter: null
})

Build docs developers (and LLMs) love

Get started for freeTalk to us