0
# GitHub Integration
1

2
GitHub Actions workflows, issue templates, and repository management. Projen provides comprehensive GitHub integration for modern software development workflows.
3

4
## Capabilities
5

6
### GitHub Class
7

8
Core GitHub integration component that manages repository settings and workflows.
9

10
```typescript { .api }
11
/**
12
 * GitHub integration and configuration
13
 * Manages repository settings, workflows, and automation
14
 */
15
class GitHub extends Component {
16
  constructor(project: GitHubProject, options?: GitHubOptions);
17
  
18
  /** GitHub Actions workflows */
19
  readonly workflows: Record<string, GithubWorkflow>;
20
  /** Issue templates */
21
  readonly issueTemplates: IssueTemplate[];
22
  /** Pull request template */
23
  readonly pullRequestTemplate?: PullRequestTemplate;
24
  
25
  /** Add a GitHub Actions workflow */
26
  addWorkflow(name: string, workflow: GithubWorkflow): void;
27
  /** Remove a workflow */
28
  removeWorkflow(name: string): void;
29
  /** Add issue template */
30
  addIssueTemplate(template: IssueTemplate): void;
31
  /** Add pull request template */
32
  addPullRequestTemplate(template: PullRequestTemplate): void;
33
}
34

35
interface GitHubOptions {
36
  /** Repository settings */
37
  repository?: RepositoryOptions;
38
  /** Issue templates */
39
  issueTemplates?: IssueTemplate[];
40
  /** Pull request template */
41
  pullRequestTemplate?: PullRequestTemplate;
42
  /** Mergify configuration */
43
  mergify?: boolean;
44
  /** Dependabot configuration */
45
  dependabot?: boolean;
46
  /** Auto-merge configuration */
47
  autoMerge?: boolean;
48
  /** Stale bot configuration */
49
  stale?: boolean;
50
}
51

52
interface RepositoryOptions {
53
  /** Repository description */
54
  description?: string;
55
  /** Repository topics */
56
  topics?: string[];
57
  /** Homepage URL */
58
  homepage?: string;
59
  /** Repository visibility */
60
  private?: boolean;
61
  /** Branch protection settings */
62
  branchProtection?: BranchProtectionOptions;
63
}
64
```
65

66
### GitHubProject Class
67

68
Base project class with GitHub integration and repository management.
69

70
```typescript { .api }
71
/**
72
 * Base project with GitHub features and repository management
73
 * Extends Project with GitHub-specific functionality
74
 */
75
class GitHubProject extends Project {
76
  constructor(options: GitHubProjectOptions);
77
  
78
  /** GitHub integration component */
79
  readonly github?: GitHub;
80
  /** Default release branch */
81
  readonly defaultReleaseBranch: string;
82
  /** Release workflow */
83
  readonly releaseWorkflow?: GithubWorkflow;
84
  /** Build workflow */
85
  readonly buildWorkflow?: GithubWorkflow;
86
  
87
  /** Add GitHub Actions workflow */
88
  addGitHubWorkflow(name: string, workflow: GithubWorkflow): void;
89
}
90

91
interface GitHubProjectOptions extends ProjectOptions {
92
  /** Default release branch (default: "main") */
93
  defaultReleaseBranch?: string;
94
  /** GitHub integration options */
95
  github?: boolean;
96
  /** GitHub configuration */
97
  githubOptions?: GitHubOptions;
98
  /** Enable release workflow */
99
  release?: boolean;
100
  /** Release workflow options */
101
  releaseOptions?: ReleaseOptions;
102
  /** Enable build workflow */
103
  buildWorkflow?: boolean;
104
  /** Build workflow options */
105
  buildWorkflowOptions?: BuildWorkflowOptions;
106
}
107
```
108

109
**Basic GitHub Project Example:**
110

111
```typescript
112
import { GitHubProject } from "projen";
113

114
const project = new GitHubProject({
115
  name: "my-github-project",
116
  defaultReleaseBranch: "main",
117
  
118
  // GitHub features
119
  github: true,
120
  githubOptions: {
121
    repository: {
122
      description: "My awesome GitHub project",
123
      topics: ["typescript", "projen", "automation"],
124
      homepage: "https://my-project.com",
125
    },
126
    mergify: true,
127
    dependabot: true,
128
    stale: true,
129
  },
130
  
131
  // Release automation
132
  release: true,
133
  
134
  // Build workflow
135
  buildWorkflow: true,
136
});
137
```
138

