payload-plugin-jobs-runner

An admin UI for Payload that lets non-technical users trigger, watch, and retry Jobs tasks & workflows on demand — the tasks/workflows developers define in code, made runnable with a click. Access-gated per user.

Built for Payload 4.0.

What it does

• Auto-discovers everything registered in config.jobs.tasks and config.jobs.workflows.
• Renders a Jobs Runner panel (a job select + Run button, live result, recent-jobs list with Retry).
• Mounts on the Modular Dashboard (as a widget) and/or the Jobs collection list — configurable.
• Unhides the payload-jobs collection and gives it a readable columns default.
• Runs jobs in-process via payload.jobs.runByID — no background runner required (ideal for serverless / local dev).
• Gates which tasks/workflows each user may run via an access callback (great with a roles field).

Install

npm install payload-plugin-jobs-runner

Peer deps: payload (4.0 canary), react / react-dom 19.

Usage

import { jobsRunnerPlugin } from 'payload-plugin-jobs-runner'

export default buildConfig({
  jobs: {
    tasks: [/* ... */],
    workflows: [/* ... */],
    deleteJobOnComplete: false, // keep history visible
  },
  plugins: [
    jobsRunnerPlugin({
      // Gate who can run what (return true to allow). Runs server-side for the
      // UI list AND the run/retry endpoints.
      access: ({ req, slug, type }) => {
        const roles = (req.user as { roles?: string[] | null } | null)?.roles
        return roles?.includes('admin') ? true : ['safeTask'].includes(slug)
      },
      // Where to mount (both default true):
      views: { dashboard: true, jobsCollection: true },
      // Optionally limit which slugs appear at all:
      // include: ['taskA', 'workflowB'],
    }),
  ],
})

After adding/removing tasks or components, run payload generate:importmap.

Endpoints

All gated by access and require an authenticated user:

• GET /api/run-jobs/runnables — tasks/workflows the current user may run
• POST /api/run-jobs/run { slug, input? } — queue + run now, returns the job
• POST /api/run-jobs/retry { id } — re-run an existing job
• GET /api/run-jobs/recent — recent jobs
• POST /api/run-jobs/clear — clear job history

Config

| Option | Type | Description | | --- | --- | --- | | access | ({ req, slug, type }) => boolean \| Promise<boolean> | Gate which runnables a user may run. Default: any authenticated user. | | include | string[] | Restrict which task/workflow slugs appear at all. | | views.dashboard | boolean | Mount as a dashboard widget. Default true. | | views.jobsCollection | boolean | Mount on the Jobs collection list. Default true. | | disabled | boolean | Disable the plugin (no UI, no endpoints). |

License

MIT