GitHub Issues

GitHub Issues integration allows your product to fetch, create, and manage issues in GitHub repositories. This is ideal for DevSecOps workflows, where vulnerabilities, incidents, or findings can be automatically converted into GitHub issues for tracking and remediation. The integration uses GitHub's REST API v3 (or optionally GraphQL API) for operations like listing repositories, retrieving issues, and creating new ones.

Credentials Needed

To connect with GitHub's API, you need a Personal Access Token (PAT) or a GitHub App Installation Token (for enterprise or multi-user setups).

Option 1 — Personal Access Token (Recommended for simplicity):

• GitHub Personal Access Token (PAT)
• GitHub Username (optional for reference)

Option 2 — GitHub App (for enterprise integrations):

• App ID
• Client ID
• Client Secret
• Installation Access Token

The PAT method is sufficient for most single-user or organization-level integrations. GitHub Apps are recommended for multi-tenant or scalable SaaS integrations.

Permissions Needed / API Scopes

When generating a Personal Access Token (PAT), select the following scopes:

Scope	Description
repo	Full control of private and public repositories (required for reading/writing issues)
read:org	Read organization and team data (if accessing org repos)
user:email	Read authenticated user's email (optional)
read:project	Read GitHub Projects (optional)
write:discussion (optional)	Add issue-linked discussions if needed

Minimum Required Scope: repo

Creating Users / Access Tokens

Step 1: Create a Personal Access Token (PAT)

1. Log in to GitHub → https://github.com/settings/tokens
2. Click "Generate new token (Classic)" → choose Fine-grained tokens if using new version
3. Provide a name/label (e.g., IssueIntegrationToken)
4. Under Repository access, select:
   • Specific repositories (recommended) or
   • All repositories (if needed)
5. Under Permissions, enable:
   • Read and Write for Issues
6. Click Generate Token and copy it securely

⚠️ This token will only be shown once. Store it in your platform's secret vault.

Test Connectivity

List User Repositories

curl -H "Authorization: Bearer <GITHUB_PAT>" \
     -H "Accept: application/vnd.github+json" \
     https://api.github.com/user/repos

Example Response:

[
  {
    "id": 123456,
    "name": "security-dashboard",
    "full_name": "user/security-dashboard",
    "private": false,
    "html_url": "https://github.com/user/security-dashboard"
  }
]

List Issues in a Repository

curl -H "Authorization: Bearer <GITHUB_PAT>" \
     -H "Accept: application/vnd.github+json" \
     https://api.github.com/repos/user/security-dashboard/issues

Example Response:

[
  {
    "id": 7891011,
    "number": 42,
    "title": "XSS vulnerability in login form",
    "state": "open",
    "assignee": {"login": "johndoe"},
    "html_url": "https://github.com/user/security-dashboard/issues/42"
  }
]

Create a New Issue

curl -X POST \
  -H "Authorization: Bearer <GITHUB_PAT>" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/user/security-dashboard/issues \
  -d '{
    "title": "SQL Injection vulnerability found in /api/login",
    "body": "A critical SQLi vulnerability has been detected in the login API endpoint. Please fix urgently.",
    "labels": ["security", "critical"],
    "assignees": ["johndoe"]
  }'

Example Response:

{
  "id": 990001,
  "number": 101,
  "title": "SQL Injection vulnerability found in /api/login",
  "state": "open",
  "html_url": "https://github.com/user/security-dashboard/issues/101"
}

Save the Results in the Platform and Create Connection

1. In your product's integration settings, securely store:
   • GITHUB_PAT
   • GITHUB_USERNAME (optional)
2. Label the connection as GitHub Issues Integration
3. Test by retrieving repositories or listing issues
4. Once validated, enable automation flows like:
   • Auto-create GitHub issues for new vulnerabilities
   • Sync issue statuses back to your product
   • Add comments to existing GitHub issues when updates occur

Best Practices

• Use Fine-grained PATs with least privilege (specific repos, read/write issues only)
• Store all credentials securely in your secret manager (not environment variables)
• Rotate tokens every 90 days
• Respect GitHub's rate limit (typically 5000 requests/hour per user)
• Use pagination (?per_page=100&page=n) for large datasets
• Use the ETag header to cache responses and reduce API load
• For multi-user SaaS integrations, prefer GitHub App authentication (installation tokens)
• For automation, link GitHub issues to your product's entities using custom labels or structured titles (e.g., [Vuln-1234] SQL Injection)
• Handle HTTP 403 (Forbidden) and 401 (Unauthorized) with appropriate re-authentication prompts

Useful GitHub Issues API Endpoints

Resource	Method	Endpoint	Description
List repositories	GET	/user/repos	Lists repositories accessible by token
List issues	GET	/repos/{owner}/{repo}/issues	Lists issues in a repo
Get issue details	GET	/repos/{owner}/{repo}/issues/{issue_number}	Fetch a specific issue
Create issue	POST	/repos/{owner}/{repo}/issues	Create new issue
Update issue	PATCH	/repos/{owner}/{repo}/issues/{issue_number}	Edit title, description, or state
Add comment	POST	/repos/{owner}/{repo}/issues/{issue_number}/comments	Add comment to an issue
List labels	GET	/repos/{owner}/{repo}/labels	Retrieve all available labels

Official Docs: https://docs.github.com/en/rest/issues/issues

Example Workflow in Your Platform

1. Vulnerability or task identified in your product
2. Automatically call the GitHub API to create a linked issue
3. Store the issue_number and html_url for bidirectional tracking
4. On resolution in GitHub, webhook triggers status sync back to your product

Webhook Integration (Optional)

You can configure GitHub Webhooks to notify your system when issues are updated or closed.

1. Go to the repository → Settings → Webhooks → Add webhook
2. Set Payload URL = your platform's webhook endpoint
3. Choose "application/json" as content type
4. Select events:
   • issues
   • issue_comment
   • label (optional)
5. Save the webhook

This allows real-time syncing of GitHub issue changes into your system.