From 6362a929b2f0b7f5189bb43fe672fed59c745d36 Mon Sep 17 00:00:00 2001
From: Yuki Okesaku <yuokesak@yahoo-corp.jp>
Date: Fri, 28 Aug 2026 09:40:11 +0900
Subject: [PATCH] feat: add annotation column to stages table

---
 config/annotations.js                         |  4 +++-
 config/base.js                                |  3 ++-
 ...00000-add-annotations-columns-to-stages.js | 21 +++++++++++++++++++
 models/stage.js                               | 15 +++++++++----
 test/data/config.base.stages.yaml             |  3 +++
 test/data/stage.yaml                          |  4 ++++
 6 files changed, 44 insertions(+), 6 deletions(-)
 create mode 100644 migrations/20260901000000-add-annotations-columns-to-stages.js

diff --git a/config/annotations.js b/config/annotations.js
index edaccafb..838d1f4b 100644
--- a/config/annotations.js
+++ b/config/annotations.js
@@ -40,6 +40,7 @@ const RESERVED_PIPELINE_ANNOTATIONS = [
     'screwdriver.cd/pipelineDescription',
     'screwdriver.cd/useDeployKey'
 ];
+const RESERVED_STAGE_ANNOTATIONS = ['screwdriver.cd/manualStartEnabled'];
 
 /**
  * The definition of the annotations pieces
@@ -48,5 +49,6 @@ const RESERVED_PIPELINE_ANNOTATIONS = [
 module.exports = {
     annotations: SCHEMA_ANNOTATIONS,
     reservedJobAnnotations: RESERVED_JOB_ANNOTATIONS,
-    reservedPipelineAnnotations: RESERVED_PIPELINE_ANNOTATIONS
+    reservedPipelineAnnotations: RESERVED_PIPELINE_ANNOTATIONS,
+    reservedStageAnnotations: RESERVED_STAGE_ANNOTATIONS
 };
diff --git a/config/base.js b/config/base.js
index 41840407..11eee403 100644
--- a/config/base.js
+++ b/config/base.js
@@ -46,7 +46,8 @@ const SCHEMA_STAGE = Joi.object()
         setup: SCHEMA_SETUP_JOB,
         teardown: SCHEMA_TEARDOWN_JOB,
         requires: Job.requires,
-        sourcePaths: Job.sourcePaths
+        sourcePaths: Job.sourcePaths,
+        annotations: Annotations.annotations
     })
     .unknown(false);
 
diff --git a/migrations/20260901000000-add-annotations-columns-to-stages.js b/migrations/20260901000000-add-annotations-columns-to-stages.js
new file mode 100644
index 00000000..d0cf2ee6
--- /dev/null
+++ b/migrations/20260901000000-add-annotations-columns-to-stages.js
@@ -0,0 +1,21 @@
+/* eslint-disable new-cap */
+
+'use strict';
+
+const prefix = process.env.DATASTORE_SEQUELIZE_PREFIX || '';
+const table = `${prefix}stages`;
+
+module.exports = {
+    up: async (queryInterface, Sequelize) => {
+        await queryInterface.sequelize.transaction(async transaction => {
+            await queryInterface.addColumn(
+                table,
+                'annotations',
+                {
+                    type: Sequelize.TEXT
+                },
+                { transaction }
+            );
+        });
+    }
+};
diff --git a/models/stage.js b/models/stage.js
index 9ce2a816..e747348b 100644
--- a/models/stage.js
+++ b/models/stage.js
@@ -2,6 +2,7 @@
 
 const Joi = require('joi');
 const Regex = require('../config/regex');
+const Annotations = require('../config/annotations');
 const mutate = require('../lib/mutate');
 
 const MODEL = {
@@ -22,6 +23,8 @@ const MODEL = {
 
     description: Joi.string().max(256).description('Description of the Stage').example('Deploys canary jobs'),
 
+    annotations: Annotations.annotations.description('Stage-level annotations'),
+
     archived: Joi.boolean().description('Flag if the stage is archived').example(true).default(false)
 };
 
@@ -49,7 +52,11 @@ module.exports = {
      * @type {Joi}
      */
     get: Joi.object(
-        mutate(MODEL, ['id', 'pipelineId', 'name', 'jobIds'], ['description', 'setup', 'teardown', 'archived'])
+        mutate(
+            MODEL,
+            ['id', 'pipelineId', 'name', 'jobIds'],
+            ['description', 'setup', 'teardown', 'annotations', 'archived']
+        )
     ).label('Get Stage metadata'),
 
     /**
@@ -58,9 +65,9 @@ module.exports = {
      * @property update
      * @type {Joi}
      */
-    update: Joi.object(mutate(MODEL, [], ['jobIds', 'description', 'setup', 'teardown', 'archived'])).label(
-        'Update Stage'
-    ),
+    update: Joi.object(
+        mutate(MODEL, [], ['jobIds', 'description', 'setup', 'teardown', 'annotations', 'archived'])
+    ).label('Update Stage'),
 
     /**
      * List of fields that determine a unique row
diff --git a/test/data/config.base.stages.yaml b/test/data/config.base.stages.yaml
index b94b77b7..75492bf1 100644
--- a/test/data/config.base.stages.yaml
+++ b/test/data/config.base.stages.yaml
@@ -5,6 +5,9 @@ canary:
     description: "Canary jobs for testing"
     sourcePaths:
         - src/
+    annotations:
+        scrwedriver.cd/manualStartEnabled: false
+        foo: bar
 prod:
     jobs:
         - deploy-west
diff --git a/test/data/stage.yaml b/test/data/stage.yaml
index 450f88da..6ec3928a 100644
--- a/test/data/stage.yaml
+++ b/test/data/stage.yaml
@@ -6,3 +6,7 @@ jobIds: [1, 2, 3, 4]
 description: 'Deploys canary jobs'
 setup: 222
 teardown: 333
+annotations:
+  screwdriver.cd/manualStartEnabled: true
+  screwdriver.cd/foo: bar
+  baz: qux