GitHub Trigger

The GitHub trigger responds to webhook events from your repositories in real-time. When events like pushes, pull requests, issues, or releases occur, VoltOps executes your configured agents or workflows.

For trigger setup and usage instructions, see the Usage Guide.

Use Cases:

• Run code review agents when pull requests are opened
• Automate issue triage and labeling
• Trigger deployments on release events
• Monitor security advisories and vulnerabilities
• Sync repository changes across systems

Setting Credential

To set up GitHub authentication, you need to create a credential. This is configured in Step 1 (Connection) when creating a trigger.

1. Navigate to the VoltOps Triggers page
2. Select GitHub as the provider
3. In the Connection step, either select an existing credential or create a new one
4. Choose between Personal Access Token or OAuth 2.0 and follow the instructions below.

Personal Access Token

Create your token:

1. Visit github.com/settings/tokens
2. Click Generate new token → New personal access token (classic)
3. Create a personal access token with repo and admin:repo_hook scopes

Configure in VoltOps Console:

1. Enter your Personal Access Token so VoltOps can create and verify repository webhooks
2. VoltOps generates and stores the webhook secret. No additional configuration is required
3. Configure optional fields:
   • GitHub Server: Update if using GitHub Enterprise (e.g., https://github.example.com/api/v3). Default: https://api.github.com
   • Repository Owner: Optional default repository owner
   • Account Label: Optional label for organization or user

OAuth 2.0

OAuth 2.0 supports token rotation and revocable access.

Setup steps:

1. Copy the OAuth Redirect URL displayed in the console (e.g., https://api.voltagent.dev/triggers/oauth/callback/github)
2. Navigate to GitHub Settings → Developer settings → OAuth Apps and create a new OAuth App
3. Provide a name and homepage URL for your OAuth App
4. Paste the OAuth Redirect URL as the Authorization callback URL in GitHub
5. Generate a Client ID and Client Secret in GitHub, then enter them in VoltOps Console
6. Configure optional fields:
   • GitHub Server: Update if using GitHub Enterprise (e.g., https://github.example.com/api/v3). Default: https://api.github.com
   • Account Label: Optional label for organization or user
   • Repository Owner: Optional default repository owner
7. Click Authorize with GitHub to complete the authorization flow

Required OAuth Scopes:

VoltOps requests the following scopes during authorization:

• repo - Access repositories
• admin:repo_hook - Manage webhooks
• user - Access user profile
• read:user - Read user profile data

OAuth Redirect URL

The redirect URL is provided by VoltOps Console and routes the OAuth callback to the correct endpoint. You must copy this URL exactly as shown in the console, including the protocol (https://) and path.

When to Use OAuth

Use OAuth 2.0 for team environments, production deployments, or credential rotation requirements. Personal Access Tokens are simpler for individual development.

Trigger Configuration

After configuring credentials, you need to specify which repository and events to monitor.

Select the credential you created and configure the repository settings:

• Owner: Enter the GitHub repository owner (username or organization name)
• Repository: Enter the repository name within the owner's account
• Branch Filter (Optional): Provide a branch name to restrict push events. Leave blank to allow all branches

VoltOps listens for events from this repository and configures the GitHub webhook automatically.

Add Target to Activate Binding

After configuring your GitHub trigger, you need to add a target (agent or workflow) to activate the binding. For detailed instructions on:

• Adding targets to activate bindings
• Mapping trigger data to agent inputs
• Testing triggers with sample payloads
• Deploying and monitoring triggers

See the Add Target to Activate Binding section. These steps are the same for all trigger providers.

Event Types

GitHub triggers support all GitHub webhook events. VoltOps configures the webhook when you create a trigger. No manual webhook setup is required.

When creating a trigger in VoltOps Console, you can select which events to listen for. The trigger will only execute when the selected events occur.

GitHub webhook events include:

Hide 51 events

PushWEBHOOK

Commits pushed to a repository branch or tag

Pull RequestWEBHOOK

Pull request activity (opened, closed, synchronized, merged, labeled, assigned)

Pull Request ReviewWEBHOOK

Pull request review submitted, edited, or dismissed

IssuesWEBHOOK

Issue activity (created, edited, deleted, transferred, pinned, closed, reopened)

Issue CommentWEBHOOK

Comments on issues or pull requests (created, edited, deleted)

ReleaseWEBHOOK

Release published, edited, deleted, or prereleased

ForkWEBHOOK

User forks a repository

StarWEBHOOK

Star added to or removed from a repository

WatchWEBHOOK

Someone stars a repository

CreateWEBHOOK

Repository, branch, or tag created

DeleteWEBHOOK

Repository branch or tag deleted

Branch Protection RuleWEBHOOK

Branch protection rules changed

PublicWEBHOOK

Repository made public

RepositoryWEBHOOK

Repository created, deleted, archived, unarchived, publicized, privatized, edited, renamed, transferred, or changed

ProjectWEBHOOK

Project created, updated, closed, reopened, edited, or deleted

Project CardWEBHOOK

Project card created, edited, moved, converted, or deleted

Project ColumnWEBHOOK

Project column created, updated, moved, or deleted

MilestoneWEBHOOK

Milestone created, edited, closed, opened, or deleted

LabelWEBHOOK

Label created, edited, or deleted

Check RunWEBHOOK

Check run created, completed, or rerequested

Check SuiteWEBHOOK

Check suite completed or requested

DeploymentWEBHOOK

Deployment created

Deployment StatusWEBHOOK

Deployment status updated

StatusWEBHOOK

Commit status updated

Workflow DispatchWEBHOOK

Manual workflow trigger

Workflow JobWEBHOOK

Workflow job queued, in progress, or completed

Workflow RunWEBHOOK

Workflow run requested, in progress, or completed

Page BuildWEBHOOK

Pages site built

DeployWEBHOOK

Deployment request

Code Scanning AlertWEBHOOK

Code scanning alert created, fixed, appeared in branch, closed, or reopened

Repository Vulnerability AlertWEBHOOK

Security vulnerability detected

Security AdvisoryWEBHOOK

Security advisory published, updated, or withdrawn

Repository AdvisoryWEBHOOK

Repository security advisory published, updated, or reported

DiscussionWEBHOOK

Discussion created, edited, deleted, or changed

Discussion CommentWEBHOOK

Comment on a discussion

MemberWEBHOOK

Collaborator added to repository

MembershipWEBHOOK

User added or removed from team

TeamWEBHOOK

Team created, deleted, edited, added to repository, or removed from repository

Team AddWEBHOOK

Team added to repository

OrganizationWEBHOOK

Organization deleted, renamed, member added, member removed, or member invited

Org BlockWEBHOOK

Organization blocks or unblocks a user

SponsorshipWEBHOOK

Sponsorship created, cancelled, edited, tier changed, or pending tier change

Commit CommentWEBHOOK

Comment on a commit

Pull Request Review CommentWEBHOOK

Comment on pull request diff

Pull Request Review ThreadWEBHOOK

Review thread resolved or unresolved

Deploy KeyWEBHOOK

Deploy key added or removed

GollumWEBHOOK

Wiki page updated

PackageWEBHOOK

Package published or updated

Repository DispatchWEBHOOK

Custom webhook event

Repository ImportWEBHOOK

Repository import completed

MetaWEBHOOK

Webhook modified

Configuration Parameters

After setting up authentication in Step 1 (Connection), configure the trigger options in Step 2 (Configuration).

Owner

Enter the GitHub repository owner (username or organization name).

Repository

Enter the repository name within the owner's account.

tip

VoltOps listens for events from this repository and configures the GitHub webhook automatically.

Branch Filter (Optional)

Restrict push events to a specific branch. Leave blank to allow all branches.

note

The branch filter only applies to push events. Other events (pull requests, issues, releases, etc.) are not affected by this filter.

GitHub Enterprise Support

VoltOps supports GitHub Enterprise Server deployments. When creating your credential, configure the GitHub server field to point to your GitHub Enterprise API endpoint.

GitHub Enterprise API endpoints typically follow the format https://[hostname]/api/v3. The default is https://api.github.com for GitHub.com.

Payload Structure

VoltOps wraps GitHub webhook payloads in a standardized format. The payload structure includes metadata about the event and the complete GitHub webhook data.

Wrapper Format

All GitHub events delivered by VoltOps follow this structure:

{
  "event": "push", // The GitHub event type (push, pull_request, issues, etc.)
  "deliveryId": "e7edfcf0-bfa8-11f0-81d5-e3c9c0d87c3c", // Unique identifier for this webhook delivery
  "repository": {
    // Simplified repository information
    "id": 123456,
    "name": "repo-name",
    "fullName": "owner/repo-name",
    "owner": "owner-name",
    "private": false,
    "htmlUrl": "https://github.com/owner/repo-name"
  },
  "payload": {
    // Complete GitHub webhook payload
    // GitHub webhook payload here
  }
}

For complete examples of push, pull request, and issue events, see the GitHub webhook documentation.