Getting Started

Getting Started

Prerequisites

• Node.js ≥ 20 or Docker
• A GitHub Personal Access Token with repo scope
• A GitLab Personal Access Token with api scope
• A publicly reachable server (or a tunnel like ngrok)

Installation

From Source

git clone https://github.com/wildfirebill-docker/hub2lab.git
cd hub2lab
npm install

Via Docker

docker pull ghcr.io/wildfirebill-docker/hub2lab:latest

Initial Configuration

1. Create Environment File

cp .env.example .env

Edit .env with your credentials:

Variable	Required	Default	Description
PORT	No	3000	HTTP server port
GITHUB_TOKEN	Yes	—	GitHub PAT with repo scope
GITHUB_WEBHOOK_SECRET	Yes	—	Secret for verifying GitHub webhook signatures
GITLAB_TOKEN	Yes	—	GitLab PAT with api scope
GITLAB_WEBHOOK_SECRET	Yes	—	Token for verifying GitLab webhook requests
GITLAB_BASE_URL	No	https://gitlab.com	GitLab instance URL (for self-hosted GitLab)
MAPPING_FILE	No	./mapping.json	Path to mapping configuration
MIRROR_DIR	No	./mirrors	Temp directory for git mirror operations
SYNC_MARKER	No	[hub2lab]	Marker in commit messages to prevent loops
LOG_DIR	No	./logs	Directory for log files
LOG_LEVEL	No	info	Winston log level (debug, info, warn, error)

2. Create Mapping File

cp mapping.example.json mapping.json

See the Mapping Guide for detailed configuration options.

3. Generate Tokens

GitHub PAT:

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Repository access: All repositories
3. Permissions: Contents (read and write), Metadata (read-only)
4. Or use a classic token with repo scope

GitLab PAT:

1. Go to GitLab → Preferences → Access Tokens
2. Scopes: api, write_repository
3. Create and copy the token

Running

Development (with hot-reload)

npm run dev

Production (compiled)

npm run build
npm start

Docker

docker run -d \
  --name hub2lab \
  -p 3000:3000 \
  -v /path/to/.env:/app/.env \
  -v /path/to/mapping.json:/app/mapping.json \
  ghcr.io/wildfirebill-docker/hub2lab:latest

Docker Compose

See Docker Deployment for a docker-compose example.

Verifying It Works

curl http://localhost:3000/health

Expected response:

{"status":"ok","timestamp":"2026-07-20T13:00:00.000Z"}

Next Steps

Once hub2lab is running:

1. Set up GitHub webhooks
2. Set up GitLab webhooks
3. Monitor the logs for sync activity