0
# CI Integration
1

2
Specialized continuous integration and deployment capabilities optimized for automated build environments.
3

4
## Capabilities
5

6
### CI Command
7

8
Execute tasks with CI-optimized defaults and enhanced logging for build systems.
9

10
```bash { .api }
11
/**
12
 * Run tasks in CI environment with CI-optimized behavior
13
 * Provides enhanced logging and failure handling for automated builds
14
 */
15
moon ci [...targets]
16

17
# Arguments:
18
# [...targets]    Task targets to execute in CI mode
19

20
# CI-Optimized Defaults:
21
# --no-bail       Continue executing tasks on failures (opposite of moon run default)
22
# --affected      Automatically determine affected projects (when appropriate)
23
# --remote        Use remote comparison for affected detection
24
# --summary       Show execution summary by default
25

26
# Additional Options:
27
# All standard run options are available:
28
-f, --force             Force run ignoring affected status
29
--dependents           Run downstream dependents  
30
-i, --interactive      Interactive mode (usually not needed in CI)
31
--query <statement>    Filter projects using query language
32
-u, --updateCache      Bypass cache and update items
33
--profile <type>       Generate performance profiles
34
--status <type>        Filter by change status for affected runs
35
--stdin                Accept touched files from stdin
36
```
37

38
**Usage Examples:**
39

40
```bash
41
# Basic CI execution - runs affected tasks
42
moon ci :build :test
43

44
# Force run all projects in CI
45
moon ci :build :test --force
46

47
# CI with specific project targets
48
moon ci app:build server:test
49

50
# Continue on failures and show summary
51
moon ci :lint :test --summary
52

53
# Filter by query in CI environment
54
moon ci :build --query "projectType=application"
55

56
# Profile performance in CI
57
moon ci :build --profile cpu
58
```
59

60
### Affected Detection in CI
61

62
Optimized affected file detection for CI/CD pipelines.
63

64
```bash { .api }
65
# CI Affected Detection Behavior:
66
# - Uses git diff against base branch by default
67
# - Automatically detects common CI environments
68
# - Integrates with pull request change detection
69
# - Optimizes for build performance
70

71
# Environment Variables for CI:
72
MOON_BASE=<branch>      Base branch for comparison (default: main/master)
73
MOON_HEAD=<commit>      Head commit for comparison (default: HEAD)
74
CI=true                 Enables CI mode automatically
75

76
# Common CI patterns:
77
# GitHub Actions: compares against github.base_ref
78
# GitLab CI: uses CI_MERGE_REQUEST_TARGET_BRANCH_NAME
79
# Jenkins: configurable via environment variables
80
```
81

82
**CI Affected Examples:**
83

84
```bash
85
# Standard CI affected run
86
moon ci :test --affected
87

88
# Compare specific branches
89
MOON_BASE=develop moon ci :build --affected
90

91
# Include specific change types
92
moon ci :lint --affected --status modified --status added
93

94
# Force affected detection against remote
95
moon ci :test --affected --remote
96
```
97

98
### Cache Optimization for CI
99

100
Leverage caching for faster CI builds and consistent results.
101

102
```bash { .api }
103
# CI Cache Strategies:
104

105
# Remote Cache Integration:
106
# - Shared cache between CI runs
107
# - Team member cache sharing
108
# - Branch-specific cache keys
109

110
# Cache Configuration:
111
--cache read-write      Standard caching (default)
112
--cache read           Read-only cache (useful for deploy builds)  
113
--cache write          Write-only cache (useful for cache warming)
114
--updateCache          Force cache refresh for specific runs
115

116
# Environment Variables:
117
MOON_CACHE_MODE=<mode>  Override cache behavior
118
MOON_REMOTE_CACHE_URL   Remote cache endpoint
119
```
120

121
**CI Cache Examples:**
122

123
```bash
124
# Standard CI with caching
125
moon ci :build :test
126

127
# Read-only cache for deployment builds
128
moon ci :build --cache read
129

130
# Warm cache without reading
131
moon ci :build --cache write
132

133
# Force cache update for nightly builds
134
moon ci :build :test --updateCache
135
```
136

137
### Enhanced CI Logging
138

139
Structured logging and reporting optimized for CI systems.
140

141
```bash { .api }
142
# CI Logging Features:
143
# - Structured output for build system parsing
144
# - Progress indicators and timing information
145
# - Error aggregation and reporting
146
# - Integration with CI platform notifications
147

148
# Logging Options:
149
--log info             Standard CI logging (default)
150
--log debug           Detailed debugging information
151
--log trace           Full execution tracing
152
--quiet               Minimal output (errors only)
153
--summary             Execution summary and statistics
154
--logFile <file>      Write logs to file for archiving
155
```
156

157
**CI Logging Examples:**
158

