WebRobot
App Builder · pages

Documentation · App Builder

Export to GitHub and phones

What the export gives you

Export code puts the app in a GitHub repository of yours, for the platforms you choose:

PlatformWhat the repository gets
Web app (Next.js code)The app runtime and the kit (the same code that serves apps on WebRobot), the app's manifest, a README, a Dockerfile, an .env.example and a workflow that builds a container image.
AndroidA phone shell (Capacitor) that opens the app, and a GitHub Actions workflow that builds it.
iPhoneThe same shell, and a workflow that builds it on GitHub's macOS machines.

The exported code is not written by a model: it is the reviewed runtime code plus your app's manifest. The exported web app behaves like the hosted one. Its agents keep running on WebRobot with the app's own API key, which you put in your environment. The key is never written to the repository.

Before you export

  • Publish the app first. The export uses the published manifest, whose agents already exist on the platform. Until then the panel says Publish the app first: the exported code uses its published agents. and the Export button stays disabled.
  • Be an admin of the organization. The GitHub access is stored as an encrypted credential of the organization, and only admins can store and read credentials.

Open the panel with Export code in App Studio, or with Export code on an app's card in the apps list. The panel is titled Export to GitHub: web and phone apps.

Connect GitHub

The first time, the panel shows Sign in to GitHub and allow WebRobot to create repositories and push code for you. and Connect GitHub.

  1. Press Connect GitHub. GitHub asks you to sign in and to grant WebRobot two scopes: repo (create repositories and push code) and workflow (write the build workflows in .github/workflows).
  2. Approve. GitHub sends you back to App Studio with the export panel open and the message GitHub connected as @<login>. Choose the repository below and press Export.

If you refuse, the message is GitHub access was not granted: nothing was connected. If something fails, it is GitHub connection failed: followed by the reason. The sign-in must be completed within 10 minutes.

The access token is stored encrypted as a cloud credential of your organization named github-oauth (provider github). Every admin of the organization exports with the same connection. To disconnect, delete that credential in Cloud Credentials.

Once connected, the panel shows Connected as @<login> and a switch account link. Other states:

MessageWhat to do
The GitHub connection expired.Press Connect GitHub again.
GitHub must also allow WebRobot to write the app's build workflow (.github/workflows).The connection lacks the workflow scope. Press Reconnect GitHub and approve.
GitHub is not configured on this console yet.The export is not available on this installation.

Choose the repository

FieldMeaning
OwnerYour GitHub account, or one of the GitHub organizations you belong to.
Repository nameDefaults to the app's slug. Letters, digits, ., _ and -; other characters become -.
New repositoryGitHub creates the repository. Private repository is ticked by default.
Existing repository (a pull request)The code goes to a branch and a pull request.

Press Export (it shows Exporting…). The export is one commit, with the message <app name> v<N> — <platforms> (WebRobot App Studio, kit <version>), for example Physio Booking v3 — web + android (WebRobot App Studio, kit <version>).

New repository

The repository is created (initialised, so it has a default branch), and the commit lands on its default branch. The panel says Repository created with the app on <branch> (<N> files) and links to the repository.

If the repository already exists, for example after an earlier attempt, the export stops with <owner>/<repo> already exists (a previous attempt may have created it): untick "new repository" and export to it — it gets a branch and a pull request.

Existing repository

Your default branch is never written. The commit goes to the branch webrobot/<slug> and a pull request is opened against the default branch, titled WebRobot: <commit message>. The panel says Pushed to webrobot/<slug> (<N> files) and links to the pull request.

Exporting again moves webrobot/<slug> to the new commit (the branch is overwritten, not merged) and the open pull request shows it. Review and merge it like any other change.

Your GitHub account needs push access to the repository; otherwise the export stops with your GitHub account cannot push to <owner>/<repo>.

What is in the web export

