MkSaaS DocsCron Jobs
Learn how to set up and use Cron Jobs in MkSaaS
MkSaaS requires a daily scheduled task to distribute credits to users and handle credit expiration. You can set this up using GitHub Actions (recommended) or an external service like cron-job.org.
If you enable credits system, you must setup cron jobs to distribute credits to users and handle credit expiration.
Credits
Learn more about Credits
Method 1: GitHub Actions (Recommended)
GitHub Actions runs the pnpm run distribute-credits script directly in a CI environment. This avoids API timeout issues that can occur with HTTP-based cron services, and requires no external service.
The workflow file is already included in the template at .github/workflows/distribute-credits.yml. It runs daily at 00:10 UTC and supports manual triggering via workflow_dispatch.
Verify the Workflow File
Make sure .github/workflows/distribute-credits.yml exists in your repository. If you cloned from the template, it should already be there. The workflow contents:
name: Distribute Credits
on:
schedule:
- cron: '10 0 * * *'
workflow_dispatch:
jobs:
distribute:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install pnpm
uses: pnpm/action-setup@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'pnpm'
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Run credit distribution
env:
DATABASE_URL: ${{ secrets.DATABASE_URL }}
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
FEISHU_WEBHOOK_URL: ${{ secrets.FEISHU_WEBHOOK_URL }}
run: pnpm run distribute-creditsAdd GitHub Secrets
Go to your GitHub repository > Settings > Secrets and variables > Actions, and add the following secrets:
| Secret | Required | Description |
|---|---|---|
DATABASE_URL | Yes | Your PostgreSQL connection string |
DISCORD_WEBHOOK_URL | No | Discord webhook for distribution notifications |
FEISHU_WEBHOOK_URL | No | Feishu webhook for distribution notifications |
Push and Verify
Push the workflow file to your repository's default branch. Go to the Actions tab to confirm the workflow appears.
To test it immediately, select the "Distribute Credits" workflow and click Run workflow. You can check execution logs and status from the same page.
Method 2: cron-job.org (Alternative)
cron-job.org is a free external cron job scheduler. It triggers credit distribution by sending an HTTP request to your API endpoint.
Create an Account
Create a new account at cron-job.org.
Create a Cron Job
Go to Cron Job Dashboard > Cronjobs, click CREATE CRONJOB.
Configure Basic Settings
In the Cron Job Common section, set the Title and URL. Set Execution schedule to run daily at any time (e.g. 00:00). The URL format is:
https://{YOUR-DOMAIN}/api/distribute-credits
Configure Advanced Settings
In the Cron Job Advance section, set Username and Password, and set Timeout to 30 seconds.
These are not your cron-job.org account credentials. They are basic authentication credentials for the API endpoint. Keep them secret.
Set Environment Variables
Add the credentials you configured above to your environment variables:
CRON_JOBS_USERNAME=YOUR-USERNAME
CRON_JOBS_PASSWORD=YOUR-PASSWORDYou can test the cron job by clicking TEST RUN on the cron job page, then checking the response in the Response tab. Execution history is also available there.
If you are setting up the environment, now you can go back to the Environment Setup guide and continue. The rest of this guide can be read later.
Environment Setup
Set up environment variables
File Structure
.github/workflows/distribute-credits.ymlâ GitHub Actions workflow for scheduled credit distribution (Method 1)src/app/api/distribute-credits/route.tsâ API route for HTTP-based credit distribution (Method 2, used by cron-job.org)
Reference
Next Steps
Now that you have set up scheduled credit distribution, you may want to explore these related integrations: