fastlane-plugin-pharen

Ship an iOS build to Pharen from your Fastfile. One action, pharen_release, runs after build_app: it registers the release, uploads every dSYM for crash symbolication, uploads the build, and returns an OTA install link — with nothing to configure in the lane.

The plugin is a thin wrapper over the pharen CLI. Authentication, .pharen.yml resolution, debug-id parsing, and server-side dedupe all live in the CLI; the plugin only derives what the CLI needs from the lane context and the built artifacts. It adds no runtime gem dependencies of its own.

Install

fastlane add_plugin pharen

Once per repository, you also need:

the pharen CLI on PATH (or point pharen_binary: / PHAREN_BINARY at it),
a committed .pharen.yml at the repo root (org: and app: — no secrets),
PHAREN_AUTH_TOKEN in the environment (your one secret — see Configuration).

Quickstart

lane :beta do
  build_app(scheme: "MyApp")
  pharen_release
end

pharen_release derives everything else: the IPA and dSYMs from the lane context; the version, build number, and bundle id from the IPA's own Info.plist; the commit sha from git. It registers the release, uploads every dSYM the archive produced, uploads the build, prints the OTA install link, and returns it (also available in lane_context[SharedValues::PHAREN_INSTALL_URL]).

Actions

`pharen_release`

The whole integration in one call after build_app.

Option	Env	Default	Description
`ipa`	`PHAREN_IPA`	lane context (`IPA_OUTPUT_PATH`)	Path to the `.ipa`.
`dsym_paths`	`PHAREN_DSYM_PATHS`	lane context (`DSYM_OUTPUT_PATH` + `DSYM_PATHS`)	dSYM bundles or `.zip`s to upload.
`pharen_binary`	`PHAREN_BINARY`	`pharen`	Command that invokes the CLI (may include arguments, e.g. `node /path/to/cli.js`).
`strict`	`PHAREN_STRICT`	`false`	Fail the lane on any step's error instead of warning and continuing.

Returns the install link on success, or nil when a step is skipped or fails outside strict mode.

`pharen_upload_build`

Upload the IPA and get the install link back, standalone.

pharen_upload_build            # IPA from the lane context → install link

Option	Env	Default	Description
`ipa`	`PHAREN_IPA`	lane context (`IPA_OUTPUT_PATH`)	Path to the `.ipa`.
`pharen_binary`	`PHAREN_BINARY`	`pharen`	Command that invokes the CLI.
`strict`	`PHAREN_STRICT`	`false`	Fail the lane on error instead of warning and continuing.

`pharen_upload_symbols`

Upload dSYMs for crash symbolication, standalone.

pharen_upload_symbols                                    # dSYMs from the lane context
pharen_upload_symbols(dsym_paths: ["path/to/App.dSYM"])  # or explicit

Option	Env	Default	Description
`dsym_paths`	`PHAREN_DSYM_PATHS`	lane context (`DSYM_OUTPUT_PATH` + `DSYM_PATHS`)	`.dSYM` bundles, dSYM `.zip`s (as produced by `gym`/`download_dsyms`), or raw DWARF binaries.
`pharen_binary`	`PHAREN_BINARY`	`pharen`	Command that invokes the CLI.
`strict`	`PHAREN_STRICT`	`false`	Fail the lane on error instead of warning and continuing.

Configuration

Two things live outside the lane, and only one of them is a secret:

.pharen.yml — committed at the repo root, holding org: and app:. No secrets belong in it. The CLI walks up from its working directory to find it, so it resolves whether fastlane runs from the repo root or the fastlane/ directory.
PHAREN_AUTH_TOKEN — your one secret, read from the environment (a CI secret in practice). Only the CLI reads it, and only from the environment. The plugin never reads, prints, or passes the token, so it never lands in a log line or a process argument list.

Failure posture

The default is warn-don't-fail: if a step errors, the plugin logs a loud warning and lets the build continue. A telemetry step should never be the reason a release build fails.

Pass strict: true (or set PHAREN_STRICT=1) in CI lanes where an unsymbolicated or undistributed release must be a hard stop; then any step's error fails the lane.

Two things hold regardless of mode:

Missing dSYMs always warn loudly. A build shipped without its symbols produces crashes that can never be read, and uploading symbols later does not retroactively symbolicate the crashes it already caused. Archive with DEBUG_INFORMATION_FORMAT=dwarf-with-dsym so the dSYMs exist to upload.
Re-runs are safe. The server dedupes symbols by debug id, and the CLI exits 0 when every file is already uploaded — so retrying a lane never double-uploads or errors on work already done.

Troubleshooting

pharen not found. The CLI isn't on PATH. Install it and make pharen resolvable, or point pharen_binary: / PHAREN_BINARY at it (it may include arguments, e.g. node /path/to/cli.js).
"no IPA" or "no dSYMs in the lane context". Run the action after build_app/gym (and download_dsyms, if you fetch symbols from App Store Connect), or pass ipa: / dsym_paths: explicitly.
Release registration warns but the build still uploads. Expected in warn mode: registration records provenance, so a failed registration degrades metadata without stopping distribution. Use strict: true if you need it to stop the lane.
Not using fastlane? The pharen CLI runs the same three steps directly. See the documentation at https://pharen.ai/docs.

License

MIT — see LICENSE.