159
```bash
160
# Standard CI logging with summary
161
moon ci :test --summary
162

163
# Detailed logging for debugging CI issues
164
moon ci :build --log debug
165

166
# Minimal output for clean CI logs
167
moon ci :deploy --quiet
168

169
# Archive detailed logs
170
moon ci :test --logFile ci-run.log
171

172
# Trace performance issues
173
moon ci :build --log trace --dump
174
```
175

176
### Docker Integration
177

178
Specialized Docker support for containerized CI environments.
179

180
```bash { .api }
181
/**
182
 * Docker-related utilities for CI environments
183
 * Handles containerized build and deployment scenarios
184
 */
185
moon docker <subcommand>
186

187
# Subcommands:
188
scaffold    Generate Dockerfile and docker-compose configurations
189
sync        Sync Docker configurations with workspace changes
190
```
191

192
**Docker CI Examples:**
193

194
```bash
195
# Generate Docker configurations for CI
196
moon docker scaffold
197

198
# Update Docker configs after workspace changes  
199
moon docker sync
200

201
# Typical CI Docker workflow:
202
# 1. moon docker scaffold (in repository setup)
203
# 2. docker build -t app .
204
# 3. docker run app moon ci :test
205
```
206

207
### Migration and Legacy Integration
208

209
Migrate existing CI pipelines to moon.
210

211
```bash { .api }
212
/**
213
 * Migrate from other build tools to moon
214
 * Converts existing configurations and workflows
215
 */
216
moon migrate <source>
217

218
# Migration Sources:
219
from-package-json    Convert package.json scripts to moon tasks
220
from-turborepo       Migrate from Turborepo configuration
221

222
# Migration Process:
223
# 1. Analyzes existing configuration
224
# 2. Generates equivalent moon configuration
225
# 3. Provides migration report and recommendations
226
```
227

228
**Migration Examples:**
229

230
```bash
231
# Migrate from package.json scripts
232
moon migrate from-package-json
233

234
# Convert Turborepo workspace
235
moon migrate from-turborepo
236

237
# Review migration results
238
moon project-graph --json | jq '.tasks'
239
```
240

241
### Performance Profiling in CI
242

243
Generate performance profiles for CI optimization.
244

245
```bash { .api }
246
# Profiling Options:
247
--profile cpu          Generate CPU usage profile
248
--profile heap         Generate memory usage profile  
249
--dump                 Create trace profile for analysis
250

251
# Profile Analysis:
252
# - Profiles can be opened in Chrome DevTools (chrome://tracing)
253
# - Use Perfetto (ui.perfetto.dev) for detailed analysis
254
# - Identify bottlenecks in task execution
255
# - Optimize parallelization and caching
256
```
257

258
**CI Profiling Examples:**
259

260
```bash
261
# Profile CPU usage during build
262
moon ci :build --profile cpu
263

264
# Monitor memory usage
265
moon ci :test --profile heap
266

267
# Full execution trace
268
moon ci :build --dump
269

270
# Combine profiling with other options
271
moon ci :build --profile cpu --summary --logFile build-profile.log
272
```
273

274
### Parallel Execution Control
275

276
Optimize CI resource usage through concurrency control.
277

278
```bash { .api }
279
# Concurrency Configuration:
280
--concurrency <n>      Set maximum parallel tasks
281
-c <n>                 Short form of concurrency
282

283
# Environment Control:
284
MOON_CONCURRENCY=<n>   Set via environment variable
285

286
# CI Resource Optimization:
287
# - Match concurrency to available CPU cores
288
# - Consider memory constraints for parallel tasks
289
# - Balance between speed and resource usage
290
# - Account for external service rate limits
291
```
292

293
## CI Environment Detection
294

295
Moon automatically detects and optimizes for common CI environments:
296

297
```bash { .api }
298
# Supported CI Platforms:
299
# - GitHub Actions
300
# - GitLab CI/CD  
301
# - Jenkins
302
# - CircleCI
303
# - Azure DevOps
304
# - Bitbucket Pipelines
305
# - Travis CI
306
# - Generic CI (via CI=true environment variable)
307

308
# Automatic Optimizations:
309
# - Affected detection strategies
310
# - Logging format and verbosity
311
# - Cache key generation
312
# - Progress reporting
313
# - Error handling and reporting
314
```
315

316
## Error Handling in CI
317

318
Robust error handling for automated environments:
319

320
- **Task Failures**: CI mode continues execution by default (`--no-bail`)
321
- **Dependency Failures**: Safely skips downstream tasks when dependencies fail
322
- **Network Issues**: Retry logic for remote cache and tool downloads
323
- **Resource Constraints**: Graceful handling of memory and disk space limits
324
- **Timeout Handling**: Configurable timeouts for long-running tasks
325
- **Exit Codes**: Proper exit codes for CI system integration (0 = success, non-zero = failure)