diff --git a/packages/@aws-cdk/aws-codestar/README.md b/packages/@aws-cdk/aws-codestar/README.md index 3f423f3b8a5ab..87c1685ad6ffd 100644 --- a/packages/@aws-cdk/aws-codestar/README.md +++ b/packages/@aws-cdk/aws-codestar/README.md @@ -6,11 +6,32 @@ > All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use. +![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge) + +> The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package. + --- -This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project. +## GitHub Repository + +To create a new GitHub Repository and commit the assets from S3 bucket into the repository after it is created: ```ts import * as codestar from '@aws-cdk/aws-codestar'; +import * as s3 from '@aws-cdk/aws-s3' + +new codestar.GitHubRepository(stack, 'GitHubRepo', { + owner: 'aws', + repositoryName: 'aws-cdk', + accessToken: cdk.SecretValue.secretsManager('my-github-token', { + jsonField: 'token', + }), + contentsBucket: s3.Bucket.fromBucketName(stack, 'Bucket', 'bucket-name'), + contentsKey: 'import.zip', +}); ``` + +## Update or Delete the GitHubRepository + +At this moment, updates to the `GitHubRepository` are not supported and the repository will not be deleted upon the deletion of the CloudFormation stack. You will need to update or delete the GitHub repository manually. diff --git a/packages/@aws-cdk/aws-codestar/lib/github-repository.ts b/packages/@aws-cdk/aws-codestar/lib/github-repository.ts new file mode 100644 index 0000000000000..0afd45eb0c826 --- /dev/null +++ b/packages/@aws-cdk/aws-codestar/lib/github-repository.ts @@ -0,0 +1,126 @@ +import * as s3 from '@aws-cdk/aws-s3'; +import * as cdk from '@aws-cdk/core'; +import * as codestar from './codestar.generated'; + +/** + * GitHubRepository resource interface + */ +export interface IGitHubRepository extends cdk.IResource { + /** + * the repository owner + */ + readonly owner: string + + /** + * the repository name + */ + readonly repo: string +} + +/** + * Construction properties of {@link GitHubRepository}. + */ +export interface GitHubRepositoryProps { + /** + * The GitHub user name for the owner of the GitHub repository to be created. If this + * repository should be owned by a GitHub organization, provide its name + */ + readonly owner: string; + + /** + * The name of the repository you want to create in GitHub with AWS CloudFormation stack creation + */ + readonly repositoryName: string; + + /** + * The GitHub user's personal access token for the GitHub repository + */ + readonly accessToken: cdk.SecretValue; + + /** + * The name of the Amazon S3 bucket that contains the ZIP file with the content to be committed to the new repository + */ + readonly contentsBucket: s3.IBucket; + + /** + * The S3 object key or file name for the ZIP file + */ + readonly contentsKey: string; + + /** + * The object version of the ZIP file, if versioning is enabled for the Amazon S3 bucket + * + * @default - not specified + */ + readonly contentsS3Version?: string; + + /** + * Indicates whether to enable issues for the GitHub repository. You can use GitHub issues to track information + * and bugs for your repository. + * + * @default true + */ + readonly enableIssues?: boolean; + + /** + * Indicates whether the GitHub repository is a private repository. If so, you choose who can see and commit to + * this repository. + * + * @default RepositoryVisibility.PUBLIC + */ + readonly visibility?: RepositoryVisibility; + + /** + * A comment or description about the new repository. This description is displayed in GitHub after the repository + * is created. + * + * @default - no description + */ + readonly description?: string; +} + +/** + * The GitHubRepository resource + */ +export class GitHubRepository extends cdk.Resource implements IGitHubRepository { + + public readonly owner: string; + public readonly repo: string; + + constructor(scope: cdk.Construct, id: string, props: GitHubRepositoryProps) { + super(scope, id); + + const resource = new codestar.CfnGitHubRepository(this, 'Resource', { + repositoryOwner: props.owner, + repositoryName: props.repositoryName, + repositoryAccessToken: props.accessToken.toString(), + code: { + s3: { + bucket: props.contentsBucket.bucketName, + key: props.contentsKey, + objectVersion: props.contentsS3Version, + }, + }, + enableIssues: props.enableIssues ?? true, + isPrivate: props.visibility === RepositoryVisibility.PRIVATE ? true : false, + repositoryDescription: props.description, + }); + + this.owner = cdk.Fn.select(0, cdk.Fn.split('/', resource.ref)); + this.repo = cdk.Fn.select(1, cdk.Fn.split('/', resource.ref)); + } +} + +/** + * Visibility of the GitHubRepository + */ +export enum RepositoryVisibility { + /** + * private repository + */ + PRIVATE, + /** + * public repository + */ + PUBLIC, +} diff --git a/packages/@aws-cdk/aws-codestar/lib/index.ts b/packages/@aws-cdk/aws-codestar/lib/index.ts index 4114892b944da..ff8a544388441 100644 --- a/packages/@aws-cdk/aws-codestar/lib/index.ts +++ b/packages/@aws-cdk/aws-codestar/lib/index.ts @@ -1,2 +1,3 @@ // AWS::CodeStar CloudFormation Resources: export * from './codestar.generated'; +export * from './github-repository'; diff --git a/packages/@aws-cdk/aws-codestar/package.json b/packages/@aws-cdk/aws-codestar/package.json index d0c07ad1c6489..2b1d9cfc7773c 100644 --- a/packages/@aws-cdk/aws-codestar/package.json +++ b/packages/@aws-cdk/aws-codestar/package.json @@ -67,22 +67,30 @@ "devDependencies": { "@aws-cdk/assert": "0.0.0", "cdk-build-tools": "0.0.0", + "cdk-integ-tools": "0.0.0", "cfn2ts": "0.0.0", "pkglint": "0.0.0" }, "dependencies": { + "@aws-cdk/aws-s3": "0.0.0", "@aws-cdk/core": "0.0.0", "constructs": "^3.0.2" }, "peerDependencies": { + "@aws-cdk/aws-s3": "0.0.0", "@aws-cdk/core": "0.0.0", "constructs": "^3.0.2" }, "engines": { "node": ">= 10.13.0 <13 || >=13.7.0" }, + "awslint": { + "exclude": [ + "props-physical-name:@aws-cdk/aws-codestar.GitHubRepositoryProps" + ] + }, "stability": "experimental", - "maturity": "cfn-only", + "maturity": "experimental", "awscdkio": { "announce": false } diff --git a/packages/@aws-cdk/aws-codestar/test/codestar.test.ts b/packages/@aws-cdk/aws-codestar/test/codestar.test.ts index e394ef336bfb4..bc551f25a41d3 100644 --- a/packages/@aws-cdk/aws-codestar/test/codestar.test.ts +++ b/packages/@aws-cdk/aws-codestar/test/codestar.test.ts @@ -1,6 +1,56 @@ import '@aws-cdk/assert/jest'; -import {} from '../lib'; +import { Bucket } from '@aws-cdk/aws-s3'; +import * as cdk from '@aws-cdk/core'; +import { GitHubRepository, RepositoryVisibility } from '../lib'; -test('No tests are specified for this package', () => { - expect(true).toBe(true); +describe('GitHub Repository', () => { + let stack: cdk.Stack; + + beforeEach(() => { + const app = new cdk.App(); + stack = new cdk.Stack(app, 'GitHubDemo'); + }); + + test('create', () => { + new GitHubRepository(stack, 'GitHubRepo', { + owner: 'foo', + repositoryName: 'bar', + accessToken: cdk.SecretValue.secretsManager('my-github-token', { + jsonField: 'token', + }), + contentsBucket: Bucket.fromBucketName(stack, 'Bucket', 'bucket-name'), + contentsKey: 'import.zip', + }); + + expect(stack).toHaveResource('AWS::CodeStar::GitHubRepository', { + RepositoryAccessToken: '{{resolve:secretsmanager:my-github-token:SecretString:token::}}', + RepositoryName: 'bar', + RepositoryOwner: 'foo', + Code: { + S3: { + Bucket: 'bucket-name', + Key: 'import.zip', + }, + }, + }); + }); + + test('enable issues and private', () => { + new GitHubRepository(stack, 'GitHubRepo', { + owner: 'foo', + repositoryName: 'bar', + accessToken: cdk.SecretValue.secretsManager('my-github-token', { + jsonField: 'token', + }), + contentsBucket: Bucket.fromBucketName(stack, 'Bucket', 'bucket-name'), + contentsKey: 'import.zip', + enableIssues: true, + visibility: RepositoryVisibility.PRIVATE, + }); + + expect(stack).toHaveResourceLike('AWS::CodeStar::GitHubRepository', { + EnableIssues: true, + IsPrivate: true, + }); + }); });