Skip to content

Commit 06983c5

Browse files
subhamay-cloudworkssubhamay-cloudworks
committed
feat: implement CloudFormation Configuration Processor GitHub Action
Complete implementation of a GitHub Action that processes CloudFormation deployment configurations, merges parameter files with environment-specific overrides, and generates outputs for stack deployment. Features implemented: - ConfigurationReader: Reads and validates CloudFormation configuration files - ParameterMerger: Merges default and environment-specific parameters - StackNameGenerator: Generates dynamic stack names for CI builds and environments - CiBuildIdGenerator: Creates unique identifiers for CI build deployments - Main action entry point with comprehensive error handling - Action configuration with proper inputs/outputs definition - Comprehensive test suite with unit and integration tests - Input validation and robust error handling - Complete documentation with examples and troubleshooting guide Key capabilities: - Flexible configuration structure with customizable folder paths - Parameter merging with environment-specific overrides - Dynamic stack naming for both CI builds and environment deployments - Unique CI build identifiers for parallel deployments - Comprehensive validation with clear error messages - Well-documented with usage examples and troubleshooting Built with Kiro - AI-powered development assistant Implements all requirements from CloudFormation Configuration Processor specification
1 parent 5f3c19a commit 06983c5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+8089
-116
lines changed

‎.gitignore‎

Lines changed: 68 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,84 @@
1-
# Ignore MacOS system files
2-
.DS_Store
3-
# Ignore Python cache files
4-
__pycache__/
5-
6-
# Node.js
1+
# Dependencies
72
node_modules/
83
npm-debug.log*
94
yarn-debug.log*
105
yarn-error.log*
6+
pnpm-debug.log*
117

8+
# Build outputs
9+
dist/
10+
build/
11+
*.tgz
1212

13-
# Optional: include package-lock.json in GitHub Actions for reproducible builds
14-
# Uncomment the following line if you DO want to commit the lock file:
15-
#!package-lock.json
16-
17-
# VS Code settings
18-
.vscode/
19-
20-
# macOS
21-
.DS_Store
13+
# Test outputs and coverage
14+
coverage/
15+
.nyc_output/
16+
test-results/
17+
test-results.json
18+
*.lcov
2219

2320
# Logs
2421
logs/
2522
*.log
2623
*.log.*
2724

28-
# Coverage & test output
29-
coverage/
30-
.nyc_output/
31-
test-results/
25+
# Runtime data
26+
pids/
27+
*.pid
28+
*.seed
29+
*.pid.lock
3230

33-
# Semantic release artifacts (if any)
34-
.release-it.json
35-
36-
# GitHub Actions
37-
dist/
38-
*.tgz
39-
40-
# Misc
31+
# Environment variables
4132
.env
4233
.env.local
43-
.env.production
34+
.env.development
4435
.env.test
36+
.env.production
37+
38+
# IDE and editor files
39+
.vscode/
40+
.idea/
41+
*.swp
42+
*.swo
43+
*~
44+
45+
# OS generated files
46+
.DS_Store
47+
.DS_Store?
48+
._*
49+
.Spotlight-V100
50+
.Trashes
51+
ehthumbs.db
52+
Thumbs.db
53+
54+
# Temporary files
55+
tmp/
56+
temp/
57+
.tmp/
58+
.temp/
59+
60+
# Cache directories
61+
.cache/
62+
.parcel-cache/
63+
.eslintcache
64+
65+
# Optional npm cache directory
66+
.npm
67+
68+
# Optional REPL history
69+
.node_repl_history
70+
71+
# Semantic release artifacts
72+
.release-it.json
73+
74+
# Vitest
75+
.vitest/
76+
77+
# GitHub Actions specific
78+
action.zip
79+
80+
# Kiro IDE (keep Kiro configuration)
81+
# .kiro/ - Keep this for development
82+
83+
# Documentation build artifacts (if any)
84+
docs/build/

