To add your iOS or Android project to Appcircle, you need to complete the following checklist The list is divided into sub-sections.
Before building the project on Appcircle, it should be checked whether it builds properly on your local computer. Frequently, the developers do not send the changes on their local computer, or their changes may not end up on the repo because of .gitignore file. The following steps should be followed to check that the project can be built without errors. If possible, these steps should be tried in a virtual machine, if not, with a different user or folder.
- Clone the repo to another folder
- If it's an iOS project and using Cocoapods or Carthage, run pod install or carthage bootsrap.
- Build the project.
If you get any errors, correct them and push them to your repo. Since Appcircle always starts a machine from scratch. Appcircle should have access to all files required to build your project.
If your projects builds without an error, you need to complete the following sections.
- Extra suggestions
FirewallAccessing Repositories in Internal Networks (Firewalls)
The person who will add the repository to Appcircle must be the owner of the repository. If the owner of the repository has too many repositories, a bot user can be created just for Appcircle so that only the required repositories can be accessed.
Repo access is achieved for GitHub and Gitlab by installing an app to the repository. The user who added the repo must have the required access to add the application
If your repo is Self Hosted with Gitlab or Bitbucket, your repo will be added with an Access Token.
You will need to generate Personal Access Token or Project Access Token for Gitlab. Personal Access Token allows to access all the repositories of that person. Project Access Token allows to access all the repositories under the specified project.
Bitbucket also allows using repository tokens to access a single repository. Personal Access Token allows to access all the repositories of that person. Project Access Token allows to access all the repositories under the specified project.
Appcircle needs admin permission to function properly. The admin permission is needed to create relevant WebHooks automatically.
If the dependencies used by the repo are in a different project or that person does not have access to that repo, the project will throw an error while building. So the added token must have access to all the dependencies needed to build the project.
If the extra libraries you use are in a private repo, these repositories must be accessible with the tokens we mentioned above. If this is not possible, these libraries should be accessed in one of the following ways.
- SSH Private Key
- .netrc file
SSH Private Key
You will need to create a new SSH key and upload the public key to your Repo and the private key to Appcircle. These files can be created easily by following the document below.
The .netrc file contains login and initialization information used by the auto-login process. You can use this component to add credentials for hosts such as your repositories or external hosts. Git automatically recognizes the .netrc file
To upload artifacts to the App Store or GooglePlay, the files must be signed. The files listed below must be uploaded to Appcircle's Signing Module
There are 2 types of signing for iOS, Manual and Automatic.
Manual Signing requires you to upload the provisioning profile for each bundle id. For Automatic code signing, only 2 certificates and App Store Connect Key must be added.
- Distribution Certificate. The certificate must be uploaded as .p12 file. It would be better to create a distribution certificate from scratch for Appcircle.
- Provisioning profiles created with the above certificates. After uploading the Provisioning profile files, a green checkmark image will appear next to the entry. If it does not appear, you may need to refresh the page. If the error persists, it means that the certificate file is missing on Appcircle.
Automatic signing can be used for projects that can be built with Xcode 13 and later. This requires the following
- 1 Distribution Certificate
- 1 Development Certificate
- App Store Connect API Key
When the above credentials are provided, Xcode automatically creates provisioning profiles and signs the application. It is important to add both development and distribution certificates. If you do not provide the required certificates, Xcode will constantly create new certificates in your account.
The only thing that needs to be installed for Android is the keystore file you used to sign the project. Simply uploading this file will often not be sufficient for signing. You will also need to make changes to the build.gradle file and sign it with the keystore installed on the Appcircle environment. Please check the following document for this process.
App Store, Google Play, or Huawei App Gallery keys must be added to Appcircle to upload IPA or APK files. To create these files, the following documents can be followed.
- It will be better to manage confidential or constantly changing information with Environment Variables. This will allow you to get different outputs by selecting different variable groups without changing your code.
- It is important that the versions you use for React Native and Flutter are written on the config screen. If you don't set a version, it will be built with the latest version.
- If you are using React Native, you can turn off Flipper with the following change in the Podfile. This will shorten your build times.
post_install do |installer|
- If you are using CocoaPods, SwiftPM or Carthage, you need to commit Podfile.lock Package.resolved and Cartfile.resolved files. When these files are not available, the wrong versions may be installed.
- You should not make any local changes to your pods. If you are going to make a change, you must fork the original pod and make the changes in that fork. Appcircle must have the access to the same code as you have on your local machine.
- Don't forget to add your gradle folder to your repo. Appcircle uses ./gradlew command to build your poject. Therefore, if that file does not exist, the build will fail
- You may experience Gradle build errors if your project uses Bintray resources. Since JFrog has shutdowned Bintray on May 1, 2021. You should update your
build.gradlefile and move it to Maven Central. Replace
mavenCentral()in all your
build.gradlefiles. Please be aware that some of your dependencies may not exist on Maven.
- If you are using jitpack in your project, it will be useful to upload these dependencies to
mavenCentral(). It is recommended to create your Maven repo to host your dependencies. Jitpack has reliability issues and you may not experience those issues on your local computer since your builds use cache. However, Appcircle will download your dependencies each time you start a build and Jitpack may create a problem in the long run.