BEST PRACTICES

Common Issues and Troubleshooting

Repository Connection Issues

Please note that currently only Git repositories are supported. Any third party version control repositories need to be transferred to a proper Git repository on either Github or Bitbucket.

How to change your connected GitHub, Bitbucket or GitLab account?

You will need to go to your Github, Bitbucket or GitLab account and revoke access to Appcircle and then reconnect your account from Appcircle.

Unable to see the repositories in the connected repository provider

Please check if you have owner/admin access in the specific organization from which the repositories will be connected. Appcircle does not allow connections to the repositories with a member-level access.

Unable to grant access to an GitHub organization

If you are unable to grant access to a specific organization while connecting to GitHub, it is likely that the permission for Appcircle needs an update from the organization application access settings.

To resolve, go to Organization Settings ->Third-party access and press edit next to Appcircle to authorize it for the organization.

Issues in connecting to the repositories with SSH

For the SSH connections, a key pair in PEM format is required. The public key is entered/stored in the Git provider while the private key is entered in Appcircle.

Please refer to this guide for the commands to generate a compatible key pair for SSH connections.

Accessing internal/on-premise repositories

The only available option for connecting to the internal/on-premise repositories is to use SSH and whitelist Appcircle resources if the repositories are not accessible from the public internet.

Please refer to this guide for connecting to the repositories in internal networks.

How to connect to AWS CodeCommit repositories through SSH?

AWS CodeCommit requires the creation of a dedicated user for repository connections through SSH (i.e. the root user cannot be used for this purpose).

Please refer to this guide for creating a user for SSH connections.

  • First, create a user in AWS IAM and assign the following permissions to the user:

  • Go to IAM -> Users -> User -> Security credentials and select "Upload SSH key".

  • Take a note of the SSH key ID generated by AWS as follows:

  • Once you login with the newly generated user and copy the repository URL in SSH format, you will receive URL as follows: ssh://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyDemoRepo

  • For the SSH connection to be initialized, you need to add the public key to your URL to have it in the following format, which then can be entered in Appcircle to be used in SSH connections.ssh://[email protected]/v1/repos/MyDemoRepo

How to enable triggers for AWS CodeCommit repositories?

Appcircle supports AWS CodeCommit triggers through an Amazon SNS topic.

For more information, please refer to: https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-notify-sns.html

After you follow the steps in the referenced document above to create a trigger, you need to create a notification rule under CodeCommit Settings as shown below to add a webhook URL.

Then select the "Enable raw message delivery" option while adding the webhook URL as a subscription to the topic.

General Build Troubleshooting

There may be a bunch of reasons for a build to fail.

Best way to learn the reason is to check the build logs. See Working With Build Logs section for details on this.

Build logs will display everything happened in each workflow step in details and let you examine what went wrong during the build.

If you are unable to determine the exact cause, feel free to get in touch with Appcircle using the in-app messaging for additional support.

Troubleshooting Workflow Steps for Build Failures

Most build failures are related with the following build steps. If you encounter any errors, please remove or edit the following steps and get a build to help isolate the cause of the issue.

  • iOS Sign Errors: If the selected provisioning profile does not match with the selected bundle ID or if the certificate is not valid, you may have an issue in the iOS signing step. In this case, you may try getting an unsigned build

  • Xcode Build for Simulator step: This step is required to use the Preview on Device feature and it requires the app to be built for the x86 architecture. In some projects, there may be dependencies that are not compatible with x86. In this case, please remove this step from the workflow or remove the conflicting dependencies to get a successful build.

  • Android Sign Errors: If you encounter errors while signing your Android app, you can remove this step to get an unsigned build or you can configure the app signing within your project.

Build is Taking Too Long

With every build, a brand new virtual machine is started to perform your workflow and build your application.

Some applications may have 3rd party dependencies which need to be installed before the build is performed. With every new build, these dependencies need to be re-installed.

One way to speed up the build time may be to manage your dependencies in your project. This will speed up your builds significantly if your application has excess amount of dependencies to be installed.

If you still think that your build is taking significantly longer than it should, please feel free to get in touch with Appcircle for additional support.

iOS-Specific Issues

Xcode Scheme Errors

Your iOS application project needs to have a shared scheme in order to be built outside Xcode. Xcode doesn't share schemes by default so you will have to do it manually.

  1. On Xcode, select Product > Scheme > Manage Schemes

  2. Select Shared for your xcproject or xcworkspace

  3. Scheme container needs to be set to the corresponding Xcode project or workspace

  4. Please do not forget to add your .xcscheme file to version control so it will be uploaded to your Git repository

For details on iOS builds please refer to Building iOS Applications

Cocoapods Errors Due to Missing xcworkspace

