This sample project illustrates all of the necessary steps to successfully build and publish Ionic + Cordova Android and iOS apps with Codemagic. It covers the basic steps such as build versioning, code signing and publishing.
You can find more detailed instructions as well numerous guides to advanced features in our official documentation.
The apps you have available on Codemagic are listed on the Applications page. Click Add application to add a new app.
- If you have more than one team configured in Codemagic, select the team you wish to add the app to.
- Connect the repository where the source code is hosted. Detailed instructions that cover some advanced options are available here.
- Select the repository from the list of available repositories. Select the appropriate project type.
- Click Finish: Add application
Codemagic uses a YAML configuration file to configure the CI/CD workflow. The name of the file must be codemagic.yaml
and it must be located in the root directory of the repository. This sample project includes a codemagic.yaml
file covering all of the steps outlined below. You can update the file with your own information and reuse it to build your own projects.
All applications have to be digitally signed before they are made available to the public to confirm their author and guarantee that the code has not been altered or corrupted since it was signed.
If you don't have one yet, you can create a keystore for signing your release builds with the Java Keytool utility by running the following command:
keytool -genkey -v -keystore codemagic.keystore -storetype JKS \
-keyalg RSA -keysize 2048 -validity 10000 -alias codemagic
Keytool then prompts you to enter your personal details for creating the certificate, as well as provide passwords for the keystore and the key. It then generates the keystore as a file called codemagic.keystore in the directory you're in. The key is valid for 10,000 days.
- Open your Codemagic Team settings, and go to codemagic.yaml settings > Code signing identities.
- Open Android keystores tab.
- Upload the keystore file by clicking on Choose a file or by dragging it into the indicated frame.
- Enter the Keystore password, Key alias and Key password values as indicated.
- Enter the keystore Reference name. This is a unique name used to reference the file in
codemagic.yaml
- Click the Add keystore button to add the keystore.
For each of the added keystore, its common name, issuer, and expiration date are displayed.
Note: The uploaded keystore cannot be downloaded from Codemagic. It is crucial that you independently store a copy of the keystore file as all subsequent builds released to Google Play should be signed with the same keystore. However, keep the keystore file private and do not check it into a public repository.
To tell Codemagic to fetch the uploaded keystores from the Code signing identities section during the build, list the reference of the uploaded keystore under the android_signing
field.
Add the following code to the environment
section of your codemagic.yaml
file:
workflows:
android-workflow:
name: Android Workflow
# ....
environment:
android_signing:
- keystore_reference
Default environment variables are assigned by Codemagic for the values on the build machine:
- Keystore path:
CM_KEYSTORE_PATH
- Keystore password:
CM_KEYSTORE_PASSWORD
- Key alias:
CM_KEY_ALIAS
- Key alias password:
CM_KEY_PASSWORD
To sign your Android app, simply modify your android/app/build.gradle
as follows:
...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (System.getenv()["CI"]) { // CI=true is exported by Codemagic
storeFile file(System.getenv()["CM_KEYSTORE_PATH"])
storePassword System.getenv()["CM_KEYSTORE_PASSWORD"]
keyAlias System.getenv()["CM_KEY_ALIAS"]
keyPassword System.getenv()["CM_KEY_PASSWORD"]
} else {
keyAlias keystoreProperties['keyAlias']
keyPassword keystoreProperties['keyPassword']
storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null
storePassword keystoreProperties['storePassword']
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...
Signing iOS applications requires Apple Developer Program membership.
It is recommended to create a dedicated App Store Connect API key for Codemagic in App Store Connect. To do so:
- Log in to App Store Connect and navigate to Users and Access > Keys.
- Click on the + sign to generate a new API key.
- Enter the name for the key and select an access level. We recommend choosing
App Manager
access rights, read more about Apple Developer Program role permissions here. - Click Generate.
- As soon as the key is generated, you can see it added to the list of active keys. Click Download API Key to save the private key for later. Note that the key can only be downloaded once.
- Open your Codemagic Team settings, and go to Team integrations > Developer Portal > Manage keys.
- Click the Add key button.
- Enter the
App Store Connect API key name
. This is a human readable name for the key that will be used to refer to the key later in application settings. - Enter the
Issuer ID
andKey ID
values. - Click on Choose a .p8 file or drag the file to upload the App Store Connect API key downloaded earlier.
- Click Save.
Codemagic lets you upload code signing certificates as PKCS#12 archives containing both the certificate and the private key which is needed to use it. When uploading, Codemagic will ask you to provide the certificate password (if the certificate is password-protected) along with a unique Reference name, which can then be used in the codemagic.yaml
configuration to fetch the specific file.
- Open your Codemagic Team settings, and go to codemagic.yaml settings > Code signing identities.
- Open iOS certificates tab.
- Upload the certificate file by clicking on Choose a .p12 or .pem file or by dragging it into the indicated frame.
- Enter the Certificate password and choose a Reference name.
- Click Add certificate
Note: If you do not yet have a Signing certificate, you can have Codemagic create a new certificate automatically or fetch a previously created one. Please check the iOS code signing documentation for details.
Codemagic allows you to upload a provisioning profile to be used for the application or to fetch a profile from the Apple Developer Portal.
The profile's type, team, bundle id, and expiration date are displayed for each profile added to Code signing identities. Furthermore, Codemagic will let you know whether a matching code signing certificate is available in Code signing identities (a green checkmark in the Certificate field) or not.
You can upload provisioning profiles with the .mobileprovision
extension, providing a unique Reference name is required for each uploaded profile.
- Open your Codemagic Team settings, and go to codemagic.yaml settings > Code signing identities.
- Open iOS provisioning profiles tab.
- Upload the provisioning profile file by clicking on Choose a .mobileprovision file or by dragging it into the indicated frame.
- Enter the Reference name for the profile.
- Click Add profile.
To fetch all uploaded signing files matching a specific distribution type and bundle identifier during the build, define the distribution_type
and bundle_identifier
fields in your codemagic.yaml
configuration. Note that it is necessary to configure both of the fields.
workflows:
ios-workflow:
name: iOS Workflow
# ....
environment:
ios_signing:
distribution_type: app_store # or: ad_hoc | development | enterprise
bundle_identifier: com.example.id
Note: If you are publishing to the App Store or you are using TestFlight to distribute your app to test users, set the
distribution_type
toapp_store
. When using a third party app distribution service such as Firebase App Distribution, set thedistribution_type
toad_hoc
To apply the profiles to your project during the build, add the following script before your build scripts:
scripts:
# ... your dependencies installation
- name: Set up code signing settings on Xcode project
script: xcode-project use-profiles
# ... your build commands
Add the following scripts to your codemagic.yaml
file in order to prepare the build environment and start the actual build process.
In this step, you can also define the build artifacts you are interested in. These files will be available for download when the build finishes. For more information about artifacts, see here.
scripts:
- name: Install npm dependencies and update Cordova version
script: |
npm install
npm ci # equivalent of npm install for CI systems.
# Requires package-lock.json or npm-shrinkwrap.json to be present
cvm install 9.0.0
cvm use 9.0.0
- name: Setup Cordova Android platform
script: |
ionic cordova platform remove android --nosave
ionic cordova platform add android \
--confirm \
--no-interactive \
--noresources
- name: Build Android Cordova App
script: |
ionic cordova build android \
--release \
--no-interactive \
--prod \
--device
- name: Sign APK
script: |
APK_PATH=$(find platforms/android/app/build/outputs/apk/release -name "*.apk" | head -1)
jarsigner \
-sigalg SHA1withRSA \
-digestalg SHA1 \
-keystore $CM_KEYSTORE_PATH \
-storepass $CM_KEYSTORE_PASSWORD \
-keypass $CM_KEY_PASSWORD \
$APK_PATH $CM_KEY_ALIAS
artifacts:
- platforms/android/app/build/outputs/**/*.apk
environment:
vars:
XCODE_WORKSPACE: "platforms/ios/YOUR_APP.xcworkspace"
XCODE_SCHEME: "YOUR_SCHEME"
scripts:
- name: Install npm dependencies and update Cordova version
script: |
npm install
npm ci # equivalent of npm install for CI systems.
# Requires package-lock.json or npm-shrinkwrap.json to be present
cvm install 9.0.0
cvm use 9.0.0
- name: Setup Cordova iOS platform
script: |
ionic cordova platform remove ios --nosave
ionic cordova platform add ios \
--confirm \
--no-interactive \
--noresources
- name: Cocoapods installation
script: |
cd platforms/ios && pod install
- name: Update dependencies and copy web assets to native project
script: |
# if you don't need to update native dependencies, use this:
# npx cap copy
#
# to update native dependencies, use this command:
npx cap sync
- name: Set up code signing settings on Xcode project
script: |
xcode-project use-profiles
- name: Build ipa for distribution
script: |
package_type=$(defaults read ~/export_options.plist method)
identity=$(defaults read ~/export_options.plist signingCertificate)
team=$(defaults read ~/export_options.plist teamID)
profile=$(find '/Users/builder/Library/MobileDevice/Provisioning Profiles' -name "*.mobileprovision")
profile_uuid=$(grep UUID -A1 -a "$profile" | grep -io "[-A-F0-9]\{36\}")
cat <<EOF > build.json
{
"ios": {
"release": {
"codeSignIdentity": "$identity",
"developmentTeam": "$team",
"packageType": "$package_type",
"provisioningProfile": "$profile_uuid"
}
}
}EOF
cordova build ios --release --device --buildConfig='build.json'
artifacts:
- build/ios/ipa/*.ipa
- /tmp/xcodebuild_logs/*.log
- $HOME/Library/Developer/Xcode/DerivedData/**/Build/**/*.app
- $HOME/Library/Developer/Xcode/DerivedData/**/Build/**/*.dSYM
Codemagic offers a wide array of options for app publishing and the list of partners and integrations is continuously growing. For the most up-to-date information, check the guides in the Configuration > Publishing section of these docs. To get more details on the publishing options presented in this guide, please check the Email publishing, App Store Connect and the Google Play Store publishing docs.
If the build finishes successfully, release notes (if passed), and the generated artifacts will be published to the provided email address(es). If the build fails, an email with a link to build logs will be sent.
If you don’t want to receive an email notification on build success or failure, you can set success
to false
or failure
to false
accordingly.
workflows:
sample-workflow-id:
environment:
# ...
scripts:
# ...
publishing:
email:
recipients:
- [email protected]
- [email protected]
notify:
success: true
failure: false
Configuring Google Play publishing is simple as you only need to provide credentials and choose the desired track. If the app is in draft
status, please also include the submit_as_draft: true
or promote the app status in Google Play.
kmm-android:
# ...
publishing:
google_play:
credentials: $GCLOUD_SERVICE_ACCOUNT_CREDENTIALS
track: internal
submit_as_draft: true
Codemagic enables you to automatically publish your iOS or macOS app to App Store Connect for beta testing with TestFlight or distributing the app to users via App Store. Codemagic uses the App Store Connect API key for authenticating communication with Apple's services. You can read more about generating an API key from Apple's documentation page.
Please note that:
- for App Store Connect publishing, the provided key needs to have App Manager permission,
- and in order to submit your iOS application to App Store Connect, it must be code signed with a distribution certificate.
The following snippet demonstrates how to authenticate with and upload the IPA to App Store Connect, submit the build to beta tester groups in TestFlight and configure releasing the app to App Store. See additional configuration options for App Store Connect publishing here.
Note: Please note that you will need to create an app record in App Store Connect before you can automate publishing with Codemagic. It is recommended to upload the very first version of the app manually. Suppose you have set up an app record but have not manually uploaded the app's first version. In that case, manual configuration of the settings must be done on App Store Connect after the build is complete, such as uploading the required screenshots and providing the values for the privacy policy URL and application category.
# Integration section is required to make use of the keys stored in
# Codemagic UI under Apple Developer Portal integration.
integrations:
app_store_connect: <App Store Connect API key name>
publishing:
app_store_connect:
# Use referenced App Store Connect API key to authenticate binary upload
auth: integration
# Configuration related to TestFlight (optional)
# Optional boolean, defaults to false. Whether or not to submit the uploaded
# build to TestFlight beta review. Required for distributing to beta groups.
# Note: This action is performed during post-processing.
submit_to_testflight: true
# Specify the names of beta tester groups that will get access to the build
# once it has passed beta review.
beta_groups:
- group name 1
- group name 2
# Configuration related to App Store (optional)
# Optional boolean, defaults to false. Whether or not to submit the uploaded
# build to App Store review. Note: This action is performed during post-processing.
submit_to_app_store: true
# Optional, defaults to MANUAL. Supported values: MANUAL, AFTER_APPROVAL or SCHEDULED
release_type: SCHEDULED
# Optional. Timezone-aware ISO8601 timestamp with hour precision when scheduling
# the release. This can be only used when release type is set to SCHEDULED.
# It cannot be set to a date in the past.
earliest_release_date: 2021-12-01T14:00:00+00:00
# Optional. The name of the person or entity that owns the exclusive rights
# to your app, preceded by the year the rights were obtained.
copyright: 2021 Nevercode Ltd
Having followed all of the above steps, you now have a working codemagic.yaml
file that allows you to build, code sign, automatically version, and publish your project using Codemagic CI/CD.
Save your work, commit the changes to the repository, open the app in the Codemagic UI and start the build to see it in action.
While this basic workflow configuration is incredibly useful, it is certainly not the end of the road and there are numerous advanced actions that Codemagic can help you with.
We encourage you to investigate Running tests with Codemagic to get you started with testing, as well as additional guides such as the one on running tests on Firebase Test Lab or Registering iOS test devices.
Documentation on using codemagic.yaml teaches you to configure additional options such as changing the instance type on which to build, speeding up builds by configuring Caching options, or configuring builds to be automatically triggered on repository events.