CI/CD Integration

FlowDeck CLI is designed to work seamlessly in CI/CD environments like GitHub Actions, GitLab CI, CircleCI, Bitrise, and other automation platforms.

License Configuration

In CI environments, FlowDeck validates your license through an environment variable instead of machine activation. This approach:

Does not consume activation slots
Works across ephemeral CI runners
Requires no persistent storage

Using your license as an environment variable does not count against your activation limit, but this functionality is restricted to CI/CD environments only. For local development, you must activate the license using flowdeck license activate <key>.

Setting the License Key

Set the FLOWDECK_LICENSE_KEY environment variable in your CI configuration:

env:
  FLOWDECK_LICENSE_KEY: ${{ secrets.FLOWDECK_LICENSE_KEY }}

variables:
  FLOWDECK_LICENSE_KEY: $FLOWDECK_LICENSE_KEY

environment:
  FLOWDECK_LICENSE_KEY: $FLOWDECK_LICENSE_KEY

envs:
  - FLOWDECK_LICENSE_KEY: $FLOWDECK_LICENSE_KEY

Store your license key as a secret in your CI platform. Never commit license keys to version control.

Supported CI Platforms

FlowDeck automatically detects these CI environments:

Platform	Detection Variable
GitHub Actions	`GITHUB_ACTIONS`
GitLab CI	`GITLAB_CI`
CircleCI	`CIRCLECI`
Jenkins	`JENKINS_URL`
Travis CI	`TRAVIS`
Bitrise	`BITRISE_IO`
Buildkite	`BUILDKITE`
TeamCity	`TEAMCITY_VERSION`
Azure Pipelines	`TF_BUILD`
AWS CodeBuild	`CODEBUILD_BUILD_ID`
Xcode Cloud	`XCODE_CLOUD`
Codemagic	`CODEMAGIC`
Appcircle	`APPCIRCLE`
Bitbucket Pipelines	`BITBUCKET_BUILD_NUMBER`
Semaphore CI	`SEMAPHORE`
Drone CI	`DRONE`
AppVeyor	`APPVEYOR`

For other CI systems, set CI=true along with your license key.

Installing FlowDeck in CI

Using the Install Script

curl -fsSL https://flowdeck.studio/install.sh | bash

GitHub Actions Example

name: Build and Test

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: macos-14

    env:
      FLOWDECK_LICENSE_KEY: ${{ secrets.FLOWDECK_LICENSE_KEY }}

    steps:
      - uses: actions/checkout@v4

      - name: Install FlowDeck
        run: |
          curl -fsSL https://flowdeck.studio/install.sh | bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Initialize FlowDeck
        run: |
          flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"

      - name: Build
        run: flowdeck build --verbose

      - name: Test
        run: flowdeck test --streaming

Alternative: Using Config Files

      - name: Build
        run: flowdeck build --config .flowdeck/ci-config.json --streaming

      - name: Test
        run: flowdeck test --config .flowdeck/ci-config.json --streaming

Configuration File

For reproducible CI builds, use a configuration file instead of command-line arguments:

Create a Config File

Create .flowdeck/ci-config.json in your repository:

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "configuration": "Release",
  "platform": "iOS",
  "version": "18.0",
  "xcodebuild": {
    "args": ["-enableCodeCoverage", "YES"],
    "env": {
      "CI": "true"
    }
  }
}

Use in CI

flowdeck build -c .flowdeck/ci-config.json --json
flowdeck test -c .flowdeck/ci-config.json --json

These CI examples use the explicit --config file format for one complete command invocation. That format is separate from the project settings files at .flowdeck/config.json and .flowdeck/config.local.json.

Config File Reference

Field	Type	Required	Description
`workspace`	string	Yes	Path to `.xcworkspace` or `.xcodeproj`
`scheme`	string	Yes	Scheme name to build
`configuration`	string	No	Build configuration (`Debug`/`Release`). Default: `Debug`
`platform`	string	No	Target platform: `iOS`, `macOS`, `watchOS`, `tvOS`, `visionOS`
`version`	string	No	OS version (e.g., `18.0`). Uses latest if not specified
`simulatorUdid`	string	No	Specific simulator UDID
`derivedDataPath`	string	No	Custom derived data path (default: `~/Library/Developer/FlowDeck/DerivedData`)
`xcodebuild`	object	No	Passthrough settings for xcodebuild
`xcodebuild.args`	array	No	Arguments appended to xcodebuild
`xcodebuild.env`	object	No	Environment variables for xcodebuild

See Xcodebuild Arguments for complete passthrough options and Configuration File for all config fields.

Output Modes

JSON (Default for CI)

Use --json for machine-readable output:

flowdeck build --config .flowdeck/ci-config.json --json

This outputs NDJSON (newline-delimited JSON) events that can be parsed by CI tools:

{"type":"app_log","level":"info","message":"Build Started"}
{"type":"app_log","level":"info","message":"Resolving Packages"}
{"type":"app_log","level":"info","message":"Building"}
{"type":"result","operation":"build","success":true}

Streaming (Human-Readable)

