Deployment API is live!

Hi Canaries, super excited to share that the Deployment Pipeline and Workflow APIs are live! They are under the API Explorer described as “startExectution”

image

We just released the docs around the feature as well: https://docs.harness.io/article/s3leksekny-trigger-workflow-or-a-pipeline-using-api

I know teams want examples, here are some of my examples of using it!

The Workflow

My objective in this article is to share how I deployed a basic Fargate Pipeline via API.

So I first queried the by Application Name and Returned Application ID and PipelineID

query {
  applicationByName(name:"Harness Demo"){
    id
    name
    pipelines(limit:4){
      nodes{
        id
        description
      }
    }
  }
}

After getting the correct information, I created the startExecution Mutation to execute the deployment.
I need to pass the Application ID and Pipeline ID as inputs. Based on my mutation, I want to return notes, execution id, and application id.

  startExecution (input:$startExecution){
    clientMutationId
    execution {
      notes
      id
      application{
        id
      }
    }
  }
}

So for the Parameters to execute the query, I passed the information below:

{
  "startExecution": {
    "applicationId": "<YOUR APPLICATION ID>",
    "notes": "Demo",
    "executionType": "PIPELINE",
    "entityId": "<YOUR PIPELINE ID>",
    "serviceInputs": {
      "name": "fargate-nginx",
      "artifactValueInput": {
        "buildNumber": {
          "buildNumber": "1.10.1",
          "artifactSourceName": "library_nginx"
        },
        "valueType": "BUILD_NUMBER"
        }
    }
  	}
}

Once, passing in these parameters, I received a return payload and the pipeline executed!

{
  "data": {
    "startExecution": {
      "clientMutationId": null,
      "execution": {
        "notes": "Demo",
        "id": "<YOUR EXECUTION ID>",
        "application": {
          "id": "<YOUR APPLICATION ID>"
        }
      }
    }
  }
}

and I also see in the Continuous Deployment Page this beautiful deployment!

In the UI, we tell the user what triggered the deployment. In this example we show that the Admin API key was used to deploy this pipeline.


For our Scripters, here is a sample script with the startExecution API call:

#ARGUMENTS
APPLICATIONID="<YOUR APPLICATION ID>"
PIPELINEID="<YOUR PIPELINE ID>"
BUILDNO="<YOUR BUILD NO>"
SERVICENAME="<YOUR SERVICE NAME>"
ARTIFACTSOURCENAME="<YOUR ARTIFACT SOURCE>"
# Execute Pipeline
func_execute_pipeline(){
	curl --request POST \
	  --url 'https://app.harness.io/gateway/api/graphql?accountId='$HARNESS_ACCOUNT_ID'' \
	  --header 'content-type: application/json' \
	  --header 'x-api-key:'$HARNESS_KEY' \
	  --data '{"query":"\nmutation($startExecution: StartExecutionInput!){\n  startExecution (input:$startExecution){\n    clientMutationId\n    execution {\n      notes\n      id\n      application{\n        id\n      }\n    }\n  }\n}","variables":{"startExecution":{"applicationId":"'$APPLICATIONID'","notes":"Demo","executionType":"PIPELINE","entityId":"'$PIPELINEID'","serviceInputs":{"name":"'$SERVICENAME'","artifactValueInput":{"buildNumber":{"buildNumber":"'$BUILDNO'","artifactSourceName":"'$ARTIFACTSOURCENAME'"},"valueType":"BUILD_NUMBER"}}}}}'
}

also for the Get Application by Name Script Sample:

# Get Application By Name
APPNAME="<YOUR APP NAME>"
func_getAppByName(){
curl --request POST \
  --url 'https://app.harness.io/gateway/api/graphql?accountId='$HARNESS_ACCOUNT_ID'' \
  --header 'content-type: application/json' \
  --header 'x-api-key:'$HARNESS_KEY' \
  --data '{"query":"query {\n  applicationByName(name:\"'$APPNAME'\"){\n    id\n    name\n    pipelines(limit:4){\n      nodes{\n        id\n        description\n      }\n    }\n  }\n}\n\n"}'
}

Security
These API Calls are tied to either the user login session in the UI, meaning the user that is logged in. The user is tied to a user group and that user group will have a certain set of permissions assuming the group is not admin. The user will only be able to trigger deployments based on the access the user has. This means, if you don’t have access to a particular application, you will not be able to trigger that workflow or pipeline.

The API Key given to teams is tied to a user group. Therefore the permissions the user group is granted will restrict what the user can do with the API. If the usergroup doesn’t have execute permissions to workflows or pipelines then they won’t be able to deploy via API as they don’t have access to do it in the UI either.

Use the new power wisely! Cheers :slight_smile:

4 Likes

I’ve added this successfully to our developer tooling now, it’s very impressive! Ours is written in Ruby, so I could use the graphql-client gem to do all the hard work - we just define the queries and pass in the variables.

This makes it easy for our engineers to quickly start a deployment with our usual parameters, and select between different environments and pipelines by using a few extra command line options. We’ve also been able to add a lookup of git branch names into artifact build numbers which wasn’t possible through the web UI.

I’m hoping to add some monitoring of the execution next as well as giving users the link to the web UI.

3 Likes