Bitbucket
[ .NET MAUI ]
Repository Structure
- The .NET MAUI project (
*.csproj) This guide provides step-by-step instructions on how to connect your Bitbucket repository with the AppAmbit Dashboard to enable automated CI/CD workflows. Bitbucket pipelines for automated CI/CD are defined here: bitbucket-pipelines.yml: Handles the build and signing process for the Android APK and IPA. This pipeline activates automatically on pushes to the develop branch.
Prerequisites
Before you begin, ensure you have an existing Bitbucket repository with a configured bitbucket-pipelines.yml file that generates the required build artifacts.
Workflow Variables
Android
| VARIABLE | DESCRIPTION | EXAMPLE |
|---|---|---|
TYPE_RELEASE |
Release type (alpha, beta, release) |
alpha |
BUILD_CONFIGURATION |
Build Configuration (Debug, Release) |
Release |
BUILD_FRAMEWORK |
Target Framework for Android | net8.0-android |
APK_NAME |
APK base name (without extension) | com_appambit_testapp |
PROJECT_DIR |
MAUI Project Route | ./AppAmbitTestingApp |
KEYSTORE_ASC |
Name of the GPG encrypted keystore file | appambit.keystore.asc |
KEYSTORE_FILE |
File generated by decrypting the previous one | appambit.keystore |
iOS
| VARIABLE | DESCRIPTION | EXAMPLE |
|---|---|---|
TYPE_RELEASE |
Release type (alpha, beta, release) |
alpha |
PROJECT_PATH |
Relative path to your iOS project's .csproj file |
AppMauiTestApp/AppMauiTestApp.csproj |
IPA_NAME |
Base name of the IPA file (without .ipa extension) |
ipa_name_ios |
Secrets and variables
Android
| SECRET | DESCRIPTION |
|---|---|
| ANDROID_KEYSTORE_FILE | Full contents of the encrypted .asc file (copied as plain text) |
| ANDROID_KEYSTORE_PASSWORD | Keystore password |
| ANDROID_KEYSTORE_PASSWORD_ALIAS | Password of the alias within the keystore |
| ANDROID_KEYSTORE_PASSWORD_GPG | Password used to decrypt the .asc file |
iOS
| SECRET | DESCRIPTION |
|---|---|
| IOS_APPLE_P12_PASSWORD | Password of the .p12 certificate used for signing |
| IOS_P12_CERTIFICATE_BASE64 | Base64-encoded .p12 distribution certificate |
| IOS_PROVISIONING_PROFILE_BASE64 | Provisioning profile in Base64 format |
Info
If you're not sure about having this credentials you can go to generating variables
[ Android ]
Repository Structure
- The Android project (
build.gradle.kts) This guide provides step-by-step instructions on how to connect your Bitbucket repository with the AppAmbit Dashboard to enable automated CI/CD workflows. Bitbucket pipelines for automated CI/CD are defined here: bitbucket-pipelines.yml: Handles the build and signing process for the Android APK This pipeline activates automatically on pushes to the develop branch.
Prerequisites
Before you begin, ensure you have an existing Bitbucket repository with a configured bitbucket-pipelines.yml file that generates the required build artifacts.
Workflow Variables
| VARIABLE | DESCRIPTION | EXAMPLE |
|---|---|---|
PACKAGE_NAME |
Name used in the package app | appambit-testapp |
APK_NAME |
APK name file | com_appambit_testapp |
BUNDLE_NAME |
Name of the ZIP artifact file | my_app_bundle.zip |
Secrets and variables
| SECRET | DESCRIPTION |
|---|---|
SIGNING_KEY_STORE_BASE64 |
Full contents of the .jks/.keystore file, encoded in Base64. |
SIGNING_KEY_ALIAS |
Alias name inside the keystore that identifies the key. |
SIGNING_KEY_PASSWORD |
Password of the private key associated with the alias in the keystore. |
SIGNING_STORE_PASSWORD |
Password of the keystore file itself (.jks/.keystore). |
SIGNING_KEY_STORE_PATH |
Path to the keystore file. (e.g. mykey.keystore) |
BITBUCKET_USERNAME |
Your Bitbucket account username. |
BITBUCKET_APP_PASSWORD |
Bitbucket app password used for authentication in pipelines/CI/CD. |
Info
If you're not sure about having this credentials you can go to generating variables
[ iOS ]
Repository Structure
- The iOS project (
*.xcodeproj) This guide provides step-by-step instructions on how to connect your Bitbucket repository with the AppAmbit Dashboard to enable automated CI/CD workflows. Bitbucket pipelines for automated CI/CD are defined here: bitbucket-pipelines.yml: Handles the build and signing process for the iOS IPA This pipeline activates automatically on pushes to the develop branch.
Prerequisites
Before you begin, ensure you have an existing Bitbucket repository with a configured bitbucket-pipelines.yml file that generates the required build artifacts.
Workflow Variables
| VARIABLE | DESCRIPTION | EXAMPLE |
|---|---|---|
BUNDLE_IDENTIFIER |
The unique app identifier used in the provisioning profile and Info.plist. | com.AppAmbit.TestApp |
IOS_ADHOC_PROFILE |
The name/UUID of the AdHoc provisioning profile used for signing. | AppAmbit TestApp - AdHoc |
IOS_INFO_PLIST |
Path to the export options .plist file generated for Xcode build export. |
AppAmbit-Testing-App-Info.plist |
SCHEME |
The Xcode scheme that defines the build configuration for the app. | AppAmbitTestingApp |
SDK |
The SDK to be used by Xcode for building the app. | iphoneos |
DESTINATION |
The target platform/device for the build process. | generic/platform=iOS |
CONFIGURATION |
The build configuration used in Xcode (usually Release or Debug). |
Release |
ARCHIVE_PATH |
The path where the .xcarchive package will be created. |
AppAmbitTestingApp.xcarchive |
APP_NAME_BASE |
Base name used for the final IPA and ZIP artifact files. | app_appambit_testapp |
Secrets and variables
| SECRET | DESCRIPTION |
|---|---|
IOS_P12_CERTIFICATE_BASE64 |
Base64-encoded contents of the iOS signing certificate (.p12 file). |
IOS_PROVISIONING_PROFILE_BASE64 |
Base64-encoded contents of the provisioning profile (.mobileprovision). |
IOS_APPLE_TEAM_ID |
The Apple Developer Team ID used for code signing. |
IOS_APPLE_P12_PASSWORD |
Password for unlocking the .p12 certificate. |
SIGNING_KEY_STORE_PATH |
Path to the Android keystore file (.jks or .keystore). |
BITBUCKET_USERNAME |
Your Bitbucket account username. |
BITBUCKET_APP_PASSWORD |
Bitbucket app password for authenticating pipelines/CI/CD. |
Info
If you're not sure about having this credentials you can go to generating variables
[ Flutter]
Repository Structure
- Flutter Project (
pubspec.yml)
Located at the root of the repository, this file defines the project configuration, dependencies, and platforms. - Workflow Files (
.github/workflows/)
Bitbucket pipelines for automated CI/CD are defined here: build-android.yml: Handles the build and signing process for the Android APK.build-ios.yml: Manages the build and signing of the iOS IPA.
Prerequisites
Before you begin, ensure you have an existing Bitbucket repository with a configured bitbucket-pipelines.yml file that generates the required build artifacts.
Workflow Variables
Android
| VARIABLE | DESCRIPTION | EXAMPLE |
|---|---|---|
APK_NAME |
Name of the generated APK artifact | app_appambit_testapp_apk |
PROJECT_PATH |
Path to the Flutter test app project | appambit_sdk_flutter/appambit_test_app |
ARTIFACTS_DIR |
Directory where build artifacts will be stored | artifacts |
TEST_PROJECT_NAME |
Test Example folder name | appambit_test_app |
FLUTTER_VERSION |
Is you actual version for flutter | '3.35.4' |
iOS
| VARIABLE | DESCRIPTION | EXAMPLE |
|---|---|---|
IOS_INFO_PLIST |
Export options property list used for iOS builds | ExportOptions.plist |
BUNDLE_IDENTIFIER |
Unique iOS app bundle identifier | com.AppAmbit.TestApp |
IPA_NAME |
Base name of the generated IPA artifact | app_appambit_testapp_ipa |
ROOT_DIR |
Root directory of the Flutter SDK project | appambit_sdk_flutter |
TEST_PROJECT_NAME |
Test Example folder name | appambit_test_app |
FLUTTER_VERSION |
Is you actual version for flutter | '3.35.4' |
Secrets and variables
Android
| SECRET | DESCRIPTION |
|---|---|
| KEYSTORE_BASE64 | Base64-encoded contents of the Android keystore file |
| KEYSTORE_PASSWORD | Password of the keystore used for signing |
| KEY_ALIAS | Alias name of the key inside the keystore |
| KEY_PASSWORD | Password for the key alias inside the keystore |
| ATLASSIAN_EMAIL | Email address associated with the Atlassian (Bitbucket) account |
| ATLASSIAN_API_TOKEN | API token used to authenticate with Atlassian services |
iOS
| SECRET | DESCRIPTION |
|---|---|
| IOS_PROVISIONING_PROFILE_BASE64 | Base64-encoded iOS provisioning profile file |
| IOS_P12_CERTIFICATE_BASE64 | Base64-encoded .p12 distribution certificate |
| IOS_P12_PASSWORD | Password of the .p12 certificate used for signing |
| IOS_KEYCHAIN_PASSWORD | Password used to create or unlock the temporary keychain |
| IOS_APPLE_TEAM_ID | Apple Developer Team ID associated with the signing account |
| IOS_ADHOC_PROFILE | Ad hoc provisioning profile identifier used for distribution |
| ATLASSIAN_EMAIL | Email address associated with the Atlassian (Bitbucket) account |
| ATLASSIAN_API_TOKEN | API token used to authenticate with Atlassian services |
Info
If you're not sure about having this credentials you can go to generating variables and bitbucket docs
Running the workflow for the first time
- Ensure the
bitbucket-pipelines.ymlfile exists in the root directory. - Ensure Pipelines are enabled in your Bitbucket repo (
Repository settings > Pipelines > Enabled). - Push to the develop branch to trigger it automatically.
- If everything went well, you will be able to see and download your APK and IPA files in the download section.
Note
The workflow includes steps to generate both an APK and an IPA. If you do not have a self-hosted macOS runner, refer to the MacOS Self-Hosted Runner section for setup instructions — or remove the IPA-related steps from the workflow if iOS builds are not required.
MacOS Self-Hosted Runner
To build the iOS application, you must configure a macOS self-hosted runner. You can do this from:
Repository > Settings > Runners > Create Runner, and follow the installation steps on your macOS machine.
Important
If you notice that the step xcode-select -s /Applications/Xcode.app/Contents/Developer fail or becomes unresponsive, it's likely because the runner was not started with elevated (sudo) permissions.
Make sure to start the runner using:
- bash
- sudo ./bitbucket-pipelines-runner
This ensures that commands like xcode-select, security, and others requiring administrator access will work properly during the IPA build process.
For more information see bitbucket documentation
Where to find the generated APK or IPA
- In Bitbucket, after running the pipeline, go to the corresponding run.
- In the Artifacts section, download the APK or IPA.
Artifact File
To ensure your pipeline executes correctly and artifacts are successfully uploaded to the Delivery section, please review and adhere to the following guidelines.
Important
It is critical that the delivery process is executed correctly. A ZIP archive must be created and uploaded to the Downloads section using a CI/CD Workflow. This archive should contain the build artifact intended for deployment (e.g., APK, IPA, etc.). The ZIP file may include either a single file or multiple files—both formats are acceptable as long as the required deployment artifact is present in a ZIP format.
If you need an example of how to create it correctly, you can check out our official workflows .NET MAUI. Android. iOS.
Delivering Builds with Push to AppAmbit
Once your CI/CD pipeline is configured, you’re ready to deliver builds to testers or users. Next Step: Push to AppAmbit to distribute your app directly from your CI pipeline.
Once your build setup is complete and you've pushed to AppAmbit, you can view and manage your releases directly from the dashboard.
AppAmbit website Dashboard > Releases tab