This document contains instructions for maintaining the code in this repo including the product and its documentation. The marketing website and product docs live in the separate firezone/website repository.

Table of Contents:

• Releasing
• Apple Client
• Breaking API Changes

Note: The version for all published components is set from scripts/bump-versions.sh.

1. Run the Kotlin or Swift workflow from main as appropriate.
2. Android uploads to Firebase App Distribution and Google Play internal testing; Apple uploads to TestFlight.
3. Test the resulting Firebase App Distribution or TestFlight build.
4. Submit the release for review:
   • For Apple, follow the Apple client instructions below.
   • For Android, run the Submit Android release workflow on main, choosing production or Intune (closed testing). Review its prepare summary and the Play Console, then approve the protected google-play environment. Start a new run if the draft changed while approval was pending.

Before the first dispatch, explicitly create the google-play environment with required reviewers, restrict deployments to main, and set its GOOGLE_PLAY_CONFIGURED variable to true. GitHub otherwise creates a referenced environment without protection.

Configure organization access for the Intune closed testing track in Play Console before submitting to it. Both targets also update the shared store screenshots and require manual publication under Managed Publishing.

Given that main is tested:

1. Go to the draft release of the component you want to publish
2. Double-check that the assets attached are from a recent CI and include the correct changes.
3. Publish the release. Tags and release name should be auto generated. This will trigger pushing Docker images to ghcr.io.
4. Publishing the release triggers the Publish release workflow (.github/workflows/publish-release.yml), which opens two version-bump PRs automatically:
   1. In this repo: propagates the new version across the product via scripts/bump-versions.sh.
   2. In firezone/website: converts the component's <Unreleased> changelog section into a dated entry and updates the displayed version markers (src/app/api/releases/route.ts, redirects.js).
5. Review and merge both PRs. Edit the release notes in the website PR's changelog entry if the drafted notes need changes.
6. Update the known issues in firezone/website under src/app/kb/client-apps/* as needed.
7. When the website PR merges and deploys, the site redirects to the new version(s).

This results in a gap where GitHub knows about the release but nobody else does. This is okay because we can undo the GitHub release, and it prevents any queued PRs from landing in the release while you execute this process.

1. Run the Swift workflow from main. It uploads the iOS and macOS builds and updates the GitHub draft.
2. After QA passes, run the Submit Apple release workflow from main, selecting iOS or macOS.
3. When prepare finishes, inspect the selected version through the pending app-store-review deployment link. Cancel the workflow if another build is needed, or approve it to submit that version with manual release. Repeat for the other platform when ready.

The draft must come from a Swift run after this workflow was introduced. Rerun a failed submission job after fixing the error; an already-submitted build is left unchanged. A fresh Swift dispatch generates a new build number.

Required secrets in the main-only app-store GitHub Environment:

• APPLE_APP_STORE_CONNECT_APP_MANAGER_API_KEY_ID (team key)
• APPLE_APP_STORE_CONNECT_APP_MANAGER_API_KEY (raw .p8 contents)

The workflow also uses the repository secret APPLE_APP_STORE_CONNECT_ISSUER_ID.

Do not configure required reviewers on app-store; app-store-review is the approval gate.

The app-store-review GitHub Environment requires reviewers, a main deployment restriction, and APP_STORE_REVIEW_CONFIGURED=true. It has no secrets.

• Log in to the following URL: https://appstoreconnect.apple.com/
• Go to Apps
• Go to Firezone
• Click on TestFlight
  • Note: You can't delete a Version in TestFlight
• There is "internal testing" and "external testing"
  • "internal testing" is only the Firezone team
  • "external testing" is the beta customers
• Click on the testing group you want to release to and on the testing group page:
  • Click the + on the Builds sections
  • Select the build you want to push out
  • Check the Automatically notify testers
  • Type a description of what you want users to see in the notification sent to users (e.g. a small change log of what's in this release)
  • Click Submit for Review
    • Then you have to wait for it to be reviewed (has been a matter of minutes as of late)

(Alternative way to push out a release)

• After login go to Builds (select either ios/macos)
• Find the Version section you want to release and drop down to show list of builds
• Find the build you want to push out, hover over the Groups column and select the + icon
• From here it's the same as the instructions above to type a description, etc...

We should notify customers 2 weeks in advance for any API-breaking changes.