Package: pepperize.cdk-github
CDK GithubManage GitHub resources like repositories, teams, members, integrations and workflows with the AWS CDK as Custom Resources in CloudFormation withcdk-github.You configure the endpoint, method and parameters documented by@octokit/restand AWS CloudFormation runs them anytime you create, update (if you changed the custom resource), or delete stacks. When CloudFormation sends a lifecycle event notification, then your custom resource sends the request to theGitHub REST API.InstallTypeScriptnpminstall@pepperize/cdk-githuboryarnadd@pepperize/cdk-githubPythonpipinstallpepperize.cdk-githubC#dotnet add package Pepperize.CDK.GithubJava<dependency><groupId>com.pepperize</groupId><artifactId>cdk-github</artifactId><version>${cdkGithub.version}</version></dependency>ContributingContributions of all kinds are welcome :rocket: Check out ourcontributor's guide.For a quick start,fork and check outa development environment:gitclonegit@github.com:pepperize/cdk-githubcdcdk-github# install dependenciesyarn# build with projenyarnbuildGetting StartedCreating a GitHub AppInstalling GitHub AppsCreate an AWS Secrets Manager secret{"appId":"123456","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nExample==\n-----END RSA PRIVATE KEY-----","installationId":"12345678"}Add@pepperize/cdk-githubto your project dependenciesyarnadd@pepperize/cdk-githubAdd yourmain.tsconstapp=newApp();conststack=newStack(app,"GithubCustomResources");Just for simplicity, it's up to you how to organize your app :wink:Import your secretconstsecret=secrets_manager.Secret.fromSecretNameV2(stack,"Auth","cdk-github/github-token");Configure GitHub App authenticate as an installationconstauthOptions=AuthOptions.appAuth(secret);Add your first GitHub Custom Resource with the AWS CDKnewGithubCustomResource(stack,"GithubRepo",{onCreate:{//👇TheendpointoftheGitHubAPI.endpoint:"repos",//👇ThemethodoftheGitHubAPI.method:"createInOrg",//https://octokit.github.io/rest.js/v19/#repos-create-in-orgparameters:{//👇Therequestparameterstosend.org:"pepperize",name:"cdk-github",},//👇TheobjectkeysfromtheGitHubAPIresponsetoreturntoCFN.outputPaths:["id","full_name"],//👇ThisbecomestheCFNPhysicalIDvisibleintheConsole.physicalResourceId:custom_resources.PhysicalResourceId.fromResponse("full_name"),//👇Don't throw an error if message matching this regex.ignoreErrorCodesMatching:"name already exists on this account",},//👇Theimplementedauthenticationstrategy.authOptions:AuthOptions.appAuth(secret),});Deploy your first GitHub Custom ResourcenpxcdkdeployAuthenticationGitHub App or installation authenticationConfigure the AWS SecretsManager Secret with the AuthOptions that will be passed tooctokit.auth. i.e. as an installation:{"appId":"123456","privateKey":"-----BEGIN RSA PRIVATE KEY-----\nExample==\n-----END RSA PRIVATE KEY-----","installationId":"12345678"}Lookup the secret in your AWS CDK app://👇LookupyoursecretcontainingtheAuthOptionsconstsecret=secrets_manager.Secret.fromSecretNameV2(stack,"Auth","cdk-github/github-token");//👇ThiswillsendthesecretarntothecustomresourcehandlerconstauthOptions=AuthOptions.appAuth(secret);The custom resource handler will configureoctokit.jswith thecreateAppAuth:constgetSecretValueResponse=awaitSSM.getSecretValue({SecretId:secret}).promise();constoctokitOptions:OctokitOptions={authStrategy:createAppAuth,auth:(auth=JSON.parse(getSecretValueResponse.SecretString)),};Supported through@octokit/auth-appPersonal Access Token authenticationJust add your PAT to an SSM StringParameter//👇LookupyourparametercontainingtheTOKENconstparameter=ssm.StringParameter.fromStringParameterName(stack,"Auth","cdk-github/github-token");//👇ThiswillsendtheparameterarntothecustomresourcehandlerconstauthOptions=AuthOptions.tokenAuth(parameter);Supported through@octokit/auth-tokenUnauthenticated//👇ThiswillconfigureoctokitwithoutauthenticationconstauthOptions=AuthOptions.unauthenticated();Manage a GitHub Repository - Example@octokit/plugin-rest-endpoint-methodsconstauth=secrets_manager.Secret.fromSecretNameV2(stack,"Auth","cdk-github/github-token");constrepo=newGithubCustomResource(stack,"GithubRepo",{onCreate:{//https://octokit.github.io/rest.js/v19/#repos-create-in-orgendpoint:"repos",method:"createInOrg",parameters:{org:"pepperize",name:"cdk-github",},outputPaths:["id","full_name"],physicalResourceId:custom_resources.PhysicalResourceId.fromResponse("full_name"),ignoreErrorCodesMatching:"name already exists on this account",},onUpdate:{//https://octokit.github.io/rest.js/v19#repos-getendpoint:"repos",method:"get",parameters:{owner:"pepperize",repo:"cdk-github",},outputPaths:["id","full_name"],physicalResourceId:custom_resources.PhysicalResourceId.fromResponse("full_name"),},onDelete:{//https://octokit.github.io/rest.js/v19#repos-deleteendpoint:"repos",method:"delete",parameters:{owner:"pepperize",repo:"cdk-github",},outputPaths:[],},authOptions:AuthOptions.appAuth(auth),});//👇ThiswillreturnthecreatedrepositoryidasaCDKTokenrepo.getAtt("id");Manage GitHub Actions SecretsEnvironment SecretManages an environment secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.//👇TheGitHubAPIauthenticationsecretconstauth=secrets_manager.Secret.fromSecretNameV2(scope,"Auth","cdk-github/github-token");//👇TheAWSSecretsManagerSecrettoconfigureasGitHubActionsecret.constsecret=secrets_manager.Secret.fromSecretNameV2(scope,"Secret","any-secret/example");newGithubActionsSecretEnvironment(scope,"GithubRepo",{//👇Therepositoryid,whichyoumaylookupfromthepagesourceorviaacustomresourcerepositoryId:"558989134",environmentName:"production",//👇ThenameofthecreatedGitHubsecretsecretName:"example",//👇ThesourceAWSSecretsManagersecretandJSONfieldtousesource:GithubActionsSecret.fromSecretsManager(secret,"some-json-field"),authOptions:AuthOptions.appAuth(auth),//👇WhethertodeleteorretaintheGitHubsecretonresourceremovalremovalPolicy:RemovalPolicy.DESTROY,});You may retrieve therepository_idfrom the GitHub Repository page source's meta tag i.e.<meta name="octolytics-dimension-repository_id" content="558989134">or from anotherGithubCustomResourceviagetAtt().SeeGitHub Developer Guide,API ReferenceOrganization SecretManage an GitHib Actions organization secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.//👇TheGitHubAPIauthenticationsecretconstauth=secrets_manager.Secret.fromSecretNameV2(scope,"Auth","cdk-github/github-token");//👇TheAWSSecretsManagerSecrettoconfigureasGitHubActionsecret.constsecret=secrets_manager.Secret.fromSecretNameV2(scope,"Secret","any-secret/example");newGithubActionsSecretOrganization(scope,"GithubRepo",{organizationName:"pepperize",//👇ThenameofthecreatedGitHubsecretsecretName:"example",//👇ThesourceAWSSecretsManagersecretandJSONfieldtousesource:GithubActionsSecret.fromSecretsManager(secret,"some-json-field"),visibility:Visibility.ALL,authOptions:AuthOptions.appAuth(auth),//👇WhethertodeleteorretaintheGitHubsecretonresourceremovalremovalPolicy:RemovalPolicy.DESTROY,});SeeGitHub Developer Guide,API ReferenceRepository SecretManage an GitHib Actions Repository secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.//👇TheGitHubAPIauthenticationsecretconstauth=secrets_manager.Secret.fromSecretNameV2(scope,"Auth","cdk-github/github-token");//👇TheAWSSecretsManagerSecrettoconfigureasGitHubActionsecret.constsecret=secrets_manager.Secret.fromSecretNameV2(scope,"Secret","any-secret/example");newGithubActionsSecretRepository(scope,"GithubRepo",{owner:"pepperize",repositoryName:"cdk-github",//👇ThenameofthecreatedGitHubsecretsecretName:"example",//👇ThesourceAWSSecretsManagersecretandJSONfieldtousesource:GithubActionsSecret.fromSecretsManager(secret,"some-json-field"),authOptions:AuthOptions.appAuth(auth),//👇WhethertodeleteorretaintheGitHubsecretonresourceremovalremovalPolicy:RemovalPolicy.DESTROY,});SeeGitHub Developer Guide,API Reference