Scheduled Jobs

1. Overview

The application includes a built-in job scheduler that automatically runs recurring maintenance tasks and background operations. As an administrator, you can view, configure, and manually trigger these jobs through the Scheduler management UI.

2. Accessing the Scheduler

Go to Settings → Advanced → Scheduled Jobs to see every registered job and its current status.

Required permission: scheduler:read to view jobs, scheduler:write to modify them.

3. Understanding the Job List

The scheduler dashboard shows all registered jobs with the following information:

Screenshot needed

scheduler-jobs.png

Settings → Advanced → Scheduled jobs

4. Job Statuses

Each job run is recorded with one of these statuses:

5. Configuring Jobs

Changing the Schedule

If a job has the "Schedule Editable" flag (shown as a pencil icon next to the schedule), you can change when it runs:

1. Click the pencil icon on the job's row
2. Enter a new cron expression (in UTC) or interval
3. Check Next run, shown in your own time zone under the field
4. Click Save Changes

Screenshot needed

scheduler-edit-schedule.png

Editing a job's schedule, with the next run in the viewer's time

The new schedule takes effect immediately — no restart required.

Cron expression format: minute hour day-of-month month day-of-week

Changing Job Parameters (Metadata)

Some jobs have configurable parameters (e.g., retention days, batch size). If a job has the "Metadata Editable" flag:

1. Click the job name to open its detail view
2. Click Edit Parameters
3. Modify the values (each parameter has a description and valid range)
4. Click Save

Changes take effect on the next scheduled run.

Enabling / Disabling Jobs

If a job has the "Toggleable" flag:

1. Click the toggle switch next to the job name
2. Confirm the action

Disabled jobs will not run on their schedule but remain registered. Re-enabling them resumes normal scheduling.

6. Manual Execution

If a job has the "Manual Run" flag (shown as a play button ▶️):

1. Click the Run Now button next to the job
2. The job will execute immediately using its current configuration

• Manual runs use the same parameters (metadata) as scheduled runs
• If the job is already running (on another node), the manual run will be rejected with a "conflict" message
• Manual runs are recorded in run history just like scheduled runs

7. Viewing Run History

Each job maintains a detailed execution history:

1. Click the job name to open its detail view
2. Select the Run History tab

Each run record shows:

• Started At — When the execution began
• Duration — How long it took
• Status — Success, Failure, Timeout, or Skipped
• Node — Which server node executed the job (in multi-node deployments)
• Attempt — Retry attempt number (if retries are configured)
• Error — Error message (for failed runs)
• Parameters — Snapshot of the metadata used for that specific run

Run history is automatically cleaned up after the configured retention period (default: 30 days, minimum 50 runs per job are always kept).

8. Built-in Jobs

The application ships with these pre-configured jobs:

Session Cleanup (auth-session-cleanup)

Scheduled Backup (backup-scheduled)

Backup Cleanup (backup-cleanup)

API Token Cleanup (apitoken-cleanup)

Download Usage (download-usage)

Token Usage (token-usage-flush)

Run History Cleanup (scheduler-run-history-cleanup)

Event Delivery (event-dispatch)

Search Change Cleanup (index-events-prune)

Event Cleanup (event-outbox-cleanup)

Policy Compliance Check (policy-compliance-scan)

Automation Run Cleanup (automation-run-cleanup)

Directory Sync (directory-sync)

Directory Sync History Cleanup (directory-sync-run-cleanup)

Email Delivery (mail-dispatch)

Email History Cleanup (mail-cleanup)

Deleted Repositories (repository-purge)

Repository Metadata Rebuilds (repository-repair)

Old Metadata Rebuilds (repository-repair-prune)

Background Promotions (promotion-run)

Old Promotions (promotion-prune)

Unused Artifact Content (artifact-blob-gc)

Download Counts (artifact-download-flush)

Abandoned Uploads (artifact-upload-temp-cleanup)

Unused Docker Layers (docker-gc)

Unfinished Docker Uploads (docker-upload-cleanup)

RubyGems Index Warm-up (rubygems-index-warm)

RubyGems Index Compaction (rubygems-index-compact)

Unfinished Conan Uploads (conan-upload-cleanup)

Artifact Inspection (browse-inspect)

Ended Quarantines (quarantine-expiry)

9. Multi-Node Behavior

In clustered deployments (multiple application nodes), the scheduler ensures:

• Singleton jobs run on exactly one node per scheduled interval — no duplicate execution
• Any node can pick up a job — the first to acquire the distributed lock wins
• If a node crashes mid-job, the lock automatically expires and another node picks it up on the next scheduled run
• The Node column in run history shows which server executed each run

You do not need to configure anything for this. The lock is kept in PostgreSQL, so jobs keep running once per cluster while Redis is unavailable.

10. Health Monitoring

The scheduler tracks job health based on consecutive failures:

When a job becomes unhealthy:

• An alert event is fired (can be consumed by notification plugins)
• The job continues to run on schedule — it is NOT automatically disabled
• When the job succeeds again, it returns to healthy status and a recovery event is fired

11. Permissions

12. Troubleshooting

"Job is currently executing, conflict"

This means the job is already running on another node. Wait for it to complete, or check the run history to see if it's stuck (exceeding its max duration).

Job shows as "Timeout"

The job exceeded its maximum allowed execution time and was cancelled. This could mean:

• The operation is taking longer than expected (e.g., large dataset to clean up)
• There's a performance issue with the underlying operation
• Contact your system administrator to investigate or increase the timeout

Job keeps failing (Unhealthy)

Check the run history for error messages. Common causes:

• Database connectivity issues
• Insufficient permissions for the cleanup operation
• Resource constraints (memory, disk space)

Schedule changes not taking effect

• Verify you have scheduler:write permission
• Check that the job has "Schedule Editable" enabled
• Ensure the cron expression is valid (the UI validates this before saving)

Job not running at expected time

• Check if the job is disabled (toggle switch)
• In multi-node deployments, the job runs on one node — check all nodes' logs
• The schedule uses UTC time — verify your timezone expectations

13. Environment Variables (Server Configuration)

These are configured by the system administrator at deployment time:

14. FAQ

Q: Can I add custom jobs? A: Custom jobs are added by developers through the codebase. The scheduler UI manages existing registered jobs. If you need a new recurring task, contact your development team.

Q: What happens during a server restart? A: Running jobs are given a grace period to complete (default: 30 seconds). If they don't finish in time, they are cancelled and recorded as "timeout". On the next startup, the scheduler detects any missed fire times and handles them according to each job's misfire policy.

Q: Can I see which node ran a job? A: Yes — the run history shows the Node ID for each execution. This is useful for debugging in multi-node deployments.

Q: What timezone do schedules use? A: All cron schedules use UTC, whatever time zone the servers or viewers are in. Last and next run times, and the next run shown while you edit a schedule, are in your own time zone.

Q: Will disabling a job cause data to accumulate? A: Yes — if you disable a cleanup job, the data it would normally clean up will continue to grow. Only disable jobs temporarily and re-enable them when the issue is resolved.