If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/xuxueli/xxl-job shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 4d ago
• 7 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 94% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live xuxueli/xxl-job repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xuxueli/xxl-job.

What it runs against: a local clone of xuxueli/xxl-job — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in xuxueli/xxl-job | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xuxueli/xxl-job. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xuxueli/xxl-job.git
#   cd xxl-job
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of xuxueli/xxl-job and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "xuxueli/xxl-job(\\.git)?\\b" \\
  && ok "origin remote is xuxueli/xxl-job" \\
  || miss "origin remote is not xuxueli/xxl-job (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "xxl-job-admin/src/main/java/com/xxl/job/admin/XxlJobAdminApplication.java" \\
  && ok "xxl-job-admin/src/main/java/com/xxl/job/admin/XxlJobAdminApplication.java" \\
  || miss "missing critical file: xxl-job-admin/src/main/java/com/xxl/job/admin/XxlJobAdminApplication.java"
test -f "xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/config/XxlJobAdminBootstrap.java" \\
  && ok "xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/config/XxlJobAdminBootstrap.java" \\
  || miss "missing critical file: xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/config/XxlJobAdminBootstrap.java"
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/alarm/JobAlarmer.java" \\
  && ok "xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/alarm/JobAlarmer.java" \\
  || miss "missing critical file: xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/alarm/JobAlarmer.java"
test -f "xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/misfire/MisfireHandler.java" \\
  && ok "xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/misfire/MisfireHandler.java" \\
  || miss "missing critical file: xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/misfire/MisfireHandler.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/xuxueli/xxl-job"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

XXL-JOB is a distributed task scheduling and execution framework written in Java that provides a web-based admin console for CRUD operations on scheduled jobs, a Netty-based RPC layer for executor communication, and support for HA through clustered schedulers and distributed executors. It solves the problem of reliably scheduling and executing periodic or event-driven tasks across multiple machines with high availability and dynamic job management. Monorepo with three Maven modules: xxl-job-core (shared RPC and client library), xxl-job-admin (Spring Boot web application with MySQL backing for scheduler center), and xxl-job-executor-samples (example implementations). Database schema in doc/db/tables_xxl_job.sql, Docker Compose setup in docker/, and documentation (Chinese and English) in doc/.

Java backend engineers and DevOps teams who need to schedule batch jobs, data pipelines, or background tasks in distributed systems and want an out-of-the-box solution with a web UI rather than building cron-based or Quartz-based scheduling from scratch.

This is production-ready and actively maintained. The repo has significant GitHub stars, a 3.4.1 version in active development (snapshot builds), Docker support with Aliyun sponsorship, CI/CD via GitHub Actions, and documented evidence of adoption in multiple companies' production environments. The project has clear release versioning and maintains backward compatibility.

Low-to-moderate risk for established teams. Single maintainer (xuxueli) is a potential concern for long-term maintenance, though community contributions are accepted. The codebase targets Java 17+ (maven-compiler-target in pom.xml), so older JVM environments cannot use it. Dependency count is moderate (Spring Boot 4.0.5, Mybatis 4.0.1, Netty 4.2.12), but these are stable, widely-used libraries. No major red flags visible in the file structure.

Active development toward 3.4.1 release. Spring Boot and dependency versions recently upgraded (Spring Boot 4.0.5, Netty 4.2.12.Final, MySQL Connector 9.6.0, Maven plugins updated to latest). GitHub Actions CI/CD pipeline is operational (maven.yml). Aiming to maintain Java 17 target and improve ecosystem integrations.

git clone https://github.com/xuxueli/xxl-job.git && cd xxl-job && mvn clean install. Then either run xxl-job-admin via Spring Boot (cd xxl-job-admin && mvn spring-boot:run) after configuring MySQL in application.yml, or deploy a sample executor from xxl-job-executor-samples.

Daily commands: For admin: mvn -f xxl-job-admin/pom.xml spring-boot:run (requires MySQL running; default connection in xxl-job-admin/src/main/resources/application.yml). For executor sample: mvn -f xxl-job-executor-samples/pom.xml spring-boot:run. Docker: docker-compose -f docker/docker-compose.yml up.