139
### GitHub Actions Workflows
140

141
Comprehensive GitHub Actions workflow management.
142

143
```typescript { .api }
144
/**
145
 * GitHub Actions workflow definition
146
 * Represents a complete CI/CD workflow
147
 */
148
class GithubWorkflow extends Component {
149
  constructor(github: GitHub, name: string, options?: WorkflowOptions);
150
  
151
  /** Workflow name */
152
  readonly name: string;
153
  /** Workflow triggers */
154
  readonly triggers: WorkflowTriggers;
155
  /** Workflow jobs */
156
  readonly jobs: Record<string, Job>;
157
  
158
  /** Add workflow trigger */
159
  addTrigger(trigger: WorkflowTrigger): void;
160
  /** Add job to workflow */
161
  addJob(name: string, job: Job): void;
162
  /** Remove job from workflow */
163
  removeJob(name: string): void;
164
}
165

166
interface WorkflowOptions {
167
  /** Workflow triggers */
168
  triggers?: WorkflowTriggers;
169
  /** Workflow jobs */
170
  jobs?: Record<string, Job>;
171
  /** Workflow permissions */
172
  permissions?: WorkflowPermissions;
173
  /** Environment variables */
174
  env?: Record<string, string>;
175
  /** Concurrency settings */
176
  concurrency?: ConcurrencyOptions;
177
}
178

179
interface WorkflowTriggers {
180
  /** Push triggers */
181
  push?: PushTrigger;
182
  /** Pull request triggers */
183
  pullRequest?: PullRequestTrigger;
184
  /** Schedule triggers */
185
  schedule?: ScheduleTrigger[];
186
  /** Manual dispatch */
187
  workflowDispatch?: WorkflowDispatchTrigger;
188
  /** Repository dispatch */
189
  repositoryDispatch?: RepositoryDispatchTrigger;
190
}
191

192
interface Job {
193
  /** Job name */
194
  name?: string;
195
  /** Runner type */
196
  runsOn: string | string[];
197
  /** Job steps */
198
  steps: JobStep[];
199
  /** Job environment */
200
  env?: Record<string, string>;
201
  /** Job timeout */
202
  timeoutMinutes?: number;
203
  /** Job strategy */
204
  strategy?: JobStrategy;
205
  /** Job permissions */
206
  permissions?: JobPermissions;
207
  /** Job needs */
208
  needs?: string | string[];
209
  /** Job condition */
210
  if?: string;
211
}
212

213
interface JobStep {
214
  /** Step name */
215
  name?: string;
216
  /** Action to use */
217
  uses?: string;
218
  /** Command to run */
219
  run?: string;
220
  /** Step inputs */
221
  with?: Record<string, any>;
222
  /** Environment variables */
223
  env?: Record<string, string>;
224
  /** Step condition */
225
  if?: string;
226
  /** Continue on error */
227
  continueOnError?: boolean;
228
}
229
```
230

231
**GitHub Workflow Example:**
232

233
```typescript
234
import { GitHubProject, Job } from "projen";
235

236
const project = new GitHubProject({
237
  name: "workflow-example",
238
  github: true,
239
});
240

241
// Create custom CI workflow
242
const ciJob: Job = {
243
  runsOn: "ubuntu-latest",
244
  steps: [
245
    {
246
      name: "Checkout",
247
      uses: "actions/checkout@v3",
248
    },
249
    {
250
      name: "Setup Node.js",
251
      uses: "actions/setup-node@v3",
252
      with: {
253
        "node-version": "18",
254
        "cache": "npm",
255
      },
256
    },
257
    {
258
      name: "Install dependencies",
259
      run: "npm ci",
260
    },
261
    {
262
      name: "Run tests",
263
      run: "npm test",
264
    },
265
    {
266
      name: "Build",
267
      run: "npm run build",
268
    },
269
  ],
270
};
271

272
project.github?.addWorkflow("ci", {
273
  triggers: {
274
    push: { branches: ["main"] },
275
    pullRequest: { branches: ["main"] },
276
  },
277
  jobs: {
278
    test: ciJob,
279
  },
280
});
281
```
282

283
### Dependabot Configuration
284

285
Automatic dependency updates with Dependabot.
286

