Release tracking and likely commits

Attach an exact build ID to each distributed app so NativeWatch can investigate errors against the code you shipped. Publishing PHP source evidence lets an issue suggest commits that changed its reported locations between releases.

#Prepare the project and CI

Save the project's GitHub owner/repository and create a CI token in project settings. Store the token as NATIVEWATCH_RELEASE_TOKEN in your CI secret store. It is separate from the ingest key used by the app.

Give the publishing step a clean checkout with complete Git history and SDK dependencies installed. In GitHub Actions, configure checkout with fetch-depth: 0. Choose the full 40-character SHA of the previous shipped build, rather than a branch name that can move.

Only the publishing step should receive the CI token. Never put it in your app's bundled .env, SDK configuration, mobile resources or release artifact. Use NATIVEWATCH_URL=https://native.watch for the destination.

#Publish from the exact checkout

Set PREVIOUS_SHIPPED_SHA in CI to the previous release's full commit SHA and replace the repository and version below:

php artisan nativewatch:release 1.4.0 \
  --repository=your-company/your-app \
  --previous="$PREVIOUS_SHIPPED_SHA"

On success, the command confirms a build ID shaped as 1.4.0@FULL_CURRENT_COMMIT_SHA. Bundle that exact value as NATIVEWATCH_RELEASE in the app built from this checkout. Two builds with the same version and different SHAs remain distinct.

You can calculate the ID without a token or network request:

php artisan nativewatch:release 1.4.0 --id-only

For a monorepo, pass --path=/checkout/apps/mobile to both commands, replacing the example path with the Laravel app's actual location. The manifest records its source root so app-relative stack paths can match repository paths.

For the first baseline, use the current full SHA as --previous. Its empty change set deliberately produces no likely commit. Subsequent releases should compare against the previously shipped SHA.

#Understand what the suggestion means

NativeWatch matches reported PHP paths and positive line numbers against changed-line evidence from the exact build. The issue page uses its latest occurrence's build ID. It does not substitute the current repository head.

A likely commit is a starting point for investigation, not proof of cause. Candidates rank by distinct matching reported locations, and at most three appear. Compiled Blade line numbers, JavaScript bundles and native addresses are not attributed by this PHP release feature. Use iOS symbolication for native source locations.

CI sends build and previous SHAs, repository/source-root identity, commit SHAs, file paths and changed-line ranges. It does not send source text, commit messages or author names and emails. The evidence is derived from Git's incremental blame format.

#Handle publication failures

A dirty or shallow checkout, missing history or a previous SHA that is not an ancestor stops publication. Resolve the checkout problem and retry from the same exact build. Oversized evidence is rejected rather than silently truncated.

Publication is immutable per project and build ID. Identical retries are safe; conflicting evidence returns HTTP 409. Do not reuse a build ID for different source. If a manifest arrives after an occurrence, reload the issue to resolve its commit evidence.

If no candidate appears, compare the occurrence's full release value with the published ID, confirm the PHP source path and line, and check that the location changed since the previous shipped build. An unchanged line or absent manifest can legitimately produce no suggestion. Keep error context and release verification together when investigating.