🎮 Minecraft PaperMC Server on GitHub (24/7 Free)

Based on: How to make Minecraft Server Using Github [Java Edition] by BlueOnTheSky
Server Type: PaperMC (Java Edition)
Hosting: GitHub Codespaces (60 hrs/month free) + GitHub Actions (2000 min/month free) + playit.gg tunnel

---

🚀 Quick Start (5 minutes)

Option A: GitHub Codespaces (Recommended for 24/7)

1. Fork this repo → Click "Fork" button above
2. Open in Codespaces → Code → Codespaces → Create codespace on main
3. Wait for setup (auto-runs scripts/setup-server.sh)
4. Claim your tunnel: In terminal, run:

   ./playit claim

   • Copy the claim code shown
   • Go to https://playit.gg/claim and paste it
5. Set claim code as Codespace secret:
   • Codespace → Settings (gear) → Codespace secrets → New secret
   • Name: PLAYIT_CLAIM_CODE | Value: your claim code
6. Start server:

   ./start-server.sh

7. Connect using the address from playit.gg (e.g., cool-name.region.ply.gg:12345)

Option B: GitHub Actions (Backup/Automated)

1. Add PLAYIT_CLAIM_CODE as Repository Secret (Settings → Secrets → Actions)
2. Enable Actions on fork
3. Run workflow manually or wait for scheduled runs (every 6 hours)

---

📁 Repository Structure

minecraft-github-server/
├── .devcontainer/
│   └── devcontainer.json      # Codespaces config (Java 21, ports, post-create)
├── .github/
│   └── workflows/
│       └── minecraft-server.yml  # GitHub Actions workflow
├── scripts/
│   ├── download-paper.sh      # Downloads latest PaperMC
│   ├── setup-server.sh        # Sets up server.properties, playit, EULA
│   ├── start-tunnel.sh        # Starts playit.gg tunnel
│   └── start-server.sh        # Main entry point
├── server.properties          # Generated on first run
├── eula.txt                   # Generated on first run (eula=true)
├── paper.jar                  # Downloaded on first run
├── playit                     # playit.gg tunnel binary
├── start-server.sh            # Run this to start
└── README.md                  # This file

---

⚙️ Configuration

Server Properties (server.properties)

Key settings for Codespaces + playit.gg:

server-port=25565
server-ip=0.0.0.0
max-players=20
view-distance=10
simulation-distance=6
gamemode=survival
difficulty=easy
enable-command-block=false
white-list=false
enforce-secure-profile=true

Java Flags (Aikar's Flags Optimized for 2GB RAM)

-Xms1G -Xmx2G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 ...

Located in .devcontainer/devcontainer.json and start-server.sh

Plugins

Drop .jar files into plugins/ folder (created on first run):

mkdir -p plugins
# Download plugins from https://hangar.papermc.io/ or https://modrinth.com/plugins
# Example: ViaVersion, ViaBackwards, LuckPerms, EssentialsX, WorldEdit

---

🔧 playit.gg Tunnel Setup

Why playit.gg?

• Free TCP/UDP tunneling (no port forwarding needed)
• Works from Codespaces, GitHub Actions, any cloud
• Custom subdomain (e.g., myserver.na.ply.gg:12345)
• Supports Bedrock cross-play with GeyserMC plugin

Claim Your Tunnel

# In Codespace terminal or locally:
./playit claim
# Follow the link, authorize, copy claim code

Add as Secret

Platform	Location
Codespaces	Codespace Settings → Secrets → PLAYIT_CLAIM_CODE
GitHub Actions	Repo Settings → Secrets → Actions → PLAYIT_CLAIM_CODE

---

💰 Free Tier Limits & 24/7 Strategy

Platform	Free Limit	Strategy
GitHub Codespaces	60 hours/month (personal)	Primary 24/7; keep tab open
GitHub Actions	2000 minutes/month	Backup: scheduled runs every 6h
playit.gg	Unlimited tunnels	Always free

True 24/7 Approach

1. Primary: Codespaces (keep browser tab open, auto-stops after 30 min inactivity)
2. Backup: GitHub Actions scheduled workflow (runs 6h every 6h = 24h coverage)
3. World persistence: Commit world/ folder to repo periodically (see workflow)

---

🌍 Bedrock Cross-Play (Optional)

Add to plugins/:

1. GeyserMC + Floodgate (from https://download.geysermc.org/)
2. Bedrock players connect via same playit.gg address (port 19132 UDP)

---

🛠️ Commands Reference

Command	Description
./start-server.sh	Start server + tunnel
./playit claim	Get new tunnel claim code
./playit --secret <code>	Run tunnel manually
stop	In server console: graceful shutdown
save-all	Force world save
save-off / save-on	Disable/enable auto-save

---

📦 World Backup Strategy

Add to workflow or run manually:

# Commit world folder to repo (keeps history)
git config user.name "github-actions"
git config user.email "actions@github.com"
git add world/
git commit -m "World backup $(date)"
git push

Note: GitHub has 100MB file limit, 1GB repo limit. For large worlds, use Git LFS or external storage.

---

🔗 Useful Links

• PaperMC Downloads: https://papermc.io/downloads
• playit.gg: https://playit.gg/
• Aikar's Java Flags: https://mcflags.emc.gs/
• GeyserMC (Bedrock): https://geysermc.org/
• Plugin Sources: https://hangar.papermc.io/ | https://modrinth.com/plugins

---

📜 License

MIT License - Feel free to fork and customize!

---

Based on: BlueOnTheSky's YouTube Tutorial
Enhanced for: GitHub Codespaces + Actions 24/7 free hosting