-
-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathguide.html
More file actions
440 lines (410 loc) · 26.6 KB
/
guide.html
File metadata and controls
440 lines (410 loc) · 26.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
<!DOCTYPE html>
<html lang="en" class="scroll-smooth"> <!-- Added scroll-smooth for smooth scrolling -->
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>GitHub Contribution Bot – User Guide</title>
<!-- ✅ FIXED: Favicon using LOCAL file -->
<link rel="icon" type="image/x-icon" href="/favicon.ico">
<link rel="icon" type="image/png" sizes="192x192" href="/icon.png">
<link rel="apple-touch-icon" href="/icon-512.png">
<link rel="manifest" href="/manifest.json">
<script src="https://cdn.tailwindcss.com"></script>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<!-- Font Awesome for hamburger icon -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta3/css/all.min.css">
<style>
body {
font-family: 'Inter', sans-serif;
}
/* Ensure main content scrolls independently if sidebar is sticky */
main {
overflow-y: auto;
}
/* Custom styles for sidebar toggle on small screens */
@media (max-width: 768px) {
aside {
position: fixed;
top: 0;
left: -100%; /* Hidden by default */
height: 100%;
transition: left 0.3s ease-in-out;
z-index: 50; /* Ensure it's above other content */
}
aside.active {
left: 0; /* Show when active */
}
.overlay {
display: none;
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 100%;
background-color: rgba(0, 0, 0, 0.5);
z-index: 40;
}
.overlay.active {
display: block;
}
.menu-button {
display: block; /* Show hamburger button on small screens */
}
.main-content-wrapper {
margin-left: 0; /* No margin when sidebar is hidden */
}
}
@media (min-width: 769px) {
.menu-button {
display: none; /* Hide hamburger button on larger screens */
}
aside {
position: sticky; /* Keep sidebar sticky on larger screens */
left: 0;
}
}
</style>
</head>
<body class="bg-gray-50 text-gray-800">
<div class="flex min-h-screen">
<!-- Overlay for mobile sidebar -->
<div id="sidebar-overlay" class="overlay" onclick="toggleSidebar()"></div>
<!-- Sidebar -->
<aside id="sidebar" class="w-64 bg-white border-r p-6 space-y-4 sticky top-0 h-screen text-sm md:relative md:left-0">
<h2 class="text-lg font-bold">📘 Guide Menu</h2>
<ul class="space-y-2">
<li><a href="#getting-started" class="text-blue-600 hover:underline" onclick="toggleSidebar()">✅ Getting Started</a></li>
<li><a href="#create-pat" class="text-blue-600 hover:underline" onclick="toggleSidebar()">🔑 Create GitHub Token</a></li>
<li><a href="#token-scopes" class="text-blue-600 hover:underline" onclick="toggleSidebar()">ℹ️ Token Scopes Explained</a></li>
<li><a href="#provide-gemini-key" class="text-blue-600 hover:underline" onclick="toggleSidebar()">✨ Provide Gemini Key</a></li>
<li><a href="#how-to-use" class="text-blue-600 hover:underline" onclick="toggleSidebar()">🛠️ How to Use</a></li>
<li><a href="#smart-rotation" class="text-blue-600 hover:underline" onclick="toggleSidebar()">🔄 Smart Rotation</a></li>
<li><a href="#safe-mode" class="text-blue-600 hover:underline" onclick="toggleSidebar()">🧠 Safe Mode Explained</a></li>
<li><a href="#commit-preview" class="text-blue-600 hover:underline" onclick="toggleSidebar()">👀 Commit Preview Modal</a></li>
<li><a href="#stats-panel" class="text-blue-600 hover:underline" onclick="toggleSidebar()">📈 Stats Panel</a></li>
<li><a href="#what-to-do" class="text-blue-600 hover:underline" onclick="toggleSidebar()">⚠️ What To Do</a></li>
<li><a href="#what-not-to-do" class="text-blue-600 hover:underline" onclick="toggleSidebar()">🚫 What Not To Do</a></li>
<li><a href="#pro-tips" class="text-blue-600 hover:underline" onclick="toggleSidebar()">🧪 Pro Tips</a></li>
<li><a href="#advanced-usage" class="text-blue-600 hover:underline" onclick="toggleSidebar()">💻 Advanced Usage</a></li>
<li><a href="#banned-risk" class="text-blue-600 hover:underline" onclick="toggleSidebar()">🚫 Can You Get Banned?</a></li>
<li><a href="index.html" class="text-green-600 hover:underline font-medium">⬅️ Back to App</a></li>
<li><button onclick="downloadPDF()" class="w-full bg-blue-500 text-white py-2 px-4 rounded-md font-semibold hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 transition duration-300 ease-in-out shadow-md mt-4">
⬇️ Download as PDF
</button></li>
</ul>
</aside>
<!-- Main Content Wrapper -->
<div class="flex-1 p-6 space-y-6 main-content-wrapper">
<!-- Hamburger menu button for mobile -->
<button class="menu-button fixed top-4 left-4 bg-blue-600 text-white p-2 rounded-md shadow-lg z-50" onclick="toggleSidebar()">
<i class="fas fa-bars"></i>
</button>
<!-- Banner at the top -->
<header class="flex flex-col items-center justify-center p-4 bg-white shadow-md rounded-lg mb-6 text-center">
<img src="/icon-512.png" alt="GitHub Bot Logo" class="h-16 w-auto mb-4">
<h1 class="text-3xl font-bold text-center">📘 GitHub Contribution Bot – User Guide</h1>
<p class="text-sm text-gray-600 mt-2">Scan to access the guide on your mobile device!</p>
<!-- Removed QR Code Image -->
</header>
<section id="getting-started">
<h2 class="text-xl font-semibold">✅ Getting Started</h2>
<p>This bot helps automate GitHub commits to maintain your contribution graph and simulate human-like activity.</p>
<ul class="list-disc list-inside mt-2 text-sm">
<li>Requires a GitHub Personal Access Token (classic)</li>
<li>Use with your own public repositories</li>
<li>Commits to any file path you choose (e.g., <code>log.md</code>)</li>
</ul>
</section>
<section id="create-pat">
<h2 class="text-xl font-semibold">🔑 How to Create a GitHub Personal Access Token (PAT)</h2>
<p class="text-sm mt-2">To use this bot, you need a GitHub Personal Access Token with the necessary permissions. Follow these steps:</p>
<ol class="list-decimal list-inside text-sm mt-2 space-y-2">
<li>Go to your GitHub settings: Navigate to <a href="https://github.com/settings/tokens" target="_blank" class="text-blue-600 hover:underline">GitHub Personal Access Tokens</a>.</li>
<li>Click on "Generate new token (classic)".</li>
<li>Give your token a descriptive name (e.g., "GitHub Bot Token").</li>
<li>Set an expiration date (e.g., 90 days or 1 year) or "No expiration" (use with caution).</li>
<li>Under "Select scopes", **check the <code>repo</code> checkbox**. For fetching your real contribution heatmap, you also need to check <code>read:user</code>.</li>
<li>Click "Generate token" at the bottom of the page.</li>
<li>**IMPORTANT:** Copy the generated token immediately. You will not be able to see it again! Store it securely.</li>
<li>Paste this token into the "GitHub Personal Access Token (PAT)" field in the bot's "Main Controls" tab.</li>
</ol>
<p class="text-xs text-gray-500 mt-2">For more details, refer to GitHub's official documentation on <a href="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens" target="_blank" class="text-blue-600 hover:underline">managing personal access tokens</a>.</p>
</section>
<section id="token-scopes">
<h2 class="text-xl font-semibold">ℹ️ Token Scopes Explained</h2>
<p class="text-sm mt-2">GitHub Personal Access Tokens require specific permissions, called "scopes," to perform actions on your behalf. Here's what the bot needs:</p>
<ul class="list-disc list-inside text-sm mt-2 space-y-1">
<li><strong><code>repo</code>:</strong> This scope grants the bot full control over your private repositories. It is essential for the bot to create, update, and delete files (i.e., make commits) in the repositories you select. Without this, the bot cannot commit.</li>
<li><strong><code>read:user</code>:</strong> This scope allows the bot to read your user profile data. It is specifically used to fetch your public GitHub activity events for displaying your "Real GitHub Contribution Heatmap." Without this, the heatmap feature might not work correctly.</li>
</ul>
<p class="text-xs text-gray-500 mt-2">Providing only the necessary scopes is a security best practice to limit the bot's access to your GitHub account.</p>
</section>
<section id="provide-gemini-key">
<h2 class="text-xl font-semibold">✨ How to Provide Gemini API Key</h2>
<p class="text-sm mt-2">The bot can generate smart commit messages using the Gemini API. To enable this feature, you need to provide your Gemini API Key:</p>
<ol class="list-decimal list-inside text-sm mt-2 space-y-2">
<li>Obtain your Gemini API Key from the Google AI Studio or Google Cloud Console.</li>
<li>In the bot's "Main Controls" tab, locate the "Gemini API Key (for Smart Commit Messages)" input field.</li>
<li>Paste your Gemini API Key into this field.</li>
<li>The key will be automatically saved to your browser's local storage for future use.</li>
</ol>
<p class="text-xs text-gray-500 mt-2">Ensure your API key is kept confidential and is not shared publicly.</p>
</section>
<section id="how-to-use">
<h2 class="text-xl font-semibold">🛠️ How to Use</h2>
<ol class="list-decimal list-inside text-sm">
<li>Paste your GitHub token (with <code>repo</code> and <code>read:user</code> scopes)</li>
<li>Select one or more of your repositories</li>
<li>Set the file path and branch (default: <code>main</code>)</li>
<li>Optionally provide your Gemini API Key for smart commit messages.</li>
<li>Use Manual, Auto Commit, or Safe Mode options.</li>
<li>Explore the new features like Smart Rotation, Commit Preview, and Stats Panel.</li>
</ol>
</section>
<section id="smart-rotation">
<h2 class="text-xl font-semibold">🔄 Smart Rotation</h2>
<p class="text-sm mt-2">Smart Rotation is a feature designed to distribute automated commits more evenly across multiple selected repositories.</p>
<ul class="list-disc list-inside text-sm mt-2">
<li>When enabled, the bot will cycle through your selected repositories in a round-robin fashion for each subsequent auto-commit.</li>
<li>This helps create a more natural and diversified contribution graph across your projects.</li>
<li>You can enable or disable this feature using the "Enable Smart Rotation (Round-Robin Repos)" checkbox in the "Main Controls" tab.</li>
</ul>
</section>
<section id="safe-mode">
<h2 class="text-xl font-semibold">🧠 Safe Mode Explained</h2>
<p>Safe Mode simulates real human behavior by:</p>
<ul class="list-disc list-inside text-sm mt-1">
<li>⏱️ Adding random delays between commits (20–30 minutes)</li>
<li>🔀 Rotating across multiple repos</li>
<li>🧾 Generating natural, varied commit messages</li>
<li>💤 Occasionally skipping commits to avoid bot detection</li>
</ul>
<p class="text-sm mt-2">Enable this feature using the "Enable Safe Mode (Human-like Behavior)" checkbox in the "Main Controls" tab for a more organic contribution pattern.</p>
</section>
<section id="commit-preview">
<h2 class="text-xl font-semibold">👀 Commit Preview Modal</h2>
<p class="text-sm mt-2">The Commit Preview Modal provides a confirmation step before a commit is actually made, whether manually or automatically.</p>
<ul class="list-disc list-inside text-sm mt-2">
<li><strong>Why it's useful:</strong>
<ul class="list-circle list-inside ml-4">
<li>Avoids sending incorrect or duplicate messages.</li>
<li>Allows you to edit the message or content, making the commit feel more personal, especially in Safe Mode.</li>
<li>Provides transparency on what's going on behind-the-scenes.</li>
</ul>
</li>
<li><strong>What it shows:</strong>
<ul class="list-circle list-inside ml-4">
<li>Commit message</li>
<li>File path</li>
<li>Content snippet</li>
<li>(Optional) A countdown timer for auto-commits.</li>
</ul>
</li>
<li>You can enable or disable this feature using the "Enable Commit Preview" checkbox in the "Main Controls" tab.</li>
</ul>
</section>
<section id="stats-panel">
<h2 class="text-xl font-semibold">📈 Stats Panel</h2>
<p class="text-sm mt-2">The Stats Panel provides insights into your bot's usage and commit activity.</p>
<ul class="list-disc list-inside text-sm mt-2">
<li><strong>Total Commits:</strong> The total number of commits made by the bot.</li>
<li><strong>Safe Mode Commits:</strong> The number and percentage of commits made while Safe Mode was enabled.</li>
<li><strong>First Commit Date:</strong> The date of the very first commit recorded by the bot.</li>
<li><strong>Average Interval:</strong> The average time between commits.</li>
<li><strong>Top Used Repo:</strong> The repository where the most commits have been made.</li>
</ul>
<p class="text-sm mt-2">You can access this panel via the "Stats" tab and reset the statistics at any time using the "Reset Stats" button.</p>
</section>
<section id="what-to-do">
<h2 class="text-xl font-semibold">⚠️ What To Do</h2>
<ul class="list-disc list-inside text-sm">
<li>✅ Use your own repos</li>
<li>✅ Let commits spread over time</li>
<li>✅ Commit real or test data, not junk</li>
<li>✅ Keep messages unique or random</li>
</ul>
</section>
<section id="what-not-to-do">
<h2 class="text-xl font-semibold">🚫 What Not To Do</h2>
<ul class="list-disc list-inside text-sm text-red-600">
<li>❌ Don’t spam commits every few seconds</li>
<li>❌ Don’t push to other users’ repos</li>
<li>❌ Don’t use stolen tokens or fake accounts</li>
<li>❌ Don’t game contribution stats dishonestly</li>
</ul>
</section>
<section id="pro-tips">
<h2 class="text-xl font-semibold">🧪 Pro Tips</h2>
<ul class="list-disc list-inside text-sm">
<li>📱 Install the app as a PWA</li>
<li>🧭 Use multi-repo rotation for realism</li>
<li>📊 Use the real heatmap preview to track your growth</li>
<li>🧠 Let Safe Mode handle randomness</li>
<li>👀 Enable Commit Preview for transparency and control.</li>
<li>📈 Monitor your bot's activity with the Stats Panel.</li>
</ul>
</section>
<section id="advanced-usage">
<h2 class="text-xl font-semibold">💻 Advanced Usage (Dev Mode)</h2>
<p class="text-sm">Trigger Safe Mode loop manually:</p>
<pre class="bg-gray-100 p-3 rounded text-xs mt-1">safeAutoCommitLoop(["CryptoExplor/test-repo", "CryptoExplor/logs"]);</pre>
<p class="text-sm mt-1">Stop loop manually:</p>
<pre class="bg-gray-100 p-3 rounded text-xs">safeModeEnabled = false;</pre>
</section>
<section id="banned-risk">
<h2 class="text-xl font-semibold">🚫 Can You Get Banned by GitHub for Using This Bot?</h2>
<p class="text-sm mt-2">🔍 Short Answer: Very Unlikely — If Used Responsibly</p>
<p class="text-sm mt-1">Your script does not break GitHub’s Terms of Service as long as:</p>
<ul class="list-disc list-inside text-sm mt-1">
<li>✅ You’re committing to your own repositories</li>
<li>✅ You’re not automating spam or harmful content</li>
<li>✅ You’re not trying to manipulate public-facing metrics dishonestly (e.g., for applying to jobs)</li>
<li>✅ You’re not doing this at mass scale across multiple accounts</li>
</ul>
<h3 class="text-lg font-semibold mt-4">🛑 What Might Trigger a Ban or Flag?</h3>
<div class="overflow-x-auto">
<table class="min-w-full bg-white border border-gray-200 rounded-md mt-2 text-sm">
<thead>
<tr class="bg-gray-100">
<th class="py-2 px-4 border-b text-left">Risk Factor</th>
<th class="py-2 px-4 border-b text-left">Severity</th>
<th class="py-2 px-4 border-b text-left">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td class="py-2 px-4 border-b">🔴 Spamming commits to others' repos</td>
<td class="py-2 px-4 border-b">High</td>
<td class="py-2 px-4 border-b">Could lead to suspension</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">🔴 Using fake/stolen tokens</td>
<td class="py-2 px-4 border-b">High</td>
<td class="py-2 px-4 border-b">Severe violation</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">🟠 Creating 100s of fake repos</td>
<td class="py-2 px-4 border-b">Medium</td>
<td class="py-2 px-4 border-b">Might trigger anti-abuse detection</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">🟠 Doing 1000s of commits/hour</td>
<td class="py-2 px-4 border-b">Medium</td>
<td class="py-2 px-4 border-b">Rate limits or behavioral flags</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">🟡 Committing useless content</td>
<td class="py-2 px-4 border-b">Low</td>
<td class="py-2 px-4 border-b">Allowed, but might hurt repo credibility</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">⚪ “Artificial” heatmap filling</td>
<td class="py-2 px-4 border-b">Low</td>
<td class="py-2 px-4 border-b">Common, not against rules (if to your own repos)</td>
</tr>
</tbody>
</table>
</div>
<h3 class="text-lg font-semibold mt-4">💡 Best Practices to Stay Safe</h3>
<div class="overflow-x-auto">
<table class="min-w-full bg-white border border-gray-200 rounded-md mt-2 text-sm">
<thead>
<tr class="bg-gray-100">
<th class="py-2 px-4 border-b text-left">Tip</th>
<th class="py-2 px-4 border-b text-left">Reason</th>
</tr>
</thead>
<tbody>
<tr>
<td class="py-2 px-4 border-b">✅ Use your own repos only</td>
<td class="py-2 px-4 border-b">Full control, no violation</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">✅ Set reasonable commit intervals (e.g. every 10–60 min)</td>
<td class="py-2 px-4 border-b">Looks human</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">✅ Use realistic commit messages</td>
<td class="py-2 px-4 border-b">Avoids looking bot-generated</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">✅ Avoid sudden repo bursts (100s of commits in seconds)</td>
<td class="py-2 px-4 border-b">Could trigger rate limits</td>
</tr>
<tr>
<td class="py-2 px-4 border-b">✅ Don’t automate stars, forks, watchers</td>
<td class="py-2 px-4 border-b">These are against GitHub ToS</td>
</tr>
</tbody>
</table>
</div>
<h3 class="text-lg font-semibold mt-4">✅ Real-World Example</h3>
<p class="text-sm mt-1">Many devs use tools like:</p>
<ul class="list-disc list-inside text-sm mt-1">
<li>GitHub Readme Stats</li>
<li>GitHub Activity Faker</li>
<li>…and none of them get banned, because they’re used on personal accounts in moderation.</li>
</ul>
<h3 class="text-lg font-semibold mt-4">🔐 Bonus Tip: Keep Your Token Safe</h3>
<ul class="list-disc list-inside text-sm mt-1">
<li>Never commit your token to GitHub</li>
<li>Use Classic PAT with only repo scope</li>
<li>Store in localStorage or environment only</li>
</ul>
<h3 class="text-lg font-semibold mt-4">✅ TL;DR:</h3>
<p class="text-sm mt-1">Your current bot is:</p>
<ul class="list-disc list-inside text-sm mt-1">
<li>Safe for personal use</li>
<li>Okay for automation</li>
<li>Not spammy or malicious</li>
<li>Not a ToS violation</li>
</ul>
<p class="text-sm mt-1">Just don’t abuse it, and you’re 💯 safe.</p>
</section>
<footer class="text-center text-xs text-gray-500 mt-10">
© 2025 CryptoExplor – Built by FarmLabs with ❤️
</footer>
</div>
</div>
<!-- html2pdf.js library for PDF download -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.10.1/html2pdf.bundle.min.js"></script>
<script>
// Function to toggle sidebar visibility on small screens
function toggleSidebar() {
const sidebar = document.getElementById('sidebar');
const overlay = document.getElementById('sidebar-overlay');
sidebar.classList.toggle('active');
overlay.classList.toggle('active');
}
// Function to download the guide as PDF
function downloadPDF() {
const element = document.querySelector('main'); // Select the main content to convert
const opt = {
margin: 0.5,
filename: 'github-bot-user-guide.pdf',
image: { type: 'jpeg', quality: 0.98 },
html2canvas: { scale: 2, logging: true, dpi: 192, letterRendering: true },
jsPDF: { unit: 'in', format: 'letter', orientation: 'portrait' }
};
html2pdf().set(opt).from(element).save();
}
// Close sidebar when a link is clicked (for mobile)
document.querySelectorAll('#sidebar a').forEach(link => {
link.addEventListener('click', () => {
if (window.innerWidth <= 768) { // Only close on small screens
toggleSidebar();
}
});
});
// Close sidebar if window is resized to larger than mobile while sidebar is open
window.addEventListener('resize', () => {
const sidebar = document.getElementById('sidebar');
const overlay = document.getElementById('sidebar-overlay');
if (window.innerWidth > 768) {
sidebar.classList.remove('active');
overlay.classList.remove('active');
}
});
</script>
</body>
</html>