Freshservice DevOps Extension for Azure DevOps Pipeline

Introduction

The Freshservice DevOps extension for Azure DevOps Pipelines enables seamless integration between Azure DevOps and Freshservice. This extension provides comprehensive support for change management within your CI/CD pipelines by allowing you to create a change in FS, associate a pipeline run to a change, and gate pipeline runs based on a Freshservice Change.

Features and Use Cases

Figure 1: List of Freshservice DevOps tasks available in Azure DevOps Pipeline.

Create a Change

The extension allows users to create a change record in Freshservice from both Server Tasks and Agent Tasks within an Azure DevOps Pipeline Build. This task also associates the current pipeline run with the newly created Freshservice change, ensuring traceability and alignment between development and IT operations.

Example Use Case: A developer triggers a build that automatically creates a change request in Freshservice, documenting the deployment for ITSM purposes.

Associate Pipeline Run to a Change

If a change already exists in Freshservice, users can associate the current pipeline run with this existing change by providing the ChangeId. This feature is available for both Agent and Server Tasks, enhancing the flexibility of your DevOps and Change management.

Example Use Case: An IT admin associates a pipeline run with an existing change that was created manually or via another automation process, ensuring the deployment aligns with change management policies.

Using Variables for ChangeId

Azure DevOps allows the use of variables to make pipeline configurations more dynamic and reusable. You can pass the ChangeId as a variable when running the pipeline, which can then be referenced in the task configuration.

Steps to Use Variables for ChangeId:

1. Define the Variable in the Pipeline Define the ChangeId as a variable in your pipeline configuration. This can be done in the pipeline YAML file or through the pipeline's UI.

   YAML Example:

   variables:
     freshserviceChangeId: '123456' # Replace with your actual ChangeId
   

   UI Example:

   1. Go to your Azure DevOps pipeline.
   2. Click Edit.
   3. Select the Variables tab.
   4. Add a new variable, for example, freshserviceChangeId with a value of 123456.

2. Reference the Variable in the Task Configuration In the task configuration, use the variable syntax $(variableName) to reference the ChangeId variable.

   YAML Example:

   - task: FreshService-Agent-Associate-Pipeline-Run@1
     inputs:
       changeId: $(freshserviceChangeId)
   

   UI Example:

   • Add the "Associate Pipeline Run to Freshservice Change" task to your pipeline.
   • In the ChangeId field, use the variable syntax $(freshserviceChangeId).

   In these examples, the changeId parameter of the task is set to the value of the freshserviceChangeId variable.

3. Passing the Variable at Runtime If you want to pass the ChangeId at runtime, you can override the variable when you queue the pipeline.

   UI Example:

   • Click Run pipeline.
   • Under Variables, provide the desired ChangeId value.

   YAML Example:

   jobs:
   - job: AssociateChange
     variables:
     freshserviceChangeId: $(ChangeId) # Passed at runtime
     steps:
      - task: FreshService-Agent-Associate-Pipeline-Run@1
        inputs:
        serviceConnection: 'Freshservice Connection'
        changeId: '$(freshserviceChangeId)'
   

Example Use Case: A release manager sets the ChangeId as a variable to dynamically associate different pipeline runs with different Freshservice changes based on the deployment environment or release schedule.

Note: The ChangeId variable should be defined and passed correctly to ensure the task functions as expected.

Gate a Pipeline Run using Freshservice Change

This feature enables gating of pipeline runs based on the status of a Freshservice change. By configuring a gating task in the Approvals and Checks of an Environment, users can specify a desired status for the change. The pipeline will proceed only if the change reaches the specified status, providing robust control over deployment workflows.

Example Use Case: A release manager configures a pipeline to proceed only if the associated change request is approved and marked as "Implemented," preventing unapproved changes from being deployed.

Installation and Configuration

Prerequisites

• An Azure DevOps organization
• A Freshservice account with Change and DevOps access
• Necessary permissions in Azure DevOps and Freshservice

Installation Steps

1. Navigate to the Azure DevOps Marketplace.
2. Search for "Freshservice DevOps."
3. Click on the extension and choose "Get it free." We hope you are already in this page. Why not click 'Get it free' now and try it out?
4. Follow the prompts to install the extension to your Azure DevOps organization.

Configuration in Azure DevOps

1. Go to your Azure DevOps project.
2. Navigate to the pipeline where you want to use the extension.
3. Add the relevant Freshservice tasks (Create Change, Associate Pipeline Run, Gating Check) to your pipeline.

Setting Up Service Connections

Before using the Freshservice DevOps tasks, you need to configure a service connection in Azure DevOps to connect to your Freshservice account. This service connection will be used by the tasks to authenticate and interact with Freshservice.

Creating a Freshservice Service Connection

1. Navigate to your Azure DevOps project.
2. Click on the Project settings (gear icon) in the lower-left corner.
3. Under Pipelines, select Service connections.
4. Click New service connection and select Freshservice server connection from the list and click Next.
5. Provide the necessary details:
   • Freshservice Domain: Your Freshservice domain (e.g., yourcompany.freshservice.com).
   • API Key: The API key from your Freshservice account. You can generate this in Freshservice under Profile settings.
   • Service Connection Name: A friendly name for the connection (e.g., "Freshservice Connection").
