{"id":23131677,"url":"https://github.com/peopledoc/peon","last_synced_at":"2025-04-04T07:28:26.498Z","repository":{"id":34433011,"uuid":"165065097","full_name":"peopledoc/peon","owner":"peopledoc","description":"peons... they'll build things for you.","archived":false,"fork":false,"pushed_at":"2023-09-28T00:03:11.000Z","size":675,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-03-22T20:38:34.330Z","etag":null,"topics":["approved-public","cd","continous-deployment","ghec-mig-migrated","peon","peopledoc-opensource","tribe-js"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/peopledoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-10T13:31:21.000Z","updated_at":"2023-09-27T19:10:23.000Z","dependencies_parsed_at":"2025-02-09T18:40:45.468Z","dependency_job_id":null,"html_url":"https://github.com/peopledoc/peon","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peopledoc%2Fpeon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peopledoc%2Fpeon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peopledoc%2Fpeon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peopledoc%2Fpeon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peopledoc","download_url":"https://codeload.github.com/peopledoc/peon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247137877,"owners_count":20889945,"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":["approved-public","cd","continous-deployment","ghec-mig-migrated","peon","peopledoc-opensource","tribe-js"],"created_at":"2024-12-17T11:15:52.889Z","updated_at":"2025-04-04T07:28:26.467Z","avatar_url":"https://github.com/peopledoc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Peon\n\n\u003e They do all the work behind closed doors.\n\nPeon is a minimal CD tool that can be used to run build commands on git\nrepositories and deploy built artifacts locally. The main goal is to\nallow continuous deployment of static apps.\n\nIt can receive Github webhooks, but when deployed on a machine that is not\nreachable from the internet, can also watch git repositories directly.\n\n## Usage\n\n### Prerequisites\n\n- node 11+ and yarn\n- a web server configured to serve static files from a directory\n- when using webhooks, a web server that is able to proxy requests on a\n  publicly-accessible URL to a locally-running http server\n\n### Installation\n\nClone the repository and run `yarn` at the repository root.\n\n### Peon configuration\n\nYou can set the `PEON_CONFIG` environment variable to tell Peon where to\nlook for its configuration file; by default it loads `config.json` at the\nroot of the repository.\n\nA sample config file is available at the root of the project. See\n`config.sample.json` for details.\n\nThe configuration file contains the following keys:\n\n- **Base configuration:**\n\n  - `workingDirectory`: a directory where peon stores its working data\n  - `dbBackupInterval`: database backup interval in milliseconds, defaults to\n    no backups.\n  - `dbBackupKeep`: number of previous backups to keep, defaults to keeping all.\n  - `cacheValidity`: validity in milliseconds of paths cached during builds.\n  - `cacheMaxSize`: maximum size of cache in bytes; peon will remove the oldest\n    non-expired cache items until cache size is below that limit. Set to 0 for\n    unlimited cache size.\n  - `statusDirectory`: a directory where peon will store its status pages.\n  - `statusUrl`: URL where the status directory is served (used for github\n    build status updates)\n  - `indexBuildCount`: maximum number of builds to show on status index page,\n    defaults to all builds\n  - `githubAPIToken`: a GitHub API token used to update build status on commits\n    (requires at least the `repo:status` scope).\n\n- **Watcher configuration:** enable this when you want peon to poll git\n  repositories at regular intervals (useful when the machine is not reachable\n  from the internet and thus cannot receive webhooks)\n\n  - `watcher.enabled`: boolean, enables or disables repository watchers\n  - `watcher.interval`: interval in milliseconds between polls on each\n    repository\n  - `watcher.repositories`: an array of objects for each repository to watch\n    - `watcher.repositories[].url`: url to the repository (http(s), git, ssh)\n    - `watcher.repositories[].branches`: list of branches to watch for changes.\n\n- **Webhooks configuration:** enable this when the machine is reachable from the\n  internet to listen for Github webhooks\n\n  - `webhooks.enabled`: boolean, enables or disables listening for webhooks\n  - `webhooks.port`: port to listen on; Peon will only listen on localhost so\n    you must have a web server running that proxies webhook requests received\n    on the public endpoint to this port.\n  - `webhooks.secret`: set it to something secret that you will configure on\n    your repositories on Github.\n  - `webhooks.url`: (optional) URL where webhook payloads, for manual job\n    retriggers from status pages, should be sent.\n\n- **Build output destinations configuration:** configure destinations where Peon\n  will store build outputs (using rsync). Destinations can be local or remote.\n\n  - `destinations.$name.destination`: local or remote path specification, for\n    example `/var/www/peon` or `[user@]host:/path/to/directory`. The directory\n    must exist.\n  - `destinations.$name.rootUrl`: root URL path the destination is served by a\n    webserver (without the protocol/host/port).\n  - `destinations.$name.absoluteUrl`: full URL the destination is served by a\n    webserver (**with** protocol/host/port). This is used so that peon can\n    generate links to the deployed build.\n  - `destinations.$name.shell`: used only for remote destinations; shell command\n    to use to connect to the remote. You can use it to pass SSH options (for\n    example `ssh -o StrictHostKeyChecking=no -i /path/to/id_rsa`). Note that\n    the command will run as the same user Peon is running as.\n\n- **Git auth configuration:** set up which auth method to use to clone private\n  repositories\n\n  - `git.authMethod`: `agent` to use the SSH agent for the user running Peon,\n    `key` to use a PEM-format key pair\n  - `git.privateKey`: path to the private key to use\n  - `git.publicKey`: path to the public key to use\n  - `git.keyPassword`: password for the key, use an empty string for unencrypted\n    keys\n\n- **Logger configuration:**\n  - `logger.level`: one of `error`, `info`, `debug`.\n\n**Notes:**\n\n- The user running peon must have writing rights on `workingDirectory` and\n  `statusDirectory`.\n- Do not watch a repository that also emits webhooks, it will conflict.\n\n### Running Peon\n\nRun `node ./index.js` from the repostory root. You may want to use some\nkind of process manager (forever, pm2, systemd...) to keep it running.\n\n## Repository configuration\n\nPeon will only run builds when it finds a `.peon.yml` file at the root of a\nrepository. A reference of available options follows.\n\n### `branches` (optional) - branches allowed to build\n\nBy default Peon triggers builds on all branches. To restrict branches that can\ntrigger a build, you can specify them as a list of regexps.\n\n```yaml\nbranches:\n  - ^master$\n  - ^feat/\n```\n\n### `cache` (optional) - build assets caching\n\nPeon allows storing build assets in cache after a build an restoring them before\na subsequent build. This is useful for example when one of the building steps\ndownloads dependencies based on a requirements file (eg. npm, yarn, pip) and you\ndon't want the whole process of downloading all the dependencies to run again\nwhen your project hasn't changed.\n\nYou can specify a list of paths to store, along with a file whose contents will\nbe used to determine the validity of the cache.\n\n```yaml\ncache:\n  - path: node_modules\n    source: yarn.lock\n```\n\n### `commands` (mandatory) - commands to run when building.\n\nThose commands will be run in sequence from the repository root.\n\n```yaml\ncommands:\n  - yarn\n  - yarn build -prod\n```\n\nThe following environment variables are available to those commands:\n\n- `$PEON_BUILD_ID`: ID of the build (eg. \"reponame#123\")\n- `$PEON_BUILD_DATE`: ISO-formatted timestamp of the build start date\n- `$PEON_REPO_NAME`: name of the repository being built\n- `$PEON_BRANCH`: branch being built if building a branch\n- `$PEON_TAG`: tag being built if building a tag\n- `$PEON_REF`: equivalent to `$PEON_BRANCH` or `$PEON_TAG`\n- `$PEON_COMMIT`: commit SHA1 being built\n- `$PEON_ROOT_URL`: root URL where the build will be served,\n\nAdditional environment variables may be specified in the repository\nconfiguration file, see `environment` below.\n\n### `destinations` (mandatory) - where to deploy the build output\n\nPeon configuration file allows defining a list of named destinations to deploy\nbuild outputs, both local (on the machine where Peon is running) and remote\n(using rsync). From the perspective of your project however, there is no\ndifference between local and remote destinations.\n\nThe `destinations` key in the repository configuration file specifies which\ndestination(s) you want to use when deploying your project and which branches or\ntags they apply to. Peon will use the first matching destination, and will\nabort the build when no destination matches.\n\n```yaml\ndestinations:\n  # Deploy master to production at a fixed path\n  - name: production\n    branch: ^master$\n    path: documentation/myproject/master\n  # Deploy tags vX.Y.Z to production at a variable path\n  - name: production\n    tag: ^v\\d\n    path: documentation/myproject/$PEON_TAG\n  # This rule is equivalent to both rules above\n  - name: production\n    branch: ^master$\n    tag: ^v\\d\n    path: documentation/myproject/$PEON_REF\n  # Deploy everything else to local in REPONAME/REF\n  - name: local\n```\n\nEach destination you specify has the following keys:\n\n- `name`: mandatory; name of a destination defined in Peon configuration file\n- `path`: optional; path relative to the destination to store the build into.\n  If not specified, defaults to `$PEON_REPO_NAME/$PEON_REF`. You can use peon\n  environment variables in the value.\n- `branch`: optional, ignored when building a tag; regexp checked against the\n  branch being built. If not specified, defaults to matching all branches,\n  unless a tag regexp is also specified in which case it defaults to _not_\n  matching any branch.\n- `tag`: optional, ignored when building a branch; regexp checked against the\n  tag being built, defaults to _not_ matching any tag.\n\nTo summarize the destination choice process:\n\n- When building a branch, Peon will chose the first destination that either has\n  a matching `branch` regexp or has neither a `branch` nor a `tag` regexp.\n- When building a tag, Peon will chose the first destination that explicitly\n  defines a matching `tag` regexp.\n\n### `environment` (optional) - additional build environment variables\n\nYou can specify additional environment variables that will be made available to\nall build commands. Values can include Peon environment variables.\n\n```yaml\nenvironment:\n  MYVARIABLE: myvalue\n  MYROOTURL: \"$PEON_ROOT_URL/myapp/\"\n```\n\n### `output` (mandatory) - where to find the build output\n\nThis should be the name of a directory relative to the repository root where\nPeon can find the build output. Its contents will be copied into the directory\nspecified in the `destinations` configuration.\n\n```yaml\noutput: dist\n```\n\n### `tags` (optional) - tags allowed to build\n\nBy default Peon does not trigger any build on tags. If you want to trigger\nbuilds when pushing tags, you can specify a list of tag regexps.\n\n```yaml\ntags:\n  - ^v\\d+\\.\\d+\\.\\d+$\n```\n\n_Note:_ you can only trigger builds on tags from webhooks, not from the watcher.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeopledoc%2Fpeon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeopledoc%2Fpeon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeopledoc%2Fpeon/lists"}