If you receive a pod error similar to the following, this usually indicates that although pods are used, the build is done with an xcodeproj file:

error: .../_appcircle_temp/Repository/Obj-C/Pods/Target Support Files/Pods-AEPSampleAppObjC/Pods-AEPSampleAppObjC.release.xcconfig: unable to open file (in target "AEPSampleAppObjC" in project "AEPSampleAppObjC") (in target 'AEPSampleAppObjC' from project 'AEPSampleAppObjC')

If a pod is used, the xcworkspace must be pushed to the repository and it must be selected in the build configuration for a successful build.

If you don't want to push the xcworkspace to the repository, you can alternatively enter the xcworkspace path manually in the build configuration. In this case, the xcworkspace will be generated by the Cocapods workflow component.

Provisioning Profile Error

If you receive a provisioning profile error similar to the following, it usually indicates a mismatch between the bundle ID selected in the build configuration and the provisioning profile.

error: "MyProject" requires a provisioning profile. Select a provisioning profile in the Signing & Capabilities editor. (in target MyProject from project MyProject)

In such an error, please check if the correct bundle ID is selected for the build. This is especially the case if you are using different bundle IDs for different release types such as debug or release.

Swift Version Error

If you receive an error similar to the following, the selected Xcode version in the build configuration may be incompatible with the selected Swift version in the project settings.

SWIFT_VERSION '3.0' is unsupported, supported versions are: ...

In this case, you need to upgrade the Swift version in the project settings in Xcode and once the build is confirmed to be working locally in the specific Xcode version, it can be retried in Appcircle with the same Xcode version.

Android-Specific Issues

I received a google-services.json Error but I don't want to push this file to the repository

Secret files such as the google-services.json can be added as a secret environment variable and then selected in the build configuration.

Then, you can add a custom script step before the Android build step and move the file to the expected path during the build with a code like the following (where the secret environment variable is named as GOOGLE_SERVICES_JSON) :

Bash
Bash
cd $AC_REPOSITORY_DIR/
mv $GOOGLE_SERVICES_JSON $AC_REPOSITORY_DIR/app

Flutter release mode binaries does not work on the Android emulator

To run a Flutter release mode APK in an emulator, please make sure that the emulator runs with the x86_64 ABI type and the app is configured accordingly. Emulators with x86 ABI type are not supported by Flutter . (Please refer to the following GitHub issue on the Flutter repository for more information: https://github.com/flutter/flutter/issues/28432)

Android Keystore Errors

Missing keystore path error on Android builds

You may want to build unsigned Android applications. Most common mistake done with this is Appcircle users usually forget to disable Sign Application step in the workflow.

If you do not select a keystore in the build configuration, you need to disable the Sign Application step or your build will fail.

Keystore was tempered with or password was incorrect

You may get this error message when the provided password doesn't match the keystore file.

If you are using a debug keystore, simply re-generate it. Otherwise, please make sure you have the correct keystore/password combination.

Flutter-Specific Issues

No pubspec.yaml file found error

If the pubspec.yaml file is not present in the default project path, it cannot be detected automatically by the fetch process. In such cases, the file path must be manually defined in the Flutter Build workflow step as the value of the $AC_FLUTTER_PROJECT_DIR environment variable.

For reference, please refer to the Android Flutter Build and iOS Flutter Build components.

React Native-Specific Issues

NPM/Yarn specific errors

If you face problems during NPM/Yarn install steps on Appcircle but not on your local machine, you should confirm the following steps:

  • Make sure that your packages support the node version you use.

  • Make sure that the file interactions that is done on preinstall and/or postinstall scrips are suitable to be executed on a different machine

Appcircle uses the latest(stable) node version by default.

You can access how to change your node version and other relative information about workflow steps and configurations on the page below:

App Distribution Troubleshooting

No files or multiple files received from autodistribute

A successful distribution depends on a correctly signed binary. Please check if the signing configuration is correct.

You can also check the list of the generated build artifacts to confirm the output. In Android, you can also check the ac_post_process_output.json file in the build artifacts to see if the APKs are signed or not.

In Android, please also check if gradle sign is being used for the selected build variant. If gradle sign works alongside with Appcircle signing, you will receive multiple APKs.

Deleted versions still occupy storage space

The master version of any artifact deployed from the Build to the Distribute module is stored within the build artifacts section. Once you delete such a version from the Distribute module, only the reference is removed and the binary is still available within the build artifacts of the related build. You also need to remove the binary from the build artifacts to save storage.

Access Denied on builds

On some distributed apps, the Access Denied error can be bypassed by one of these steps:

  • Launching the distribution link on a different browser and Incognito Mode

  • Clearing the browser cache if the link if pasted to a browser instead of in-line browser on mail applications

  • If there is an authorization configuration on Distribution, clearing the authorization temporarily