Skip to main content

Integrating Azure DevOps

In this section we explain how to create CI pipelines on Azure DevOps that interact with nullplatform to reflect the status of your build and to upload the assets to crete a release.

Pipelines​

To interact with nullplatform to create a build, generate assets, and finalize the build process, you are encouraged to use the Azure Pipelines extension developed by nullplatform. This extension contains several tasks that allow you to perform these activities.

info

This extension is in a private beta release. If you want to try it, please contact us and we will share the extension with your organization.

Variable group​

When you create or import an application in nullplatform, we create a variable group named nullplatform where we configure all the variables needed to interact with us. One of the more relevant variables is the NULLPLATFORM_API_KEY that allows you to get a token to interact with our API.

variable groups

Tasks​

Login​

This task gets a temporary token to communicate with our CI API.

Inputs:

  • apiKey: the one that was previously defined in the variable group, it is necessary to get access tokens.

Outputs:

  • access-token: used by the other tasks to authenticate against the nullplatform's API. Each task can access directly to this value. You do not need to use it manually.

Usage:

- task: NullplatformLogin@0
    inputs:
      apiKey: '$(NULLPLATFORM_API_KEY)'
    name: NullplatformLogin

Metadata​

This task retrieves from nullplatform information about your application, which will be used in further tasks of the build process.

Usage:

- task: NullplatformMetadata@0 
    inputs:
      resource: application
    name: NullPlatformApplicationMetadata

This task outputs a metadata string variable with a JSON containing the required information for the build process. For example:

[
  {
    "id": 1710580793,
    "name": "Documentation",
    "code_repository": {
      "url":  "https://dev.azure.com/myorg/myapp",
      "application_path": null
    }
  }
]
Monorepos

If your repository is a monorepo, instead of a single result, you will get an array with all the nullplatform applications contained in the repository.

Parameter​

Use this task to get output variables with the necessary information to generate the assets of your application.

Usage:

task: NullplatformParameter@0
  inputs:
    applicationId: $(applicationId)
  name: NullplatformApplicationParameters
  displayName: "Get build parameters"

As input, it receives one of the application ids that you got previously from the NullplatformMetadata task.

As result of this task, you get output variables with the necessary information to generate the assets of your application. For example, if you are building a docker image application, you will have the following output variables:

  • BUILD_AWS_ACCESS_KEY
  • BUILD_AWS_SECRET_ACCESS_KEY
  • BUILD_AWS_REGION

Later, in the pipeline, you can use these variables like this:

"$(NullplatformApplicationParameters.BUILD_AWS_ACCESS_KEY)"

Build​

Use this task to signal nullplatform about creation, updates, and finalization of a build in nullplatform.

Create a new build:

- task: NullplatformBuild@0
    inputs:
      action: create
      status: pending
      applicationId: '$(applicationId)'
    name: CreateBuild
    displayName: "Creating build in Nullplatform"

Update the build's status:

- task: NullplatformBuild@0
    inputs:
      action: update
      id: $(CreateBuild.id)
      status: in_progress
    name: UpdateBuild
    displayName: "Update build in Nullplatform"

Finalize the build with success or failure:

- task: NullplatformBuild@0
    inputs:
      action: update
      id: $(CreateBuild.id)
      status: $(npBuildStatus)
    name: FinalizeBuild
    displayName: "Finalize Nullplatform build"
    condition: always()

Asset​

Use this task to create assets for your build. Examples of assets are docker-images and lambda functions.

As input of this task you need the build ID that was generated when you created the build.

Example for a docker-image asset:

- task: NullplatformAsset@0
    inputs:
      buildId: $(CreateBuild.id)
      action: create
      type: 'docker-image'
    name: Asset
    displayName: "Create asset for build"

As the output you will get output variables with asset information. The variables are:

  • id: the asset IID.
  • buildId: the ID of the associated build.
  • name: the name of the asset (eg: "main").
  • type: docker-image, lambda.
  • targets: this is a json string containing a collection of urls by provider where the asset must be uploaded. For example: 
    [
        {
          "provider": "aws-ecr",
          "url": "aaa.dkr.ecr.us-east-1.amazonaws.com/namespace/application-documentation:yyy-main"
        }
    ]
  • metadata: the asset associated metadata (this is a key-value object).

Templates​

Templates allow you to group the most import actions in relevant groups, making pipelines shorter. Here are some examples that showcase how to achieve this.

