Bitrise Getting Started: CI/CD Setup for Mobile Apps (2026)

Getting started overview

Getting started with Bitrise involves a sequence of steps that configure the platform to build and test your mobile application automatically. The process typically begins with creating a Bitrise account, followed by connecting a code repository and defining a build workflow. Bitrise is specialized for mobile development, offering pre-configured steps for common tasks such as signing iOS apps or running Android unit tests. The platform integrates with various version control systems, including GitHub, GitLab, Bitbucket, and Azure DevOps, allowing for automated trigger builds on code pushes or pull requests.

This guide outlines the initial setup, from account creation and obtaining necessary credentials to executing your first automated build. Understanding the core concepts of Bitrise, such as apps, workflows, and steps, is essential for effective use of the platform. Bitrise provides a web-based user interface for most configurations, complemented by a command-line interface (CLI) for local testing and advanced automation Bitrise getting started guide.

Here's a quick reference table for the initial setup:

Create an account and get keys

To begin using Bitrise, navigate to the Bitrise pricing page and select a plan. A free Starter tier is available, supporting up to 2 concurrent builds, 45 minutes of build time, and 1 user. After selecting a plan, you will proceed to account creation, which can be done using an email address or by authenticating through a supported version control system like GitHub, GitLab, or Bitbucket. Using a version control system for signup simplifies the subsequent process of adding your mobile application.

Personal Access Tokens (PATs) and API Tokens

For programmatic interaction with Bitrise, such as using the Bitrise CLI or integrating with external tools, you will need to generate API tokens. Bitrise distinguishes between Personal Access Tokens (PATs) and App API Tokens:

• Personal Access Tokens (PATs): These tokens are tied to your user account and grant access to multiple apps, depending on your permissions. PATs are suitable for CLI usage or scripts that manage multiple Bitrise applications under your user scope. To generate a PAT, navigate to your Bitrise Profile settings.
• App API Tokens: These tokens are specific to a single Bitrise application and are used for interacting with that particular app's API. They are useful for integrations where you want to grant access only to a specific project. App API tokens can be found in the "Code" tab of your application's settings on Bitrise.

It is recommended to store these tokens securely and restrict their permissions to the minimum necessary for their intended use. Treat all API tokens as sensitive credentials.

Your first request

A "first request" in the context of Bitrise typically refers to successfully running your first automated build, which involves cloning your repository, executing build steps, and generating an artifact. This process demonstrates the core functionality of the platform. While Bitrise does offer a comprehensive Bitrise API reference for programmatic interaction, the initial "first request" is usually a GUI-driven build.

Steps to run your first build:

1. Add your application: After signing in, click "Add your first app" or the "+" icon to add a new app. You will be prompted to:

   • Select an account (your personal account or an organization).
   • Choose your privacy setting (Public or Private).
   • Select your Git provider (e.g., GitHub, GitLab, Bitbucket). Bitrise will require authorization to access your repositories.
   • Select the repository containing your mobile project.
   • Choose the branch you want to build (e.g., main or develop).

2. Set up repository access: Bitrise will automatically set up an SSH key or deploy key for repository access. Confirm the auto-detection or manually provide the necessary key Bitrise adding an app.

3. Stack and project scanner: Bitrise will analyze your repository to detect the project type (e.g., iOS, Android, Flutter, React Native) and suggest a suitable virtual machine stack (e.g., macOS for iOS, Ubuntu for Android). It will also try to auto-configure the project, such as detecting the Xcode project file or Android build.gradle.

4. Initial workflow setup: Based on the project detection, Bitrise will suggest an initial workflow. This workflow typically includes steps for installing dependencies, running tests, and archiving the application. You can accept the default or customize it using the Workflow Editor.

5. Trigger the first build: Once the initial setup is complete, Bitrise will offer to trigger the first build. Click the button to start the build process. You can monitor the progress and view the build logs in real-time on the Bitrise dashboard.

6. Review build results: Upon completion, the build will show a status (success or failure). Examine the build logs to understand each step's outcome and troubleshoot any issues. A successful first build confirms that Bitrise can access your repository, build your project, and execute the defined workflow.

