CI Setup Guide

IMDF Validation Gate (#127)

The imdf-validate CI job validates IMDF exports against Apple's IMDF Sandbox and Safe Software's FME IMDFValidator.

Apple IMDF Sandbox Token

1. Request access at https://developer.apple.com/indoor-maps/
2. Obtain your API token from the Apple Developer portal
3. Add as a repository secret: Settings → Secrets → APPLE_IMDF_TOKEN

FME IMDFValidator (Safe Software)

1. Obtain an FME Workbench license from https://www.safe.com/
2. Download the IMDF Workbench template from Safe Software's FME Hub
3. Add your FME license key as: Settings → Secrets → FME_LICENSE_KEY
4. The CI job runs: fme workbench IMDFValidator.fmw --DestDataset <archive>

Local validation

Without CI secrets, validate locally:

# Using the IMDF package validator
pnpm --filter @bloomsparkagency/imdf run test

# Apple IMDF Sandbox (manual)
# Upload your .imdf.zip to https://imdf-sandbox.apple.com

---

📖 Documentation Deployment (Private Cloudflare Pages)

The documentation site is a VitePress application located in apps/docs that builds and compiles content from the monorepo root docs/ folder. Since the library contains proprietary maps SDK code and documentation, we host it securely on Cloudflare Pages and restrict access using Cloudflare Access (Zero Trust).

Continuous Deployment Workflow

The CD pipeline is automated via the .github/workflows/deploy-docs.yml workflow.

• Trigger: Executes automatically on every push to the main branch when changes are detected in:
  • docs/** (documentation markdown files)
  • apps/docs/** (VitePress config and assets)
  • .github/workflows/deploy-docs.yml (the workflow itself)
• Deployment Action: The workflow builds the static site into apps/docs/dist and deploys it to Cloudflare Pages using cloudflare/pages-action@1.

---

Cloudflare Pages Project Creation

Before running the deployment workflow, you must first create a Direct Upload Pages project in your Cloudflare account under the exact name used in the CI workflow:

1. Log in to your Cloudflare Dashboard.
2. On the left sidebar, navigate to Workers & Pages.
3. Click Create (or Create application).
4. Select the Pages tab and click Upload assets (Direct Upload).
5. Set the Project name to exactly bloomspark-map-docs and click Create project.

---

GitHub Repository Configuration

To enable the deployment workflow, ensure the following Repository Secrets are added under Settings > Secrets and variables > Actions:

1. CLOUDFLARE_ACCOUNT_ID: Your Cloudflare Account ID (visible on the Cloudflare Dashboard Home sidebar or Workers & Pages page).
2. CLOUDFLARE_API_TOKEN: A Cloudflare API Token created with Cloudflare Pages: Edit permissions.

---

Restricting Access via Cloudflare Access (Zero Trust)

To keep the documentation private to organization members and collaborators for free (up to 50 users), follow these steps in your Cloudflare account:

1. Enable Cloudflare Zero Trust

1. Log in to the Cloudflare Dashboard.
2. On the left sidebar, click on Zero Trust. If you haven't used it before, select the free plan and complete the initial onboarding.

2. Create an Access Application

1. In the Zero Trust dashboard, navigate to Access > Applications.
2. Click Add an Application and select Self-hosted.
3. Configure the application details:
   • Application name: BloomSpark Maps SDK Docs
   • Session Duration: Choose a session length (e.g., 24 hours or 1 month to avoid frequent logins).
   • Application domain: Enter the domain of your Cloudflare Pages project (e.g., bloomspark-map-docs.pages.dev).

3. Configure the Identity Providers

• Under Identity providers, select the authentication methods you wish to support. By default, One-Time PIN (OTP) is enabled and works perfectly by sending a secure code to the user's email address.
• You can optionally connect other providers such as GitHub, Google, or Okta.

4. Define Access Policies

1. Click Next to proceed to the Policies tab.
2. Create a policy to specify who is allowed to access the site:
   • Policy name: Authorized Team Members
   • Action: Allow
   • Rules (Include):
     • Select Emails to input specific email addresses (e.g., developer@bloomsparkagency.com), OR
     • Select Emails ending in to whitelist an entire domain (e.g., bloomsparkagency.com), OR
     • Select GitHub Organization to limit access to members of your GitHub org.
3. Click Next and then Add Application.

Once complete, visiting your documentation URL will present a secure login page. Only authenticated users meeting your policies will be allowed to view the documentation site.