{"id":20475157,"url":"https://github.com/plicity/plicity","last_synced_at":"2026-05-05T03:38:28.627Z","repository":{"id":57137279,"uuid":"249738451","full_name":"plicity/plicity","owner":"plicity","description":null,"archived":false,"fork":false,"pushed_at":"2020-03-29T14:29:07.000Z","size":380,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-23T23:46:52.538Z","etag":null,"topics":["build","cloud","gitlab","openshift","openshift-operator"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plicity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-24T15:01:15.000Z","updated_at":"2021-09-30T06:13:20.000Z","dependencies_parsed_at":"2022-09-01T03:01:21.862Z","dependency_job_id":null,"html_url":"https://github.com/plicity/plicity","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plicity%2Fplicity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plicity%2Fplicity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plicity%2Fplicity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plicity%2Fplicity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plicity","download_url":"https://codeload.github.com/plicity/plicity/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242041967,"owners_count":20062318,"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":["build","cloud","gitlab","openshift","openshift-operator"],"created_at":"2024-11-15T15:14:50.540Z","updated_at":"2026-05-05T03:38:23.603Z","avatar_url":"https://github.com/plicity.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PLICITY 🏗\n\nAn Open Source Node.js Cloud-Operator for Development supported by [consol](https://www.consol.de) with 💛.\n\nThis project is \"work in progress\" 🚧. Many features are still missing. Same for security. ⚠ Don't use this version in production.\n\n![plicity logo](./doc/plicity-logo.svg)\n\n## 🤔 What is it?\n\nYou and your team 👥\n\n- ✔ is developing a web application in the ☁ cloud?\n- ✔ use branches for parallel 🔃 feature development?\n\n... great, maybe PLICITY can help you! 👨‍⚕️\n\nThe idea is very simple 💡\n\n- 🔍 PLICITY will watch your Git repository\n- 🔧 every time a branch is created, it will trigger a hook\n- 🚮 same for deleting or updating a branch\n\nA simple idea needs simple implementation ✌:\n\n- 📃 the operator is Node.js script in your project\n- 🕶 it will start everything and implement the hooks\n- 👌 hooks are simple JS callbacks\n\n```javascript\noperator.start({\n  onCreateBranch:     setup,      // a new git branch is created\n  onChangeBranchHead: startBuild, // push to a branch\n  onDeleteBranch:     deleteAll,  // delete a remote branch\n  onServerBuild:      startBuild  // press \"Build\" in the Operator UI\n});\n```\n\n**onCreateBranch**\n\nWhen a new git branch is created, we could `oc process -f ...yml | oc apply -f -` a template which will deploy everything needed for the application? It should create an `ImageStream`, `BuildConfig`, ..., maybe also a new isolated Database and of course a `Route` because we want to access it.\n\n```javascript\nasync function setup(event) {\n  await oc.project(event.args.openshiftProject);\n  await oc.applyTemplate(`${__dirname}/setup.yml`, {\n    GITLAB_REPOSITORY_URL: event.gitlabRepositoryUrl, // needed for BuildConfig\n    BRANCH_NAME_NORMALIZED: event.branchNormalized,   // needed for BuildConfig\n    NAME: event.args.name // used as prefix for all resource names and labels\n  });\n}\n```\n\n**onChangeBranchHead, onServerBuild**\n\nWhen a branch has a new commit or someone presses \"Build\" in the Operator UI, we simply want to start the build.\n\n```javascript\nasync function startBuild(event) {\n  await oc.project(event.args.openshiftProject);\n  await oc.startBuild(`${event.args.name}-${event.branchNormalized}`, {commit: event.commit});\n}\n```\n\n**onDeleteBranch**\n\nWhen a branch is deleted, we want to delete everything we set up in `setup`. We use labels, that we can delete everything with one command.\n\n```javascript\nasync function deleteAll(event) {\n  await oc.project(event.args.openshiftProject);\n  await oc.deleteAll(`app.plicity.io/branch=${event.args.name}-${event.branchNormalized}`);\n}\n```\n\n**Conclusion**\n\nOf course you're free to do more in the hooks, like running smoke 🚬 or ⚙ integration tests or create 📫 notifications on your Slack channel.\n\nYou run the operator. You implement the hooks. Everything is under your control. Create your very best build pipeline for development. PLICITY will ♥ to support you and your team with 🚀 development, 🧪 testing and finally ⛵ ship faster.\n\nNow give it a try and please give feedback 😬.\n\n## Install\n\n*Before using it, please also check Security section.*\n\nThe target folder has to exist and should be empty.\n\n### 1. Initialize your project\n```bash\nnpm init @plicity \u003ctarget dir\u003e\n```\n\n### 2. Commit plicity to your repository\n```bash\ngit add -A\ngit commit -m 'add plicity'\ngit push\n```\n\n### 3. Update .env file\n\nGo into your target directory and open `/plicity/.env`.\n\n#### 3.1 Openshift Configuration\n\nYou can get url and token by copying your login command\n\n![openshift copy login command](./doc/openshift-login.png)\n\nIt should look like this:\n\n`oc login https://openshift.mycompany.org:8443 --token=abcdefghijklmnopqrstuvwxyz0123456789`\n\nUse an openshift project which is already created for your app.\n\n```bash\nPLICITY_OPENSHIFT_URL=https://openshift.mycompany.org:8443\nPLICITY_OPENSHIFT_TOKEN=abcdefghijklmnopqrstuvwxyz0123456789\nPLICITY_OPENSHIFT_PROJECT=plicity-test\n```\n\n#### 3.2 Gitlab Configuration\n\n*Note: Gitlab project needs to be public. Also see Security section.*\n\n##### 3.2.1 `PLICITY_GITLAB_HOST`\n\nJust the Gitlab host. Not the URL to the repository.\n\n```bash\nPLICITY_GITLAB_HOST=https://gitlab.mycompany.org\n```\n\n##### 3.2.2 `PLICITY_GITLAB_PROJECT_ID`\n\nGo to your Gitlab Project and copy the `Project ID`.\n\n![gitlab project id](./doc/gitlab-project-id.png)\n\n```bash\nPLICITY_GITLAB_PROJECT_ID=1147\n```\n\n##### 3.2.3 `PLICITY_GITLAB_TOKEN`\n\nGo to `Settings`.\n\n![gitlab settings](./doc/gitlab-settings.png)\n\nGo to `Access Tokens`.\n\n![gitlab access token](./doc/gitlab-access-token.png)\n\nCreate Access Token.\n\n![gitlab create access token](./doc/gitlab-create-access-token.png)\n\n```bash\nPLICITY_GITLAB_TOKEN=abcdefghijklmnop\n```\n\n#### 3.3 Further PLICITY configuration\n\n##### 3.3.1 `PLICITY_NAME`\n\nName of the Operator and used as prefix `$name-...` for all OpenShift resources. It has to only contain valid characters or it will crash.\n\n```bash\nPLICITY_NAME=pli\n```\n\n##### 3.3.1 `PLICITY_LOG_LEVEL`\n\n*Just for local development of your Operator.*\n\nValid log level according to [pino](https://github.com/pinojs/pino) logger. In OpenShift it will run `info`.\n\n```bash\nPLICITY_LOG_LEVEL=debug\n```\n\n##### 3.3.1 `PLICITY_LOG_PRETTY`\n\n*Just for local development of your Operator.*\n\nLog output has json format. Make it human-readable setting this to `true`. In OpenShift it will output json.\n\n```bash\nPLICITY_LOG_PRETTY=true\n```\n\n### Example\n\n```bash\nmkdir demo-app\nnpm init @plicity demo-app\n# npx: installed 123 in 9.758s\n# ✔ copied 10 files to demo-app\n# ✔ install dependencies\n# ✔ add scripts - write demo-app/plicity/package.json\n# ℹ 1. please commit and push\n# ℹ 2. update demo-app/plicity/.env\n# ℹ 3. initialize openshift: `cd demo-app/plicity; npm run init`.\n\ncd demo-app/plicity\ncat .env\n# PLICITY_OPENSHIFT_URL=https://openshift.mycompany.org:8443\n# PLICITY_OPENSHIFT_TOKEN=abcdefghijklmnopqrstuvwxyz0123456789\n# PLICITY_OPENSHIFT_PROJECT=plicity-test\n# \n# PLICITY_GITLAB_HOST=https://gitlab.mycompany.org\n# PLICITY_GITLAB_TOKEN=abcdefghijklmnop\n# PLICITY_GITLAB_PROJECT_ID=1147\n# \n# PLICITY_NAME=pli\n# PLICITY_LOG_LEVEL=debug\n# PLICITY_LOG_PRETTY=true\n\nnpm run init\n# \u003e plicity@1.0.0 init demo-app/plicity\n# \u003e plicity init\n# \n# INFO  (…openshift/oc.js): using KUBECONFIG /tmp/.kube/config\n```\n\nCheck OpenShift to see Operator build.\n\n![openshift operator build](./doc/openshift-operator-build.png)\n\nWhen Operator POD is up and running all branches will be deployed.\n\n![openshift operator build](./doc/openshift-master-build.png)\n\n\n### Advanced Settings\n\nIf you want to use your own registry:\n\n```bash\nnpm init @plicity \u003ctarget dir\u003e \\\n  --npm-registry=http://registry.mycompany.org \\\n  --npm-strict-ssl=false\n```\n\n## Security\n\nGood things first 😬:\n\n- 100% On-Premise in your Private or Public Cloud.\n- No OpenShift cluster admin rights needed.\n- Your OpenShift token **is not** exposed. The Operator will run with a special `ServiceAccount` with a `RoleBinding` allowed to control your project. Your token is just used for the initial setup or if you want to run the Operator local, e.g. updating it.\n\nNeed of improvement 🤐:\n\n- Gitlab project needs to be public. Yet no authentication implemented.\n- We give full Gitlab access to the Operator. Assumption is that the only API call we need at current is to add and remove the badge to the Gitlab project. This may change when implementing authentication for OpenShift for Gitlab.\n- Your Gitlab Token is exposed as OpenShift secret. Everyone with access to your project can use that Gitlab token.\n\nGrey zone 🤫:\n\n- download OpenShift client `oc` from https://github.com/openshift/origin/releases/download/v3.11.0/openshift-origin-client-tools-v3.11.0-0cbc58b-linux-64bit.tar.gz. Customizable alternative location to be implemented.\n\n## Contribution\n\n *alphabetical order*\n\n- Renoth, Philipp: core dev ([Twitter](https://twitter.com/daaitch), [GitHub](https://github.com/DaAitch))\n- Tillian, Valeska: logo design ([Xing](https://www.xing.com/profile/Valeska_Tillian))\n\n## Known Issues\n\n- Will not work on Windows and probably not on MacOS\n- Only OpenShift compatible with oc v3.11.0 and Gitlab supported\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplicity%2Fplicity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplicity%2Fplicity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplicity%2Fplicity/lists"}