Skip to main content

Adding and managing apps

Abstract

You can add new apps on Bitrise with the API: add the app, generate SSH keys, and set up the app’s initial configuration.

You can add new apps on Bitrise with the API: add the app, generate SSH keys, and set up the app’s initial configuration.

In addition, you can list all apps belonging, for example, to a single user or to a specific Workspace.

Adding a new app with the API

Table 1. Endpoints used in adding a new app with the Bitrise API

Endpoints

Function

Required role on the app's team

POST /apps/register

Add a new app.

N/A

POST /apps/{app-slug}/register-ssh-key

Add an SSH key to a specific app.

Owner or Admin

POST /apps/{app-slug}/finish

Save the application at the end of the application add process.

N/A

POST /apps/{app-slug}/bitrise.yml

Upload a new bitrise.yml for your application.

Owner or Admin


Apps with HTTPS Git URLs

The procedure and the examples are aimed at adding a private app with an SSH git URL. If you want to add an app with an HTTPS git URL, you can skip adding an SSH key.

  1. Register the app by calling the register endpoint and setting all required parameters.

    You need to set your git provider, the repository URL, the slug of the repository as it appears at the provider, and the slug of the owner of the repository. You also need to add the slug of the Workspace that will own the app: due to legacy naming conventions, you need the organization_slug parameter.

    curl -X POST -H 'Authorization: ACCESS-TOKEN' 'https://api.bitrise.io/v0.1/apps/register' -d \
    '{
          "provider": "github",
          "is_public": false,
          "organization_slug": "$ORG_SLUG"
          "repo_url": "git@github.com:api_demo/example-repository.git",
          "type": "git",
          "git_repo_slug": "example-repository",
          "git_owner": "api_demo"
     }'      
  2. Once done, call the register-ssh-key endpoint to set up the SSH keys you created so that Bitrise can clone your repository when running a build.

    You need to provide both your private and public SSH key. Please note that if you wish to copy the private key manually, you need to escape all the line breaks with \n.

    You can also set whether you want to automatically register the public key at your git provider: set the is_register_key_into_provider_service parameter to either true or false.

    curl -X POST -H 'Authorization: ACCESS-TOKEN' 'https://api.bitrise.io/v0.1/apps/APP-SLUG/register-ssh-key' -d \
    '{
        "auth_ssh_private_key": "your-private-ssh-key",
        "auth_ssh_public_key": "your-public-ssh-key",
        "is_register_key_into_provider_service": false
     }'  
  3. Finish the app registration process by calling the finish endpoint.

    This endpoint allows you to configure your apps: set the project type, the stack on which the build will run (this may vary based on your app), and the initial configuration settings.

    You can also set Environment Variables, as well as immediately specify a Workspace that will be the owner of the application. Please note that the mode parameter must be set to the value of manual.

    curl -X POST -H 'Authorization: ACCESS-TOKEN' 'https://api.bitrise.io/v0.1/apps/APP-SLUG/finish' -d \
    '{
         "project_type": "ios",
         "stack_id": "osx-xcode-13.2.x",
         "config": "default-ios-config",
         "mode": "manual",
         "envs": {
               "env1": "val1",
               "env2": "val2"
         },
         "organization_slug": "e1ec3dea540bcf21"
     }'
    

Managing an existing app

Table 1. Endpoints related to managing an existing app with the Bitrise API

Endpoints

Function

Required role on the app's team

GET /apps

Get list of your apps.

Any

GET /apps/{app-slug}

Get a specific app.

Any

GET /apps/{app-slug}/bitrise.yml

Get the bitrise.yml of a specific app.

Owner or Admin

GET /apps/{app-slug}/branches

List the branches of an app’s repository.

Any

GET /organizations/{org-slug}/apps

Get list of the apps for a Workspace.

Any

GET /users/{user-slug}/apps

Get list of the apps for a user.

Any


The response to any GET request regarding one or more apps will contain the app slug, its project type, the git provider, the repository’s owner and URL:

{
  "data": [
    {
      "slug": "eeeeefffff00000",
      "title": "sample-app",
      "project_type": "android",
      "provider": "github",
      "repo_owner": "example-user",
      "repo_url": "git@github.com:example-user/sample-app.git",
      "repo_slug": "android-gradle-kotlin-dsl",
      "is_disabled": false,
      "status": -1,
      "is_public": false,
      "owner": {
        "account_type": "organization",
        "name": "Test Org",
        "slug": "fffffeeeee00000"
      },
      "avatar_url": null
    },
    {

You can also download the existing bitrise.yml file of any app: the response will contain the full YAML configuration.