ScriptFabric for Jira Cloud

GitHub Integration Technical Reference

Feature-focused reference for GitHub webhooks, event automation, HAPI APIs, and Jira ↔ GitHub workflows.

SCOPE: This document is based strictly on the supported GitHub capabilities provided for ScriptFabric for Jira Cloud.

Contents

  1. Supported GitHub Webhook Events
  2. Event Type Details
  3. Automated Webhook Provisioning & Lifecycle
  4. Inbound Webhook Execution Engine
  5. Event Handler Automation & context.github
  6. Canarys HAPI — git.* Scripting API
  7. Repository APIs
  8. GitHub Issue APIs
  9. Pull Request APIs
  10. Commit & Branch APIs
  11. Releases & GitHub Actions APIs
  12. Practical Jira–GitHub Automation Examples
  13. Security & Reliability Features
  14. Complete Supported Feature Summary
  15. End-to-End Jira ↔ GitHub Automation Coverage

1. Supported GitHub Webhook Events

ScriptFabric supports 12 GitHub event types for webhook subscriptions.

Event Type Available Actions / Activity Common Jira Use Cases
push Git commits pushed to branches or tags Update Jira issue, record commit information, trigger validation
pull_request PR actions: opened, closed, reopened, synchronized, merged, labeled, assigned Transition Jira issue, add comments, update development status
pull_request_review PR review submitted, edited, or dismissed Update Jira review status, notify teams
issues GitHub issue created, edited, closed, reopened, or labeled Synchronize GitHub Issues with Jira
issue_comment Comments posted on issues or pull requests Mirror GitHub comments into Jira
create Git branch or tag created Create/update Jira tracking information
delete Git branch or tag deleted Record branch/tag lifecycle changes
release Release published, edited, or deleted Update Jira release information
workflow_run GitHub Actions workflow requested, completed, or failed Build/CI status updates in Jira
deployment Deployment created or triggered Track deployment activity
deployment_status Deployment state: success, failure, in-progress Update Jira deployment/release status
check_run Check suite/run completed or updated Report CI/check results to Jira

2. Event Type Details

  • 2.1 push: Triggered when commits are pushed to a GitHub repository, including pushes to branches or tags. Typical automation includes adding commit activity to Jira or triggering branch-specific validation.
  • 2.2 pull_request: Handles Pull Request lifecycle events: opened, closed, reopened, synchronized, merged, labeled, and assigned. This is a primary event for development workflow automation.
  • 2.3 pull_request_review: Handles Pull Request review submitted, edited, or dismissed events and can be used to record review activity in Jira.
  • 2.4 issues: Handles GitHub Issue created, edited, closed, reopened, or labeled events for GitHub Issue/Jira synchronization.
  • 2.5 issue_comment: Triggered when a comment is posted on a GitHub Issue or Pull Request, enabling real-time comment synchronization.
  • 2.6 create: Triggered when a GitHub branch or tag is created.
  • 2.7 delete: Triggered when a GitHub branch or tag is deleted.
  • 2.8 release: Handles GitHub Release published, edited, or deleted activity.
  • 2.9 workflow_run: Handles GitHub Actions workflow requested, completed, or failed events, enabling CI/CD status synchronization.
  • 2.10 deployment: Triggered when a GitHub deployment is created or triggered.
  • 2.11 deployment_status: Tracks deployment status changes including success, failure, and in-progress states.
  • 2.12 check_run: Handles GitHub Check Run completion or update events and can report check results to Jira.

3. Automated Webhook Provisioning & Lifecycle

3.1 Direct Webhook Registration

ScriptFabric can register webhooks directly on GitHub repositories through the GitHub API, removing the need for manual GitHub webhook setup for each repository.

3.2 Dynamic HMAC-SHA256 Secrets

Each webhook can use a dynamically generated secret. Incoming GitHub payloads are validated using the X-Hub-Signature-256 header.

3.3 Orphan Webhook Cleanup

ScriptFabric supports cleanup of webhook registrations that are no longer associated with active ScriptFabric configuration.