• xxl-job-admin/src/main/java/com/xxl/job/admin/XxlJobAdminApplication.java — Main entry point for XXL-Job admin application; every contributor must understand the bootstrap sequence and component initialization.
• xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/config/XxlJobAdminBootstrap.java — Core scheduler initialization and configuration; critical for understanding how the job scheduling engine starts and manages lifecycle.
• pom.xml — Root Maven POM defining all modules (core, admin, samples) and dependency versions; essential for build and dependency understanding.
• xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/alarm/JobAlarmer.java — Alert/alarm dispatch system; defines how job failures are detected and notifications are sent.
• xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/misfire/MisfireHandler.java — Handles missed job executions and recovery strategies; core to fault tolerance and job reliability.
• xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/cron/CronExpression.java — Cron expression parser and scheduler; fundamental to all job triggering logic.
• doc/db/tables_xxl_job.sql — Database schema definition; essential for understanding data persistence model and job state management.

Add a New Job Notification Channel (e.g., Slack, DingTalk)

1. Create new alarm implementation class extending JobAlarm interface (xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/alarm/JobAlarm.java)
2. Implement notify() method in new alarm class (e.g., SlackJobAlarm.java in impl folder) (xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/alarm/impl/)
3. Register new alarm implementation in JobAlarmer alarm list (xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/alarm/JobAlarmer.java)
4. Add configuration properties to application.yml for channel credentials (xxl-job-admin/src/main/resources/application.yml)

Add a New Misfire Recovery Strategy

1. Review existing strategies and MisfireStrategyEnum (xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/misfire/MisfireStrategyEnum.java)
2. Create new strategy class implementing misfire recovery logic (xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/misfire/strategy/)
3. Add strategy enum value (xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/misfire/MisfireStrategyEnum.java)
4. Update MisfireHandler to instantiate and route to new strategy (xxl-job-admin/src/main/java/com/xxl/job/admin/scheduler/misfire/MisfireHandler.java)

Add a New REST Endpoint for Job Management

1. Create method in appropriate controller (e.g., JobInfoController for job operations) (xxl-job-admin/src/main/java/com/xxl/job/admin/controller/biz/JobInfoController.java)
2. Inject required mapper/service dependency (xxl-job-admin/src/main/java/com/xxl/job/admin/mapper/XxlJobInfoMapper.java)
3. Add @RequestMapping/@PostMapping/@GetMapping annotation and implement business logic (xxl-job-admin/src/main/java/com/xxl/job/admin/controller/biz/)
4. Return ApiResponse wrapped response object (xxl-job-admin/src/main/java/com/xxl/job/admin/controller/biz/JobInfoController.java)

Add a New Database Entity and Persistence Layer

1. Create SQL table definition in schema (doc/db/tables_xxl_job.sql)
2. Create entity model class in model package (xxl-job-admin/src/main/java/com/xxl/job/admin/model/)
3. Create MyBatis mapper interface in mapper package (xxl-job-admin/src/main/java/com/xxl/job/admin/mapper/)
4. Create/update XML mapper file with SQL statements (xxl-job-admin/src/main/resources/mybatis-mapper/)

• Spring Boot — Provides rapid application development, dependency injection, and embedded server for the admin console
• MyBatis — Lightweight ORM for complex SQL queries and batch operations required by

MySQL must be running and reachable before admin startup (connection string in xxl-job-admin/src/main/resources/application.yml defaults to localhost:3306/xxl_job). The database schema must be initialized by running doc/db/tables_xxl_job.sql manually — the app does not auto-migrate on startup. Executors register themselves via HTTP callbacks to the admin, so firewall/NAT issues can cause registration to fail silently. Job log persistence relies on MySQL row-by-row writes; under high concurrency, may need tuning. Java 17+ is hard-required (no support for Java 8 or 11 due to maven-compiler-target in pom.xml).