Example: single repository, application, and docker image asset​

Initiate the interaction with nullplatform:​
steps:
  - task: NullplatformLogin@0
    inputs:
      apiKey: '$(NULLPLATFORM_API_KEY)'
    name: NullplatformLogin

  - task: NullplatformMetadata@0 
    inputs:
      resource: application
    name: NullPlatformApplicationMetadata

  ## As it's only one application, we save the first application id in the variable $applicationId to be used in next tasks.
  - task: PowerShell@2
    inputs:
      targetType: 'inline'
      script: |
        $applicationsMetadata = ConvertFrom-Json -InputObject '$(NullPlatformApplicationMetadata.metadata)'
        $applicationId = $applicationsMetadata[0].id
        $applicationName = $applicationsMetadata[0].name
        Write-Host "##vso[task.setvariable variable=applicationId]$applicationId"
        Write-Host "##vso[task.setvariable variable=applicationName]$applicationName"
    displayName: 'Save first application into build context'

  ## Create and update to "in progress" the Nullplatform build
  - task: NullplatformBuild@0
    inputs:
      action: create
      status: pending
      applicationId: '$(applicationId)'
    name: CreateBuild
    displayName: "Creating build in Nullplatform"

  - task: NullplatformBuild@0
    inputs:
      action: update
      id: $(CreateBuild.id)
      status: in_progress
    name: UpdateBuild
    displayName: "Update build in Nullplatform"

Here we grouped the login task, application metadata task and initiated the build in nullplatform

Build your assets​
steps:
  - task: NullplatformAsset@0
    inputs:
      buildId: $(CreateBuild.id)
      action: create
      type: 'docker-image'
    name: Asset
    displayName: "Create asset for build"

  ## Build the docker image
  - script: |
      docker build -t $(Asset.name) .
    displayName: 'Build docker image'

Here we create docker-image asset in nullplatform, and we use the given asset name to build a Docker image using the Docker CLI.

Push your assets​
steps:
  - task: PowerShell@2
    inputs:
      targetType: 'inline'
      script: |
        $assetTargets = ConvertFrom-Json -InputObject '$(Asset.targets)'
        $assetTargetUrl = $assetTargets[0].url
        Write-Host "##vso[task.setvariable variable=assetTargetUrl]$assetTargetUrl"
    displayName: 'Save asset target into build context'

  - script: |
      export AWS_ACCESS_KEY_ID="$(NullplatformApplicationParameters.BUILD_AWS_ACCESS_KEY)"
      export AWS_SECRET_ACCESS_KEY="$(NullplatformApplicationParameters.BUILD_AWS_SECRET_ACCESS_KEY)"
      export AWS_DEFAULT_REGION="$(NullplatformApplicationParameters.BUILD_AWS_REGION)"
      export ECR_REGISTRY=$(echo "$(assetTargetUrl)" | cut -d '/' -f 1)
      aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $ECR_REGISTRY
      docker tag $(Asset.name) $(assetTargetUrl)
      docker push $(assetTargetUrl)
      echo "##vso[task.setvariable variable=npBuildStatus]successful"
    displayName: 'Push docker image'

Here we tag and push the previous build to the image registry using the variables obtained from the NullplatformApplicationParameters task.

Finalize the build​

Finally, using this task you can inform nullplatform that the build has finalized.

- task: NullplatformBuild@0
    inputs:
      action: update
      id: $(CreateBuild.id)
      status: $(npBuildStatus)
    name: FinalizeBuild
    displayName: "Finalize Nullplatform build"
    condition: always()

Using these four templates you can craft the following pipeline:

trigger:
- master

pool: 'Default'

variables:
- name: npBuildStatus
  value: 'failed' # the build fails until the opposite is indicated. The nullplatform-asset-push.yml sets this variable to successful.
- group: nullplatform

steps:
  #the first template of this example
- template: .azure/templates/nullplatform-start.yml
  
- task: NullplatformParameter@0
  inputs:
    applicationId: $(applicationId)
  name: NullplatformApplicationParameters
  displayName: "Get build parameters"

  #the second template of this example
- template: .azure/templates/nullplatform-asset-build.yml

  #the third template of this example
- template: .azure/templates/nullplatform-asset-push.yml

  #the last template of this example
- template: .azure/templates/nullplatform-end.yml