Use --streaming for clean, human-readable output in CI logs. This shows individual pass/fail results grouped by test class, with a summary at the end:

flowdeck build --config .flowdeck/ci-config.json --streaming
flowdeck test --config .flowdeck/ci-config.json --streaming

Parsing JSON Results

# Check if build succeeded
flowdeck build --config .flowdeck/ci-config.json --json | \
  jq -s 'last | select(.success == true)' && echo "Build passed"

# Extract errors
flowdeck build --config .flowdeck/ci-config.json --json | \
  jq 'select(.level == "error")'

Simulator Management in CI

Boot a Specific Simulator

# List available simulators
flowdeck simulator list -P iOS -A --json

# Boot by name
flowdeck simulator boot "iPhone 16"

# Boot by UDID (more reliable in CI)
flowdeck simulator boot "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"

Create a Simulator (if needed)

flowdeck simulator create -n "CI-iPhone" --device-type "iPhone 16" --runtime "iOS 18.0"

Best Practices

1. Use Config Set or Configuration Files

For reproducibility, either use flowdeck config set or config files:

# Option 1: Save settings once
flowdeck config set -w MyApp.xcworkspace -s MyApp -S "iPhone 16"
flowdeck build --json

# Option 2: Use config file
flowdeck build -c .flowdeck/ci-config.json --json

2. Choose the Right Output Mode

Use --json when you need machine-readable output for parsers or dashboards. Use --streaming when you want clean, human-readable CI logs:

flowdeck build --json        # Machine-readable NDJSON events
flowdeck test --streaming    # Human-readable grouped results

3. Specify Simulator by UDID

Simulator names can vary across CI runners. Use UDIDs for consistency:

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "simulatorUdid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"
}

Or resolve dynamically:

# Get the first available iPhone 16 simulator UDID
SIMULATOR_UDID=$(flowdeck simulator list -P iOS --json | \
  jq -r '.[] | select(.name | contains("iPhone 16")) | .udid' | head -1)

flowdeck config set -w MyApp.xcworkspace -s MyApp -S "$SIMULATOR_UDID"
flowdeck build --json

4. Clean Before Release Builds

flowdeck clean --all
flowdeck build -c .flowdeck/release-config.json --json

5. Use Derived Data Paths

Avoid conflicts with concurrent builds:

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "derivedDataPath": "/tmp/flowdeck-derived-data"
}

Troubleshooting

”License validation failed”

Ensure FLOWDECK_LICENSE_KEY is set correctly:

# Check if variable is set
echo $FLOWDECK_LICENSE_KEY

# Verify CI detection
flowdeck license status

“Simulator not found”

List available simulators and use exact names or UDIDs:

flowdeck simulator list -P iOS -A --json

Build Timeout

Increase timeout for large projects:

# GitHub Actions
- name: Build
  timeout-minutes: 30
  run: flowdeck build --config .flowdeck/ci-config.json --json

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

CI/CD Integration

License Configuration

Setting the License Key

Supported CI Platforms

Installing FlowDeck in CI

Using the Install Script

GitHub Actions Example

Alternative: Using Config Files

Configuration File

Create a Config File

Use in CI

Config File Reference

Output Modes

JSON (Default for CI)

Streaming (Human-Readable)

Parsing JSON Results

Simulator Management in CI

Boot a Specific Simulator

Create a Simulator (if needed)

Best Practices

1. Use Config Set or Configuration Files

2. Choose the Right Output Mode

3. Specify Simulator by UDID

4. Clean Before Release Builds

5. Use Derived Data Paths

Troubleshooting

”License validation failed”

“Simulator not found”

Build Timeout

​License Configuration

​Setting the License Key

​Supported CI Platforms

​Installing FlowDeck in CI

​Using the Install Script

​GitHub Actions Example

​Alternative: Using Config Files

​Configuration File

​Create a Config File

​Use in CI

​Config File Reference

​Output Modes

​JSON (Default for CI)

​Streaming (Human-Readable)

​Parsing JSON Results

​Simulator Management in CI

​Boot a Specific Simulator

​Create a Simulator (if needed)

​Best Practices

​1. Use Config Set or Configuration Files

​2. Choose the Right Output Mode

​3. Specify Simulator by UDID

​4. Clean Before Release Builds

​5. Use Derived Data Paths

​Troubleshooting

​”License validation failed”

​“Simulator not found”

​Build Timeout

License Configuration

Setting the License Key

Supported CI Platforms

Installing FlowDeck in CI

Using the Install Script

GitHub Actions Example

Alternative: Using Config Files

Configuration File

Create a Config File

Use in CI

Config File Reference

Output Modes

JSON (Default for CI)

Streaming (Human-Readable)

Parsing JSON Results

Simulator Management in CI

Boot a Specific Simulator

Create a Simulator (if needed)

Best Practices

1. Use Config Set or Configuration Files

2. Choose the Right Output Mode

3. Specify Simulator by UDID

4. Clean Before Release Builds

5. Use Derived Data Paths

Troubleshooting

”License validation failed”

“Simulator not found”

Build Timeout