feat(2911): Job Templates - Pipeline Usage Report (#2912)

Author: nathom

.prettierrc.yaml

@@ -1 +1,6 @@
 trailingComma: "none"
+printWidth: 110
+singleQuote: true
+tabWidth: 4
+arrowParens: "avoid"
+htmlWhitespaceSensitivity: "strict"

package.json

@@ -138,12 +138,12 @@
     }
   },
   "devDependencies": {
+    "@cucumber/cucumber": "^9.0.0",
     "@octokit/rest": "^19.0.5",
     "chai": "^4.3.7",
     "chai-as-promised": "^7.1.1",
     "chai-jwt": "^2.0.0",
     "coveralls": "^3.1.1",
-    "@cucumber/cucumber": "^9.0.0",
     "eslint": "^8.28.0",
     "eslint-config-screwdriver": "^7.0.0",
     "form-data": "^4.0.0",

plugins/templates/README.md

@@ -131,6 +131,38 @@ If the deleted version was the last published, the API would set the `latest` at
 * `name` - Name of the template
 * `version` - Version of the template
 
+##### Get Report of Pipelines that use a template version
+
+`GET /templates/{name}/{version}/usage/pipelines`
+
+
+###### Arguments
+
+'name', 'version'
+
+* `name` - Name of the template
+* `version` - Version of the template
+
+###### Example response
+
+```json
+[
+    {
+        id: 4,
+        name: 'nathom/sd-uses-template',
+        scmRepo: {
+          branch: 'main',
+          name: 'nathom/sd-uses-template',
+          url: 'https://github.com/nathom/sd-uses-template/tree/main/pipe2',
+          rootDir: 'pipe2',
+          private: false
+        },
+        lastRun: '2023-07-31T17:15:37.510Z',
+        admins: { nathom: true }
+    },
+]
+```
+
 #### Template Tag
 Template tag allows fetching on template version by tag. For example, tag `mytemplate@1.1.0` as `stable`.
 

plugins/templates/getPipelineUsage.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const boom = require('@hapi/boom');
+const joi = require('joi');
+const schema = require('screwdriver-data-schema');
+const nameSchema = schema.models.template.base.extract('name');
+const versionSchema = schema.models.template.base.extract('version');
+const tagSchema = schema.models.templateTag.base.extract('tag');
+const getSchema = schema.api.pipelineUsage.get;
+
+module.exports = () => ({
+    method: 'GET',
+    path: '/templates/{name}/{versionOrTag}/usage/pipelines',
+    options: {
+        description: 'Get information for the pipelines that are being used by a specific template version.',
+        notes: 'Returns information aboout the pipelines using the template version.',
+        tags: ['api', 'templates', 'pipelines', 'metrics'],
+        auth: {
+            strategies: ['token'],
+            scope: ['user', 'build']
+        },
+
+        handler: async (request, h) => {
+            const { templateFactory } = request.server.app;
+            const { name, versionOrTag } = request.params;
+
+            return templateFactory
+                .getPipelineUsage(`${name}@${versionOrTag}`)
+                .then(pipelines => {
+                    return h.response(pipelines);
+                })
+                .catch(err => {
+                    if (err.message === 'Template does not exist') {
+                        throw boom.notFound(`Template ${name}@${versionOrTag} does not exist`);
+                    } else {
+                        throw err;
+                    }
+                });
+        },
+        response: {
+            schema: getSchema
+        },
+        validate: {
+            params: joi.object({
+                name: nameSchema,
+                versionOrTag: joi.alternatives().try(versionSchema, tagSchema)
+            })
+        }
+    }
+});

plugins/templates/index.js

@@ -13,6 +13,7 @@ const removeTagRoute = require('./removeTag');
 const removeVersionRoute = require('./removeVersion');
 const updateTrustedRoute = require('./updateTrusted');
 const getTemplateByIdRoute = require('./getTemplateById');
+const getPipelineUsage = require('./getPipelineUsage');
 
 /**
  * Template API Plugin
@@ -87,7 +88,8 @@ const templatesPlugin = {
             removeTagRoute(),
             removeVersionRoute(),
             updateTrustedRoute(),
-            getTemplateByIdRoute()
+            getTemplateByIdRoute(),
+            getPipelineUsage()
         ]);
     }
 };

test/plugins/data/pipelineUsage.json

@@ -0,0 +1,15 @@
+[
+    {
+        "id": 4,
+        "name": "screwdriver/build",
+        "scmRepo": {
+            "branch": "main",
+            "name": "screwdriver/build",
+            "url": "https://github.com/nathom/sd-uses-template/tree/main/pipe2",
+            "rootDir": "pipe2",
+            "private": false
+        },
+        "lastRun": "2023-07-31T17:15:37.510Z",
+        "admins": { "nathom": true }
+    }
+]

test/plugins/data/templateVersionsMetrics.json

@@ -1,64 +1,83 @@
-[{
-  "id": 7969,
-  "name": "screwdriver/build",
-  "labels": ["stable"],
-  "version": "0.0.1",
-  "description": "this is a template to test",
-  "maintainer": "foo@bar.com",
-  "pipelineId": 8765,
-  "config": {
-      "steps": [{
-          "echo": "echo hello"
-      }]
-  },
-  "metrics": {
-    "jobs": {
-      "count": 2
+[
+    {
+        "id": 7969,
+        "name": "screwdriver/build",
+        "labels": ["stable"],
+        "version": "0.0.1",
+        "description": "this is a template to test",
+        "maintainer": "foo@bar.com",
+        "pipelineId": 8765,
+        "config": {
+            "steps": [
+                {
+                    "echo": "echo hello"
+                }
+            ]
+        },
+        "metrics": {
+            "jobs": {
+                "count": 2
+            },
+            "builds": {
+                "count": 7
+            },
+            "pipelines": {
+                "count": 1
+            }
+        }
     },
-    "builds": {
-      "count": 7
-    }
-  }
-},{
-  "id": 7970,
-  "name": "screwdriver/build",
-  "labels": ["stable"],
-  "version": "1.0.2",
-  "description": "this is a template to test",
-  "maintainer": "foo@bar.com",
-  "pipelineId": 8765,
-  "config": {
-      "steps": [{
-          "echo": "echo hello"
-      }]
-  },
-  "metrics": {
-    "jobs": {
-      "count": 1
-    },
-    "builds": {
-      "count": 9
-    }
-  }
-}, {
-  "id": 7971,
-  "name": "screwdriver/build",
-  "labels": ["stable"],
-  "version": "3.2.1",
-  "description": "this is a template to test",
-  "maintainer": "foo@bar.com",
-  "pipelineId": 8765,
-  "config": {
-      "steps": [{
-          "echo": "echo hello"
-      }]
-  },
-  "metrics": {
-    "jobs": {
-      "count": 5
+    {
+        "id": 7970,
+        "name": "screwdriver/build",
+        "labels": ["stable"],
+        "version": "1.0.2",
+        "description": "this is a template to test",
+        "maintainer": "foo@bar.com",
+        "pipelineId": 8765,
+        "config": {
+            "steps": [
+                {
+                    "echo": "echo hello"
+                }
+            ]
+        },
+        "metrics": {
+            "jobs": {
+                "count": 1
+            },
+            "builds": {
+                "count": 9
+            },
+            "pipelines": {
+                "count": 1
+            }
+        }
     },
-    "builds": {
-      "count": 13
+    {
+        "id": 7971,
+        "name": "screwdriver/build",
+        "labels": ["stable"],
+        "version": "3.2.1",
+        "description": "this is a template to test",
+        "maintainer": "foo@bar.com",
+        "pipelineId": 8765,
+        "config": {
+            "steps": [
+                {
+                    "echo": "echo hello"
+                }
+            ]
+        },
+        "metrics": {
+            "jobs": {
+                "count": 5
+            },
+            "builds": {
+                "count": 13
+            },
+            "pipelines": {
+                "count": 3
+            }
+        }
     }
-  }
-}]
+]

test/plugins/templates.test.js

@@ -12,6 +12,7 @@ const testtemplateversions = require('./data/templateVersions.json');
 const testTemplateVersionsMetrics = require('./data/templateVersionsMetrics.json');
 const testTemplateWithNamespace = require('./data/templateWithNamespace.json');
 const testpipeline = require('./data/pipeline.json');
+const testPipelineUsage = require('./data/pipelineUsage.json');
 const TEMPLATE_INVALID = require('./data/template-validator.missing-version.json');
 const TEMPLATE_VALID = require('./data/template-validator.input.json');
 const TEMPLATE_VALID_NEW_VERSION = require('./data/template-create.input.json');
@@ -69,7 +70,8 @@ describe('template plugin test', () => {
             list: sinon.stub(),
             listWithMetrics: sinon.stub(),
             getTemplate: sinon.stub(),
-            get: sinon.stub()
+            get: sinon.stub(),
+            getPipelineUsage: sinon.stub()
         };
         templateTagFactoryMock = {
             create: sinon.stub(),
@@ -432,6 +434,55 @@ describe('template plugin test', () => {
         });
     });
 
+    describe('GET /templates/name/versionOrTag/usage/pipelines', () => {
+        let options;
+
+        beforeEach(() => {
+            options = {
+                method: 'GET',
+                url: '/templates/screwdriver%2Fbuild/1.7.3/usage/pipelines'
+            };
+        });
+
+        it('returns 200 and all pipelines that use the template version', () => {
+            templateFactoryMock.getPipelineUsage.resolves(testPipelineUsage);
+
+            return server.inject(options).then(reply => {
+                assert.deepEqual(reply.result, testPipelineUsage);
+                assert.equal(reply.statusCode, 200);
+                assert.calledWith(templateFactoryMock.getPipelineUsage, `screwdriver/build@1.7.3`);
+            });
+        });
+
+        it('returns 200 even if no pipelines are using the template version', () => {
+            templateFactoryMock.getPipelineUsage.resolves([]);
+
+            return server.inject(options).then(reply => {
+                assert.deepEqual(reply.result, []);
+                assert.equal(reply.statusCode, 200);
+                assert.calledWith(templateFactoryMock.getPipelineUsage, `screwdriver/build@1.7.3`);
+            });
+        });
+
+        it('returns 404 when the template does not exist', () => {
+            templateFactoryMock.getPipelineUsage.returns(Promise.reject(new Error('Template does not exist')));
+            const error = {
+                statusCode: 404,
+                error: 'Not Found',
+                message: 'Template screwdriver/build@1.7.3 does not exist'
+            };
+
+            return server.inject(options).then(reply => {
+                const payload = JSON.parse(reply.payload);
+
+                Object.keys(error).forEach(k => {
+                    assert.equal(payload[k], error[k]);
+                });
+                assert.calledWith(templateFactoryMock.getPipelineUsage, `screwdriver/build@1.7.3`);
+            });
+        });
+    });
+
     describe('GET /templates/name/metrics', () => {
         let options;
 
@@ -1241,7 +1292,10 @@ describe('template plugin test', () => {
 
             templateFactoryMock.get.resolves(testTemplateV1);
             templateFactoryMock.get
-                .withArgs({ name: `${templateNameSpace}/${templateName}`, version: templateVersion1 })
+                .withArgs({
+                    name: `${templateNameSpace}/${templateName}`,
+                    version: templateVersion1
+                })
                 .resolves(testTemplateV1);
             templateTagFactoryMock.list.resolves([testTemplateTag]);
         });
@@ -1274,7 +1328,10 @@ describe('template plugin test', () => {
             return server.inject(options).then(reply => {
                 assert.equal(reply.statusCode, error.statusCode);
                 assert.deepEqual(reply.result, error);
-                assert.calledWith(templateFactoryMock.get, { name: 'test-namespace/test-template', version: '1.0.0' });
+                assert.calledWith(templateFactoryMock.get, {
+                    name: 'test-namespace/test-template',
+                    version: '1.0.0'
+                });
             });
         });