For advanced users who prefer a command-line approach, the Bitrise CLI allows for local testing of bitrise.yml workflow configurations, mirroring the cloud environment. This can be particularly useful for debugging complex build issues before pushing changes to your remote repository.

Common next steps

After successfully running your first build on Bitrise, several common next steps enhance your CI/CD pipeline:

• Explore the Workflow Editor: Bitrise's Workflow Editor is a graphical interface for defining and managing your build steps. You can add, remove, and reorder steps, configure inputs and outputs, and create multiple workflows for different scenarios (e.g., a "pull request" workflow that only runs tests, and a "release" workflow that builds and deploys). Common steps include installing dependencies (e.g., npm, CocoaPods, Gradle), running unit tests, UI tests, code analysis, and deploying to app stores or internal distribution platforms like Firebase App Distribution Firebase App Distribution documentation.

• Set up environment variables and secrets: Securely manage sensitive information such as API keys, signing credentials, and configuration values using Bitrise environment variables and secrets. Secrets are encrypted and not logged, making them suitable for production credentials Bitrise environment variables and secrets.

• Configure branching and triggering: Define when Bitrise should trigger a new build. You can configure automatic triggers based on pushes to specific branches, pull request events, or scheduled intervals. This ensures that your CI/CD pipeline runs consistently with your development workflow.

• Integrate with third-party services: Bitrise offers a wide range of integrations with developer tools and services. This includes code quality tools, testing platforms, notification services (e.g., Slack), and deployment targets (e.g., Apple App Store, Google Play Store, Microsoft App Center).

• Artifact management: Configure steps to store and manage build artifacts, such as APKs, IPAs, test reports, and symbol files. Bitrise provides built-in artifact storage, and you can also integrate with external storage solutions.

Troubleshooting the first call

If your first Bitrise build fails, the build logs are the primary resource for diagnosing issues. Here are common problems and troubleshooting steps:

• Repository access issues:

  • Error: "Failed to clone repository" or "Authentication failed."
  • Solution: Verify that Bitrise has the correct SSH key or deploy key configured for your repository. Ensure the key has read access. If you're using a private repository, confirm that Bitrise has been granted necessary permissions on your Git provider (e.g., GitHub App permissions).

• Missing dependencies:

  • Error: "Command not found" for tools like npm, pod (CocoaPods), or gradle. Missing packages or modules.
  • Solution: Ensure your workflow includes steps to install all necessary project dependencies. For example, add a "Run npm command" step before your build step for JavaScript projects, or a "CocoaPods install" step for iOS projects. Check if your Podfile.lock or package-lock.json is committed to the repository.

• Project configuration errors:

  • Error: "Xcode project not found", "Gradle build failed", or similar messages indicating the build tool cannot find or process your project.
  • Solution: Review the project path configurations in your Bitrise workflow steps. Ensure the paths to your Xcode workspace/project file or Android build.gradle are correct. Sometimes, Bitrise's auto-detection might pick an incorrect path if multiple project files exist.

• Environment variable issues:

  • Error: Build fails due to missing environment variables (e.g., API keys, build flavors).
  • Solution: Confirm that all required environment variables are correctly set in the Bitrise workflow or app-level environment variables. Pay attention to whether they are marked as "is_secret" if they contain sensitive data.

• Build timeout:

  • Error: "Build timed out."
  • Solution: This indicates the build took longer than the allocated time for your Bitrise plan. Optimize your workflow to reduce build duration, or consider upgrading your Bitrise plan if longer build times are consistently needed.

• Caching issues:

  • Error: Inconsistent build results or slower builds.
  • Solution: Implement caching steps (e.g., for Gradle, CocoaPods, npm modules) to reuse dependencies between builds, speeding up subsequent runs. Ensure your caching strategy invalidates caches when dependencies change Bitrise caching basics.

If you cannot resolve the issue using the logs, consult the Bitrise DevCenter troubleshooting section or contact Bitrise support.