{"id":13581693,"url":"https://github.com/jshiv/cronicle","last_synced_at":"2025-12-25T08:47:43.868Z","repository":{"id":39867399,"uuid":"202371441","full_name":"jshiv/cronicle","owner":"jshiv","description":"cronicle is a simple and scalable task scheduler that builds on the foundations of git, golang and standard logging","archived":false,"fork":false,"pushed_at":"2022-08-24T20:41:31.000Z","size":398,"stargazers_count":22,"open_issues_count":12,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-05T21:44:58.784Z","etag":null,"topics":["cicd","cron","distributed","git","golang-tools","task-scheduler","workflow-engine"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jshiv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-14T14:51:50.000Z","updated_at":"2024-09-16T22:41:13.000Z","dependencies_parsed_at":"2022-08-26T01:12:20.275Z","dependency_job_id":null,"html_url":"https://github.com/jshiv/cronicle","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jshiv%2Fcronicle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jshiv%2Fcronicle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jshiv%2Fcronicle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jshiv%2Fcronicle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jshiv","download_url":"https://codeload.github.com/jshiv/cronicle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247470449,"owners_count":20944146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cicd","cron","distributed","git","golang-tools","task-scheduler","workflow-engine"],"created_at":"2024-08-01T15:02:11.044Z","updated_at":"2025-12-25T08:47:43.855Z","avatar_url":"https://github.com/jshiv.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"Cronicle\n---\ngit integrated distributed workflow scheduler that provides a pull model for CI/CD and versioning on job execution.\n\n---\n\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/jshiv/cronicle)](https://pkg.go.dev/github.com/jshiv/cronicle)\n\n## Install\n\nLinux\n```bash\nwget -c https://github.com/jshiv/cronicle/releases/download/v0.3.8/cronicle_0.3.8_Linux_x86_64.tar.gz -O - | tar -xz\nsudo mv cronicle /usr/local/bin/cronicle\n```\n\nMac/Windows download from the [releases page.](https://github.com/jshiv/cronicle/releases/latest)\n\n## Quick start\n```bash\ncronicle run --command \"/bin/echo cronicle\" --cron \"@every 5s\"\n```\n\nThe `cronicle.hcl` file maintains the `schedule as code` for task execution.\n\n`cronicle init --path cron` will produce a default file:\n```hcl\n//cronicle.hcl\nschedule \"example\" {\n  cron       = \"@every 5s\"\n\n  task \"hello\" {\n    command = [\"python\", \"run.py\"]\n    repo {\n      url = \"https://github.com/jshiv/cronicle-sample.git\"\n    }\n  }\n}\n```\n\n`cronicle run --path cron/cronicle.hcl`\n```\nINFO[2020-10-06T21:44:16-07:00] Starting Scheduler...                         cronicle=start\nINFO[2020-10-06T21:44:16-07:00] Loading config...                             cronicle=heartbeat path=./cronicle.hcl\nINFO[2020-10-06T21:44:21-07:00] Queuing...                                    schedule=example\nINFO[2020-10-06T21:44:21-07:00]                                               attempt=1 schedule=example task=hello\nINFO[2020-10-06T21:44:21-07:00] X: 0.360346904169                             commit=f99ad6af7de email=jason.shiverick@gmail.com exit=0 schedule=example success=true task=hello\n```\n\n---\n\n\n## Example Deployments\n\n* [Centralize cronicle logs on a local loki/graphana log aggregator](deploy/local/README.md)\n* [Distribute cronicle tasks with nsq message broker](deploy/nsq/README.md)\n\n\n---\n\n## Breakdown of `cronicle.hcl`\n\n\n### `repo` (optional)\nA `repo` block is available at the `config`, `schedule` and `task` level but the behavior is different depending on which level it is assigned.\nAt the `config` level, a `repo` block enables the `cronicle.hcl` file to be tracked by a remote git repo, a heartbeat process will fetch and refresh the cronicle.hcl from the remote `repo`. At the `schedule` level, the `repo` block will be used as a default `repo` for any `tasks` that do not have an explicitly assigned `repo` block. At the `task` level a `repo` block will override the default `repo` with any details given.\n_Note: setting remote requires that any changes to the cronicle repo to be made through \nthe remote git repo, any local changes will be removed by `git checkout`._\n```hcl\nrepo {\n  // url or path to a remote git repository\n  url    = \"git@github.com:jshiv/cronicle-sample.git\"\n\n  // local ssh private key with read access to remote private repo\n  key    = \"~/.ssh/id_rsa\"\n\n  // branch to checkout for execution\n  branch = \"\"\n\n  // commit to checkout for execution, mutually exclusive to branch\n  commit = \"\"\n}\n```\n\n\n### `task`\nContains the executable command, dependency relationship between tasks, \na repo to execute the command against, \n```hcl\ntask \"bar\" {\n  //executable command\n  command = [\"/bin/echo\", \"Hello World --date=${date}\"]\n\n  //dependency relationship between tasks\n  depends = [\"baz\"]\n  \n  //git repo containing source code to clone/fetch on execution\n  repo ...\n\n  // retry count and wait\n  retry ...\n}\n```\n\n### `schedule`\n`schedule` is the block that sets the crontap. `task` blocks are contained within the `schedule` block.\n```hcl\nschedule \"foo\" {\n  // crontab for scheduling execution, accpets Cron experessions, @every, @once, \"\"\n  //cron = \"@once\" will execute the schedule on the first invocation of `cronicle run`\n  //cron = \"\" will only execute the schedule/task with `cronicle exec`. Useful when useing cronicle to codify non-scheduled commands.\n  cron       = \"@every 5s\"\n\n  // IANA Time Zone\n  timezone   = \"\"\n\n  // Define the window in which the schedule is valid.\n  // Outside of this window, tasks will not execute and a warring will be logged.\n  start_date = \"\"\n  end_date   = \"\"\n\n  // Default repo for all tasks in schedule \"foo\"\n  repo {\n    ...\n  }\n\n  // task \"bar\" will execute \"@every 5s\"\n  task \"bar\" {\n    ...\n  }\n  \n  // task \"baz\" will execute in parallel with task \"bar\"\n  task \"baz\" {\n    ...\n  }\n\n  // task \"last\" will execute only after \"bar\" and \"baz\" succeed \n  task \"last\" {\n    ...\n    depends = [\"bar\", \"baz\"]\n  }\n}\n```\n\n\n### `retry` (optional)\nNumber of retries and time to wait between.\n```hcl\nretry {\n  count   = 1\n  seconds = 30\n  minutes = 0\n  hours   = 0\n}\n```\n\n### `timezone` (optional)\n```hcl\n// timezone sets the timezone location to run cron and execute tasks by.\n// default local\ntimezone = \"America/Los_Angeles\"\n```\n\n### `heartbeat` (optional)\n```hcl\n// Cron expression to schedule the cronicle.hcl refresh task\nheartbeat = \"@every 60s\"\n```\n\n---\n\n## Bash Commands\n\nThe init command sets up a new schedule repository with a sample conicle.hcl file\n```bash\ncronicle init\ntree\n.\n├── cronicle.hcl\n└── .repos\n```\n\nThe `run` command starts the scheduler.\n```bash\ncronicle run\n```\n\nThe `exec` command will execute a named task/schedule for a given time or date range.\n```bash\ncronicle exec --task bar\n```\n\nThe `worker` will start a schedule consumer when `cronicle run --queue ` is in distributed mode.\n```bash\ncronicle worker --queue redis\n```\n\n---\n\n## Command Templates\nThe cronicle command string accepts the following template argumets\n```\n\t ${date}: \t\t  \"2006-01-02\"\n\t ${datetime}: \t\"2006-01-02T15:04:05Z07:00\"\n\t ${timestamp}: \t\"2006-01-02 15:04:05Z07:00\"\n\t ${path}:       task.Path\n```\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjshiv%2Fcronicle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjshiv%2Fcronicle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjshiv%2Fcronicle/lists"}