Managing files in Generic File Storage

Abstract

You can upload, delete, update, and list any project files to the Generic File Storage on Bitrise. You can access the files either via the API or in the Workflow Editor.

You can upload, delete, update, and list any project files in the GENERIC FILE STORAGE section of Bitrise.

Table 1. Endpoints related to the Generic File Storage

Endpoints	Function	Required role on the app's team
POST/apps/{app-slug}/generic-project-files	Create a generic project file	Owner or Admin
POST/apps/{app-slug}/generic-project-files/{generic-project-file-slug}/uploaded	Confirm the upload process	Owner or Admin
PATCH/apps/{app-slug}/generic-project-files/{generic-project-file-slug}	Update an uploaded project file	Owner or Admin
GET/apps/{app-slug}/generic-project-files	Get a list of the uploaded project files	Owner or Admin
GET/apps/{app-slug}/generic-project-files/{generic-project-file-slug}	Retrieve data of a specific project file	Owner or Admin
DELETE/apps/{app-slug}/generic-project-files/{generic-project-file-slug}	Delete an uploaded project file	Owner or Admin

Creating and uploading files to the Generic File Storage

Required role

You must have an admin or owner role role on the app's team to manage files in the Generic File Storage using the Bitrise API.

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

You can add new files to an application and store it in the GENERIC FILE STORAGE . When calling the relevant API endpoint, a new temporary pre-signed upload URL is created which you will use to upload the file to the GENERIC FILE STORAGE. (Please note that this pre-signed URL is time-limited and expires after 10 minutes.)

You'll need to:

Call the POST method of the generic-project-files endpoint.

This call creates a temporary pre-signed upload URL that contains a file slug which you will need later. The required parameters are:
- slug: the app slug of the Bitrise app. You can get the slug by opening the app on Bitrise and copying it from the URL of the main page, or by calling the GET /apps endpoint and finding your app in the list.
- upload_file_name: the name of the file, including the file extension. For example, MyFile.txt. The file should be in the same folder where the command is run.
- upload_file_size: the size of the file in bytes. On macOS, you can get the file size by running the stat -f%z <filename> command.
- user_env_key: you can add any name to the user env key.
Upload the file to AWS using the pre-signed upload URL.
Confirm the file upload with the POST method of the generic-project-files/GENERIC-PROJECT-FILES-SLUG/uploaded endpoint, using the slug from the response containing your pre-signed upload URL.

This sets the processed flag to true which means the file is now available on Bitrise. This flag can't be changed again afterwards!

Example 1. Creating and uploading a file

Creating the temporary pre-signed upload URL:

curl -X POST "https://api.bitrise.io/v0.1/apps/<APP-SLUG>/generic-project-files" -H "accept: application/json" -H "Authorization: <ACCESS-TOKEN>" -H "Content-Type: application/json" -d "{ \"upload_file_name\": \"Test_File.md\", \"upload_file_size\": 4865, \"user_env_key\": \"Test_File\"}"

Response:

{
  "data": {
    "upload_file_name": "Test_File.md",
    "upload_file_size": 4865,
    "slug": "<GENERIC-PROJECT-FILE-SLUG>",
    "processed": false,
    "is_expose": true,
    "is_protected": false,
    "upload_url": "https://concrete-userfiles-production.s3.us-west-2.amazonaws.com/project_file_storage_documents/uploads/24043/original/Test-File?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAIV2YZWMVCNWNR2HA%2F20190402%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20190402T125827Z&X-Amz-Expires=600&X-Amz-SignedHeaders=content-length%3Bhost&X-Amz-Signature=e1557901d5a07b1b3578d9ffdf84a9b0188b742bfff9c8175a3e87f12c7e2c4e",
    "user_env_key": "Test_File",
    "exposed_meta_datastore": null
  }
}

Uploading the file to AWS:

curl -T Test_File.md "<UPLOAD_URL>"

Confirming the file upload:

curl -X POST -H 'Authorization: <ACCESS-TOKEN>' 'https://api.bitrise.io/v0.1/apps/<APP-SLUG>/generic-project-files/<GENERIC-PROJECT-FILES-SLUG>/uploaded'

Response:

