Create deployments with the Deployment push API

In many cases, you can use git tags to identify and configure your deployments in Flow. In some circumstances, git tags may not be the best option for your organization. In these cases, use Flow’s Deployment push API to send deployment information to Flow regardless of git tag usage.

The Deployment push API is currently in beta and available only to select customers. Reach out to your Flow contact if you’re interested in joining the beta.

Permissions

Users using the Deployment push API must have a valid API key and the Deployment Push API permission. To enable API permissions for users, you must have the Manage User Permissions permission. Learn more about administrative permissions and API keys in Flow.

If a user does not have both the Deployment Push API permission and an API key, they can't use the Deployment push API. If your user can't GET or POST data via the Deployment push API, verify they have both the permission and a valid API key.

To enable the Deployment Push API permission for a user, make sure the permission is added to at least one role they are assigned to.

Prerequisites

In addition to the required permissions, Flow also needs:

The repositories you want deployments for to be imported into Flow. Learn more about managing repositories.
The integration containing the repositories to be in a healthy data status. Learn more about integration data statuses.
The Deployment push API deployment source to be enabled for the repositories. Each repository can only have one deployment source enabled at a time.
We strongly recommend setting up deployment inclusion rules for all repositories so you only see the correct deployments in Flow.

To make it easier to set up deployment sources and inclusion rules for all your repositories, use the Actions for all integrations menu on the integrations page or the Actions for all repos menu on the Repos page to set these up in bulk.

Calling the API

Call the API endpoint over standard HTTPS. Use any tool or programming language that can add the authorization: bearer <API Key> header.

The base URL for the API is https://api.appfireflow.com.

Deployment format

The API expects you to send your deployments in the following format:

{	
	"repo_url": "https://github.com/exampleorg/examplerepo.git",
    "vendor_id": 775604895,
	"deployment_identifier": "Release-123",
	"deployment_sha": "47ab9c17702d84484d9900cc33333683a4428292",
	"deployment_sha_list": ["cdfe00c0883643dc89bfbe0a2f3f30fdddc7fc02", 
							"0900ffa907adfc0cfb8392fb4d255730b63e8007", 
							"09d6f277a915a49c8e353819e5a3737dd62468a4", 
							"060583a642705f331a5d7f271fe9faefb2767d78"],
}

Repository URL: You must provide the complete repository URL to link your deployment to the repository project.
- Ensure the URL is properly formatted with scheme, hostname, org, repository name and in some specific cases suffix like .git will also be required.
- To locate the accepted repository URL and its format, open the repository details page for your repository in Flow, then copy the link from the Visit URL button.
Vendor ID: The unique ID assigned to your repository by your vendor. Find your vendor ID on the Repos page.
Deployment Identifier: The unique identifier for your deployment. This could be a release version number, a build number, or any other text that distinguishes this deployment.
- Setting up this identifier is critical to being able to reliably set up deployment inclusion rules to filter deployments that are sent to Flow.
Deployment SHA: The unique hexadecimal SHA value to identify your deployment. This should be the commit SHA for the commit associated with the deployment. It should be in a format similar to: 060583a642705f331a5d7f271fe9faefb2767d78
Deployment SHA List: The list commit SHAs from this deployment in a list format.

Endpoints

URL	Method	Input JSON / Query parameters	Example response

URL	Method	Input JSON / Query parameters	Example response
`/dora-push-api/deployment`	POST	`{ "repo_url": "https://github.com/exampleorg/examplerepo", "vendor_id": 775604895, "deployment_identifier": "Release-123", "deployment_sha": "asf93wnsfiq31", "deployment_sha_list": ["asf93wnsfiq31", "asf93wnsfiq31", "asf93wnsfiq31", "asf93wnsfiq31"], }`	`{ "message": "Data loaded successfully", "request_id": "e754cc82e9194b3abfd096b73ae56a9d" }`
`/dora-push-api/deployment`	GET	`/?repo_url=https://github.com/Git-Prime/terraform-bc-infrastructure&vendor_id=775604895&deployment_sha=asf93wnsfiq31`	`{ "id": "4070::https://github.com/exampleorg/examplerepo::775604895", "deployment_identifier": "Release-123", "deployment_sha": "asf93wnsfiq31", "deployment_sha_list": [ "asf93wnsfiq31", "asf93wnsfiq31", "asf93wnsfiq31", "asf93wnsfiq31" ], "timestamp": "2024-07-30T04:42:29.290019" }`

Common Responses

Failure - Unable to identify Flow organization

Status Code: 401

Response JSON:

{
"error": "Org ID not found in the authorizer"
}

Failure - User does not have the required permission

Status Code: 401

Response JSON:

{
"error": "You do not have permission to perform this action"
}

Failure - Unable to identify permissions for the user

Status Code: 401

Response JSON:

{
"error": "Authorizer data not found"
}

Failure - Unallowed method

Status Code: 405

Response JSON:

{
"error": "Unsupported HttpMethod: <unsupported method name>"
}

Failure - Other exceptions

Status Code: 500

Response JSON:

{
"error": "Unable to process: error: <error text>"
}

Response for POST

Success

Status Code: 200

Response JSON:

{
"message": "Data loaded successfully",
"request_id": "e754cc82e9194b3abfd096b73ae56a9d"
}

Failure - Missing parameters

Status Code: 400

Response JSON:

{
"error": "Missing required data: <missing parameters>"
}

Failure - Unhealthy integration

Status Code: 400

Response JSON:

{
"error": "Integration for this project is not in a healthy state. Integration Id: 123456"
}

Failure - Unable to insert deployment data

Status Code: 500

Response JSON:

{
"error": "Error while loading data to DynamoDB: <error text>"
}

Response for GET

Success

Status Code: 200

Response JSON:

{
    "id": "4070::https://github.com/exampleorg/examplerepo::775604895",
    "deployment_identifier": "Release-123",
    "deployment_sha": "asf93wnsfiq31",
    "deployment_sha_list": [
        "asf93wnsfiq31",
        "asf93wnsfiq31",
        "asf93wnsfiq31",
        "asf93wnsfiq31"
    ],
    "timestamp": "2024-07-30T04:42:29.290019"
}

Failure - Missing parameters

Status Code: 400

Response JSON:

{
"error": "Missing required data: <missing parameters>"
}

Failure - Unable to retrieve data/Other technical errors

Status Code: 500

Response JSON:

{
"error": "Error while fetching data from DynamoDB: <error text>"
}