{"id":22206974,"url":"https://github.com/fkirc/capacitor-build-safety","last_synced_at":"2025-03-25T03:54:49.822Z","repository":{"id":47808073,"uuid":"293605613","full_name":"fkirc/capacitor-build-safety","owner":"fkirc","description":"Make app releases safer. Reduce thinking with automated checks.","archived":false,"fork":false,"pushed_at":"2023-10-30T22:58:34.000Z","size":612,"stargazers_count":1,"open_issues_count":11,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-22T19:43:58.921Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/fkirc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-09-07T18:40:23.000Z","updated_at":"2023-10-30T22:49:33.000Z","dependencies_parsed_at":"2024-12-15T12:33:36.619Z","dependency_job_id":"c05f4f6f-39d7-4895-acdc-1e644ec35a6b","html_url":"https://github.com/fkirc/capacitor-build-safety","commit_stats":{"total_commits":134,"total_committers":4,"mean_commits":33.5,"dds":"0.35074626865671643","last_synced_commit":"15912a2ec5802cae38f58a09e6e210bbc9872c0f"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkirc%2Fcapacitor-build-safety","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkirc%2Fcapacitor-build-safety/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkirc%2Fcapacitor-build-safety/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fkirc%2Fcapacitor-build-safety/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fkirc","download_url":"https://codeload.github.com/fkirc/capacitor-build-safety/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245394770,"owners_count":20608123,"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":[],"created_at":"2024-12-02T18:43:47.959Z","updated_at":"2025-03-25T03:54:49.803Z","avatar_url":"https://github.com/fkirc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# capsafe - Make Builds Traceable And Safer\n\nIf a tester cannot immediately see from which commit and which branch a given build originates, then this lack of certainty can cause a huge waste of time.\nMoreover, there are industries that require each deployment to be _end-to-end traceable_.\nTo be _end-to-end traceable_, we want a bombproof trace all the way from an app or web-server back to the specific Git-commit that was used to build it.\n\nTo do so, `capsafe` adds a file `commit-evidence.json` to all your builds.\n\n\u003ca href=\"https://github.com/fkirc/capacitor-build-safety/actions?query=branch%3Amaster\"\u003e\u003cimg alt=\"CI status\" src=\"https://github.com/fkirc/capacitor-build-safety/workflows/CI/badge.svg/?branch=master\"\u003e\u003c/a\u003e\n\n`capsafe` was written with [Capacitor](https://capacitorjs.com/) in mind, although you do not need to use Capacitor.\nCapacitor is a great tool for cross-platform app development (iOS/Android/Web).\nHowever, Capacitor builds are prone to mistakes.\nIn particular, the following mistakes can lead to broken app releases or wasted developer time:\n\n- Forgetting to build/sync a web-build for the most recent commit (leads to outdated or broken apps).\n- Wrong Capacitor configs (leads to broken apps, see this [issue](https://github.com/ionic-team/capacitor/discussions/1478) for details).\n\n`capsafe` helps to prevent those mistakes.\nFor example, `capsafe` prevents broken Android releases with the following message, if a developer forgot to sync Capacitor for the most recent commit:\n\n`error: Current commit 25a7a56bca71 does not match with commit 8c8476eb77f6 in 'android/app/src/main/assets/public/commit-evidence.json': Run 'capsafe disable' to disable this check temporarily (if you know what you are doing)`\n\nSimilarly, `capsafe` prevents broken iOS-builds if a developer forgot to do a web-build:\n\n`error: 'ios/App/public/commit-evidence.json' does not exist: Run 'capsafe disable' to disable this check temporarily (if you know what you are doing)`\n\nBeside of native apps, `capsafe` is also usable for browser-based tests that run against web-builds.\n`capsafe` ensures that browser-based tests are always running against the latest commit.\n\n## How it works\n\n`capsafe` provides three commands to prevent broken apps: `create-commit-evidence`, `verify-commit-evidence`, `validate-capacitor-config`.\nTypically, those commands run in the following steps:\n\n- After each web-build, `create-commit-evidence` creates a file `commit-evidence.json` in your web-build folder. `commit-evidence.json` contains information about the current HEAD-commit (the tree hash and the commit hash).\n- Naturally, Capacitor-commands like `cap sync` copy `commit-evidence.json` to native asset directories, along with all other web-assets.\n- Later on, during each native app build, `verify-commit-evidence` verifies that the current HEAD-commit still matches with `commit-evidence.json` in the respective native asset directory.\n- `validate-capacitor-config` runs before each app release or in a continuous integration pipeline.\n\n## Disable checks temporarily\n\nFor pure native development, the checks of `capsafe` might be annoying.\nIn this case, you can quickly disable `capsafe` by running:\n\n`npx capsafe disable`\n\nThis will disable safety checks until you switch the current branch, or until you delete `capsafe.disable.json`.\nTo remain safe, you should add `capsafe.disable.json` to your `.gitignore`.\n\n## Integration Manual\n\nFirstly, install `capsafe` via npm:\n\n`npm install --save-dev capacitor-build-safety`\n\nNext, extend your build scripts for Web/Android/iOS, depending on your setup.\n\n### Extend Web build scripts\n\nEnsure that `create-commit-evidence` is invoked after each web build.\nFor example, your `package.json` might contain a build script like this:\n\n```\n\"scripts\": {\n  \"build: \"node scripts/build.js\"\n}\n```\n\nIn this case, you can extend the build script with a simple `\u0026\u0026`-chaining:\n\n```\n\"scripts\": {\n  \"build: \"node scripts/build.js \u0026\u0026 npx capsafe create-commit-evidence build\"\n}\n```\n\n### Extend Android build scripts\n\nTo enforce that `verify-commit-evidence` succeeds before every Android build, add the following to your app-module's `build.gradle`:\n\n```Groovy\nafterEvaluate {\n    preBuild.dependsOn(verifyCommitEvidence)  // Each build must use the most recent commit.\n    preProductionReleaseBuild.dependsOn(verifyCommitEvidence, validateCapacitorConfig) // Capacitor config must be only validated for production builds.\n}\ntask verifyCommitEvidence(type: Exec) {\n    commandLine 'npx', 'capsafe', 'verify-commit-evidence', 'src/main/assets/public'\n}\ntask validateCapacitorConfig(type: Exec) {\n    commandLine 'npx', 'capsafe', 'validate-capacitor-config', 'src/main/assets/capacitor.config.json'\n}\n```\n\n### Extend iOS build scripts\n\nYou can use Xcode to enforce that `verify-commit-evidence` succeeds before every iOS build.\nTo do so, navigate to your app target's `Build Phases` and add a new `Run Script Phase`.\nPaste the following snippet into the `Run Script Phase`:\n\n`npx capsafe verify-commit-evidence public/`\n\nTo run as fast as possible, place the `Run Script Phase` before all other `Build Phases`.\nOnce this is done, Xcode should generate something like this in your app's `project.pbxproj`:\n\n```\nB8DF42F32508BDBC00B0603F /* Run Script */ = {\n    isa = PBXShellScriptBuildPhase;\n    buildActionMask = 2147483647;\n    files = (\n    );\n    inputFileListPaths = (\n    );\n    inputPaths = (\n    );\n    name = \"Run Script\";\n    outputFileListPaths = (\n    );\n    outputPaths = (\n    );\n    runOnlyForDeploymentPostprocessing = 0;\n    shellPath = /bin/sh;\n    shellScript = \"npx capsafe verify-commit-evidence public/\";\n    showEnvVarsInLog = 0;\n};\n```\n\n### Extend Web tests\n\nIf you have tests that run against a web-build (without live reload), then you might extend your web tests like so:\n\n```\nnpx capsafe verify-commit-evidence build \u0026\u0026 my_web_testing_tool\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffkirc%2Fcapacitor-build-safety","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffkirc%2Fcapacitor-build-safety","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffkirc%2Fcapacitor-build-safety/lists"}