Adding and managing apps

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.

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"
 }'      
```
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
 }'  
```
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.

Uploading a new bitrise.yml file

Required role

You must have an admin or owner role on the app's team to upload a new bitrise.yml file.

For a complete list of user roles and role cheatsheets, check User roles on app teams.

The bitrise.yml file contains the configuration of your builds. You can modify the current one via the API by posting a full YAML configuration. In the below example, we are:

Creating a bitrise.yml with format version 11.
Setting the Bitrise Step Library as the default Step source.
Setting the stack to Xcode 14.
Setting the BITRISE_PROJECT_PATH Environment Variable to point to the build.gradle file.
Adding a Script Step.
Creating a trigger map that triggers the primary Workflow if code is pushed to any branch of the app's repository.

curl --fail -X POST -H "Authorization: $ACCESS_TOKEN" "https://api.bitrise.io/v0.1/apps/$APP_SLUG/bitrise.yml" -d \
'{
  "app_config_datastore_yaml": {
    "format_version": 11,
    "default_step_lib_source": "https://github.com/bitrise-io/bitrise-steplib.git",
    "meta": {
      "bitrise.io": {
        "stack": "osx-xcode-14.0.x"
      }
    },
    "app": {
      "envs": [
        {
          "BITRISE_PROJECT_PATH": "build.gradle",
          "opts": {
            "is_expand": false
          }
        }
      ]
    },
    "workflows": {
      "primary": {
        "steps": [
          {
          "script@1": {}
          }
        ]
      }
    },
    "trigger_map": [
      {
        "push_branch": "*",
        "workflow": "primary"
      }
    ]
  }
}'

By calling this endpoint, you replace the app’s current bitrise.yml file. You can, of course, modify this uploaded bitrise.yml either via the API or on the website itself.