{
  "data": {
    "upload_file_name": "Test_File.md",
    "upload_file_size": 4865,
    "slug": "<GENERIC-PROJECT-FILE-SLUG>",
    "processed": true,
    "is_expose": true,
    "is_protected": false,
    "user_env_key": "Test_File",
    "exposed_meta_datastore": null
  }
}

Retrieving a specific file's data

Required role

You must have an admin or owner role role on the app's team to manage files in the Generic File Storage using the Bitrise API.

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

Retrieve a specific file’s data from the Generic File Storage with the GET method of the generic-project-files endpoint. The returned data includes, among other things, the file's name, size, and download URL, as well as its current status.

The required parameters are:

App slug
Generic project file slug

Example 1. Retrieving a file

Request:

 curl -X GET -H  'Authorization: <ACCESS-TOKEN>' 'https://api.bitrise.io/v0.1/apps/<APP-SLUG>/generic-project-files/<GENERIC-PROJECT-FILE-SLUG>'

Response:

{
  "data": {
    "upload_file_name": "Test_File.md",
    "upload_file_size": 4865,
    "slug": "01D7F228E7N8Q8WQJKJM8FV3XM",
    "processed": true,
    "is_expose": true,
    "is_protected": false,
    "download_url": "https://concrete-userfiles-production.s3.us-west-2.amazonaws.com/project_file_storage_documents/uploads/24043/original/Test-File?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAIV2YZWMVCNWNR2HA%2F20190402%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20190402T132712Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=241be52184b63867262360743931c546c166a99719787ce417e3be11bc12bbed",
    "user_env_key": "Test_File",
    "exposed_meta_datastore": null
  }
}

Availability of the `download_url`

Note that the download_url is generated only when the provisioning profile’s is_protected attribute is false.

Listing the uploaded files of an app

Required role

You must have an admin or owner role role on the app's team to manage files in the Generic File Storage using the Bitrise API.

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

Get a list of an app's files that were uploaded to the Generic File Storage using the GET method. Please note that the maximum number of files is 50.

The required parameter is:

App slug

Optional parameters are:

next: slug of the first file in the response (as a string)
limit: max number of elements per page (as an integer)

Example 1. Listing the apps

Request:

curl -X GET -H 'Authorization: <ACCESS-TOKEN>' 'https://api.bitrise.io/v0.1/apps/<APP-SLUG>/generic-project-files'

Response:

{
  "data": [
    {
      "upload_file_name": "realmtasks.jks",
      "upload_file_size": 2068,
      "slug": "a37f6a0ff582f4ea",
      "processed": true,
      "is_expose": true,
      "is_protected": false,
      "user_env_key": "ANDROID_KEYSTORE",
      "exposed_meta_datastore": null
    },
    {
      "upload_file_name": "Test_File.md",
      "upload_file_size": 4865,
      "slug": "01D7F228E7N8Q8WQJKJM8FV3XM",
      "processed": true,
      "is_expose": true,
      "is_protected": false,
      "user_env_key": "Test_File",
      "exposed_meta_datastore": null
    }
  ],
  "paging": {
    "total_item_count": 2,
    "page_item_limit": 50
  }
}

As you can see, the example response shows the list of files specific to an app. Files uploaded to the ANDROID KEYSTORE SECTION and to the GENERIC FILE STORAGE are both shown. This is due to that the fact that Android keystore files are specific generic project files but represented in a separate UI field from generic project files.

Deleting a file from the Generic File Storage

You can delete your uploaded file from the Generic File Storage using the DELETE method.

Required role

You must have an admin or owner role role on the app's team to manage files in the Generic File Storage using the Bitrise API.

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

The required parameters are:

App slug
Generic project file slug

curl -X DELETE -H "Authorization:<ACCESS-TOKEN>" "https://api.bitrise.io/v0.1/apps/<APP-SLUG>/generic-project-files/<GENERIC-PROJECT-FILES-SLUG>"

In this section:

Managing files in Generic File Storage

Creating and uploading files to the Generic File Storage

Required role

Retrieving a specific file's data

Required role

Availability of the download_url

Listing the uploaded files of an app

Required role

Deleting a file from the Generic File Storage

Required role

Search results

Availability of the `download_url`