Bitbucket
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. GitHub Actions workflows 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
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.
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