PathWhat
manifest/<slug>.vertical.yamlThe published manifest, as YAML, with a header naming the published version.
apps/runtimeThe Next.js app that renders a manifest.
packages/vertical-kitSign-in, credits, runs, the WebRobot client.
schema/vertical-app.schema.jsonThe manifest contract. python3 scripts/validate.py manifest/*.yaml checks a manifest against it.
DockerfileBuilds an image that serves this one app (single-app mode).
.env.exampleThe settings the app needs.
.github/workflows/build.ymlBuilds the container image and pushes it to GitHub Container Registry (ghcr.io/<owner>/<repo>:<commit>) on every push to main, or by hand.
README.mdHow to run it.

The hosted runtime's deployment files, sample manifests and operations scripts are left out.

Settings

Copy .env.example to apps/runtime/.env.local for development (never commit it). In production pass the same values to the container. <SLUG> is the slug in upper case with _ for -.

VariableValue
VK_APP_<SLUG>_WEBROBOT_API_KEYThe app's API key: in the WebRobot console, Cloud Credentials › vertical-app-<slug>.
VK_APP_<SLUG>_ADMIN_EMAILSWho is admin of the app, comma separated.
VK_APP_<SLUG>_EMAIL_ORG_IDOptional: the organization whose mail server sends the sign-in links.
VK_SESSION_SECRET32 or more random characters, for example from openssl rand -base64 36.
DATABASE_URLA PostgreSQL connection string. Without it data lives in memory (development only).
WEBROBOT_API_URLhttps://api.webrobot.eu
VK_SINGLE_APPtrue: serve this one manifest on whatever domain the app is deployed on.

Run it

cp .env.example apps/runtime/.env.local   # fill in the key, the admin emails, a session secret, the database
npm ci
npm run dev -w @webrobot/vertical-runtime    # http://localhost:3000

In production: docker build -t <slug> . then docker run --env-file apps/runtime/.env.local -p 3000:3000 <slug>.

The agents keep running on the WebRobot platform and their usage is billed to your organization. Payments to you (Stripe Connect) and the platform fee stay configured on WebRobot.

Phone apps

Tick Android and/or iPhone. The phone app is a Capacitor shell that opens your app's web address: the same screens, agents and data, with the person's own session. Nothing of the app is copied into the phone app, so what you publish in App Studio reaches the phones without a new store release. No platform key is ever on the phone. On the phone, users sign in with the 6-digit code from the sign-in email.

If you tick only phone platforms, the repository gets the phone project, its workflows, the manifest (for reference) and a README, and no web code.

Phone settings

The fields start from the app's spec.mobile, if it has one.

FieldRule
Store identifierRequired. Reverse-DNS, lower case, at least three parts, for example com.yourcompany.physiobooking. It never changes once the app is in a store.
Name under the icon (optional)At most 30 characters. Empty: the app's name.
Address the phone app opens (optional)Empty: the app hosted on WebRobot (https://<slug>.webrobot.eu, or spec.host if set). Set it if you host the web app yourself. It must be https:// plus a host name, optionally a port, with no path.

These settings go into the exported repository only. They are not saved in the app in App Studio, so fill them in again on the next export, or put them in spec.mobile in the JSON tab.

spec:
  mobile:
    appId: com.yourcompany.physiobooking
    appName: Physio Booking
    capabilities:
      - name: camera
        reason: To photograph your medical reports.

Phone features

Only the features you tick go into the app: only their plugins are installed and only their permissions are requested. For most of them you must write why the app needs it; the phone shows that text when it asks the person.

Label in the panelNameReason required
Camera and photoscamerayes
Locationlocationyes
Location in the backgroundbackgroundLocationyes
Push notificationspushno
Reminders on the phonelocalNotificationsno
Face ID / fingerprintbiometricsyes
Barcode and QR scannerbarcodeyes
Microphonemicrophoneyes
Speech to textspeechyes
Contactscontactsyes
Calendarcalendaryes
Bluetooth devicesbluetoothyes
Files on the phonefilesno
Share sheetshareno
Vibrationhapticsno

App stores refuse permissions an app does not use, so the export checks both directions:

  • A feature must be used by the app. files, share and haptics are always accepted. The others need a part of the app that uses them:

    FeatureUsed by
    locationa location field
    barcodea barcode field
    cameraa file field with capture
    calendaran add-to-calendar action in a view
    sharea share action in a view
    biometricsthe app lock, spec.mobile.lock: biometric
    microphonea chat view (voice)
    pushnotifications: a trigger that notifies, a schedule that delivers, or the email when a report is ready
  • Not available yet: contacts, bluetooth, backgroundLocation, localNotifications and speech. No part of an app can use them yet, so the export refuses them with no part of the app can use it yet: remove it.

  • A part of the app that needs a feature must have it. For example a location field without location is refused with a position field (…) needs 'location' in the phone app.

  • backgroundLocation also needs location.

The panel shows a problem in amber and keeps Export disabled until it is solved: Store identifier: reverse-DNS, lower case, e.g. com.yourcompany.<slug>, Write why the app needs each phone feature you ticked: the phone shows it when asking, or The phone app opens an https address (https://host). The checks on the app's use of features run when you press Export; their errors start with the phone app settings are not valid.

What is in the phone export

PathWhat
mobile/package.jsonCapacitor and only the plugins of the features you ticked, at fixed versions.
mobile/capacitor.config.jsonThe store identifier, the name, the address the shell opens, the app's colours.
mobile/mobile.jsonWhat the build applies to the native projects: permissions, iOS usage texts, version, orientation, icon and splash colours.
mobile/www/index.htmlThe page shown when the phone has no connection, with a retry button.
mobile/scripts/native.mjs, mobile/scripts/icon.mjsBuild helpers: apply mobile.json, make the icon.
mobile/README.mdHow the builds work and which keys the stores need.
.github/workflows/android.ymlThe Android build.
.github/workflows/ios.ymlThe iPhone build.

The native folders (android/, ios/) are generated during the build and are not kept in the repository. The build number is the workflow run number, so every upload has a higher one.

Android builds

The workflow runs on every push to main that changes mobile/, and by hand from the Actions tab.

  • Without a signing key it builds a debug APK you can install on a phone. Download it from the run's artifacts.
  • With a signing key it builds a signed bundle (AAB) for Google Play.
  • With a Play service account as well, it uploads the bundle to the internal testing track as a draft. Google Play wants the very first bundle uploaded by hand in the Play Console; the workflow uploads the next ones.

Add these secrets to your repository (Settings › Secrets and variables › Actions):

SecretWhat
ANDROID_KEYSTORE_BASE64Your upload keystore, base64-encoded.
ANDROID_KEYSTORE_PASSWORDThe keystore password.
ANDROID_KEY_ALIASThe key alias, for example upload.
ANDROID_KEY_PASSWORDThe key password.
PLAY_SERVICE_ACCOUNT_JSONOptional: a Google Play service account, for the upload.
GOOGLE_SERVICES_JSONWith push notifications: the Firebase google-services.json of the app. Without it, the Android build does not register for notifications.

iPhone builds

The workflow runs on GitHub's macOS machines, only by hand (Actions › ios › Run workflow), because macOS minutes cost more.

  • Without Apple keys it builds the app for the simulator, to check that it compiles.
  • With the keys Xcode signs with your team and uploads the build to App Store Connect. It appears in TestFlight, and you submit it for review from there.

First create the app in App Store Connect with the bundle id equal to your store identifier. Then add:

SecretWhat
APPLE_TEAM_IDYour Apple Developer team id (10 characters).
APPSTORE_API_KEY_IDAn App Store Connect API key (Users and Access › Integrations), role Admin.
APPSTORE_API_ISSUER_IDThe issuer id shown above the keys.
APPSTORE_API_KEY_P8The content of the downloaded AuthKey_….p8 file.

What you provide

  • A GitHub account (or organization) and its Actions minutes.
  • For a self-hosted web app: a place to run the container, a PostgreSQL database, the app's API key and a session secret.
  • For Android in Google Play: your Google Play developer account, an upload keystore, and optionally a service account; for push, a Firebase project.
  • For iPhone in the App Store: your Apple Developer account, the app record in App Store Connect and an App Store Connect API key.

The store accounts and signing keys are yours. WebRobot never holds them: they live as secrets of your repository.

Limits

  • Only the published version is exported. Publish your latest changes first.
  • The export is one-way. Changes you make in the repository do not come back to App Studio.
  • Exporting again to an existing repository overwrites the webrobot/<slug> branch.
  • The web build workflow runs on pushes to main. After merging the pull request into another default branch, start it by hand.
  • Some phone features are not available yet (see Phone features).
  • The phone app always opens a web address over HTTPS: it does not work without a connection, and shows its offline page instead.