projen-pipelines 0.0.1 → 0.0.3

package/README.md

@@ -1 +1,154 @@
-# replace this
+# Projen Pipelines
+
+[![npm version](https://badge.fury.io/js/projen-pipelines.svg)](https://www.npmjs.com/package/projen-pipelines)
+
+
+Projen Pipelines is a projen library that provides high-level abstractions for defining continuous delivery (CD) pipelines for AWS CDK applications.
+It is specifically designed to work with the projen project configuration engine.
+
+This library provides high-level abstractions for defining multi-environment and multi-account AWS CDK applications with ease.
+With this library, you can handle complex deployment scenarios with less code and manage your AWS infrastructure in a more efficient and straightforward way.
+
+## Getting Started
+
+### Installation
+
+To install the package, add the package `projen-pipelines` to your projects devDeps in your projen configuration file.
+
+
+After installing the package, you can import and use the constructs to define your CDK Pipelines.
+
+### Usage
+
+You can start using the constructs provided by Projen Pipelines in your AWS CDK applications. Here's a brief example:
+
+```typescript
+import { awscdk } from 'projen';
+import { CDKPipeline, CDKPipelineOptions } from 'projen-pipelines';
+
+// Define your AWS CDK TypeScript App
+const app = new awscdk.AwsCdkTypeScriptApp({
+  cdkVersion: '2.80.0',
+  name: 'my-awesome-app',
+  defaultReleaseBranch: 'main',
+  devDeps: [
+    'projen-pipelines',
+  ],
+});
+
+// Create the pipeline
+new CDKPipeline(app, {
+  stackPrefix: 'MyApp',
+  pkgNamespace: '@company-assemblies',
+  environments: {
+    dev: { account: '111111111111', region: 'eu-central-1' },
+    prod: { account: '222222222222', region: 'eu-central-1' },
+  },
+});
+```
+
+After running projen (`npx projen`) a new file called `src/app.ts` will be created and contain a specialized CDK App class for your project.
+
+You can then use this in your `main.ts` to configure your deployment.
+
+```typescript
+import { PipelineApp } from './app';
+import { BackendStack } from './stack';
+
+const app = new PipelineApp({
+  provideDevStack: (scope, id, props) => {
+    return new BackendStack(scope, id, {
+      ...props,
+      apiHostname: 'api-dev',
+      myConfigSetting: 'value-for-dev',
+    });
+  },
+  provideProdStack: (scope, id, props) => {
+    return new BackendStack(scope, id, {
+      ...props,
+      apiHostname: 'api',
+      myConfigSetting: 'value-for-prod',
+    });
+  },
+  providePersonalStack: (scope, id, props) => {
+    return new BackendStack(scope, id, {
+      ...props,
+      apiHostname: `api-${props.stageName}`,
+      myConfigSetting: 'value-for-personal-stage',
+    });
+  },
+});
+
+app.synth();
+```
+
+### Deployment
+
+The `CDKPipeline` class creates and adds several tasks to the projen project that then can be used in your pipeline to deploy your application to AWS.
+
+Here's a brief description of each one:
+
+1. **deploy:personal** - This task deploys the application's personal stage, which is a distinct, isolated deployment of the application. The personal stage is intended for personal use, such as testing and development.
+
+2. **watch:personal** - This task deploys the personal stage of the application in watch mode. In this mode, the AWS CDK monitors your application source files for changes, automatically re-synthesizing and deploying when it detects any changes.
+
+3. **diff:personal** - This task compares the deployed personal stage with the current state of the application code. It's used to understand what changes would be made if the application were deployed.
+
+4. **destroy:personal** - This task destroys the resources created for the personal stage of the application.
+
+5. **deploy:feature** - This task deploys the application's feature stage. The feature stage is used for new features testing before these are merged into the main branch.
+
+6. **diff:feature** - This task is similar to `diff:personal`, but for the feature stage.
+
+7. **destroy:feature** - This task destroys the resources created for the feature stage of the application.
+
+8. **deploy:<stageName>** - This task deploys a specific stage of the application (like 'dev' or 'prod').
+
+9. **diff:<stageName>** - This task compares the specified application stage with the current state of the application code.
+
+10. **publish:assets** - This task publishes the CDK assets to all accounts. This is useful when the CDK application uses assets like Docker images or files from the S3 bucket.
+
+11. **bump** - This task bumps the version based on the latest git tag and pushes the updated tag to the git repository.
+
+12. **release:push-assembly** - This task creates a manifest, bumps the version without creating a git tag, and publishes the cloud assembly to your registry.
+
+Remember that these tasks are created and managed automatically by the `CDKPipeline` class. You can run these tasks using the `npx projen TASK_NAME` command.
+
+
+## Contributing
+
+We welcome all contributions to Projen Pipelines! Here's how you can get started:
+
+1. **Fork the Repository**: Click the 'Fork' button at the top right of this page to duplicate this repository in your GitHub account.
+
+2. **Clone your Fork**: Clone the forked repository to your local machine.
+
+```bash
+git clone https://github.com/<your_username>/projen-pipelines.git
+```
+
+3. **Create a Branch**: To keep your work organized, create a branch for your contribution.
+
+```bash
+git checkout -b my-branch
+```
+
+4. **Make your Changes**: Make your changes, additions, or fixes to the codebase. Remember to follow the existing code style.
+
+5. **Test your Changes**: Before committing your changes, make sure to test them to ensure they work as expected and do not introduce bugs.
+
+6. **Commit your Changes**: Commit your changes with a descriptive commit message using conventional commit messages.
+
+```bash
+git commit -m "feat: Your descriptive commit message"
+```
+
+7. **Push to your Fork**: Push your commits to the branch in your forked repository.
+
+```bash
+git push origin my-branch
+```
+
+8. **Submit a Pull Request**: Once your changes are ready to be reviewed, create a pull request from your forked repository's branch into the `main` branch of this repository.
+
+Your pull request will be reviewed and hopefully merged quickly. Thanks for contributing!

package/lib/engine/base.d.ts

@@ -0,0 +1,22 @@
+import { awscdk } from 'projen';
+import { CDKPipeline, CDKPipelineOptions, Environment } from '../pipeline';
+export interface SynthStageOptions {
+    readonly commands: string[];
+}
+export interface AssetUploadStageOptions {
+    readonly commands: string[];
+}
+export interface DeployStageOptions {
+    readonly stageName: string;
+    readonly commands: string[];
+    readonly env: Environment;
+}
+export declare abstract class BaseEngine {
+    protected app: awscdk.AwsCdkTypeScriptApp;
+    protected props: CDKPipelineOptions;
+    protected pipeline: CDKPipeline;
+    constructor(app: awscdk.AwsCdkTypeScriptApp, props: CDKPipelineOptions, pipeline: CDKPipeline);
+    abstract createSynth(options: SynthStageOptions): void;
+    abstract createAssetUpload(options: AssetUploadStageOptions): void;
+    abstract createDeployment(options: DeployStageOptions): void;
+}

package/lib/engine/base.js

@@ -0,0 +1,16 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseEngine = void 0;
+const JSII_RTTI_SYMBOL_1 = Symbol.for("jsii.rtti");
+class BaseEngine {
+    constructor(app, props, pipeline) {
+        this.app = app;
+        this.props = props;
+        this.pipeline = pipeline;
+    }
+}
+_a = JSII_RTTI_SYMBOL_1;
+BaseEngine[_a] = { fqn: "projen-pipelines.BaseEngine", version: "0.0.3" };
+exports.BaseEngine = BaseEngine;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFzZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9lbmdpbmUvYmFzZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7OztBQWlCQSxNQUFzQixVQUFVO0lBQzlCLFlBQXNCLEdBQStCLEVBQVksS0FBeUIsRUFBWSxRQUFxQjtRQUFyRyxRQUFHLEdBQUgsR0FBRyxDQUE0QjtRQUFZLFVBQUssR0FBTCxLQUFLLENBQW9CO1FBQVksYUFBUSxHQUFSLFFBQVEsQ0FBYTtJQUczSCxDQUFDOzs7O0FBSm1CLGdDQUFVIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgYXdzY2RrIH0gZnJvbSAncHJvamVuJztcbmltcG9ydCB7IENES1BpcGVsaW5lLCBDREtQaXBlbGluZU9wdGlvbnMsIEVudmlyb25tZW50IH0gZnJvbSAnLi4vcGlwZWxpbmUnO1xuXG5leHBvcnQgaW50ZXJmYWNlIFN5bnRoU3RhZ2VPcHRpb25zIHtcbiAgcmVhZG9ubHkgY29tbWFuZHM6IHN0cmluZ1tdO1xufVxuXG5leHBvcnQgaW50ZXJmYWNlIEFzc2V0VXBsb2FkU3RhZ2VPcHRpb25zIHtcbiAgcmVhZG9ubHkgY29tbWFuZHM6IHN0cmluZ1tdO1xufVxuXG5leHBvcnQgaW50ZXJmYWNlIERlcGxveVN0YWdlT3B0aW9ucyB7XG4gIHJlYWRvbmx5IHN0YWdlTmFtZTogc3RyaW5nO1xuICByZWFkb25seSBjb21tYW5kczogc3RyaW5nW107XG4gIHJlYWRvbmx5IGVudjogRW52aXJvbm1lbnQ7XG59XG5cbmV4cG9ydCBhYnN0cmFjdCBjbGFzcyBCYXNlRW5naW5lIHtcbiAgY29uc3RydWN0b3IocHJvdGVjdGVkIGFwcDogYXdzY2RrLkF3c0Nka1R5cGVTY3JpcHRBcHAsIHByb3RlY3RlZCBwcm9wczogQ0RLUGlwZWxpbmVPcHRpb25zLCBwcm90ZWN0ZWQgcGlwZWxpbmU6IENES1BpcGVsaW5lKSB7XG5cblxuICB9XG5cbiAgYWJzdHJhY3QgY3JlYXRlU3ludGgob3B0aW9uczogU3ludGhTdGFnZU9wdGlvbnMpOiB2b2lkO1xuICBhYnN0cmFjdCBjcmVhdGVBc3NldFVwbG9hZChvcHRpb25zOiBBc3NldFVwbG9hZFN0YWdlT3B0aW9ucyk6IHZvaWQ7XG4gIGFic3RyYWN0IGNyZWF0ZURlcGxveW1lbnQob3B0aW9uczogRGVwbG95U3RhZ2VPcHRpb25zKTogdm9pZDtcblxufSJdfQ==

package/lib/engine/github.d.ts

@@ -0,0 +1,22 @@
+import { awscdk } from 'projen';
+import { AssetUploadStageOptions, BaseEngine, DeployStageOptions, SynthStageOptions } from './base';
+import { CDKPipeline, CDKPipelineOptions } from '../pipeline';
+export interface RoleMap {
+    readonly feature?: string;
+    readonly dev?: string;
+    readonly prod?: string;
+}
+export interface GithubEngineConfig {
+    readonly defaultAwsRoleArn?: string;
+    readonly awsRoleArnForSynth?: string;
+    readonly awsRoleArnForAssetPublishing?: string;
+    readonly awsRoleArnForDeployment?: RoleMap;
+}
+export declare class GitHubEngine extends BaseEngine {
+    private deploymentWorkflow;
+    private deploymentStages;
+    constructor(app: awscdk.AwsCdkTypeScriptApp, props: CDKPipelineOptions, pipeline: CDKPipeline);
+    createSynth(options: SynthStageOptions): void;
+    createAssetUpload(options: AssetUploadStageOptions): void;
+    createDeployment(options: DeployStageOptions): void;
+}

package/lib/engine/github.js

@@ -0,0 +1,100 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubEngine = void 0;
+const JSII_RTTI_SYMBOL_1 = Symbol.for("jsii.rtti");
+const workflows_model_1 = require("projen/lib/github/workflows-model");
+const base_1 = require("./base");
+class GitHubEngine extends base_1.BaseEngine {
+    constructor(app, props, pipeline) {
+        super(app, props, pipeline);
+        this.deploymentStages = [];
+        this.deploymentWorkflow = this.app.github.addWorkflow('deploy');
+        this.deploymentWorkflow.on({
+            push: {
+                branches: ['main'], // TODO use defaultReleaseBranch
+            },
+            workflowDispatch: {},
+        });
+    }
+    createSynth(options) {
+        const steps = [{
+                name: 'Checkout',
+                uses: 'actions/checkout@v2',
+                env: {
+                    CI: 'true',
+                },
+            }];
+        if (this.props.githubConfig?.awsRoleArnForSynth) {
+            steps.push({
+                name: 'AWS Credentials',
+                uses: 'aws-actions/configure-aws-credentials@master',
+                with: {
+                    'role-to-assume': this.props.githubConfig.awsRoleArnForSynth,
+                    'role-session-name': 'GitHubAction',
+                    'aws-region': 'us-east-1',
+                },
+            });
+        }
+        steps.push(...options.commands.map(cmd => ({
+            run: cmd,
+        })));
+        this.deploymentWorkflow.addJob('synth', {
+            name: 'Synth CDK application',
+            runsOn: ['ubuntu-latest'],
+            permissions: { idToken: workflows_model_1.JobPermission.WRITE, contents: workflows_model_1.JobPermission.READ },
+            steps,
+        });
+    }
+    createAssetUpload(options) {
+        this.deploymentWorkflow.addJob('assetUpload', {
+            name: 'Publish assets to AWS',
+            needs: ['synth'],
+            runsOn: ['ubuntu-latest'],
+            permissions: { idToken: workflows_model_1.JobPermission.WRITE, contents: workflows_model_1.JobPermission.READ },
+            steps: [{
+                    name: 'Checkout',
+                    uses: 'actions/checkout@v2',
+                }, {
+                    name: 'AWS Credentials',
+                    uses: 'aws-actions/configure-aws-credentials@master',
+                    with: {
+                        'role-to-assume': this.props.githubConfig?.awsRoleArnForAssetPublishing ?? this.props.githubConfig?.defaultAwsRoleArn,
+                        'role-session-name': 'GitHubAction',
+                        'aws-region': 'us-east-1',
+                    },
+                },
+                ...options.commands.map(cmd => ({
+                    run: cmd,
+                }))],
+        });
+    }
+    createDeployment(options) {
+        this.deploymentWorkflow.addJob(`deploy-${options.stageName}`, {
+            name: `Deploy stage ${options.stageName} to AWS`,
+            needs: this.deploymentStages.length > 0 ? ['assetUpload', `deploy-${this.deploymentStages.at(-1)}`] : ['assetUpload'],
+            runsOn: ['ubuntu-latest'],
+            permissions: { idToken: workflows_model_1.JobPermission.WRITE, contents: workflows_model_1.JobPermission.READ },
+            steps: [{
+                    name: 'Checkout',
+                    uses: 'actions/checkout@v2',
+                }, {
+                    name: 'AWS Credentials',
+                    uses: 'aws-actions/configure-aws-credentials@master',
+                    with: {
+                        'role-to-assume': this.props.githubConfig?.awsRoleArnForDeployment?.[options.stageName] ?? this.props.githubConfig?.defaultAwsRoleArn,
+                        'role-session-name': 'GitHubAction',
+                        'aws-region': options.env.region,
+                    },
+                },
+                ...options.commands.map(cmd => ({
+                    run: cmd,
+                }))],
+        });
+        this.deploymentStages.push(options.stageName);
+    }
+}
+_a = JSII_RTTI_SYMBOL_1;
+GitHubEngine[_a] = { fqn: "projen-pipelines.GitHubEngine", version: "0.0.3" };
+exports.GitHubEngine = GitHubEngine;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2l0aHViLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2VuZ2luZS9naXRodWIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUFFQSx1RUFBMkU7QUFDM0UsaUNBQW9HO0FBZ0JwRyxNQUFhLFlBQWEsU0FBUSxpQkFBVTtJQUsxQyxZQUFZLEdBQStCLEVBQUUsS0FBeUIsRUFBRSxRQUFxQjtRQUMzRixLQUFLLENBQUMsR0FBRyxFQUFFLEtBQUssRUFBRSxRQUFRLENBQUMsQ0FBQztRQUh0QixxQkFBZ0IsR0FBYSxFQUFFLENBQUM7UUFLdEMsSUFBSSxDQUFDLGtCQUFrQixHQUFHLElBQUksQ0FBQyxHQUFHLENBQUMsTUFBTyxDQUFDLFdBQVcsQ0FBQyxRQUFRLENBQUMsQ0FBQztRQUNqRSxJQUFJLENBQUMsa0JBQWtCLENBQUMsRUFBRSxDQUFDO1lBQ3pCLElBQUksRUFBRTtnQkFDSixRQUFRLEVBQUUsQ0FBQyxNQUFNLENBQUMsRUFBRSxnQ0FBZ0M7YUFDckQ7WUFDRCxnQkFBZ0IsRUFBRSxFQUFFO1NBQ3JCLENBQUMsQ0FBQztJQUNMLENBQUM7SUFFTSxXQUFXLENBQUMsT0FBMEI7UUFDM0MsTUFBTSxLQUFLLEdBQWMsQ0FBQztnQkFDeEIsSUFBSSxFQUFFLFVBQVU7Z0JBQ2hCLElBQUksRUFBRSxxQkFBcUI7Z0JBQzNCLEdBQUcsRUFBRTtvQkFDSCxFQUFFLEVBQUUsTUFBTTtpQkFDWDthQUNGLENBQUMsQ0FBQztRQUVILElBQUksSUFBSSxDQUFDLEtBQUssQ0FBQyxZQUFZLEVBQUUsa0JBQWtCLEVBQUU7WUFDL0MsS0FBSyxDQUFDLElBQUksQ0FBQztnQkFDVCxJQUFJLEVBQUUsaUJBQWlCO2dCQUN2QixJQUFJLEVBQUUsOENBQThDO2dCQUNwRCxJQUFJLEVBQUU7b0JBQ0osZ0JBQWdCLEVBQUUsSUFBSSxDQUFDLEtBQUssQ0FBQyxZQUFZLENBQUMsa0JBQWtCO29CQUM1RCxtQkFBbUIsRUFBRSxjQUFjO29CQUNu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T0FBTyxDQUFDLEdBQUcsQ0FBQyxNQUFNO3FCQUNqQztpQkFDRjtnQkFDRCxHQUFHLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUMsQ0FBQztvQkFDOUIsR0FBRyxFQUFFLEdBQUc7aUJBQ1QsQ0FBQyxDQUFDLENBQUM7U0FDTCxDQUFDLENBQUM7UUFDSCxJQUFJLENBQUMsZ0JBQWdCLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxTQUFTLENBQUMsQ0FBQztJQUNoRCxDQUFDOzs7O0FBakdVLG9DQUFZIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgYXdzY2RrIH0gZnJvbSAncHJvamVuJztcbmltcG9ydCB7IEdpdGh1YldvcmtmbG93IH0gZnJvbSAncHJvamVuL2xpYi9naXRodWInO1xuaW1wb3J0IHsgSm9iUGVybWlzc2lvbiwgSm9iU3RlcCB9IGZyb20gJ3Byb2plbi9saWIvZ2l0aHViL3dvcmtmbG93cy1tb2RlbCc7XG5pbXBvcnQgeyBBc3NldFVwbG9hZFN0YWdlT3B0aW9ucywgQmFzZUVuZ2luZSwgRGVwbG95U3RhZ2VPcHRpb25zLCBTeW50aFN0YWdlT3B0aW9ucyB9IGZyb20gJy4vYmFzZSc7XG5pbXBvcnQgeyBDREtQaXBlbGluZSwgQ0RLUGlwZWxpbmVPcHRpb25zIH0gZnJvbSAnLi4vcGlwZWxpbmUnO1xuXG5leHBvcnQgaW50ZXJmYWNlIFJvbGVNYXAge1xuICByZWFkb25seSBmZWF0dXJlPzogc3RyaW5nO1xuICByZWFkb25seSBkZXY/OiBzdHJpbmc7XG4gIHJlYWRvbmx5IHByb2Q/OiBzdHJpbmc7XG59XG5cbmV4cG9ydCBpbnRlcmZhY2UgR2l0aHViRW5naW5lQ29uZmlnIHtcbiAgcmVhZG9ubHkgZGVmYXVsdEF3c1JvbGVBcm4/OiBzdHJpbmc7XG4gIHJlYWRvbmx5IGF3c1JvbGVBcm5Gb3JTeW50aD86IHN0cmluZztcbiAgcmVhZG9ubHkgYXdzUm9sZUFybkZvckFzc2V0UHVibGlzaGluZz86IHN0cmluZztcbiAgcmVhZG9ubHkgYXdzUm9sZUFybkZvckRlcGxveW1lbnQ/OiBSb2xlTWFwO1xufVxuXG5leHBvcnQgY2xhc3MgR2l0SHViRW5naW5lIGV4dGVuZHMgQmFzZUVuZ2luZSB7XG5cbiAgcHJpdmF0ZSBkZXBsb3ltZW50V29ya2Zsb3c6IEdpdGh1YldvcmtmbG93O1xuICBwcml2YXRlIGRlcGxveW1lbnRTdGFnZXM6IHN0cmluZ1tdID0gW107XG5cbiAgY29uc3RydWN0b3IoYXBwOiBhd3NjZGsuQXdzQ2RrVHlwZVNjcmlwdEFwcCwgcHJvcHM6IENES1BpcGVsaW5lT3B0aW9ucywgcGlwZWxpbmU6IENES1BpcGVsaW5lKSB7XG4gICAgc3VwZXIoYXBwLCBwcm9wcywgcGlwZWxpbmUpO1xuXG4gICAgdGhpcy5kZXBsb3ltZW50V29ya2Zsb3cgPSB0aGlzLmFwcC5naXRodWIhLmFkZFdvcmtmbG93KCdkZXBsb3knKTtcbiAgICB0aGlzLmRlcGxveW1lbnRXb3JrZmxvdy5vbih7XG4gICAgICBwdXNoOiB7XG4gICAgICAgIGJyYW5jaGVzOiBbJ21haW4nXSwgLy8gVE9ETyB1c2UgZGVmYXVsdFJlbGVhc2VCcmFuY2hcbiAgICAgIH0sXG4gICAgICB3b3JrZmxvd0Rpc3BhdGNoOiB7fSxcbiAgICB9KTtcbiAgfVxuXG4gIHB1YmxpYyBjcmVhdGVTeW50aChvcHRpb25zOiBTeW50aFN0YWdlT3B0aW9ucyk6IHZvaWQge1xuICAgIGNvbnN0IHN0ZXBzOiBKb2JTdGVwW10gPSBbe1xuICAgICAgbmFtZTogJ0NoZWNrb3V0JyxcbiAgICAgIHVzZXM6ICdhY3Rpb25zL2NoZWNrb3V0QHYyJyxcbiAgICAgIGVudjoge1xuICAgICAgICBDSTogJ3RydWUnLFxuICAgICAgfSxcbiAgICB9XTtcblxuICAgIGlmICh0aGlzLnByb3BzLmdpdGh1YkNvbmZpZz8uYXdzUm9sZUFybkZvclN5bnRoKSB7XG4gICAgICBzdGVwcy5wdXNoKHtcbiAgICAgICAgbmFtZTogJ0FXUyBDcmVkZW50aWFscycsXG4gICAgICAgIHVzZXM6ICdhd3MtYWN0aW9ucy9jb25maWd1cmUtYXdzLWNyZWRlbnRpYWxzQG1hc3RlcicsXG4gICAgICAgIHdpdGg6IHtcbiAgICAgICAgICAncm9sZS10by1hc3N1bWUnOiB0aGlzLnByb3BzLmdpdGh1YkNvbmZpZy5hd3NSb2xlQXJuRm9yU3ludGgsXG4gICAgICAgICAgJ3JvbGUtc2Vzc2lvbi1uYW1lJzogJ0dpdEh1YkFjdGlvbicsXG4gICAgICAgICAgJ2F3cy1yZWdpb24nOiAndXMtZWFzdC0xJyxcbiAgICAgICAgfSxcbiAgICAgIH0pO1xuICAgIH1cblxuICAgIHN0ZXBzLnB1c2goLi4ub3B0aW9ucy5jb21tYW5kcy5tYXAoY21kID0+ICh7XG4gICAgICBydW46IGNtZCxcbiAgICB9KSkpO1xuXG4gICAgdGhpcy5kZXBsb3ltZW50V29ya2Zsb3cuYWRkSm9iKCdzeW50aCcsIHtcbiAgICAgIG5hbWU6ICdTeW50aCBDREsgYXBwbGljYXRpb24nLFxuICAgICAgcnVuc09uOiBbJ3VidW50dS1sYXRlc3QnXSxcbiAgICAgIHBlcm1pc3Npb25zOiB7IGlkVG9rZW46IEpvYlBlcm1pc3Npb24uV1JJVEUsIGNvbnRlbnRzOiBKb2JQZXJtaXNzaW9uLlJFQUQgfSxcbiAgICAgIHN0ZXBzLFxuICAgIH0pO1xuICB9XG5cbiAgcHVibGljIGNyZWF0ZUFzc2V0VXBsb2FkKG9wdGlvbnM6IEFzc2V0VXBsb2FkU3RhZ2VPcHRpb25zKTogdm9pZCB7XG4gICAgdGhpcy5kZXBsb3ltZW50V29ya2Zsb3cuYWRkSm9iKCdhc3NldFVwbG9hZCcsIHtcbiAgICAgIG5hbWU6ICdQdWJsaXNoIGFzc2V0cyB0byBBV1MnLFxuICAgICAgbmVlZHM6IFsnc3ludGgnXSxcbiAgICAgIHJ1bnNPbjogWyd1YnVudHUtbGF0ZXN0J10sXG4gICAgICBwZXJtaXNzaW9uczogeyBpZFRva2VuOiBKb2JQZXJtaXNzaW9uLldSSVRFLCBjb250ZW50czogSm9iUGVybWlzc2lvbi5SRUFEIH0sXG4gICAgICBzdGVwczogW3tcbiAgICAgICAgbmFtZTogJ0NoZWNrb3V0JyxcbiAgICAgICAgdXNlczogJ2FjdGlvbnMvY2hlY2tvdXRAdjInLFxuICAgICAgfSwge1xuICAgICAgICBuYW1lOiAnQVdTIENyZWRlbnRpYWxzJyxcbiAgICAgICAgdXNlczogJ2F3cy1hY3Rpb25zL2NvbmZpZ3VyZS1hd3MtY3JlZGVudGlhbHNAbWFzdGVyJyxcbiAgICAgICAgd2l0aDoge1xuICAgICAgICAgICdyb2xlLXRvLWFzc3VtZSc6IHRoaXMucHJvcHMuZ2l0aHViQ29uZmlnPy5hd3NSb2xlQXJuRm9yQXNzZXRQdWJsaXNoaW5nID8/IHRoaXMucHJvcHMuZ2l0aHViQ29uZmlnPy5kZWZhdWx0QXdzUm9sZUFybixcbiAgICAgICAgICAncm9sZS1zZXNzaW9uLW5hbWUnOiAnR2l0SHViQWN0aW9uJyxcbiAgICAgICAgICAnYXdzLXJlZ2lvbic6ICd1cy1lYXN0LTEnLFxuICAgICAgICB9LFxuICAgICAgfSxcbiAgICAgIC4uLm9wdGlvbnMuY29tbWFuZHMubWFwKGNtZCA9PiAoe1xuICAgICAgICBydW46IGNtZCxcbiAgICAgIH0pKV0sXG4gICAgfSk7XG4gIH1cblxuICBwdWJsaWMgY3JlYXRlRGVwbG95bWVudChvcHRpb25zOiBEZXBsb3lTdGFnZU9wdGlvbnMpOiB2b2lkIHtcbiAgICB0aGlzLmRlcGxveW1lbnRXb3JrZmxvdy5hZGRKb2IoYGRlcGxveS0ke29wdGlvbnMuc3RhZ2VOYW1lfWAsIHtcbiAgICAgIG5hbWU6IGBEZXBsb3kgc3RhZ2UgJHtvcHRpb25zLnN0YWdlTmFtZX0gdG8gQVdTYCxcbiAgICAgIG5lZWRzOiB0aGlzLmRlcGxveW1lbnRTdGFnZXMubGVuZ3RoID4gMCA/IFsnYXNzZXRVcGxvYWQnLCBgZGVwbG95LSR7dGhpcy5kZXBsb3ltZW50U3RhZ2VzLmF0KC0xKSF9YF0gOiBbJ2Fzc2V0VXBsb2FkJ10sXG4gICAgICBydW5zT246IFsndWJ1bnR1LWxhdGVzdCddLFxuICAgICAgcGVybWlzc2lvbnM6IHsgaWRUb2tlbjogSm9iUGVybWlzc2lvbi5XUklURSwgY29udGVudHM6IEpvYlBlcm1pc3Npb24uUkVBRCB9LFxuICAgICAgc3RlcHM6IFt7XG4gICAgICAgIG5hbWU6ICdDaGVja291dCcsXG4gICAgICAgIHVzZXM6ICdhY3Rpb25zL2NoZWNrb3V0QHYyJyxcbiAgICAgIH0sIHtcbiAgICAgICAgbmFtZTogJ0FXUyBDcmVkZW50aWFscycsXG4gICAgICAgIHVzZXM6ICdhd3MtYWN0aW9ucy9jb25maWd1cmUtYXdzLWNyZWRlbnRpYWxzQG1hc3RlcicsXG4gICAgICAgIHdpdGg6IHtcbiAgICAgICAgICAncm9sZS10by1hc3N1bWUnOiB0aGlzLnByb3BzLmdpdGh1YkNvbmZpZz8uYXdzUm9sZUFybkZvckRlcGxveW1lbnQ/LltvcHRpb25zLnN0YWdlTmFtZSBhcyBrZXlvZiBSb2xlTWFwXSA/PyB0aGlzLnByb3BzLmdpdGh1YkNvbmZpZz8uZGVmYXVsdEF3c1JvbGVBcm4sXG4gICAgICAgICAgJ3JvbGUtc2Vzc2lvbi1uYW1lJzogJ0dpdEh1YkFjdGlvbicsXG4gICAgICAgICAgJ2F3cy1yZWdpb24nOiBvcHRpb25zLmVudi5yZWdpb24sXG4gICAgICAgIH0sXG4gICAgICB9LFxuICAgICAgLi4ub3B0aW9ucy5jb21tYW5kcy5tYXAoY21kID0+ICh7XG4gICAgICAgIHJ1bjogY21kLFxuICAgICAgfSkpXSxcbiAgICB9KTtcbiAgICB0aGlzLmRlcGxveW1lbnRTdGFnZXMucHVzaChvcHRpb25zLnN0YWdlTmFtZSk7XG4gIH1cbn0iXX0=

package/lib/engine/index.d.ts

@@ -0,0 +1,2 @@
+export * from './base';
+export * from './github';

package/lib/engine/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base"), exports);
+__exportStar(require("./github"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZW5naW5lL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSx5Q0FBdUI7QUFDdkIsMkNBQXlCIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0ICogZnJvbSAnLi9iYXNlJztcbmV4cG9ydCAqIGZyb20gJy4vZ2l0aHViJzsiXX0=

package/lib/index.d.ts

@@ -1 +1,2 @@
 export * from './pipeline';
+export * from './engine';

package/lib/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./pipeline"), exports);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLDZDQUEyQiIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCAqIGZyb20gJy4vcGlwZWxpbmUnOyJdfQ==
+__exportStar(require("./engine"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLDZDQUEyQjtBQUMzQiwyQ0FBeUIiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgKiBmcm9tICcuL3BpcGVsaW5lJztcbmV4cG9ydCAqIGZyb20gJy4vZW5naW5lJzsiXX0=

package/lib/pipeline.d.ts

@@ -1,26 +1,154 @@
 import { Component, awscdk } from 'projen';
+import { BaseEngine, GithubEngineConfig } from './engine';
+/**
+ * The Environment interface is designed to hold AWS related information
+ * for a specific deployment environment within your infrastructure.
+ * Each environment requires a specific account and region for its resources.
+ */
 export interface Environment {
+    /**
+     * The AWS Account ID associated with the environment. It's important because
+     * different services or features could have distinct permissions and settings
+     * in different accounts.
+     */
     readonly account: string;
+    /**
+     * The AWS Region for the environment. This determines where your resources
+     * are created and where your application will run. It can affect latency,
+     * availability, and pricing.
+     */
     readonly region: string;
 }
+/**
+ * The EnvironmentMap interface is used to maintain a mapping of different types
+ * of environments used in the application. Each type of environment - personal,
+ * feature, dev, and prod, represents a different stage of development or usage.
+ */
 export interface EnvironmentMap {
+    /**
+     * The personal environment is usually used for individual development and
+     * testing, allowing developers to freely test and experiment without
+     * affecting the shared development environment.
+     */
     readonly personal: Environment;
+    /**
+     * The feature environment is typically used for developing specific features
+     * in isolation from the main codebase. This allows developers to work on
+     * individual features without impacting the stability of the dev or prod
+     * environments.
+     */
     readonly feature: Environment;
+    /**
+     * The dev environment is a shared environment where developers integrate
+     * their feature changes. It represents the latest version of the application
+     * but may not be as stable as the production environment.
+     */
     readonly dev: Environment;
+    /**
+     * The prod environment is where the live, user-facing application runs.
+     * It should be stable and only receive thoroughly tested changes.
+     */
     readonly prod: Environment;
 }
+/**
+ * The CI/CD tooling used to run your pipeline.
+ * The component will render workflows for the given system
+ */
+export declare enum PipelineEngine {
+    /** Create GitHub actions */
+    GITHUB = 0,
+    /** Create a .gitlab-ci.yaml file */
+    GITLAB = 1
+}
+/**
+ * Describes the type of pipeline that will be created
+ */
+export declare enum DeploymentType {
+    /** Deploy every commit as far as possible; hopefully into production */
+    CONTINUOUS_DEPLOYMENT = 0,
+    /** Build every commit and prepare all assets for a later deployment */
+    CONTINUOUS_DELIVERY = 1
+}
+/**
+ * The CDKPipelineOptions interface is designed to provide configuration
+ * options for a CDK (Cloud Development Kit) pipeline. It allows the definition
+ * of settings such as the stack prefix and package namespace to be used in the
+ * AWS stack, along with the environments configuration to be used.
+ */
 export interface CDKPipelineOptions {
-    readonly stackPrefix: string;
+    /**
+     * This field is used to define a prefix for the AWS Stack resources created
+     * during the pipeline's operation.
+     *
+     * @default project name
+     */
+    readonly stackPrefix?: string;
+    /**
+     * This field determines the NPM namespace to be used when packaging CDK cloud
+     * assemblies. A namespace helps group related resources together, providing
+     * better organization and ease of management.
+     */
     readonly pkgNamespace: string;
+    /**
+     * This is a map of environments to be used in the pipeline. It allows the
+     * pipeline to deploy to different environments based on the stage of the
+     * deployment process, whether that's a personal, feature, dev, or prod stage.
+     */
     readonly environments: EnvironmentMap;
+    /**
+     * This field specifies the type of pipeline to create. If set to CONTINUOUS_DEPLOYMENT,
+     * every commit is deployed as far as possible, hopefully into production. If set to
+     * CONTINUOUS_DELIVERY, every commit is built and all assets are prepared for a later deployment.
+     *
+     * @default CONTINUOUS_DELIVERY
+     */
+    readonly deploymentType?: DeploymentType;
+    /**
+     * This field determines the CI/CD tooling that will be used to run the pipeline. The component
+     * will render workflows for the given system. Options include GitHub and GitLab.
+     *
+     * @default - tries to derive it from the projects configuration
+     */
+    readonly engine?: PipelineEngine;
+    readonly githubConfig?: GithubEngineConfig;
+    readonly preInstallCommands?: string[];
+    readonly preSynthCommands?: string[];
+    readonly postSynthCommands?: string[];
 }
+/**
+ * The CDKPipeline class extends the Component class and sets up the necessary configuration for deploying AWS CDK (Cloud Development Kit) applications across multiple stages.
+ * It also manages tasks such as publishing CDK assets, bumping version based on git tags, and cleaning up conflicting tasks.
+ */
 export declare class CDKPipeline extends Component {
     private app;
     private props;
+    readonly stackPrefix: string;
+    readonly engine: BaseEngine;
     constructor(app: awscdk.AwsCdkTypeScriptApp, props: CDKPipelineOptions);
+    private createSynthStage;
+    /**
+     * This method generates the entry point for the application, including interfaces and classes
+     * necessary to set up the pipeline and define the AWS CDK stacks for different environments.
+     */
     private createApplicationEntrypoint;
+    /**
+     * This method sets up tasks to publish CDK assets to all accounts and handle versioning, including bumping the version
+     * based on the latest git tag and pushing the CDK assembly to the package repository.
+     */
     private createReleaseTasks;
+    /**
+     * This method sets up tasks for the personal deployment stage, including deployment, watching for changes,
+     * comparing changes (diff), and destroying the stack when no longer needed.
+     */
     private createPersonalStage;
+    /**
+     * This method sets up tasks for the feature deployment stage, including deployment, comparing changes (diff),
+     * and destroying the stack when no longer needed.
+     */
     private createFeatureStage;
+    /**
+     * This method sets up tasks for the general pipeline stages (dev, prod), including deployment and comparing changes (diff).
+     * @param {string} stageName - The name of the stage (e.g., 'dev', 'prod')
+     */
     private createPipelineStage;
 }