3.4 Webhook Pinging

Webhook pinging provides a mechanism to verify GitHub-to-ScriptFabric webhook connectivity.

3.5 Live GitHub Delivery Log Inspector

The delivery log inspector provides visibility into GitHub webhook deliveries for troubleshooting and operational verification.

4. Inbound Webhook Execution Engine

4.1 Webhook Receiver

The ScriptFabric GitHub webhook receiver is:

sf-github-webhook-receiver

4.2 Timing-Safe HMAC-SHA256 Verification

ScriptFabric validates GitHub's X-Hub-Signature-256 signature using the webhook secret and a timing-safe comparison.

4.3 Delivery Deduplication

The X-GitHub-Delivery identifier is used to identify a GitHub delivery and prevent duplicate execution when GitHub retries a delivery.

4.4 Asynchronous Background Execution

Accepted webhook events are dispatched asynchronously into Forge background execution, with the supported 15-minute background execution window.

5. Event Handler Automation & context.github

Event Handlers can be configured for a selected GitHub event and action filter. GitHub event information is exposed through context.github.

Property Description
deliveryId GitHub delivery identifier
event GitHub event type
action Event action
repository Repository information
sender GitHub user that generated the event
payload Event-specific GitHub payload 
const github = context.github;
console.log("Delivery:", github.deliveryId);
console.log("Event:", github.event);
console.log("Action:", github.action);
console.log("Repository:", github.repository);
console.log("Sender:", github.sender);
console.log("Payload:", github.payload);

6. Canarys HAPI — git.* Scripting API

The Canarys HAPI provides a high-level GitHub scripting API for ScriptFabric. It is available in Console, Listeners, and Scheduled Jobs.

Area Supported APIs
Repositories git.getRepo, git.createRepo, git.listOrgRepos, git.updateRepo
Issues git.listIssues, git.createIssue, git.closeIssue, git.addIssueComment
Pull Requests git.listPRs, git.createPR, git.mergePR, git.addPRReview
Commits & Branches git.listBranches, git.createBranch, git.listCommits
Releases & Actions git.createRelease, git.dispatchWorkflow, git.listWorkflowRuns

7. Repository APIs

git.getRepo

const repo = await git.getRepo("my-org", "my-repository");

git.createRepo

const repo = await git.createRepo("my-org", { name: "release-automation" });

git.listOrgRepos

const repos = await git.listOrgRepos("my-org");

git.updateRepo

await git.updateRepo("my-org", "my-repository", { description: "Updated through ScriptFabric" });

8. GitHub Issue APIs

git.listIssues

const issues = await git.listIssues("my-org", "my-repository");

git.createIssue

const issue = await git.createIssue("my-org", "my-repository", { 
  title: "Issue created from Jira", 
  body: "Created by ScriptFabric." 
});

git.closeIssue

await git.closeIssue("my-org", "my-repository", 123);

git.addIssueComment

await git.addIssueComment("my-org", "my-repository", 123, "Synchronized from Jira.");

9. Pull Request APIs

git.listPRs

const prs = await git.listPRs("my-org", "my-repository");

git.createPR

const pr = await git.createPR("my-org", "my-repository", { 
  title: "Release PR", 
  head: "release/1.0", 
  base: "main" 
});

git.mergePR

const result = await git.mergePR("my-org", "my-repository", 42);

git.addPRReview

await git.addPRReview("my-org", "my-repository", 42, { 
  body: "Automated review completed.", 
  event: "COMMENT" 
});

10. Commit & Branch APIs

git.listBranches

const branches = await git.listBranches("my-org", "my-repository");

git.createBranch

await git.createBranch("my-org", "my-repository", "feature/SF-123");

git.listCommits

const commits = await git.listCommits("my-org", "my-repository");

11. Releases & GitHub Actions APIs

git.createRelease

const release = await git.createRelease("my-org", "my-repository", { 
  tag_name: "v1.0.0", 
  name: "Version 1.0.0" 
});

git.dispatchWorkflow