287
```typescript { .api }
288
/**
289
 * Dependabot configuration for automated dependency updates
290
 * Manages security updates and version upgrades
291
 */
292
class Dependabot extends Component {
293
  constructor(github: GitHub, options?: DependabotOptions);
294
  
295
  /** Add package ecosystem for updates */
296
  addPackageEcosystem(ecosystem: string, options?: PackageEcosystemOptions): void;
297
}
298

299
interface DependabotOptions {
300
  /** Package ecosystems to monitor */
301
  packageEcosystems?: PackageEcosystem[];
302
  /** Schedule for updates */
303
  scheduleInterval?: "daily" | "weekly" | "monthly";
304
  /** Target branch for PRs */
305
  targetBranch?: string;
306
}
307

308
interface PackageEcosystem {
309
  /** Package manager (npm, pip, maven, etc.) */
310
  packageManager: string;
311
  /** Directory to monitor */
312
  directory: string;
313
  /** Update schedule */
314
  schedule: {
315
    interval: "daily" | "weekly" | "monthly";
316
    time?: string;
317
    timezone?: string;
318
  };
319
  /** Reviewers for PRs */
320
  reviewers?: string[];
321
  /** Assignees for PRs */
322
  assignees?: string[];
323
  /** Labels for PRs */
324
  labels?: string[];
325
}
326
```
327

328
### Mergify Configuration
329

330
Advanced merge rules and automation with Mergify.
331

332
```typescript { .api }
333
/**
334
 * Mergify configuration for advanced merge rules
335
 * Automates pull request merging based on conditions
336
 */
337
class Mergify extends Component {
338
  constructor(github: GitHub, options?: MergifyOptions);
339
  
340
  /** Add merge rule */
341
  addRule(rule: MergifyRule): void;
342
}
343

344
interface MergifyOptions {
345
  /** Merge rules */
346
  rules?: MergifyRule[];
347
}
348

349
interface MergifyRule {
350
  /** Rule name */
351
  name: string;
352
  /** Conditions for the rule */
353
  conditions: string[];
354
  /** Actions to take */
355
  actions: MergifyAction[];
356
}
357

358
interface MergifyAction {
359
  /** Action type */
360
  merge?: {
361
    method?: "merge" | "squash" | "rebase";
362
    strict?: boolean;
363
  };
364
  /** Delete head branch */
365
  delete_head_branch?: boolean;
366
  /** Add label */
367
  label?: {
368
    add?: string[];
369
    remove?: string[];
370
  };
371
}
372
```
373

374
### Auto-Merge and Auto-Approve
375

376
Automated pull request handling for trusted changes.
377

378
```typescript { .api }
379
/**
380
 * Auto-merge workflows for approved pull requests
381
 * Automatically merges PRs that meet criteria
382
 */
383
class AutoMerge extends Component {
384
  constructor(github: GitHub, options?: AutoMergeOptions);
385
}
386

387
/**
388
 * Auto-approve workflows for trusted changes
389
 * Automatically approves PRs from trusted sources
390
 */
391
class AutoApprove extends Component {
392
  constructor(github: GitHub, options?: AutoApproveOptions);
393
}
394

395
interface AutoMergeOptions {
396
  /** Required status checks */
397
  requiredStatusChecks?: string[];
398
  /** Merge method */
399
  mergeMethod?: "merge" | "squash" | "rebase";
400
  /** Delete branch after merge */
401
  deleteBranchAfterMerge?: boolean;
402
}
403

404
interface AutoApproveOptions {
405
  /** Trusted users/bots */
406
  allowedUsers?: string[];
407
  /** Label for auto-approval */
408
  label?: string;
409
}
410
```
411

412
### Issue and PR Templates
413

414
Standardized templates for issues and pull requests.
415

416
```typescript { .api }
417
/**
418
 * GitHub issue template configuration
419
 * Provides structured templates for different issue types
420
 */
421
class IssueTemplate {
422
  constructor(options: IssueTemplateOptions);
423
}
424

425
/**
426
 * GitHub pull request template
427
 * Standardizes PR descriptions and checklists
428
 */
429
class PullRequestTemplate extends Component {
430
  constructor(github: GitHub, options?: PullRequestTemplateOptions);
431
}
432

433
interface IssueTemplateOptions {
434
  /** Template name */
435
  name: string;
436
  /** Template description */
437
  about: string;
438
  /** Template title */
439
  title?: string;
440
  /** Template labels */
441
  labels?: string[];
442
  /** Template assignees */
443
  assignees?: string[];
444
  /** Template body */
445
  body: string;
446
}
447

448
interface PullRequestTemplateOptions {
449
  /** Template content */
450
  content: string[];
451
}
452
```
453

