ServiceNow GitHub Integration Guide

Architecture Overview

Implementation Steps

// Flow Designer GitHub Action Configuration
// Action: Get Repository
// Connection: GitHub Production Connection
// Owner: your-github-username
// Repository: your-repo-name
// The action will return repository metadata including full_name, description, and default_branch

(function process(request, response) {
    var payload = request.body.dataString;
    var signature = request.getHeader('X-Hub-Signature-256');
    var eventType = request.getHeader('X-GitHub-Event');
    
    // Verify webhook signature
    var secretKey = gs.getProperty('github.webhook.secret');
    var expectedSig = 'sha256=' + GlideDigest.getMD5Base64(secretKey + payload);
    
    if (signature !== expectedSig) {
        response.setStatus(401);
        response.setBody('Unauthorized');
        return;
    }
    
    var data = JSON.parse(payload);
    gs.info('GitHub webhook received: ' + eventType + ' for repo: ' + data.repository.full_name);
    
    response.setStatus(200);
    response.setBody('OK');
})(request, response);

// Flow Data Mapping for Repository Dispatch
// Event Type: 'servicenow-deployment'
// Client Payload:
{
    "change_number": "{{trigger.current.number}}",
    "change_description": "{{trigger.current.short_description}}",
    "deployment_window": "{{trigger.current.start_date}}",
    "environment": "production",
    "requested_by": "{{trigger.current.requested_by.display_value}}"
}

// GitHub Issue Creation Data Mapping
// Title: "{{trigger.current.short_description}}"
// Body: "Incident Number: {{trigger.current.number}}\n\nDescription: {{trigger.current.description}}\n\nServiceNow URL: https://instance.service-now.com/nav_to.do?uri=incident.do?sys_id={{trigger.current.sys_id}}"
// Labels: ["servicenow-incident", "{{trigger.current.category}}"]

Common Use Cases

Troubleshooting

Pro Tips

• →Implement webhook signature verification using HMAC-SHA256 with a rotating secret stored in encrypted system properties to prevent unauthorized webhook payloads from creating ServiceNow records. Use GlideDigest.getHMAC() method for secure signature validation and always validate the timestamp header to prevent replay attacks.
• →Create custom GitHub connection health monitoring by building a scheduled job that tests API connectivity and token validity, automatically creating incidents when authentication failures occur. This proactive approach prevents integration failures during critical deployment windows and provides early warning for token expiration.
• →Use GitHub's GraphQL API instead of REST API for complex queries requiring multiple repository or organization details to reduce API call volume and improve performance. The IntegrationHub spoke supports custom HTTP requests, allowing you to implement GraphQL queries while staying within rate limits.
• →Implement circuit breaker patterns in high-volume webhook processing by using ServiceNow's job queue system to handle webhook payloads asynchronously during GitHub outages or high-traffic periods. This prevents webhook timeout failures and ensures reliable event processing during peak usage.
• →Create GitHub repository templates with standardized workflow files that include ServiceNow integration points, making it easier for development teams to adopt the integration patterns across multiple projects. Include examples of repository dispatch handling, workflow status reporting, and deployment approval gates.
• →Use ServiceNow's Transform Maps for complex GitHub webhook payload processing, especially when dealing with different event types that require different record creation logic. This approach provides better maintainability and allows for field mapping changes without code modifications.

Known Limitations

• —GitHub's API rate limiting restricts authenticated users to 5000 requests per hour, which can be exceeded in high-volume environments with frequent webhook events or batch processing. Consider implementing request queuing and throttling mechanisms for organizations with multiple repositories and active development teams.
• —The IntegrationHub GitHub spoke requires an active IntegrationHub Starter license minimum, with some advanced features requiring Professional licenses for complex workflow orchestration. Personal Developer Instances (PDI) may have limited spoke functionality and webhook processing capabilities that don't reflect production behavior.
• —GitHub webhooks have a 10-second timeout for HTTP responses, requiring ServiceNow webhook handlers to process payloads quickly or implement asynchronous processing patterns. Complex record creation or external API calls within webhook handlers may cause timeout failures and webhook delivery retries.
• —Large GitHub repositories with extensive commit histories or file trees may cause API response payloads that exceed ServiceNow's default HTTP response size limits. This is particularly problematic when fetching repository contents, commit diffs, or comprehensive issue data requiring pagination handling.
• —GitHub's webhook delivery retry mechanism uses exponential backoff over several hours, but ServiceNow maintenance windows or instance hibernation can cause permanent webhook delivery failures. There's no built-in mechanism to replay missed webhooks, requiring custom solutions for critical event recovery.

Frequently Asked Questions