Bitrise Authentication: Methods, Credentials & Security (2026)

Authentication overview

Bitrise offers several mechanisms to authenticate users and services interacting with its platform, ensuring secure access to build processes, project settings, and data. Authentication is critical for maintaining the integrity and confidentiality of mobile application development workflows, especially in automated CI/CD environments. The choice of authentication method depends on the specific interaction: human users accessing the web UI, automated scripts or CLI tools interacting with the API, or external services sending event notifications via webhooks.

For API and CLI interactions, Bitrise primarily relies on Personal Access Tokens (PATs), which act as secure, revocable credentials. These tokens grant programmatic access with permissions scoped to the generating user. When integrating with version control systems like GitHub, GitLab, or Bitbucket, Bitrise typically uses SSH keys or OAuth-based integrations to securely clone repositories and push build statuses. Webhooks, used for triggering builds or receiving notifications from external systems, are secured with shared secrets to verify the authenticity and integrity of incoming requests.

Understanding the appropriate authentication method for each scenario, combined with adherence to security principles such as least privilege and regular credential rotation, is fundamental to securing a Bitrise-powered CI/CD pipeline. Bitrise's developer documentation provides comprehensive guides on setting up these various authentication types.

Supported authentication methods

Bitrise supports a range of authentication methods tailored for different use cases within the CI/CD ecosystem:

• Personal Access Tokens (PATs): These alphanumeric strings are used to authenticate API requests and CLI commands. PATs are associated with a user account and inherit that user's permissions, allowing programmatic access to projects, apps, and builds. They are suitable for scripting, integrations, and automated tools that need to interact with the Bitrise API. PATs can be scoped to specific permissions during creation, enhancing security by limiting potential damage if compromised.
• SSH Keys: Secure Shell (SSH) keys are primarily used for Git repository access. When you connect a Bitrise app to a source code repository, Bitrise uses an SSH key pair to securely clone the repository and fetch code for builds. This method ensures that sensitive repository credentials are not exposed directly on the build machines. Bitrise allows adding project-specific SSH keys or using a generated key for your app.
• Webhook Secrets (Shared Secrets): Webhooks are used by Bitrise to receive events from external services (e.g., Git pushes) or by Bitrise to send notifications to external services. To secure incoming webhooks, a shared secret can be configured. This secret is used to generate a hash-based message authentication code (HMAC) signature, which is then sent with each webhook request. The receiving service uses the same secret to verify the signature, ensuring the request originates from a trusted source and has not been tampered with. This is a common pattern for securing webhook payloads, as described by Mozilla's web docs.
• OAuth 2.0 (for Git Provider Integrations): While not a direct authentication method for the Bitrise API itself, OAuth 2.0 is used when connecting Bitrise to Git providers like GitHub, GitLab, or Bitbucket. This allows Bitrise to request specific permissions (e.g., read repository, post build status) from the Git provider on behalf of the user, without ever needing the user's direct credentials. This is a standard and secure way to delegate access to third-party applications.

Authentication Method Comparison

Getting your credentials

The process of obtaining credentials on Bitrise varies depending on the authentication method:

1. Personal Access Tokens (PATs):
   • Navigate to your Bitrise profile settings in the web UI.
   • Look for the 'Security' or 'Personal Access Tokens' section.
   • Click 'Create New Token'.
   • Provide a descriptive name for the token (e.g., "CI Script for Project X") and define its scope (read-only, full access, specific app access). Granting the least necessary permissions is a crucial NIST cybersecurity principle.
   • The token will be displayed once. Copy it immediately, as it will not be shown again for security reasons. Store it securely, ideally in an environment variable or a secure vault.
2. SSH Keys for Git Repositories:
   • When adding a new app on Bitrise, you will be prompted to connect your repository.
   • Bitrise can generate an SSH key pair for your app. The public key needs to be added to your Git provider (e.g., GitHub, GitLab) under the repository's deploy keys or the user's SSH keys.
   • Alternatively, you can provide your own SSH private key to Bitrise. This key should be protected with a strong passphrase.
   • For existing apps, you can manage SSH keys in the app's 'Settings' under the 'Code' or 'SSH Keys' section.