await git.dispatchWorkflow("my-org", "my-repository", "release.yml", { ref: "main" });

git.listWorkflowRuns

const runs = await git.listWorkflowRuns("my-org", "my-repository");

12. Practical Jira–GitHub Automation Examples

The following examples demonstrate key automation patterns. GitHub event data uses ScriptFabric's context.github and GitHub operations use the documented git.* API. Jira issue updates use the standard Forge Jira REST API pattern.

12.1 Example 1 — PR Opened → Jira Issue In Review

Configure an Event Handler for pull_request / opened. Extract the Jira issue key from the PR title or branch name, transition the issue to In Review, and add a comment.

12.2 Example 2 — Merged PR → Close Jira Issue

Configure pull_request / closed, then check that the PR is merged and its base branch is main.

IMPLEMENTATION: Reporter notification can be handled through the Jira notification configuration associated with the transition/comment.

12.3 Example 3 — Failed Workflow → Jira Build Comment

Configure workflow_run / completed and process only runs whose conclusion is failure.

12.4 Example 4 — Ready for Release → GitHub Workflow Dispatch

Add a ScriptFabric workflow post-function to the Jira transition into Ready for Release.

12.5 Example 5 — GitHub Issue Comments → Jira Comments

Configure issue_comment / created and map the GitHub Issue to the Jira issue using an issue key contained in the GitHub Issue title or body.

13. Security & Reliability Features

Feature Purpose
Per-webhook HMAC-SHA256 secret Authenticate GitHub webhook requests
X-Hub-Signature-256 verification Validate payload authenticity
Timing-safe comparison Reduce timing-based signature comparison risk
X-GitHub-Delivery Identify individual GitHub deliveries
Delivery deduplication Prevent duplicate execution from retries
Async background queue Process webhook automation asynchronously
Orphan cleanup Remove obsolete webhook registrations
Webhook ping Validate webhook connectivity
Delivery inspector Troubleshoot GitHub webhook deliveries

14. Complete Supported Feature Summary

  • 14.1 Webhooks: push; pull_request; pull_request_review; issues; issue_comment; create; delete; release; workflow_run; deployment; deployment_status; check_run.
  • 14.2 Webhook Management: Automatic webhook registration; per-webhook HMAC-SHA256 secrets; signature validation; webhook ping; orphan webhook cleanup; delivery log inspection.
  • 14.3 Execution Engine: sf-github-webhook-receiver; X-Hub-Signature-256 validation; timing-safe verification; X-GitHub-Delivery deduplication; asynchronous Forge background execution; 15-minute background execution window.
  • 14.4 Event Automation: Event Handler triggers; event/action filtering; context.github; delivery ID; event type; action; repository; sender; payload.
  • 14.5 Scripting APIs: Repositories, Issues, Pull Requests, Branches, Commits, Releases, and GitHub Actions through the supported git.* methods.
  • 14.6 Developer Experience: GitHub raw/blob URL script import into Script Hub or Console, plus the Rovo GitHub status action rovo-gh-status-fn.

15. End-to-End Jira ↔ GitHub Automation Coverage

ScriptFabric supports both GitHub-to-Jira event automation and Jira-to-GitHub API-driven automation.

Direction Trigger / Capability Example Outcome
GitHub → Jira push Commit activity or validation automation
GitHub → Jira pull_request Jira development workflow transition
GitHub → Jira pull_request_review Review activity synchronization
GitHub → Jira issue_comment Comment synchronization
GitHub → Jira workflow_run CI/CD result reporting
GitHub → Jira deployment_status Deployment status update
Jira → GitHub git.createPR Create Pull Request
Jira → GitHub git.mergePR Merge Pull Request
Jira → GitHub git.createRelease Create GitHub Release
Jira → GitHub git.dispatchWorkflow Trigger GitHub Actions
Jira ↔ GitHub Event Handler + git.* Bidirectional DevOps automation

SCOPE: The GitHub capability set documented here is limited to the supported capabilities supplied for ScriptFabric for Jira Cloud. No additional GitHub event types or APIs are assumed.