Skip to content

github.md

Latest commit

 

History

History
104 lines (78 loc) · 4.91 KB

github.md

File metadata and controls

104 lines (78 loc) · 4.91 KB
Raw

connector-github

GitHub API v3 integration. Personal access token authentication, webhook-driven triggers with HMAC verification, and issue/comment/diff actions.

  GitHub                  connector-github               Rule engine
     │                            │                           │
     │  webhook (push, PR,        │                           │
     │   issue, comment)          │                           │
     │  X-Hub-Signature-256       │                           │
     ├───────────────────────────►│                           │
     │                            │ verify_webhook (HMAC-256) │
     │                            │ emit TriggerEvent         │
     │                            ├──────────────────────────►│
     │                            │                           │
     │  REST v3 request           │  execute(create_issue,    │
     │  api.github.com            │           post_comment,…) │
     │  Bearer <PAT>              │  ◄────────────────────────┤
     │  ◄─────────────────────────┤                           │

Fig. 1. GitHub data flow. Inbound webhooks are HMAC-SHA256 verified against webhook_secret; outbound calls use a PAT stored as Secret<String>.

1. Configuration

TABLE I. CONFIG FIELDS

Field Type Default Description
token Secret<String> (required) GitHub Personal Access Token
webhook_secret Option<Secret<String>> None HMAC-SHA256 webhook secret for signature verification
api_base String "https://api.github.com" GitHub API base URL

2. Authentication

Personal Access Token (PAT) passed as Authorization: Bearer header on all API requests.

3. Triggers

TABLE II. TRIGGERS

Name GitHub event Payload fields
push push ref, repository (owner/repo), pusher, commits_count
pull_request_opened pull_request (action: opened) number, title, repository (owner/repo), author, url
issue_opened issues (action: opened) number, title, repository (owner/repo), author, url
issue_comment issue_comment issue_number, body, repository (owner/repo), author

Payloads are transformed from GitHub's nested webhook JSON into flat fields by the daemon's webhook handler (apps/springtaled/src/api/webhooks/github.rs). Action filtering — e.g. only firing pull_request_opened when the GitHub action field is "opened" — happens at this transformation layer, not inside the connector.

4. Actions

TABLE III. ACTIONS

Name Input fields Output fields
create_issue owner, repo, title, body (optional, default: "") number: u64, url: String, response: Object
post_comment owner, repo, issue_number: u64, body id: u64, url: String, response: Object
get_diff owner, repo, pull_number: u64 diff: String
create_branch owner, repo, branch, base (optional, default: "main") branch: String, sha: String, response: Object
commit_file owner, repo, branch, path, content (plain UTF-8), message, existing_sha (optional — blob SHA when updating; omit to create) path: String, commit_sha: String, response: Object
create_pr owner, repo, title, head, base (optional, default: "main"), body (optional Markdown, default: "") number: u64, url: String, response: Object

The three write actions compose into a full PR flow — create_branch → commit_file → create_pr — enough for a bot to open a reviewable pull request end-to-end. All three are read_only: false.

5. Capabilities Required

Capability Parameter
NetworkOutbound api.github.com

6. Example Rule

[rule]
name = "pr-auto-comment"

[trigger]
type = "ConnectorEvent"
connector = "connector-github"
event = "pull_request_opened"

[[conditions]]
type = "FieldEquals"
field = "trigger.repository"
value = "ScopeCreep-zip/Springtale"

[[actions]]
type = "RunConnector"
connector = "connector-github"
action = "post_comment"

[actions.params]
owner = "ScopeCreep-zip"
repo = "Springtale"
issue_number = "${trigger.number}"
body = "Thanks for the PR! CI checks will run automatically."

7. Webhook Verification

Inbound webhooks are verified using HMAC-SHA256. The X-Hub-Signature-256 header contains sha256=<hex-digest>. The connector computes HMAC-SHA256(webhook_secret, request_body) and compares using constant-time equality. If webhook_secret is not configured, verification is skipped.