A Guide to Using GraphQL with IBM DevOps Velocity
IBM DevOps Velocity provides powerful insights into value stream management, allowing teams to optimize their DevOps pipelines. One of its key features is GraphQL, a query language that enables users to efficiently retrieve, filter, and analyze data from Velocity’s value stream.
What is GraphQL?
GraphQL is a flexible and efficient query language for APIs, allowing clients to request only the required data. Unlike REST APIs, which return fixed data structures, GraphQL enables users to customize queries and fetch related data in a single request.
In IBM DevOps Velocity, GraphQL queries help users analyze the flow of work items, deployments, commits, and other DevOps artifacts across integrated tools.
Setting Up GraphQL in IBM DevOps Velocity
Before diving into querying, you’ll need to authenticate and set up the GraphQL IDE for use in IBM DevOps Velocity:
-
Create a User Access Key: The User Access Key is your authentication token.
-
Access GraphQL IDE: Navigate to the Velocity instance’s GraphiQL interface. You can usually access this via https://my_velocity:port/graphiql.
-
Authenticate: In the GraphiQL interface, click the "Set Headers" icon and input your authorization information by adding Authorization in the Header key field and pasting the User Access Key in the value field.
Once authenticated, you’re ready to interact with the GraphQL API. GraphQL allows you to interact with Velocity without accessing the UI.
In this blog, we’ll explore the most commonly used GraphQL mutations and queries with Velocity to help you efficiently manage pipelines, stages, applications, and value streams.
We’ve structured this in two sections:
Mutations:
1. Create a ValueStream
A ValueStream in IBM DevOps Velocity represents the flow of work items through your DevOps pipeline. It helps you visualize how work moves from one stage to another across various tools in the pipeline.
To create a new value stream, you can use the following GraphQL mutation:
mutation {
createValueStream(
name: "string"
description: "string"
tenantId: "_____"
team: { id: "string", name: "string" }
workflow: "_____"
)
}
Example: The below mutation will create a new ValueStream named GraphQL-VSM:
mutation {
createValueStream(
name: "GraphQL-VSM",
description: "test",
tenantId: "5ade13625558f2c6688d15ce",
team: { id: "5ade13625558f2c6688d15ce", name: "Default Team" },
workflow: {
_id: "66bc7b633e7318fe7d77ec00",
tenantId: "5ade13625558f2c6688d15ce",
name: "Planning",
description: "test",
query: "",
phases: [
{
name: "Planning",
description: "",
stages: [
{
name: "Backlog",
query: "",
description: "",
targets: ["To Do"],
wipLimit: 10,
showAlerts: false,
showSpeed: false
},
{
name: "To Do",
query: "",
description: "",
targets: ["In Progress"],
wipLimit: null,
showAlerts: true,
showSpeed: false
}
]
},
{
name: "Development",
description: "",
stages: [
{
name: "In Progress",
query: "",
description: "",
targets: ["In Review"],
wipLimit: null,
showAlerts: true,
showSpeed: true
},
{
name: "In Review",
query: "",
description: "",
targets: ["Completed"],
wipLimit: null,
showAlerts: true,
showSpeed: true
}
]
},
{
name: "Completed",
description: "",
stages: [
{
name: "Completed",
query: "",
description: "",
targets: [],
wipLimit: null,
showAlerts: false,
showSpeed: false
}
]
}
],
leadTimeChange: {
start: null,
end: null
},
leadTime: {
start: "Backlog",
end: "Completed"
},
cycleTime: {
start: "In Progress",
end: "Completed"
},
devCycleTime: {
start: "In Progress",
end: "In Review"
},
mappings: {
priority: {
Lowest: ["Lowest"],
Low: ["Low"],
Medium: ["Medium"],
High: ["High"],
Highest: ["Highest"]
}
},
integrations: [],
linkRules: [],
metrics: null,
metricsBar: [
{
__typename: "Chartable",
name: "Distribution",
layout: {
barType: "percent"
},
filters: {
dql: "timestamp < 30d AND cycleType = \"leadTime\""
}
},
{
__typename: "Chartable",
name: "Throughput",
layout: {
comparisonType: "percentageChange"
},
filters: {
dql: "timestamp < 30d AND cycleType = \"leadTime\""
},
overlays: [
{
__typename: "Chartable",
name: "Previous Throughput",
layout: {
comparisonType: "percentageChange"
},
filters: {
dql: "timestamp > 30d AND timestamp < 60d AND cycleType = \"leadTime\""
}
}
]
}
]
}
) {
... on Workflow {
_id
name
description
phases {
name
stages {
name
query
targets
wipLimit
showAlerts
showSpeed
}
}
leadTime {
start
end
}
cycleTime {
start
end
}
devCycleTime {
start
end
}
metricsBar {
... on Chartable {
name
layout
filters {
dql
}
}
}
}
... on WorkflowUploadError {
errors
}
}
}
This mutation defines the workflow, phases, stages, and metrics for your value stream, allowing you to tailor the process to your specific needs.
2. Adding an Environment to a Pipeline.
In DevOps, a pipeline defines the series of steps required for deploying software, while stages represent the different phases of the pipeline (e.g., build, deploy, test).
To add a new stage to a pipeline, you can use the following GraphQL mutation:
mutation {
addPipelineStages(
pipelineId: "Pipeline_ID",
stages: [{ name: "<Stage_name>", type: "<Stage_type>" }]
) {
_id
name
type
description
planId
triggers {
_id
name
}
gates {
_id
name
}
cf_space_id
promoteTo
latestAutopromotionStatus
deploymentModes
defaultDeploymentMode
groupsAndUsers
solutionVersionId
}
}
Example: If you have a value stream named “test” and wish to add a new stage named TESTING_GRAPHQL of type deploy to the pipeline with ID 7d841b25-b009-498a-80cd-5fa0eaea63a4, the mutation would look like this:
mutation {
addPipelineStages(
pipelineId: "7d841b25-b009-498a-80cd-5fa0eaea63a4",
stages: [{ name: "TESTING_GRAPHQL", type: "deploy" }]
) {
_id
name
type
description
planId
triggers {
_id
name
}
gates {
_id
name
}
cf_space_id
promoteTo
latestAutopromotionStatus
deploymentModes
defaultDeploymentMode
groupsAndUsers
solutionVersionId
}
}
3. Add Application to a Pipeline
Integrating applications into your pipeline is another vital part of DevOps. To add an application to a pipeline in IBM DevOps Velocity, you can use the following mutation:
mutation {
addApplications(
pipelineId: "_____"
applications: [{ name: "string" }]
processes: [{ name: "string" }]
type: "string"
) {
_id
name
tenant_id
description
stages {
_id
name
type
description
planId
triggers
gates
cf_space_id
promoteTo
latestAutopromotionStatus
deploymentModes
defaultDeploymentMode
groupsAndUsers
solutionVersionId
solutionVersion
}
applications {
_id
name
type
description
processes
source
inputJobId
stages
subApplications
children
level
external_id
selectedChildren
versionRegEx
}
synchronize
team {
id
name
tenantId
}
created
stats {
leadTime
}
}
}
Example: To add the application Velocity-Test-2/main to a pipeline, the mutation would be:
mutation {
addApplications(
pipelineId: "7d841b25-b009-498a-80cd-5fa0eaea63a4"
applications: [{ id: "e8b3af83-b827-4c26-bdf3-94cd95139a2d", name: "Velocity-Test-2/main" }]
processes: null
type: "ucv-ext-gitlab"
) {
_id
name
tenant_id
description
stages {
_id
name
type
description
planId
cf_space_id
promoteTo
latestAutopromotionStatus
deploymentModes
defaultDeploymentMode
groupsAndUsers
}
applications {
name
type
description
processes {
_id
name
}
inputJobId
level
external_id
selectedChildren
versionRegEx
}
synchronize
team {
id
name
tenantId
}
created
stats {
leadTime
}
}
}
4. Delete Pipeline Stages
NOTE: It is recommended to refrain from using the delete mutation outside of the Velocity UI as the UI is equipped with confirmation dialogues as a measure to avoid unintended deletions.
mutation {
deletePipelineStages(pipelineId: "_____", stageIds: ["_____"]) {
_id
name
tenant_id
description
stages {
_id
name
type
description
planId
triggers
gates
cf_space_id
promoteTo
latestAutopromotionStatus
deploymentModes
defaultDeploymentMode
groupsAndUsers
solutionVersionId
solutionVersion
}
applications {
_id
name
type
description
processes
source
inputJobId
stages
subApplications
children
level
external_id
selectedChildren
versionRegEx
}
synchronize
team {
id
name
tenantId
}
created
stats {
leadTime
}
}
}
Example: The below mutation will delete a pipeline stage with ID 7d841b25-b009-498a-80cd-5fa0eaea63a4
mutation {
deletePipelineStages(pipelineId: "7d841b25-b009-498a-80cd-5fa0eaea63a4", stageIds: ["19523150-2935-487e-9f12-f722c63d851c"]) {
_id
name
tenant_id
description
stages {
_id
name
type
description
planId
triggers {
_id
name
}
gates {
_id
name
}
cf_space_id
promoteTo
latestAutopromotionStatus
deploymentModes
defaultDeploymentMode
groupsAndUsers
solutionVersionId
solutionVersion {
_id
}
}
applications {
_id
name
type
description
processes {
_id
name
}
inputJobId
stages {
_id
name
}
subApplications {
_id
name
}
children {
_id
name
}
level
external_id
selectedChildren
versionRegEx
}
synchronize
team {
id
name
tenantId
}
created
stats {
leadTime
}
}
}
Queries
You can access detailed information from IBM DevOps Velocity through GraphQL queries. Below are some example queries that demonstrate how to retrieve various types of data.
1. Query to get Application data by application ID
You can retrieve detailed information about a specific application using its ID in below query:
{
applicationById(id: "<Application_ID>", tenantId: "<Tenant_ID>", loadChildren: true) {
_id
id
external_id
tenant_id
integration_id
name
alphaNumericName
active
createdAdHoc
json_data
type
version
level
childrenIds
children {
_id
id
external_id
tenant_id
integration_id
name
alphaNumericName
active
createdAdHoc
json_data
type
version
level
}
}
}
Example: Querying the application with ID e8b3af83-b827-4c26-bdf3-94cd95139a2d
{
applicationById(id: "e8b3af83-b827-4c26-bdf3-94cd95139a2d", tenantId: "5ade13625558f2c6688d15ce", loadChildren: true) {
_id
id
external_id
tenant_id
integration_id
name
alphaNumericName
active
createdAdHoc
json_data
type
version
level
childrenIds
children {
_id
id
external_id
tenant_id
integration_id
name
alphaNumericName
active
createdAdHoc
json_data
type
version
level
}
}
}
2. Application Environment details by tenantID
Retrieve details about an application's environment using the tenantID:
{
applicationEnvironmentsByTenantId(tenantId: "TenantID") {
_id
id
external_id
tenant_id
name
app_id
external_app_id
active
json_data
type
version
inventory {
external_version_id
components
}
}
}
Example
{
applicationEnvironmentsByTenantId(tenantId: "5ade13625558f2c6688d15ce") {
_id
id
external_id
tenant_id
name
app_id
external_app_id
active
json_data
type
version
inventory {
external_version_id
}
}
}
3. Application environment name by tenantID
To retrieve all unique application environment names for a given tenantID, you can use the following query:
{
uniqueApplicationEnvironmentNamesByTenantId(tenantId: "_____") {
name
}
}
Example
{
uniqueApplicationEnvironmentNamesByTenantId(tenantId: "5ade13625558f2c6688d15ce") {
name
}
}
