| titletext | description |
|---|---|
How to add custom scripts to your mobile app's build process |
Buddybuild analyzes your repository and configures the build settings. You can customize your build at various stages with custom build scripts.
|
Buddybuild automatically analyzes your repository and automatically configures itself with the best build settings. However, if you require custom logic as part of your build, you can include custom scripts in your repository to run at four points during the build:
During the build, the VM is yours. This means that you can run arbitrary operations during those four points.
|
Note
|
Looking for a detailed walkthrough and common examples? For a detailed walkthrough of how and when teams use custom build steps, and an ever growing list of examples, visit: https://www.buddybuild.com/blog/customizing-the-build-process |
This page contains several sub-sections:
{% include "/_common/important-environment_variable_scope.adoc" %}
| Variable Name | Description |
|---|---|
|
The numeric identifier for the current build. Example: |
|
A unique identifier for the current build job. Example: |
|
A unique identifier for the app. Useful if you have multiple apps in the same repo. Example: |
|
The name of the branch currently being built. Example: |
|
If the current build is a pull request, this is the name of the base
branch associated with the PR. Otherwise, this is the empty string
( Example: |
|
The repository slug using the Example: |
|
If the current build is a pull request, this is the pull request number. Example: |
|
This is the location of the source code on the VM. Example: |
|
This is the location of your secure files on the VM. Example: |
|
Indicates the condition that triggered the build. Example: Possible values:
|
|
Only available in post-build. Includes the filename in the path. Example: |
|
Only available in post-build. Includes the filename in the path. Example: |
|
This is the location of Example: |
|
The scheme used for the current build. Example: |
|
This is the location of the test product folder. Example: Inside you will find multiple files related to tests including
|
|
Note
|
Don’t see the information you need? No problem! Remember, the VM is yours at each build step. For
instance, you could expose |
You can also define your own environment variables through buddybuild’s dashboard. User-defined environment variables are stored securely and made available during the build.
The post-clone script runs immediately after git clone, before
buddybuild does any analysis of what is in the repository.
The buddybuild_postclone.sh script should be in the root of your
repository.
buddybuild_postclone.sh#!/usr/bin/env bash
# Example: Clone Parse example project
git clone https://github.com/example/ParseCloudCode
# Example: Expose the commit SHA accessible through $GIT_REVISION_SHA
# Environment Variable
export GIT_REVISION_SHA=$(git rev-parse HEAD)
# Example: Expose the commit author & email through the $GIT_REVISION_AUTHOR
# in the following format: Author Name <[email protected]>
export GIT_REVISION_AUTHOR=$(git log -1 --pretty=format:"%an <%ae>")|
Important
|
Some things you might want to do in a post-clone step:
|
|
Tip
|
See the Environment variables section if you need to access environment
variables in the |
The pre-build script runs before the build, but after buddybuild has automatically installed dependencies (eg. Cocoapods, Carthage, etc.).
Add the buddybuild_prebuild.sh script to your repository, next to
your .xcodeproj or build.gradle files.
buddybuild_prebuild.sh#!/usr/bin/env bash
# Example for adding a key to the Plist
/usr/libexec/PlistBuddy -c "Add APP_BRANCH String $BUDDYBUILD_BRANCH"|
Note
|
You might want to use a custom pre-build step if you need to do some extra dependency compilation, or add something custom to your plist. While you can use this to populate API keys or credentials, you can also access device keys that you’ve added on the dashboard through the BuddyBuildSDK without doing any custom build steps. |
|
Tip
|
See the Environment variables section if you need to access environment
variables in the |
The post-build script runs after a successful build (if the build fails, for any reason, the post-build script does not run).
Add the buddybuild_postbuild.sh script to the root of your
repository.
buddybuild_postbuild.sh#!/usr/bin/env bash
# Example of uploading a file to your archive service
curl \
-F "file=@$BUDDYBUILD_IPA_PATH" \
-F "build_number=$BUDDYBUILD_BUILD_NUMBER" \
-F "https://archiveservice.example.com|
Note
|
Typically, you would use this script to upload specific artifacts to various service integrations you might have.
Another example would be to use buddybuild_postbuild.sh#!/usr/bin/env bash
bundle install
bundle exec danger --fail-on-errors=true |
If the post-build step is not running for you, please check that you have code signing set up.
|
Tip
|
See the Environment variables section if you need to access environment
variables in the |
The finally script runs last, after the build, tests, and any deployment operations.
Add the buddybuild_finally.sh script to the root of your repository.
|
Note
|
You would use this script to perform any required operations,
whether your build, test execution, or deployment was successful or not.
You cannot use It is your last opportunity to upload any build artifacts to any service
integrations that you may have; once |
|
Tip
|
See the Environment variables section if you need to access environment
variables in the |
When some conditions required for your build to be successful are not met, you may want to manually fail the build. To do that, exit from your script with a non-zero status code. That is how buddybuild knows that the build must fail.
#!/usr/bin/env bash
if [[ "$BUDDYBUILD_BRANCH" =~ "release" ]]; then
echo "This script should only be used on release branch!"
echo "Aborting build"
exit 1
fiAnother way to fail the build is to use set -e. This causes the shell
that is running your script to exit immediately if one of the commands
in the script exits with a non-zero status. If you decide to use set
-e, place it before the commands that should cause an immediate exit
(typically, at the top of the script). For example:
#!/usr/bin/env bash
set -e
scp [email protected]:currencies.zip .
unzip currencies.zipThis example tries to fetch a remote file called currencies.zip, and
then unpacks the ZIP archive. If either command fails, they return a
non-zero status and the build fails.
Fabric is a platform that helps mobile teams build better apps. Many developers use Fabric’s Crashlytics kit to process crash reports. In order to use Crashlytics, the debug symbols file (dSYM) file needs to be uploaded.
The dSYM file is only generated when the Strip Debug Symbols setting is enabled in Xcode, in the build settings of your project. This setting is an optimization, as symbols can add a notable amount to the size of your compiled binary, and removal makes it much harder for others to reverse engineer your code.
When Strip Debug Symbols is enabled, the symbol names of objects within your app are removed from the compiled binary, and are written to the dSYM file. The dSYM file is useful for re-symbolicating crash reports.
Fabric includes an upload-symbols script that you can call anywhere in
your build process to upload your dSYMs. That script is included in
Fabric’s CocoaPod payload at $PODS_ROOT/Fabric/upload-symbols.
To upload your dSYMs to Fabric:
-
Create (or update)
buddybuild_postbuild.shin the root of your repository so that it contains the following lines:#!/usr/bin/env bash echo "Uploading IPAs and dSYMs to Crashlytics" CRASHLYTICS_API_KEY=Your_API_key echo "Uploading to Fabric via command line" $BUDDYBUILD_WORKSPACE/Fabric.framework/upload-symbols -a $CRASHLYTICS_API_KEY -p ios "$BUDDYBUILD_PRODUCT_DIR"
-
Commit the changes to your repository:
git add buddybuild_finally.sh git commit -m "Copy dSYMs to Crashlytics" git push -
Ensure that Build for archive is enabled in the buddybuild Dashboard for your app. If this setting is not enabled, the
dSYMsdirectory is not created and so nothing can be uploaded to Crashlytics.
For more information, see Crashlytics' Advanced Setup.
If your builds produce assets that you’d like to use in other contexts, you need to upload those assets to some persistent storage because the buddybuild VM used to build your app is deleted upon build completion; only app binaries, test results, and logs are normally saved.
You can use the buddybuild_postbuild.sh custom script to copy assets
to persistent storage such as Amazon’s Simple Storage Service, or S3.
The following example uses
environment variables to
provide your Amazon AWS credentials, and the awscli tool to perform
the upload to S3.
-
Setup the following environment variables in the buddybuild dashboard, using the appropriate values for your AWS account:
-
AWS_ACCESS_KEY_ID: your AWS access key. -
AWS_SECRET_ACCESS_KEY: your AWS secret access key. -
AWS_DEFAULT_REGION: defaults tous-west-2.
-
-
Create (or update)
buddybuild_postbuild.shin the root of your repository so that it contains the following lines:#!/usr/bin/env bash aws s3 cp my_build_asset.file s3://mybucket/Replace
my_build_asset.filewith the filename of a build artifact that you wish to copy to S3. Replacemybucketwith the identifier for the destination bucket on S3. Add as manyawscommands as required to copy each build artifact. -
Commit the changes to your repository:
git add buddybuild_finally.sh git commit -m "Copy assets to S3" git push
For more information, see:
Swiftlint is a tool to enforce Swift style and conventions. You can install it manually from a custom build step:
brew install swiftlintIf you’re running SwiftLint as part of an Xcode Run Script phase,
you will need either a buddybuild_postclone.sh file or
a buddybuild_prebuild.sh one.
For more information, see the
official documentation.
As with everything, if you need help with anything, please get in touch via Intercom or email [email protected] and we will find the best way to solve your problem.