GitHub API Integration
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub API integration in TrackerBot serves as the bridge between public users and the project's development tracking. Its primary purpose is to provide a public bug-intake portal that forwards user-submitted reports directly to GitHub as issues. This system allows the community to report both website-related bugs and data-specific inaccuracies without requiring direct access to GitHub.
Sources: README.md:12-14, AGENTS.md:10-11
The integration is managed by the webserver.js service, which runs an Express server side-by-side with the Discord bot. It handles requests from static HTML forms, validates the input, and utilizes the GitHub REST API to create issues in two distinct repositories: one for development bugs and another for data reports.
Sources: webserver.js:9-11, AGENTS.md:7-10
System Architecture
The integration follows a standard client-server-external API pattern. Users interact with frontend forms hosted by the Express web server, which then processes the data and makes authenticated POST requests to the GitHub API.
Component Relationship
The following diagram illustrates the relationship between the web forms, the web server service, and the external GitHub repositories.
Authentication and Configuration
The integration requires specific environment variables to authenticate with GitHub and route issues to the correct destinations. Authentication is performed using a Personal Access Token (PAT) included in the request headers.
Required Environment Variables
| Variable | Description | Source |
|---|---|---|
GITHUB_TOKEN | GitHub Personal Access Token with repo or issues:write scope. | README.md:46-48 |
REPO_DEV | The repository path (owner/repo) for website/app bug reports. | webserver.js:32 |
REPO_DATA_REPORT | The repository path for quest, item, and map data reports. | webserver.js:31 |
API Headers
The server constructs a GITHUB_HEADERS object for all outgoing requests to ensure proper authentication and versioning.
const GITHUB_HEADERS = {
Authorization: `token ${process.env.GITHUB_TOKEN}`,
Accept: "application/vnd.github+json",
"User-Agent": "tarkovtracker-webserver"
};
Sources: webserver.js:34-38
Data Intake and Validation
TrackerBot implements several layers of validation and sanitization before data is transmitted to the GitHub API. This includes field length capping, honeypot detection for bot prevention, and rate limiting.
Sanitization Logic
All incoming fields are truncated to prevent excessively large payloads or abuse of the GitHub API limits.
| Field | Max Length | Description |
|---|---|---|
title | 200 | The subject of the GitHub issue. |
discord | 64 | User's Discord handle for follow-up. |
category | 64 | Impacted area (e.g., "Overlay - Items"). |
reference | 500 | Optional links or screenshot URLs. |
description | 8000 | Detailed steps to reproduce or data corrections. |
Sources: webserver.js:42-53, web/data/index.html:42-50
Security Measures
- Honeypot: A hidden field (
company) is included in the web forms. If this field contains any value, the server assumes the submission is from a bot and silently ignores it by returning a success response without calling the GitHub API. - Rate Limiting: Separate rate limiters are applied to
/dataand/issueendpoints, capping submissions at 5 per minute per IP address. - Origin Validation: The
checkOriginmiddleware ensures requests come from allowed domains defined in theALLOWED_ORIGINSenvironment variable.
Sources: webserver.js:63-102
Issue Creation Workflow
The server supports two distinct issue reporting flows, each targeting a specific GitHub repository and formatting the issue body accordingly.
Sequence Diagram: Issue Submission
The following diagram demonstrates the data flow when a user submits a "Data Issue".
Endpoint Logic
/data: Combinescategoryandtitleinto the GitHub issue title:[category] title. The body includes the Discord handle, category, optional reference link, and description./issue: Forwards website-specific bugs. The body is formatted to include the user's Discord handle and a detailed description.
Sources: webserver.js:127-147, webserver.js:161-175
Error Handling and Logging
The system is designed to handle API failures gracefully while protecting sensitive credentials.
Sanitized Logging
A critical security feature in webserver.js is the logSanitizedError function. Because Axios error objects contain the request configuration—which includes the Authorization header with the raw GitHub token—the server explicitly extracts only the status code and error message for logging.
function logSanitizedError(route, err) {
const status = err.response?.status ?? "no-response";
const message = err.message ?? "unknown error";
console.error(`[${route}] GitHub API error: status=${status} message=${message}`);
}
Sources: webserver.js:189-194
Summary
The GitHub API integration provides a secure, validated, and rate-limited gateway for the community to contribute to the TarkovTracker project. By centralizing reporting through webserver.js, the project maintains organized tracking in separate repositories for development and data, while protecting the GitHub API from spam through honeypots and input sanitization.
Sources: README.md:6-14, webserver.js:116-180