454
**Issue Template Example:**
455

456
```typescript
457
import { GitHubProject } from "projen";
458

459
const project = new GitHubProject({
460
  name: "template-example",
461
  github: true,
462
  githubOptions: {
463
    issueTemplates: [
464
      {
465
        name: "Bug Report",
466
        about: "Create a report to help us improve",
467
        title: "[BUG] ",
468
        labels: ["bug", "needs-triage"],
469
        body: `**Describe the bug**
470
A clear and concise description of what the bug is.
471

472
**To Reproduce**
473
Steps to reproduce the behavior:
474
1. Go to '...'
475
2. Click on '....'
476
3. Scroll down to '....'
477
4. See error
478

479
**Expected behavior**
480
A clear and concise description of what you expected to happen.
481

482
**Environment**
483
- OS: [e.g. iOS]
484
- Browser [e.g. chrome, safari]
485
- Version [e.g. 22]`,
486
      },
487
      {
488
        name: "Feature Request",
489
        about: "Suggest an idea for this project",
490
        title: "[FEATURE] ",
491
        labels: ["enhancement"],
492
        body: `**Is your feature request related to a problem?**
493
A clear and concise description of what the problem is.
494

495
**Describe the solution you'd like**
496
A clear and concise description of what you want to happen.
497

498
**Additional context**
499
Add any other context or screenshots about the feature request here.`,
500
      },
501
    ],
502
    pullRequestTemplate: {
503
      content: [
504
        "## Description",
505
        "",
506
        "Brief description of the changes made.",
507
        "",
508
        "## Type of Change",
509
        "",
510
        "- [ ] Bug fix",
511
        "- [ ] New feature", 
512
        "- [ ] Breaking change",
513
        "- [ ] Documentation update",
514
        "",
515
        "## Testing",
516
        "",
517
        "- [ ] Tests pass locally",
518
        "- [ ] New tests added for changes",
519
        "",
520
        "## Checklist",
521
        "",
522
        "- [ ] Code follows style guidelines",
523
        "- [ ] Self-review completed",
524
        "- [ ] Documentation updated",
525
      ],
526
    },
527
  },
528
});
529
```
530

531
## Types
532

533
### GitHub-Specific Types
534

535
```typescript { .api }
536
interface WorkflowPermissions {
537
  actions?: "read" | "write";
538
  checks?: "read" | "write";
539
  contents?: "read" | "write";
540
  deployments?: "read" | "write";
541
  issues?: "read" | "write";
542
  packages?: "read" | "write";
543
  pullRequests?: "read" | "write";
544
  repositoryProjects?: "read" | "write";
545
  securityEvents?: "read" | "write";
546
  statuses?: "read" | "write";
547
}
548

549
interface PushTrigger {
550
  branches?: string[];
551
  branchesIgnore?: string[];
552
  paths?: string[];
553
  pathsIgnore?: string[];
554
  tags?: string[];
555
  tagsIgnore?: string[];
556
}
557

558
interface PullRequestTrigger {
559
  branches?: string[];
560
  branchesIgnore?: string[];
561
  paths?: string[];
562
  pathsIgnore?: string[];
563
  types?: string[];
564
}
565

566
interface ScheduleTrigger {
567
  cron: string;
568
}
569

570
interface JobStrategy {
571
  matrix?: Record<string, any>;
572
  failFast?: boolean;
573
  maxParallel?: number;
574
}
575

576
interface BranchProtectionOptions {
577
  /** Require status checks */
578
  requiredStatusChecks?: string[];
579
  /** Require up-to-date branches */
580
  requireUpToDate?: boolean;
581
  /** Require pull request reviews */
582
  requiredReviewers?: number;
583
  /** Dismiss stale reviews */
584
  dismissStaleReviews?: boolean;
585
  /** Require code owner reviews */
586
  requireCodeOwnerReviews?: boolean;
587
  /** Restrict pushes */
588
  restrictPushes?: boolean;
589
  /** Required linear history */
590
  requireLinearHistory?: boolean;
591
}
592
```