9.5 KiB

Raw Blame History

Quick Start Guide

Get your Redmine-Gitea sync server running in 5 minutes.

1. Install Prerequisites

# Install Node.js 18+ and npm
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version  # Should be 18.x or higher
npm --version   # Should be 9.x or higher

# Install PM2 globally
sudo npm install -g pm2

# Verify PM2 installation
pm2 --version

2. Clone and Setup

# Clone the repository
git clone <your-repo-url>
cd redmine-gitea-sync

# Install dependencies
npm install

3. Configure Environment

# Edit PM2 configuration file
nano ecosystem.config.cjs

Update the env section with your credentials:

env: {
  NODE_ENV: 'production',
  PORT: 3002,
  
  // Redmine
  REDMINE_API_URL: 'https://your-redmine-instance.com',
  REDMINE_API_KEY: 'your_api_key_here',
  
  // Gitea
  GITEA_API_URL: 'https://your-gitea-instance.com',
  GITEA_TOKEN: 'your_token_here',
  GITEA_OWNER: 'your_username',
  
  // Optional: Project mapping
  PROJECT_MAPPING: '{"YourRepo":"your-project"}',
}

Get Your API Keys

Redmine API Key:

Log into Redmine
Go to: My Account → API access key
Click "Show" or "Reset" to view your key
Copy the key to REDMINE_API_KEY

Gitea Token:

Log into Gitea
Go to: Settings → Applications
Generate New Token with these permissions:
- repo (Full control of repositories)
- write:issue (Write issues)
Copy the token to GITEA_TOKEN

4. Start the Server

# Start with PM2
pm2 start ecosystem.config.cjs

# Save PM2 process list
pm2 save

# Setup auto-start on system boot
pm2 startup
# Follow the command it outputs, then:
pm2 save

You should see:

[PM2] Starting /path/to/server.js in fork_mode (1 instance)
[PM2] Done.
┌─────┬──────────────────────────┬─────────┬─────────┬──────────┐
│ id  │ name                     │ mode    │ status  │ cpu      │
├─────┼──────────────────────────┼─────────┼─────────┼──────────┤
│ 0   │ redmine-gitea-sync       │ fork    │ online  │ 0%       │
└─────┴──────────────────────────┴─────────┴─────────┴──────────┘

View logs in real-time:

pm2 logs redmine-gitea-sync

You should see log output like:

[2025-12-17T01:49:47.000Z] [INFO] Redmine-Gitea Sync Server started on port 3002
[2025-12-17T01:49:47.000Z] [INFO] Redmine: https://your-redmine.com
[2025-12-17T01:49:47.000Z] [INFO] Gitea: https://your-gitea.com (owner: your_username)

Alternative: Development Mode

For testing with auto-reload:

# Stop PM2 version first
pm2 stop redmine-gitea-sync

# Run in development mode
npm run dev

5. Test the Server

# Health check
curl http://localhost:3002/health

# Status check (tests connections)
curl http://localhost:3002/status

Expected response:

{
  "status": "ok",
  "uptime": 5.234,
  "connections": {
    "redmine": "connected",
    "gitea": "connected"
  }
}

6. Configure Webhooks

Redmine Webhook

Admin access required
Navigate to: Administration → Settings → Repositories
Add webhook:
- URL: http://your-server-ip:3002/webhook/redmine
- Events: Issues created, Issues updated
Save

Note: Replace your-server-ip with your actual server IP or domain.

Gitea Webhook

Go to your repository
Navigate to: Settings → Webhooks
Add webhook:
- Target URL: http://your-server-ip:3002/webhook/gitea
- HTTP Method: POST
- POST Content Type: application/json
- Trigger On: Issues, Issue Comment
- Active: ✓ Checked
Add Webhook

7. Test the Sync

Create a Test Issue in Redmine

Create a new issue in Redmine
Wait 2-3 seconds
Check your Gitea repository - you should see a new issue

Create a Test Issue in Gitea

Create a new issue in Gitea
Wait 2-3 seconds
Check your Redmine project - you should see a new issue

Add a Comment

Add a comment to either issue
Wait 2-3 seconds
Check the other platform - the comment should appear

8. Verify Logs

# View real-time logs
pm2 logs redmine-gitea-sync

# View last 100 lines
pm2 logs redmine-gitea-sync --lines 100

# View only errors
pm2 logs redmine-gitea-sync --err

# Monitor all PM2 processes
pm2 monit

You should see output like:

[INFO] Processing Redmine issue #31: Test Issue
[INFO] Creating new Gitea issue for Redmine #31
[INFO] Successfully synced Redmine issue #31 to Gitea issue #27

PM2 Commands Quick Reference

# View status of all processes
pm2 list

# Restart the server
pm2 restart redmine-gitea-sync

# Stop the server
pm2 stop redmine-gitea-sync

# Delete from PM2
pm2 delete redmine-gitea-sync

# View detailed info
pm2 show redmine-gitea-sync

Common Issues

Issue: "Cannot connect to Redmine"

Solution:

Verify REDMINE_API_URL is correct (no trailing slash)
Test API key: curl -H "X-Redmine-API-Key: YOUR_KEY" https://your-redmine.com/issues.json
Check firewall rules

Issue: "Cannot connect to Gitea"

Solution:

Verify GITEA_API_URL is correct (no trailing slash)
Test token: curl -H "Authorization: token YOUR_TOKEN" https://your-gitea.com/api/v1/user
Check token has correct permissions

Issue: "Request failed with status code 422"

Solutions:

Update to latest version: git pull && pm2 restart redmine-gitea-sync
Enable debug logging to see validation details
See FIX_SUMMARY.md for recent fixes

Issue: "Webhook not triggering"

Solution:

Verify webhook URL is accessible from Redmine/Gitea servers
Check firewall allows incoming connections on port 3002
Test manually: curl -X POST http://localhost:3002/health

Issue: "Project not found"

Solution:

Check project mapping in ecosystem.config.cjs
Verify repository exists in Gitea
Verify project exists in Redmine
Project identifiers must match (case-sensitive)

Issue: "Comments not syncing from Redmine"

Solutions:

Ensure Redmine webhook includes "Issues updated" events
Verify notes have actual text content (not just field changes)
Clear cache: curl -X POST http://localhost:3002/cache/clear
See TROUBLESHOOTING.md

Issue: "Labels not mapping to Redmine tracker/priority"

Solutions:

Ensure label names match exactly: "bug", "feature", "High Priority"
Update to latest version with label mapping fixes
See FIX_SUMMARY.md

For detailed troubleshooting, see TROUBLESHOOTING.md

Project Mapping

If your Gitea repository name doesn't match your Redmine project identifier, configure mapping in ecosystem.config.cjs:

env: {
  // ... other config
  PROJECT_MAPPING: '{"GiteaRepoName":"redmine-project-id"}',
}

Example:

PROJECT_MAPPING: '{"AI_Smuggling":"ai-smuggling","MyApp":"my-application"}',

After updating, restart PM2:

pm2 restart redmine-gitea-sync --update-env

Alternative: Using .env file

You can also use a .env file:

PROJECT_MAPPING={"GiteaRepoName":"redmine-project-id"}

Then start without PM2:

npm start

Next Steps

PM2 Management: See PM2_GUIDE.md for complete PM2 reference
Production Deployment: See DEPLOYMENT.md
Full Documentation: See README.md
API Details: See API_DOCUMENTATION.md

Features Overview

What gets synced:

✓ Issue titles and descriptions
✓ Issue status (open/closed)
✓ Comments and journals
✓ Assignees
✓ Due dates
✓ Labels (from trackers, priorities, categories)
✓ Milestones (from Redmine versions)
✓ Estimated hours

What doesn't get synced (yet):

✗ Attachments
✗ Watchers
✗ Related issues
✗ Time entries

Customization

Disable Features

Edit ecosystem.config.cjs:

env: {
  // ... other config
  
  // Disable label sync
  SYNC_LABELS: 'false',
  
  // Disable milestone sync
  SYNC_MILESTONES: 'false',
  
  // Disable custom fields
  SYNC_CUSTOM_FIELDS: 'false',
}

Restart PM2:

pm2 restart redmine-gitea-sync --update-env

Adjust Cache TTL

env: {
  // Increase cache time (milliseconds)
  CACHE_TTL: '60000',  // 60 seconds
}

Change Log Level

env: {
  // Show debug information
  LOG_LEVEL: 'debug',
  LOG_VERBOSE: 'true',
}

Or use development mode:

pm2 start ecosystem.config.cjs --env development

Support

Need help?

Check the README.md for detailed documentation
Review API_DOCUMENTATION.md for API details
See DEPLOYMENT.md for production setup
Open an issue in the repository

Security Note

For production use:

Use HTTPS for webhook URLs
Secure your .env file: chmod 600 .env
Consider IP whitelisting
Implement webhook signature verification
Use a reverse proxy (Nginx/Apache)

See DEPLOYMENT.md for production security best practices.

9.5 KiB Raw Blame History

Quick Start Guide

1. Install Prerequisites

2. Clone and Setup

3. Configure Environment

Get Your API Keys

4. Start the Server

Alternative: Development Mode

5. Test the Server

6. Configure Webhooks

Redmine Webhook

Gitea Webhook

7. Test the Sync

Create a Test Issue in Redmine

Create a Test Issue in Gitea

Add a Comment

8. Verify Logs

PM2 Commands Quick Reference

Common Issues

Issue: "Cannot connect to Redmine"

Issue: "Cannot connect to Gitea"

Issue: "Request failed with status code 422"

Issue: "Webhook not triggering"

Issue: "Project not found"

Issue: "Comments not syncing from Redmine"

Issue: "Labels not mapping to Redmine tracker/priority"

Project Mapping

Alternative: Using .env file

Next Steps

Features Overview

Customization

Disable Features

Adjust Cache TTL

Change Log Level

Support

Security Note

9.5 KiB

Raw Blame History