3. Webhook Secrets:
   • For incoming webhooks (e.g., from a Git provider to trigger Bitrise builds), the secret is typically configured on the Git provider's side when setting up the webhook. Bitrise provides the webhook URL, and you would then input a strong, randomly generated secret into the Git provider's webhook configuration.
   • For outgoing webhooks (Bitrise sending notifications), you configure the webhook URL and a secret in your Bitrise app's 'Code' or 'Integrations' settings. The receiving service will then use this shared secret to verify the authenticity of Bitrise's requests.

Authenticated request example

Below are examples demonstrating how to use Personal Access Tokens (PATs) for authenticating with the Bitrise API and SSH keys for Git repository access.

Bitrise API Request (using PAT)

This example shows how to list your applications using a PAT with curl. Replace YOUR_BITRISE_PAT with your actual Personal Access Token.

curl -X GET \
  https://api.bitrise.io/v0.1/apps \
  -H 'accept: application/json' \
  -H 'Authorization: YOUR_BITRISE_PAT'

In this request, the Authorization header carries the PAT, authenticating the request against your Bitrise account. The API will respond with a list of applications accessible by the token's associated user.

Bitrise CLI Usage (using PAT)

To use the Bitrise CLI (bitrise CLI), you first need to authenticate it with a PAT. After installing the Bitrise CLI, follow the getting started guide to configure your environment.

bitrise setup
# During setup, you'll be prompted to provide your Personal Access Token.
# Alternatively, you can set it as an environment variable:
export BITRISE_ACCESS_TOKEN="YOUR_BITRISE_PAT"

# Now you can use CLI commands, for example, to list apps:
bitrise apps list

Setting the PAT as an environment variable is a common and secure practice for CLI tools, as it avoids hardcoding credentials directly into scripts.

Git Repository Access (using SSH Key)

When Bitrise builds your application, it uses the configured SSH key to clone your repository. You don't directly make an authenticated request with the SSH key in your scripts; instead, you ensure the key is correctly set up in your Bitrise app settings and your Git provider. For example, if your bitrise.yml workflow includes a Git clone step, it leverages the pre-configured SSH key:

steps:
- git-clone@8:
    inputs:
      repository_url: [email protected]:your-org/your-repo.git
      branch: main

Bitrise's internal mechanisms handle the SSH authentication using the private key stored securely within the build environment, matching it against the public key registered with your Git host.

Security best practices

Implementing strong security practices for authentication on Bitrise is crucial for protecting your mobile projects and intellectual property. Adhering to these guidelines helps mitigate risks associated with credential compromise:

• Use Least Privilege: Always grant the minimum necessary permissions to Personal Access Tokens and other credentials. If a token only needs to trigger builds for a specific app, do not give it full account access. Review and apply the principle of least privilege in your access controls.
• Regularly Rotate Credentials: Periodically rotate your Personal Access Tokens and SSH keys. This limits the window of opportunity for an attacker to use a compromised credential. A common practice is to rotate tokens every 90 days.
• Store Credentials Securely: Never hardcode PATs or private keys directly into your source code or public repositories. Instead, use Bitrise's Secret Environment Variables feature to store sensitive information. These variables are encrypted and only exposed at build time to the build environment. For local development, use environment variables or a secure secrets management tool.
• Monitor Usage: Regularly review the activity logs associated with your PATs and app usage. Unusual activity, such as API calls from unexpected locations or at unusual times, could indicate a compromise.
• Use Strong Passphrases for SSH Keys: If you provide your own SSH private keys, ensure they are protected with strong, unique passphrases.
• Implement Webhook Signature Verification: For all incoming webhooks that trigger Bitrise builds or send data to your services, always configure and verify the shared secret signature. This prevents unauthorized parties from spoofing webhook events.
• Enable Two-Factor Authentication (2FA): For human users accessing the Bitrise web UI, enable 2FA on their accounts. This adds an extra layer of security, making it significantly harder for unauthorized individuals to gain access even if they have a user's password.
• Limit Token Lifespan: If possible, configure PATs with a limited lifespan. While Bitrise PATs currently do not have an expiration option, it is a good practice to manually revoke and regenerate them if they are used for short-term tasks.
• Educate Your Team: Ensure all team members understand the importance of secure credential management and follow established security protocols.

By integrating these practices into your development workflow, you can significantly enhance the security posture of your Bitrise CI/CD pipelines and protect your mobile applications throughout their lifecycle.