mirror of
https://github.com/langgenius/dify-plugin-sdks.git
synced 2026-07-22 10:25:23 -04:00
Harry
6220b50946
- Bumped version from 1.3.0 to 1.3.1 in the manifest. - Removed deprecated issue comment events: issue_comment_created, issue_comment_edited, issue_comment_deleted. - Consolidated issue comment handling into a unified structure for better maintainability. - Updated README to reflect changes in event handling and provide clearer setup instructions.
95 lines
6.1 KiB
Markdown
95 lines
6.1 KiB
Markdown
GitHub Trigger (Unified Events)
|
||
|
||
Overview
|
||
- GitHub Trigger is a Dify provider that receives GitHub webhooks and emits trigger events into your workflows.
|
||
- Events are unified by family (e.g., issues, pull_request, check_run) with an actions filter, instead of splitting every action into separate events. This reduces noise and aligns with product usage.
|
||
- Each event exposes clear parameters and a comprehensive output schema (including full repository and sender objects) for reliable automation.
|
||
|
||
Quick Start
|
||
- Install dependencies: `pip install -r requirements.txt`
|
||
- In Dify, add the GitHub Trigger provider and configure Credentials.
|
||
- Create a Subscription with:
|
||
- `repository`: pick one repository (dynamic select)
|
||
- `events`: choose the webhook families you want (e.g., issues, pull_request, check_run)
|
||
- `webhook_secret` (optional): used to validate signatures; see “Webhook Secret”.
|
||
|
||
Credentials
|
||
- Access Token (recommended for simplicity)
|
||
- Generate a fine-grained or classic token with repo/webhook scopes.
|
||
- Where to create: https://github.com/settings/tokens?type=beta
|
||
- OAuth (optional)
|
||
- Register a GitHub OAuth app and provide Client ID/Secret.
|
||
- Used to obtain an access token during subscription construction.
|
||
|
||
Webhook Secret
|
||
- Purpose: verify the HMAC signature on incoming requests.
|
||
- If Dify creates the webhook: a random secret is generated and stored with the subscription.
|
||
- If you configure the webhook manually in Repository Settings → Webhooks: set the same secret in GitHub and paste it into `webhook_secret` so signatures validate.
|
||
- Reference: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
|
||
|
||
Unified Event Model
|
||
- Design: unify events per family and expose an `actions` multi-select parameter to filter actions when payload shapes are identical (e.g., star created/deleted, label created/edited/deleted).
|
||
- Benefits: fewer choices for users, simpler mental model, consistent schemas, easier reuse.
|
||
- Breaking change: legacy per-action events (e.g., issue_opened) are replaced by unified families; configure the desired actions in parameters.
|
||
|
||
Parameter Semantics
|
||
- Multi-select parameters: choose specific actions/states; leave empty to accept all supported values.
|
||
- String lists: comma-separated exact matches, case-insensitive where noted (e.g., authors, labels).
|
||
- Contains filters: “*_contains” parameters check substrings and accept comma-separated keywords; any match passes.
|
||
- Boolean flags: when set, they filter strictly (true/false). When omitted, they do not filter.
|
||
- Glob patterns: where supported (e.g., changed_files_glob), match file paths with comma-separated globs.
|
||
|
||
Implemented Events (high-level)
|
||
- Collaboration: issues, issue_comment, pull_request, pull_request_review, pull_request_review_comment, pull_request_review_thread
|
||
- CI/Automation: check_suite, check_run, workflow_run, workflow_job, status
|
||
- SCM: push, ref_change (create/delete), commit_comment, release (published), deployment, deployment_status (created)
|
||
- Governance/Security: code_scanning_alert, secret_scanning, dependabot_alert, repository_vulnerability_alert, repository_advisory, security_and_analysis, branch_protection_configuration, branch_protection_rule, repository_ruleset
|
||
- Community/Growth: discussion, discussion_comment, star, watch, fork, label, gollum (Wiki)
|
||
- Projects/Planning: milestone, project, project_column, project_card, member, merge_group, meta
|
||
- Packages: package, registry_package
|
||
- Advanced: repository, repository_import, public, custom_property_values, issue_dependencies, sub_issues, deploy_key
|
||
|
||
Output Schema Consistency
|
||
- Every unified event includes a detailed `repository` and `sender` block modeled after the Issues event style.
|
||
- Each family adds its specific object (e.g., `issue`, `pull_request`, `check_run`, `package`, `deployment`, `pages`) with commonly used fields and URLs.
|
||
- See the YAML under `events/**/` for complete schemas and parameter help.
|
||
|
||
Subscription Flow
|
||
- Provider manifest: `github_trigger/provider/github.yaml` lists all registered events.
|
||
- Dispatch: `github_trigger/provider/github.py` routes GitHub headers and payloads to the appropriate unified event.
|
||
- Subscriptions automatically create and manage webhooks on the target repository using your credentials.
|
||
|
||
Examples
|
||
- Subscribe to PR review automation
|
||
- Events: `pull_request`, `pull_request_review`, `pull_request_review_comment`
|
||
- Parameters: set `actions` to the review states you care about; optionally filter by `reviewer`, `author`, `body_contains`.
|
||
- Security guardrails
|
||
- Events: `code_scanning_alert`, `dependabot_alert`, `secret_scanning`
|
||
- Parameters: filter by `severity`, `state`, `branch`, or `subtypes` for secret scanning.
|
||
- Branch governance
|
||
- Event: `ref_change` with `event_types=create,delete` and `ref_type=branch` to detect branch creation/deletion.
|
||
|
||
Extending the Provider
|
||
- Add a new event family
|
||
- Create a folder under `events/<family>/` with `<family>.py` and `<family>.yaml`.
|
||
- Implement a subclass of `dify_plugin.interfaces.trigger.Event` with `_on_event` returning `Variables(payload)`.
|
||
- In YAML, provide `identity`, `description`, `parameters` (include helpful `help` text), and a complete `output_schema`.
|
||
- Register the YAML path in `provider/github.yaml` under `events:`.
|
||
- Utilities
|
||
- Common helpers live in `events/utils/` (payload loading, PR filters, etc.).
|
||
|
||
Troubleshooting
|
||
- Webhook not triggering: verify repository, events, and that the webhook delivery logs show 2xx.
|
||
- Signature validation failed: confirm `webhook_secret` is identical on both GitHub and the subscription.
|
||
- Filter didn’t match: check your parameter values against the actual payload (comma-separated vs exact match; action names).
|
||
- Payload variance: some security events differ by repo/app configuration; schemas cover common fields but you may need to adjust filters.
|
||
|
||
Directory Layout
|
||
- `provider/github.py`: webhook dispatch, subscription lifecycle, OAuth/API key handling
|
||
- `provider/github.yaml`: manifest, credential schemas, events listing
|
||
- `events/**`: unified event handlers (`.py`) and schemas (`.yaml`)
|
||
- `EVENTS_TODO.md`: planning and status for event coverage
|
||
|
||
Author
|
||
- langgenius
|