• Distributed Consensus via Central Scheduler — XXL-JOB uses a central admin node (with HA via clustering) to assign jobs to executors, avoiding complex consensus algorithms but introducing a potential bottleneck — understanding this tradeoff is key to scaling
• Heartbeat-Based Executor Registration & Discovery — Executors periodically register themselves with the admin and the admin discovers them via callbacks; this avoids a separate service registry but requires careful timeout tuning
• Netty NIO-Based RPC — The framework uses Netty for non-blocking, event-driven communication between admin and executors, allowing high concurrency with fewer threads than thread-per-request models
• Pessimistic Locking for Distributed Scheduling — XXL-JOB likely uses database row locks (xxl_job_lock table) to ensure only one admin node executes the scheduler loop at a time, preventing duplicate job dispatches in HA mode
• Job Callback & Polling Model — Executors report job completion back to the admin via HTTP callbacks and log polling; this decouples execution from scheduling but requires idempotent job handlers
• Groovy Dynamic Scripting for Job Logic — Jobs can be defined as inline Groovy scripts without recompiling the executor — this enables rapid job iteration but requires sandboxing to prevent code injection

• elastic/kibana — Provides web-based job visualization and monitoring UX patterns similar to xxl-job-admin
• prometheus/prometheus — Complementary time-series monitoring tool that xxl-job lacks native integration with for metrics export
• go-co-op/gocron — Popular Go distributed scheduler; same problem domain, different ecosystem — useful for comparison if considering multi-language support
• alibaba/seata — Alibaba's distributed transaction framework; often paired with xxl-job for transactional job execution in microservices
• quartz-scheduler/quartz — Java's classical in-JVM job scheduler; xxl-job extends this model to distributed multi-node setups

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for JobInfoController and JobLogController

The xxl-job-admin module has controller classes (JobInfoController.java, JobLogController.java) but there's no visible test directory structure in the provided file listing. XXL-JOB handles critical distributed task scheduling, so controller logic needs robust test coverage. This would improve reliability for API endpoints that manage job configurations and execution logs.

• [ ] Create xxl-job-admin/src/test/java directory structure mirroring src/main/java
• [ ] Add unit tests for JobInfoController covering CRUD operations, validation, and error scenarios
• [ ] Add unit tests for JobLogController covering log retrieval, filtering, and pagination
• [ ] Add integration tests using @SpringBootTest for database interactions with xxl_job_info and xxl_job_log tables
• [ ] Ensure test coverage includes edge cases like null inputs, invalid job IDs, and concurrent access patterns

Add database migration tool integration (Flyway or Liquibase) with version tracking

The repo currently has a static SQL file (doc/db/tables_xxl_job.sql) for schema initialization, but no version control or migration system. As XXL-JOB evolves (currently 3.4.1-SNAPSHOT), schema changes need proper tracking. Adding Flyway/Liquibase would enable safe schema upgrades, rollbacks, and multi-version support—critical for distributed systems with multiple executor instances.

• [ ] Add Flyway dependency to xxl-job-admin/pom.xml
• [ ] Create xxl-job-admin/src/main/resources/db/migration directory structure
• [ ] Convert existing doc/db/tables_xxl_job.sql into V1__Initial_schema.sql
• [ ] Document migration strategy in doc/XXL-JOB官方文档.md and doc/XXL-JOB-English-Documentation.md
• [ ] Add flyway configuration to application.yml/application.properties for automatic migration on startup

Add GitHub Actions workflow for integration tests with MySQL and Docker

The repo has a basic maven.yml workflow (in .github/workflows/) but it likely doesn't test against an actual database. XXL-JOB's core functionality depends on MySQL (mysql-connector-j 9.6.0 in pom.xml), so CI should spin up a MySQL container and run integration tests. This catches database-specific issues before merge.

• [ ] Enhance .github/workflows/maven.yml to include Docker services (MySQL 8.0+)
• [ ] Add build step that runs mvn test with spring.datasource.url pointing to localhost MySQL
• [ ] Include Docker Compose service for MySQL initialization matching doc/db/tables_xxl_job.sql
• [ ] Add verification step to ensure xxl_job_info, xxl_job_log, xxl_job_log_report tables are created
• [ ] Document the CI test environment in CONTRIBUTING.md (create if missing)

