curl --request POST \
  -H 'Content-Type: application/json' \
  -H 'OAUTH-TOKEN: <your-oauth-token>' \
  -d '{
        "deployment": {
          "source": {
            "head": {
              "name": "main"
            },
            "name": "Add feature X",
            "version": "abc123def456"
          },
          "stage": {
            "branch": {
              "name": "deploy-main"
            },
            "environment": "production",
            "target_directory": "/home/src/project_name"
          }
        },
        "api_key": "zkWlN0PkIKSN0C11CfUHUj84OT5XOJ6tDZ6bDRO2"
      }' \
  --url https://your-mage-instance.com/api/deployment_settings/prod/deployments

Trigger a deployment using a specific deployment setting.

POST /deployment_settings/{setting_name}/deployments

setting_name
string
required

Name of the deployment setting to use for this deployment. Find the deployment setting name on your Mage Pro cluster’s /apps/deploy page.

deployment.source.head.name
string
required

The name of the GitHub branch where the commit is located (e.g., main, feature/xyz).

deployment.source.name
string
required

A human-readable description of the commit (e.g., GitHub commit message).

deployment.source.version
string
required

The GitHub commit SHA that will be deployed.

deployment.stage.branch.name
string
required

The branch name in the target deployment environment (e.g., deploy-main).

deployment.stage.environment
string
required

The environment where the deployment will be created (e.g., development, staging, production).

deployment.stage.target_directory
string

Optional. The directory path inside the deployment environment where the code will be deployed.

curl --request POST \
  -H 'Content-Type: application/json' \
  -H 'OAUTH-TOKEN: <your-oauth-token>' \
  -d '{
        "deployment": {
          "source": {
            "head": {
              "name": "main"
            },
            "name": "Add feature X",
            "version": "abc123def456"
          },
          "stage": {
            "branch": {
              "name": "deploy-main"
            },
            "environment": "production",
            "target_directory": "/home/src/project_name"
          }
        },
        "api_key": "zkWlN0PkIKSN0C11CfUHUj84OT5XOJ6tDZ6bDRO2"
      }' \
  --url https://your-mage-instance.com/api/deployment_settings/prod/deployments