‎.kiro/specs/github-cloudformation-action/design.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# Design Document
2+
3+
## Overview
4+
5+
This GitHub reusable action will be implemented as a JavaScript-based composite action that processes CloudFormation deployment configurations. The action will read configuration files from a specified directory structure, merge parameter files with environment-specific overrides, and generate three key outputs for CloudFormation deployment pipelines: formatted parameter arrays, dynamically generated stack names, and CI build identifiers.
6+
7+
The action follows GitHub Actions best practices by using the composite action approach with JavaScript execution, providing clear input/output interfaces, and implementing robust error handling throughout the processing pipeline.
8+
9+
## Architecture
10+
11+
### High-Level Flow
12+
13+
```mermaid
14+
graph TD
15+
A[Action Invocation] --> B[Input Validation]
16+
B --> C[Read cloudformation.json]
17+
C --> D[Read default.json]
18+
D --> E[Read environment-specific.json]
19+
E --> F[Merge Parameters]
20+
F --> G[Generate Stack Name]
21+
G --> H[Generate CI Build ID]
22+
H --> I[Set Action Outputs]
23+
I --> J[Action Complete]
24+
25+
B --> K[Error: Invalid Inputs]
26+
C --> L[Error: Missing Config]
27+
D --> M[Error: Missing Default Params]
28+
E --> N[Warning: Missing Env Params]
29+
F --> O[Error: JSON Parse Failure]
30+
```
31+
32+
### Directory Structure Expected
33+
34+
```
35+
{folder}/
36+
├── cloudformation.json # Main configuration
37+
└── params/
38+
├── default.json # Default parameters
39+
├── sb-devl-us-east-1.json # Environment-specific params
40+
├── sb-test-us-east-1.json # Environment-specific params
41+
└── sb-prod-us-east-1.json # Environment-specific params
42+
```
43+
44+
## Components and Interfaces
45+
46+
### Action Definition (action.yaml)
47+
48+
**Inputs:**
49+
- `folder`: String, default "cfn", specifies the configuration folder path
50+
- `ci-build`: Boolean, determines if this is a CI build or environment deployment
51+
- `environment`: String, specifies the target environment name
52+
53+
**Outputs:**
54+
- `parameters`: JSON string array of CloudFormation parameters
55+
- `stack-name`: String, formatted stack name for deployment
56+
- `ci-build-id`: String, random identifier for CI builds or empty string
57+
58+
### Core JavaScript Modules
59+
60+
#### 1. ConfigurationReader Module
61+
```javascript
62+
class ConfigurationReader {
63+
async readCloudFormationConfig(folderPath)
64+
async readDefaultParameters(folderPath)
65+
async readEnvironmentParameters(folderPath, environment)
66+
validateJsonStructure(data, requiredFields)
67+
}
68+
```
69+
70+
**Responsibilities:**
71+
- Read and validate cloudformation.json structure
72+
- Load parameter files with error handling
73+
- Validate JSON format and required fields
74+
75+
#### 2. ParameterMerger Module
76+
```javascript
77+
class ParameterMerger {
78+
mergeParameters(defaultParams, envParams)
79+
formatForCloudFormation(mergedParams)
80+
}
81+
```
82+
83+
**Responsibilities:**
84+
- Merge default and environment-specific parameters
85+
- Convert to CloudFormation parameter array format
86+
- Handle parameter precedence (environment overrides default)
87+
88+
#### 3. StackNameGenerator Module
89+
```javascript
90+
class StackNameGenerator {
91+
async generateStackName(project, stackPrefix, isCiBuild, environment)
92+
async getCurrentBranchName()
93+
sanitizeBranchName(branchName)
94+
}
95+
```
96+
97+
**Responsibilities:**
98+
- Generate appropriate stack names based on build type
99+
- Extract current Git branch for CI builds
100+
- Sanitize branch names for CloudFormation compatibility
101+
102+
#### 4. CiBuildIdGenerator Module
103+
```javascript
104+
class CiBuildIdGenerator {
105+
generateRandomId(length = 8)
106+
validateIdFormat(id)
107+
}
108+
```
109+
110+
**Responsibilities:**
111+
- Generate random lowercase alphabetic strings
112+
- Ensure uniqueness and proper format
113+
114+
### Main Action Entry Point
115+
116+
```javascript
117+
// main.js
118+
async function run() {
119+
try {
120+
// Input processing
121+
// Configuration reading
122+
// Parameter merging
123+
// Output generation
124+
// Action output setting
125+
} catch (error) {
126+
// Error handling and action failure
127+
}
128+
}
129+
```
130+
131+
## Data Models
132+
133+
### CloudFormation Configuration Schema
134+
```json
135+
{
136+
"project": "string (required)",
137+
"template": "string (required)",
138+
"stack-prefix": "string (required)"
139+
}
140+
```
141+
142+
### Parameter File Schema
143+
```json
144+
{
145+
"ParameterName1": "string",
146+
"ParameterName2": "string",
147+
"...": "..."
148+
}
149+
```
150+
151+
### CloudFormation Parameter Output Format
152+
```json
153+
[
154+
{
155+
"ParameterName": "ParameterName1",
156+
"ParameterValue": "ParamValue1"
157+
},
158+
{
159+
"ParameterName": "ParameterName2",
160+
"ParameterValue": "ParamValue2"
161+
}
162+
]
163+
```
164+
165+
## Error Handling
166+
167+
### Error Categories and Responses
168+
169+
1. **Input Validation Errors**
170+
- Missing required folder
171+
- Invalid boolean values for ci-build
172+
- Empty environment name when ci-build is false
173+
174+
2. **File System Errors**
175+
- Missing cloudformation.json file
176+
- Missing default.json file
177+
- Inaccessible folder permissions
178+
179+
3. **JSON Parsing Errors**
180+
- Malformed JSON in configuration files
181+
- Missing required fields in cloudformation.json
182+
- Invalid parameter file structure
183+
184+
4. **Git Operation Errors**
185+
- Unable to determine current branch (CI build mode)
186+
- Git repository not initialized
187+
188+
### Error Handling Strategy
189+
190+
- **Fail Fast**: Immediately exit on critical errors (missing config files, invalid JSON)
191+
- **Graceful Degradation**: Continue with warnings for non-critical issues (missing environment-specific parameters)
192+
- **Clear Error Messages**: Provide actionable error messages with context
193+
- **Proper Exit Codes**: Use appropriate exit codes for different error types
194+
195+
## Testing Strategy
196+
197+
### Unit Testing Approach
198+
199+
1. **Configuration Reader Tests**
200+
- Valid configuration file parsing
201+
- Error handling for missing/invalid files
202+
- JSON validation edge cases
203+
204+
2. **Parameter Merger Tests**
205+
- Default parameter processing
206+
- Environment override behavior
207+
- CloudFormation format conversion
208+
- Edge cases (empty files, conflicting keys)
209+
210+
3. **Stack Name Generator Tests**
211+
- CI build name generation
212+
- Environment-based name generation
213+
- Branch name sanitization
214+
- Git operation error handling
215+
216+
4. **CI Build ID Generator Tests**
217+
- Random string generation
218+
- Format validation
219+
- Uniqueness verification
220+
221+
### Integration Testing
222+
223+
1. **End-to-End Scenarios**
224+
- Complete action execution with valid inputs
225+
- Various folder structures and configurations
226+
- Different environment and CI build combinations
227+
228+
2. **Error Path Testing**
229+
- Missing file scenarios
230+
- Invalid JSON scenarios
231+
- Git repository edge cases
232+
233+
### Test Data Structure
234+
235+
```
236+
test/
237+
├── fixtures/
238+
│ ├── valid-config/
239+
│ │ ├── cloudformation.json
240+
│ │ └── params/
241+
│ │ ├── default.json
242+
│ │ └── sb-devl-us-east-1.json
243+
│ ├── invalid-config/
244+
│ └── missing-files/
245+
├── unit/
246+
│ ├── configuration-reader.test.js
247+
│ ├── parameter-merger.test.js
248+
│ ├── stack-name-generator.test.js
249+
│ └── ci-build-id-generator.test.js
250+
└── integration/
251+
└── action.test.js
252+
```
253+
254+
## Implementation Considerations
255+
256+
### Performance Optimizations
257+
- Asynchronous file operations to prevent blocking
258+
- Minimal memory footprint for parameter processing
259+
- Efficient JSON parsing and validation
260+
261+
### Security Considerations
262+
- Input sanitization for file paths
263+
- Validation of JSON content to prevent injection
264+
- Secure handling of environment variables and tokens
265+
266+
### Maintainability Features
267+
- Modular architecture for easy testing and updates
268+
- Clear separation of concerns between components
269+
- Comprehensive error logging and debugging information
270+
- TypeScript-style JSDoc comments for better IDE support

0 commit comments

Comments
 (0)