Appcircle docs

content/en/docs/refguide/mobile/distributing-mobile-apps/building-native-apps/_index.md

@@ -19,7 +19,8 @@ Many of these guides use the Mendix Native Mobile Builder UI tool included in Me
 * [Build a Mendix Native App Locally Manually](/refguide/mobile/distributing-mobile-apps/building-native-apps/native-build-locally-manually/) – Follow this guide to build your apps locally and without an internet connection.
 * [Create a Custom Developer App](/refguide/mobile/distributing-mobile-apps/building-native-apps/how-to-devapps/) – Create a custom developer app (a substitute for the Make It Native app) which accommodates custom dependencies such as native widgets or fonts.
 * [Native Template](/refguide/mobile/distributing-mobile-apps/building-native-apps/native-template/) – The Native Template describes the native dependencies your app needs, and it includes two native apps (one for iOS and one for Android) that can be independently built to create the finished apps.
-* [Build a Mendix Native App with Bitrise](/refguide/mobile/distributing-mobile-apps/building-native-apps/bitrise/) – This guide explains how to set up Bitrise to build a Mendix native mobile app. 
+* [Build a Mendix Native App with Bitrise](/refguide/mobile/distributing-mobile-apps/building-native-apps/bitrise/) – This guide explains how to set up Bitrise to build a Mendix native mobile app.
+* [Build a Mendix Native App with Appcircle](/refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle/) – This guide explains how to set up Appcircle to build a Mendix native mobile app.
 
 {{% alert color="info" %}}
 The Mendix Native Mobile Builder does not currently support connections behind proxy servers. Please make sure you are not behind a proxy server and that your security rules allow access to the required services. For more information, see the [Firewall Settings](/refguide/system-requirements/#firewall-settings) section of System Requirements.

content/en/docs/refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle.md

@@ -0,0 +1,198 @@
+---
+title: "Build a Mendix Native App with Appcircle"
+url: /refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle/
+weight: 70
+description: Describes how to integrate with Appcircle to build a Mendix native app in the cloud.
+---
+
+## Introduction
+
+This guide helps you set up [Appcircle](https://appcircle.io) to automate building a Mendix native app in the cloud. Appcircle is a mobile CI/CD platform that provides fast, flexible build pipelines for iOS and Android apps.
+
+{{% alert color="info" %}}
+Please note that this documentation is provided as a guide only. Mendix offers support if issues arise with the Mendix build process itself, but cannot provide support for problems related to the Appcircle platform or other third-party tools described in this guide.
+{{% /alert %}}
+
+Before starting, [sign up for an Appcircle account](https://auth.appcircle.io/signup) and make sure you have created the native template project for your app by following [Using Mendix Native Mobile Builder to Set Up Your Local App](/refguide/mobile/distributing-mobile-apps/building-native-apps/native-build-locally/#using-mendix-native-mobile-builder-to-set-up-your-local-app).
+
+After building your app, you can distribute it to testers or publish it to the app stores using Appcircle. For more information, see [Distribute a Mendix Native App with Appcircle](/refguide/mobile/distributing-mobile-apps/distributing-with-appcircle/) and [Publish a Mendix Native App with Appcircle](/refguide/mobile/distributing-mobile-apps/publishing-with-appcircle/).
+
+## Set Up Your Build Profiles {#set-up-your-build-profile}
+
+Appcircle uses separate build profiles for iOS and Android. Create one profile per target platform by doing the following:
+
+1. Log in to Appcircle and go to the **Build** module.
+1. Click **Add New** (top-right corner) and select the target operating system (**iOS** or **Android**) and **React Native** as the framework.
+1. Choose how to connect your repository. Appcircle supports GitHub, GitLab, Bitbucket, Azure DevOps, and direct SSH URL connections:
+
+    {{< figure src="/attachments/refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle/add-build-profile.png" alt="Repository connection options in Appcircle" class="no-border" >}}
+1. Select the branch you want to build from. Appcircle automatically fetches the repository and fills in the build configuration.
+1. Review the auto-filled configuration, adjust if needed, and finish creating the profile.
+
+Repeat these steps to create a profile for the other platform if needed. For more information, see [Appcircle's build profile documentation](https://docs.appcircle.io/build/manage-the-connections/adding-a-build-profile/).
+
+## Set Up Code Signing for iOS {#code-signing-ios}
+
+Applications distributed to iOS devices must be signed with a certificate and a provisioning profile. You will need to be enrolled in the [Apple Developer Program](https://developer.apple.com/programs/) or the [Apple Developer Enterprise Program](https://developer.apple.com/programs/enterprise/), and have an [App Store Connect API Key](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api) available.
+
+### Add a Certificate
+
+To add a certificate, do the following:
+
+1. Go to the **Signing Identities** module from the left navigation menu and select **Apple Certificates**.
+1. Click **Add New** and choose one of the following:
+   * **Create an Apple Certificate** — generates a certificate via your App Store Connect API Key. Select a Certificate Signing Request (CSR) or generate one, then choose the certificate type (Apple Distribution).
+   * **Upload Certificate Bundle (.p12)** — upload a pre-existing *.p12* file directly.
+
+{{% alert color="warning" %}}
+Avoid using special characters such as `$` or `#` in your certificate password, as these can cause failures during import.
+{{% /alert %}}
+
+### Add a Provisioning Profile
+
+To add a provisioning profile, do the following:
+
+1. In the **Signing Identities** module, select **Apple Profiles**.
+1. Choose one of the following methods:
+   * **Register a New Profile** — select a distribution method (App Store, Ad Hoc, or Enterprise), an App ID, and a certificate. Appcircle registers the profile on the Apple Developer Portal automatically.
+   * **Fetch from App Store Connect** — select **Get Provisioning Profiles from App Store Connect** and import profiles from your account.
+   * **Upload manually** — upload one or more *.mobileprovision* files. Profiles are automatically matched with certificates; a green checkmark indicates a match.
+
+### Assign to the Build Profile
+
+In the Build module, open the iOS build profile and go to **Build Configuration**. Under the **Signing** section, choose one of the following signing methods:
+
+* **Automatic Signing** — Appcircle automatically handles provisioning profile management during the build. This requires:
+  * Xcode 13 or later
+  * A Developer or Distribution certificate
+  * An App Store Connect API key (configured in the **API Integrations** settings)
+  * The bundle identifier must already be registered in your Apple Developer account
+* **Manual Signing** — you manually select the certificate and provisioning profile for each build configuration. This gives you full control over which profiles are used. Select your bundle identifier from the dropdown, then choose the provisioning profile you added in the **Signing Identities** module. The certificate will be automatically matched based on the profile.
+
+For more details, follow [Appcircle's iOS code signing guide](https://docs.appcircle.io/signing-identities/apple-certificates).
+
+## Set Up Code Signing for Android {#code-signing-android}
+
+Applications distributed to Android devices must be signed with a keystore. To distribute via the Play Store, you will also need to [register as an Android developer](https://play.google.com/console/signup).
+
+Appcircle lets you either upload an existing keystore or generate a new one directly within the platform.
+
+To generate a new keystore within Appcircle, do the following:
+
+1. Go to the **Signing Identities** module and select **Android Keystores**.
+1. Click **Add New** and select the generate option.
+1. Fill in the required details:
+   * **Keystore Password** — password to protect the keystore file (minimum 6 characters)
+   * **Key Alias** — identifier for the signing key (for example, `my-app-key`)
+   * **Key Password** — password to protect the signing key (minimum 6 characters)
+   * Certificate information:
+     * **Common Name (CN)** — your name or organization name
+     * **Organizational Unit (OU)** — your department or division (optional)
+     * **Organization (O)** — your organization name (optional)
+     * **Locality (L)** — your city (optional)
+     * **State (ST)** — your state or province (optional)
+     * **Country Code (C)** — two-letter country code (for example, `US`)
+   * **Validity (years)** — how long the keystore remains valid (default is 25 years; Google requires at least 25 years for Play Store apps)
+1. Save the keystore. Appcircle generates the keystore file and stores it securely.
+
+{{% alert color="warning" %}}
+Store your keystore credentials securely. If you lose them, you cannot update your app on the Play Store and will need to publish a new app with a different package name.
+{{% /alert %}}
+
+To upload an existing keystore instead, do the following:
+
+1. Go to the **Signing Identities** module and select **Android Keystores**.
+1. Click **Add New** and select the upload option.
+1. Upload your *.keystore* (or *.jks*) file and fill in the **Keystore Password**, **Key Alias**, and **Key Password** fields.
+1. Save the keystore.
+
+After generating or uploading the keystore, open the Android build profile's workflow editor and ensure the **Sign Application** step is enabled and configured to use the keystore from Signing Identities.
+
+For more details, follow [Appcircle's Android code signing guide](https://docs.appcircle.io/signing-identities/android-keystores).
+
+## Configure Environment Variables {#environment-variables}
+
+Environment variables let you configure build-time and runtime settings without hardcoding values in your app. You can use them to set different configurations for development, staging, and production builds.
+
+Appcircle provides two levels of environment variable configuration:
+
+* **Global environment variables** — shared across all build profiles in your organization
+* **Build profile environment variables** — specific to a single build profile
+
+### Common Use Cases
+
+For Mendix native apps, you might use environment variables for:
+
+* **Runtime URLs** — different backend endpoints for dev, test, and production environments
+* **App configuration** — feature flags, API keys, or service endpoints
+* **Build configuration** — version numbers, build identifiers, or platform-specific settings
+
+### Add Environment Variables to Your Build Profile
+
+To configure environment variables for a specific build profile, do the following:
+
+1. Open the build profile in the **Build** module.
+1. Click the **gear icon** to open **Build Configuration** settings.
+1. Go to the **Environment Variables** tab.
+1. Click **Add New Variable** and enter:
+   * **Key** — the variable name (for example, `RUNTIME_URL`)
+   * **Value** — the variable value (for example, `https://myapp-acceptance.mendixcloud.com`)
+   * **Toggles**:
+     * **Accessible during the build** — makes the variable available to build scripts and workflow steps
+     * **Masked in logs** — hides the value in build logs (use this for sensitive values)
+1. Save the configuration.
+
+{{% alert color="info" %}}
+For sensitive values like API keys or tokens, always enable **Masked in logs** to prevent them from appearing in build output. For highly sensitive credentials, consider using Appcircle's secret management features instead.
+{{% /alert %}}
+
+### Add Global Environment Variables
+
+To configure environment variables shared across all builds in your organization, do the following:
+
+1. Go to the **Build** module and select **Environment Variables** from the left navigation menu.
+1. Click **Add New Variable**.
+1. Enter the **Key** and **Value**, and configure the toggles as needed.
+1. Save the variable.
+
+Global variables can be overridden by build profile-specific variables with the same key.
+
+### Use Environment Variables in Your App
+
+Environment variables configured in Appcircle are available during the build process. How you access them depends on your app's configuration:
+
+* **React Native environment files** — if your app uses *.env* files or libraries like `react-native-config`, you can pass Appcircle environment variables to these configuration files using custom build scripts
+* **Build scripts** — environment variables are accessible in workflow steps and custom scripts using standard environment variable syntax (for example, `$RUNTIME_URL` in shell scripts)
+
+For more details on environment variable management and advanced configurations, see [Appcircle's environment variables documentation](https://docs.appcircle.io/environment-variables/).
+
+## Build Your App {#build-your-app}
+
+Builds can be started manually or automatically triggered by commits to the repository.
+
+To start a build manually, open the build profile and click **Start Build**. Select the branch and the workflow, then confirm.
+
+{{< figure src="/attachments/refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle/build-logs.png" alt="Build profile overview showing build history in Appcircle" class="no-border" >}}
+
+While the build is running, you can view the live build logs by clicking on the build's **Commit ID** or the actions menu. The logs show each workflow step in real time, helping you monitor progress and diagnose any issues.
+
+{{% alert color="info" %}}
+Older versions of Mendix might require a specific Node version. The Appcircle workflow already includes a [Node Install](https://docs.appcircle.io/workflows/react-native-specific-workflow-steps/node-install) step — simply update the version number there to match the version in the **.nvmrc** file of your app's generated native template.
+{{% /alert %}}
+
+### Set Up Automatic Builds
+
+To trigger a build automatically every time **Build Native App** pushes an update to the native template repository, do the following:
+
+1. Open the build profile and go to the **Build Configuration** settings.
+1. Navigate to the **Triggers** section.
+1. Enable the **Push** trigger and set it to the branch you want to build from.
+1. Select the appropriate workflow.
+1. Save the configuration.
+
+Now, every time **Build Native App** updates the application bundle, a new build will be triggered automatically in Appcircle.
+
+## Read More
+
+* [Distribute a Mendix Native App with Appcircle](/refguide/mobile/distributing-mobile-apps/distributing-with-appcircle/)
+* [Publish a Mendix Native App with Appcircle](/refguide/mobile/distributing-mobile-apps/publishing-with-appcircle/)

content/en/docs/refguide/mobile/distributing-mobile-apps/distributing-with-appcircle.md

@@ -0,0 +1,75 @@
+---
+title: "Distribute a Mendix Native App with Appcircle"
+url: /refguide/mobile/distributing-mobile-apps/distributing-with-appcircle/
+weight: 25
+description: Describes how to use Appcircle's Testing Distribution module to share builds with testers.
+---
+
+## Introduction
+
+Once you have [built your Mendix native app with Appcircle](/refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle/), you can distribute it to testers using Appcircle's built-in **Testing Distribution** module. This lets you share builds with QA teams or stakeholders without going through the App Store or Google Play, making it useful for internal reviews and beta testing.
+
+{{% alert color="info" %}}
+Please note that this documentation is provided as a guide only. Mendix offers support if issues arise with the Mendix build process itself, but cannot provide support for problems related to the Appcircle platform or other third-party tools described in this guide.
+{{% /alert %}}
+
+## Prerequisites
+
+Before starting this guide, make sure you have completed the following:
+
+* Set up a build profile and built your app by following [Build a Mendix Native App with Appcircle](/refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle/)
+
+## Create a Distribution Profile {#create-distribution-profile}
+
+To create a testing distribution profile, do the following:
+
+1. Go to the **Testing Distribution** module from the left navigation menu.
+1. Click **Add New** to create a distribution profile.
+1. Give the profile a name and save it.
+
+{{< figure src="/attachments/refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle/testing-distribution-module.png" alt="Testing Distribution module in Appcircle" class="no-border" >}}
+
+## Link Distribution to Your Build Profile {#link-distribution}
+
+To automatically send builds to your testing distribution profile after a successful build, do the following:
+
+1. Open the build profile in the **Build** module and click the **gear icon** to open **Build Configuration** settings.
+1. Navigate to the **Distribution** tab (alongside the Signing and Triggers tabs).
+1. In the **Testing Distribution** section, select the distribution profile you created from the dropdown.
+1. Enable the **Auto Distribute** toggle if you want every successful build to be sent to testers automatically. If disabled, you will need to manually send builds from the build profile after they complete.
+1. (Optional) Enable **Auto Deploy on Merge** to only distribute builds from merge commits, not all commits.
+1. Save the configuration.
+
+With **Auto Distribute** enabled, every successful build will be sent to your distribution profile and testers will be notified automatically without any manual steps.
+
+## Share Builds with Testers {#share-builds}
+
+After a build is distributed to the testing distribution profile, you can share it with testers. To add testers and send them the build:
+
+1. Open your distribution profile in the **Testing Distribution** module.
+1. Go to the **Testers** section and add tester email addresses individually or import them in bulk.
+1. Select the build version you want to share.
+1. Click **Share with Testers** and choose which tester groups should receive it.
+
+Testers will receive an email notification containing:
+
+* The app name and version number
+* Release notes (if you added any)
+* A secure download link
+* Installation instructions for their device
+
+When testers click the link, they will be directed to a download page where they can:
+
+* **iOS**: Download and install the app directly (for Ad Hoc or Enterprise provisioned apps). If using an Ad Hoc profile, their device UDID must be included in the provisioning profile.
+* **Android**: Download the APK and install it. They may need to enable "Install from Unknown Sources" in their device settings.
+
+{{% alert color="info" %}}
+You can configure authentication requirements (login, OTP, none) and expiration settings for distribution links in the distribution profile settings.
+{{% /alert %}}
+
+For more details on managing testers, configuring authentication for download links, and other distribution options, see [Appcircle's Testing Distribution documentation](https://docs.appcircle.io/distribute/create-or-select-a-distribution-profile/).
+
+## Read More
+
+* [Build a Mendix Native App with Appcircle](/refguide/mobile/distributing-mobile-apps/building-native-apps/appcircle/)
+* [Publish a Mendix Native App with Appcircle](/refguide/mobile/distributing-mobile-apps/publishing-with-appcircle/)