Skip to main content

Creating New Environments

This guide walks through creating a new development environment (like development3) for the Pivot Mobile app. This is useful when you need another isolated testing environment for a large feature.

Overview​

Creating a new environment requires changes in several places:

Step 1: Apple Developer Portal​

Create App ID (Bundle ID)​

  1. Go to Apple Developer Portal
  2. Click Identifiers > + (Add)
  3. Select App IDs > Continue
  4. Select App > Continue
  5. Fill in:
    • Description: Pivot Dev 3 (or your environment name)
    • Bundle ID: jobs.pivot.dev3
  6. Enable required Capabilities:
    • Push Notifications
    • Sign in with Apple
    • Associated Domains (if using deep links)
  7. Click Register
tip

Use the same Firebase project as development and development2 (pivot-dev-59310) to keep things simple.

Step 2: App Store Connect​

Create App Entry​

  1. Go to App Store Connect
  2. Click My Apps > + > New App
  3. Fill in:
    • Platform: iOS
    • Name: Pivot Dev 3
    • Primary Language: English (Canada)
    • Bundle ID: Select jobs.pivot.dev3
    • SKU: pivot-dev3
  4. Click Create

This creates the TestFlight destination for your builds.

Step 3: Xcode Configuration​

Add Build Configurations​

You need to add two new configurations: Dev3.debug and Dev3.release.

Using Xcode UI​

  1. Open ios/pivot3.xcworkspace in Xcode
  2. Select the project (not a target) in the navigator
  3. Go to Info tab
  4. Under Configurations, click +
  5. Select Duplicate "Dev.debug" Configuration
  6. Name it Dev3.debug
  7. Repeat for Dev3.release (duplicate from Dev.release)

Update Build Settings​

For both pivot3 target and pivot3Tests target:

  1. Select the target
  2. Go to Build Settings
  3. Search for Product Bundle Identifier
  4. Set for Dev3.debug and Dev3.release: jobs.pivot.dev3
  5. Search for Provisioning Profile
  6. Set for Dev3.release: match AdHoc jobs.pivot.dev3

Create Xcode Scheme​

  1. In Xcode, go to Product > Scheme > Manage Schemes
  2. Select dev.pivot3 and click Duplicate
  3. Rename to dev3.pivot3
  4. Edit the scheme:
    • Build Configuration: Dev3.debug for Run, Dev3.release for Archive
  5. Mark as Shared (checkbox on the right)

This creates the scheme file at:

ios/pivot3.xcodeproj/xcshareddata/xcschemes/dev3.pivot3.xcscheme

Step 4: Provisioning Profile​

Generate Profile with Fastlane Match​

cd /path/to/pivot-mobile

bundle exec fastlane match adhoc \
  --app_identifier jobs.pivot.dev3 \
  --git_url git@github.com:pivotteam/pivot-mob-cert.git

This will:

  1. Create a new AdHoc provisioning profile
  2. Store it in the pivot-mob-cert repository
  3. Install it on your machine
note

If the profile already exists and needs capabilities updated, add --force:

bundle exec fastlane match adhoc --app_identifier jobs.pivot.dev3 --force

Step 5: Fastlane Lane​

Add Lane to Fastfile​

Edit fastlane/Fastfile and add a new lane:

lane :dev3 do
  app_store_connect_api_key(
    key_id: 'G29C8F9P69',
    issuer_id: '69a6de95-eb63-47e3-e053-5b8c7c11a4d1',
    key_filepath: './fastlane/qa_auth_key.p8'
  )

  latest_testflight = latest_testflight_build_number(
    app_identifier: "jobs.pivot.dev3",
    initial_build_number: 1
  )

  current_build = get_build_number(xcodeproj: "./ios/pivot3.xcodeproj")
  new_build_number = [latest_testflight.to_i, current_build.to_i].max + 1

  increment_build_number(
    build_number: new_build_number,
    xcodeproj: "./ios/pivot3.xcodeproj"
  )

  set_info_plist_value(
    path: "./ios/pivot3/Info.plist",
    key: "CurrentEnvironment",
    value: "dev3"
  )

  match(
    type: "adhoc",
    app_identifier: "jobs.pivot.dev3",
    git_url: "git@github.com:pivotteam/pivot-mob-cert.git",
    readonly: true
  )

  copy_files(
    source: "./ios/firebase/GoogleService-Info-development.plist",
    destination: "./ios/pivot3/GoogleService-Info.plist"
  )

  build_app(
    scheme: "dev3.pivot3",
    configuration: "Dev3.release",
    export_method: "ad-hoc",
    workspace: "./ios/pivot3.xcworkspace",
    output_directory: "./build",
    output_name: "pivot3-dev3.ipa"
  )

  pilot(
    app_identifier: "jobs.pivot.dev3",
    skip_waiting_for_build_processing: true,
    distribute_external: false
  )
end

Step 6: GitHub Actions Workflow​

Create Workflow File​

Create .github/workflows/ios-dev3-build.yml:

name: iOS Dev3 Build

on:
  push:
    branches: [development3]
  workflow_dispatch:

jobs:
  build:
    uses: ./.github/workflows/ios-build.yml
    with:
      environment: "Dev3"
      fastlane_lane: "dev3"
    secrets: inherit

Create the Branch​

git checkout development
git checkout -b development3
git push -u origin development3

Step 7: Update Helper Script​

Update switch-scheme.sh​

Add the new scheme to switch-scheme.sh:

case $SCHEME in
    dev)
        SCHEME_NAME="dev.pivot3"
        ;;
    dev2)
        SCHEME_NAME="dev2.pivot3"
        ;;
    dev3)                          # Add this
        SCHEME_NAME="dev3.pivot3"
        ;;
    qa)
        SCHEME_NAME="qa.pivot3"
        ;;
    prod)
        SCHEME_NAME="pivot3"
        ;;
esac

Verification Checklist​

After completing all steps, verify:

  • Apple Developer Portal

    • App ID exists with correct capabilities
    • Capabilities enabled: Push, Sign in with Apple

  • App Store Connect

    • App entry created
    • Can view app in TestFlight section

  • Xcode

    • Dev3.debug and Dev3.release configurations exist
    • dev3.pivot3 scheme exists and is shared
    • Bundle ID set to jobs.pivot.dev3

  • Fastlane

    • Provisioning profile generated
    • Lane added to Fastfile

  • GitHub

    • Workflow file created
    • Branch exists

Testing the Setup​

Test Locally​

# Switch to the new scheme
./switch-scheme.sh dev3

# Build in Xcode
# Product > Build

Test CI/CD​

# Push to trigger workflow
git checkout development3
echo "test" >> README.md
git add README.md
git commit -m "Test dev3 build"
git push origin development3

Monitor the build at: https://github.com/pivotteam/Pivotmobile/actions

Summary of Files Changed​

File/LocationChange
Apple Developer PortalNew App ID
App Store ConnectNew App
ios/pivot3.xcodeproj/project.pbxprojNew configurations
ios/pivot3.xcodeproj/xcshareddata/xcschemes/dev3.pivot3.xcschemeNew scheme
fastlane/FastfileNew lane
.github/workflows/ios-dev3-build.ymlNew workflow
switch-scheme.shNew case
pivot-mob-cert repoNew provisioning profile