6. Check Grant access permission to all pipelines to use the connection in all pipelines, then click Save.

Figure 2: Creating a Freshservice Service Connection in Azure DevOps

Using the Service Connection

When configuring tasks in your pipeline, select the Freshservice DevOps service connection from the dropdown to use it for authentication and interaction with Freshservice.

Usage Guide

Creating a Change

1. Add the "Create Freshservice Change" task to your pipeline.
2. Configure the task with necessary details like Change Type, Description, and Change Impact.

Associating a Pipeline Run to a Change

1. Add the "Associate Pipeline Run to Freshservice Change" task to your pipeline.
2. Enter the ChangeId of the existing Freshservice change you want to associate.
3. Enter the ChangeId or use a variable for the ChangeId to dynamically associate the pipeline run.
   • Example: $(freshserviceChangeId)

Configuring Gating Tasks

1. Add the "Freshservice DevOps Release Gate" task in the Approvals and Checks section of your environment.
2. Input the ChangeId and the desired status for the gating check. You may have doubt on "How to use the existing ChangeId here?". You can refer to the FAQ section for more details.
3. Configure the control options to determine how frequently the status should be checked and the Timeout .

Figure 2: Configuring a Freshservice Gating Task in Azure DevOps

Tips and Advanced Usage

Using Variable Libraries with Gating Tasks

In Azure DevOps, variables defined within a YAML pipeline are not accessible in Gating Tasks configured in the Approvals and Checks of an environment. To bridge this gap, you can use the Azure DevOps Variable Library to store and access the ChangeId. Change Creation Task sets the ChangeId as an output variable, which can be stored in the Variable Library and referenced in Gating Tasks.

Steps to Update and Use the Variable Library for Gating Tasks:

1. Create a Change and Store the ChangeId in a Variable Library

   YAML Example to Create a Change and Store ChangeId:

   stages:
   - stage: CreateChange
     jobs:
     - job: CreateChangeJob
       steps:
       - task: Freshservice-Agent-Change-Creation@1
         name: CreateChange
         inputs:
           serviceConnection: 'Freshservice Connection'
           changeType: 'Normal'
           description: 'Automated change for deployment'
           otherDetails: '...'
   
      ### to update the variable library using powershell
      - task: PowerShell@2
        name: UpdateVariableLibrary
        inputs:
          targetType: 'inline'
          script: |
            $project = "$(System.TeamProject)"
            $org = "$(System.CollectionUri)"
            $token = "$(System.AccessToken)"
            $groupId = "YourVariableGroupId" 
            $groupName = "YourVariableGroupName"  
            $changeId = "$(CreateChange.FsChangeId)"
   
            $body = @{
                name = $groupName
                type = "Vsts"
                variables = @{
                    YourVariableName = @{
                        value = $changeId
                        isSecret = $false
                    }
                }
            } | ConvertTo-Json
   
            $uri = "$org$project/_apis/distributedtask/variablegroups/$groupId/?api-version=5.0-preview.1"
            Write-Output "URI: $uri"
            Write-Output "Body: $body"
   
            $response = Invoke-RestMethod -Uri $uri -Method Put -Body $body -ContentType "application/json" -Headers @{Authorization = "Bearer $token"}
            Write-Output "Response: $response"
        env:
          SYSTEM_ACCESSTOKEN: $(System.AccessToken)
   
   

Configure the Gating Task to Use the Library Variable

In your Azure DevOps environment, configure the gating task to reference the ChangeId from the Variable Library.

UI Example:

1. Go to the Approvals and Checks configuration in the desired environment.
2. Add the "Freshservice DevOps Release Gate" task.
3. In the ChangeId field, input $(ChangeId) or $(YourVariableName) to use the variable from the Variable Library. (need to choose the right variable group in the Linked Variable Group dropdown below)

Support and Troubleshooting

For support, visit our support page or contact us at support@freshservice.com.

Common Issues:

• Authentication Errors: Ensure API keys and credentials are correctly configured.
• Task Failures: Verify pipeline and task configurations against the documentation.

FAQs

Q: Can I use this extension in YAML pipelines?
A: Yes, the extension supports both classic and YAML pipelines. But, we are looking forward to support only YAML pipelines in the future.

Q: Is there a way to revert a pipeline run if a change fails?
A: This feature needs to be handled by your rollback strategy within the pipeline.

Q: How do I find the ChangeId in Freshservice?
A: The ChangeId can be found in the URL of the change request in the Freshservice portal or via the Freshservice API.

Q: How do I use the ChangeId from a YAML pipeline in a Gating Task? A: You can use the Azure DevOps Variable Library to store and access the ChangeId from a YAML pipeline in Gating Tasks as mentioned above.

Additional Resources

• Freshservice API Documentation
• Azure DevOps Documentation