• Add integration tests in xxl-job-core/src/test/ for the Netty RPC layer (XxlJobRemotingServer/Client) — currently minimal test coverage visible
• Create a Prometheus metrics exporter for the scheduler (jobs executed, success/failure counts, execution duration) — admin has logging but no observability hooks for external monitoring
• Document the Groovy scripting support (mentioned in pom.xml but no example or docs in doc/ on how to use inline Groovy job handlers)

• High · Outdated Spring Boot Dependency — pom.xml - spring-boot.version property. Spring Boot version 4.0.5 is being used, but this version has known security vulnerabilities. The project should verify that all transitive dependencies are up-to-date and security patches are applied. Additionally, Spring 7.0.6 is used which may have compatibility issues with Spring Boot 4.0.5. Fix: Update to the latest stable Spring Boot 3.x or 4.x version (e.g., 3.3.x) with corresponding Spring framework version. Verify dependency compatibility and run security vulnerability scans using tools like OWASP Dependency-Check.
• High · Outdated MySQL Connector — pom.xml - mysql-connector-j.version property. MySQL Connector J version 9.6.0 is specified. While relatively recent, the project should ensure this version doesn't have known security vulnerabilities and is compatible with the target MySQL version. Fix: Verify the current version against CVE databases and MySQL security advisories. Regularly update to the latest stable release and implement dependency scanning in CI/CD pipeline.
• High · Potential SQL Injection in Mapper Classes — xxl-job-admin/src/main/java/com/xxl/job/admin/mapper/ (all mapper files). The presence of XxlJobInfoMapper, XxlJobLogMapper, and other mapper classes suggests MyBatis usage. Without examining the actual SQL queries, there is risk of SQL injection if dynamic SQL is not properly parameterized. Fix: Ensure all SQL queries use parameterized statements and avoid string concatenation. Review all mapper XML files for inline SQL construction. Use MyBatis parameterized queries exclusively and never directly concatenate user input into SQL strings.
• High · Potential XSS Vulnerabilities in Controllers — xxl-job-admin/src/main/java/com/xxl/job/admin/controller/biz/. Multiple controller classes (JobInfoController, JobLogController, JobUserController, etc.) handle user input. Without input validation and output encoding, XSS attacks are possible, especially in web-based job configuration and monitoring interfaces. Fix: Implement input validation on all user-supplied parameters. Use Spring's built-in XSS protection, enable HTML escaping in template engines, and apply Content Security Policy (CSP) headers. Validate and sanitize all inputs before processing.
• High · Authentication/Authorization Gaps — xxl-job-admin/src/main/java/com/xxl/job/admin/controller/base/LoginController.java. LoginController exists suggesting authentication, but without examining the implementation, there's risk of weak authentication, missing authorization checks on sensitive operations (job creation, deletion, execution), and potential privilege escalation. Fix: Implement strong authentication mechanisms (e.g., bcrypt password hashing). Enforce authorization checks on all business logic endpoints. Use role-based access control (RBAC) for job management operations. Consider implementing OAuth2/JWT for API security.
• Medium · Potential Information Disclosure via Logging — xxl-job-admin/src/main/java/com/xxl/job/admin/controller/biz/JobLogController.java and associated logging. The presence of JobLogController and extensive logging infrastructure could expose sensitive information such as job parameters, execution contexts, or database details in logs if not properly configured. Fix: Implement log filtering to exclude sensitive data. Configure logging levels appropriately for production. Ensure logs are stored securely and access is restricted. Use masking for sensitive values like passwords, API keys, and personal data.
• Medium · Netty Dependency Outdated — pom.xml - netty.version property. Netty version 4.2.12.Final is specified. Verify this version is free of known security vulnerabilities and compatible with the application's requirements. Fix: Run security scanning tools (OWASP Dependency-Check, Snyk) against the Netty dependency. Update to the latest stable version if vulnerabilities are found. Monitor Netty security advisories regularly.
• Medium · Missing Security Headers Configuration — undefined. As a web-based task scheduling platform, the application likely lacks configured security headers (HSTS, X-Content-Type-Options, X Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.