{"id":19908911,"url":"https://github.com/monkeydioude/josuke","last_synced_at":"2025-05-03T02:31:29.646Z","repository":{"id":32523653,"uuid":"92043989","full_name":"monkeydioude/josuke","owner":"monkeydioude","description":"JoJo's Bizarre webhook handler: Josuke is a tiny Github/Bitbucket post treatment tool","archived":false,"fork":false,"pushed_at":"2024-07-31T16:45:46.000Z","size":5116,"stargazers_count":12,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-26T08:49:38.730Z","etag":null,"topics":["bitbucket","github","go","integration","webhook"],"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/monkeydioude.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-22T11:00:50.000Z","updated_at":"2024-10-14T16:09:26.000Z","dependencies_parsed_at":"2024-06-19T05:30:04.933Z","dependency_job_id":null,"html_url":"https://github.com/monkeydioude/josuke","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkeydioude%2Fjosuke","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkeydioude%2Fjosuke/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkeydioude%2Fjosuke/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkeydioude%2Fjosuke/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monkeydioude","download_url":"https://codeload.github.com/monkeydioude/josuke/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252133714,"owners_count":21699585,"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":["bitbucket","github","go","integration","webhook"],"created_at":"2024-11-12T21:13:48.192Z","updated_at":"2025-05-03T02:31:29.389Z","avatar_url":"https://github.com/monkeydioude.png","language":"Go","readme":"## JoJo's Bizarre webhook handler\n_ゴゴゴゴゴゴ ！_\n\nJosuke is a tiny CI/deployment tool that reacts on Gogs/Github/Bitbucket webhook's payload.\n\nJosuke is a simple guy, 3 things and he's happy:\n- Write a JSON config file\n- Run Josuke and feed him your config\n- Go to Github/Bitbucket and set webhooks routes as specified in your config\n\n**Writing a json config file is required.**\n\n**Config file path must be given using the -c flag**: `josuke -c /path/to/config.json`.\n\nExample of a classic config.json:\n\n```json\n{\n    \"logLevel\": \"INFO\",\n    \"host\": \"127.0.0.1\",\n    \"port\": 8082,\n    \"store\": \"{directory to store payload, optional)\",\n    \"hook\": [\n        {\n            \"name\": \"gogs\",\n            \"type\": \"gogs\",\n            \"path\": \"/josuke/gogs\",\n            \"secret\": \"7YiuiG8dM1lSh5IzdrVK5XCQcBbRFMvwh5CB4b90\"\n        },\n        {\n            \"name\": \"private-gogs\",\n            \"type\": \"gogs\",\n            \"path\": \"/josuke/private-gogs\",\n            \"secret\": \"0061Gki75ieIEWaQ8y8SlGpUhGpx0HEfdF3D61Tz\",\n            \"command\": [\n                \"/home/mkd/Work/josuke/script/hook\",\n                \"%payload_path%\",\n                \"%payload_event%\",\n                \"%payload_hook%\"\n            ]\n        },\n        {\n            \"name\": \"github\",\n            \"type\": \"github\",\n            \"path\": \"/josuke/github\",\n            \"secret\": \"wd51QvLFIG3VFim5TmltV2xB40YCWwfJmnmxo9pp\"\n        },\n        {\n            \"name\": \"bitbucket\",\n            \"type\": \"bitbucket\",\n            \"path\": \"/josuke/bitbucket\"\n        }\n    ],\n    \"deployment\":\n    [\n        {\n            \"repo\": \"monkeydioude/donut\",\n            \"proj_dir\": \"donut\",\n            \"base_dir\": \"/var/www\",\n            \"branches\":\n            [\n                {\n                    \"branch\" :\"master\",\n                    \"actions\":\n                    [\n                        {\n                            \"action\": \"push\",\n                            \"commands\": [\n                                [\"echo\", \"payload written to: \", \"%payload_path%\"],\n                                [\"cd\", \"%base_dir%\"],\n                                [\"git\", \"clone\", \"%html_url%\"],\n                                [\"cd\", \"%proj_dir%\"],\n                                [\"git\", \"pull\", \"--rebase\"],\n                                [\"make\"]\n                            ]\n                        }\n                    ]\n                }\n            ]\n        }\n    ]\n}\n```\n\n#### TLS configuration ####\n\nAdd the `cert` and `key` properties inside config's json file, same level as `host`, `port`.\n```json\n{\n    \"…\": \"…\",\n    \"port\": 8082,\n    \"cert\": \"conf/cert.pem\",\n    \"key\": \"conf/key.pem\",\n    \"…\": \"…\"\n}\n```\n\nGenerate the default certificate and private key with:\n\n```sh\n#!/bin/sh\nopenssl req -x509 -newkey rsa:4096 -nodes \\\n  -out cert.pem \\\n  -keyout key.pem -days 365\n```\n\n### Keys definition\n\n- `logLevel`: optional, five levels, from the most verbose to the less verbose: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`. Defaults to `INFO`.\n- `host`: binds the server to local address. Defaults to localhost.\n- `port`: port Josuke will listen to. Defaults to 8082.\n- `store`: directory, optional. If present, every valid payload is written in this directory with a dynamic name: `{hook.name}.{timestamp}.{random string}.json`. The local path to this file is available to commands with the placeholder `%payload_path%`.\n- `hook`: array of objects defining SCM hooks for Gogs, GitHub and BitBucket.\n- `deployment`: array of objects defining deployments **repository rules** Josuke should follow.\n\n#### Hook Definition ####\n\n- `name` : logical name, used in the payload local file name if enabled.\n- `type`: SCM type, currently \"gogs\", \"github\" or \"bitbucket\".\n- `path`: local web path. This path must be specified in the SCM webhook’s parameters.\n- `secret`: signs the payload for Gogs and Github. *Optional, but strongly recommended for security purpose.* If not set, anybody can fake a payload on your webhook endpoint.\n- `command`: optional command, takes precedence over the deployment commands if set. It is run at each valid request. *Only the `%payload_path%`, `%payload_hook%` and `%payload_event%` placeholders are available in this hook scope.*\n\nThere are four types of hooks:\n- `bitbucket`\n- `gogs`\n- `github`\n- `webhook`\n\n##### Command samples #####\n\nRun a shell script `/home/me/josuke/script/hook` with the payload path and event.\n\n```json\n\"command\": [\n\t\"/home/me/josuke/script/hook\",\n\t\"%payload_path%\",\n\t\"%payload_event%\",\n\t\"%payload_hook%\"\n]\n```\n\nOn Windows, use the shell that comes with Git Bash for instance.\n\n```json\n\"command\": [\n\t\"C:/Users/me/AppData/Local/Programs/Git/bin/sh.exe\",\n\t\"C:/Users/me/josuke/script/hook\",\n\t\"%payload_path%\",\n\t\"%payload_event%\",\n\t\"%payload_hook%\"\n]\n```\n\n#### Repository rules ####\n\nThe **repository rules** objects are defined as such:\n- `repo`: name of your repository in the repository universe. No need to specify the whole **only the username and repository name is required** (ex: monkeydioude/josuke)\n- `branches`: is an array of objects defining the **branche behavior** towards specified branches.\n- `base_dir`: **OPTIONAL** Allow you to set what should be a base directory usable at **commands definition** level (ex: /var/projects/sources)\n- `proj_dir`: **OPTIONAL** Allow you to set what should be a project directory (or name) usable at **commands definition** level\n\n**branch behaviors** objects are defined as such:\n- `branch`: behavior toward a specific branch\n- `actions`: is an array of objects defining the behavior towards specific **actions**.\n\n**actions** objects are defined as such:\n- `action`: is the kind of action sent by the payload, that has been taken toward the source branch (ex: push on a branch, merge a branch with the source branch...)\n- `commands`: is an array of objects defining the series of **commands** Josuke should trigger for this `action`\n\n**commands** is an array of array of strings that should contain commands to be executed when an `action` is triggered. 1st index of the array must be the command name. Every following index should be args of the command:\n```json\n    [\n        [\"cd\", \"%base_dir%\"],\n        [\"git\", \"clone\", \"%html_url%\"],\n        [\"cd\", \"%proj_dir%\"],\n        [\"git\", \"pull\", \"--rebase\"],\n        [\"make\"]\n    ]\n\n```\n\n### You can use these 5 placeholders at command level\n\n- `%base_dir%`: referring to \"base_dir\" set in config, must be defined by `base_dir` of each `deployment`\n- `%proj_dir%`: referring to \"proj_dir\" set in config, must be defined by `proj_dir` of each `deployment`\n- `%html_url%`: retrieved from gogs/github/bitbucket's payload informations, html url of your repo\n- `%payload_hook%`: name of the hook that received the payload (`hook[\u003cnum\u003e].name` in the configuration).\n- `%payload_path%`: path to the payload, available if enabled with `store` in the configuration. Otherwise, empty.\n- `%payload_event%`: content of the event request header, be it `x-gogs-event`, `x-github-event`, `x-key-event`. It contains the webhook event, `push` for instance. If the event header is absent, it is empty.\n\n### Tests:\n\nSee [testdata/](testdata/index.md).\n\n### Functional tests:\nUsing `make ftest` will trigger `script/functional-test-runner.sh`. This script will run every script matching `test/functional/test*.sh` pattern.\n\n### Build and run instructions:\n\n__With Golang__:\n- Install [the Go language](https://golang.org/dl/)\n\nThen using Makefile (Unix/Linux/MacOS/WSL on Windows):\n- `CONF_FILE=/path/to/config/json make go_start`\n\nOr with shell startup script (Unix/Linux/MacOS/WSL on Windows):\n- `CONF_FILE=/path/to/config/json script/run.sh`\n\nOr using Golang only (only available option for Windows users not using WSL):\n- `go install`\n- `josuke -c /path/to/config/json`\n\n__With Docker__\n- Install [Docker](https://docs.docker.com/get-docker/)\n\nThen using Makefile (Unix/Linux/MacOS/WSL on Windows):\n- `CONF_FILE=/path/to/config/json make start`\n\nOr with Docker only:\n- docker build -f build/Dockerfile -t josuke .\n- docker run --network=\"host\" -d -e \"CONF_FILE=/path/to/config/json\" josuke\n\n## Healthcheck:\nOnce Josuke is running, healthcheck HTTP status is available at `/healthcheck`\n\n## Makefile:\n- `help`: display make actions help descriptions\n- `install` (dev only): setup dev env such as git hooks\n- `stop`: stop josuke running docker container\n- `start`: build josuke docker image and run it\n- `restart`: `stop` + `start`\n- `run`: run a docker container using already built josuke image\n- `sr`: `stop` + `run`\n- `shell`: run a shell (/bin/sh) in a running josuke container\n- `test`: run unit tests inside a container\n- `ftest`: run functional tests\n- `bb`: rebuild josuke binary inside a running container\n- `logs`: read josuke's log file (/var/log/josuke) inside a running container\n- `offline_logs`: read logs of the lastet, running or not, josuke container from host's physical log files (/var/lig/docker/containers/$CONTAINER_ID/$CONTAINER_ID-json.log)\n- `attach`: attach a tty to a running container. Be advised that detaching the freshly attached tty might require to kill process. ちょっとダメね\n\nDefault make rule is `start`\n\n_DORA !_\n\n\n![](https://68.media.tumblr.com/7b9b18644e2d491cc25267ebde23ec23/tumblr_ohxk9dpmoq1tqvsfso1_540.gif)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkeydioude%2Fjosuke","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonkeydioude%2Fjosuke","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkeydioude%2Fjosuke/lists"}