Manage GitHub resources like repositories, teams, members, integrations and workflows with the AWS CDK as Custom Resources in CloudFormation with cdk-github.
You configure the endpoint, method and parameters documented by @octokit/rest and 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 the GitHub REST API.
TypeScript
npm install @pepperize/cdk-github
or
yarn add @pepperize/cdk-github
Python
pip install pepperize.cdk-github
C#
dotnet add package Pepperize.CDK.Github
Java
<dependency>
<groupId>com.pepperize</groupId>
<artifactId>cdk-github</artifactId>
<version>${cdkGithub.version}</version>
</dependency>
Contributions of all kinds are welcome 🚀 Check out our contributor's guide.
For a quick start, fork and check out a development environment:
git clone git@github.com:pepperize/cdk-github
cd cdk-github
# install dependencies
yarn
# build with projen
yarn build
-
Create an AWS Secrets Manager secret
{ "appId": "123456", "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nExample==\n-----END RSA PRIVATE KEY-----", "installationId": "12345678" }
-
Add @pepperize/cdk-github to your project dependencies
yarn add @pepperize/cdk-github
-
Add your
main.ts
const app = new App(); const stack = new Stack(app, "GithubCustomResources");
Just for simplicity, it's up to you how to organize your app 😉
-
Import your secret
const secret = secrets_manager.Secret.fromSecretNameV2(stack, "Auth", "cdk-github/test");
-
Configure GitHub App authenticate as an installation
const authOptions = AuthOptions.appAuth(secret);
-
Add your first GitHub Custom Resource with the AWS CDK
new GithubCustomResource(stack, "GithubRepo", { onCreate: { // 👇The endpoint of the GitHub API. endpoint: "repos", // 👇The method of the GitHub API. method: "createInOrg", // https://octokit.github.io/rest.js/v19/#repos-create-in-org parameters: { // 👇The request parameters to send. org: "pepperize", name: "cdk-github", }, // 👇The object keys from the GitHub API response to return to CFN. outputPaths: ["id", "full_name"], // 👇This becomes the CFN Physical ID visible in the Console. physicalResourceId: custom_resources.PhysicalResourceId.fromResponse("full_name"), // 👇Don't throw an error if message matching this regex. ignoreErrorCodesMatching: "name already exists on this account", }, // 👇The implemented authentication strategy. authOptions: AuthOptions.appAuth(secret), });
-
Deploy your first GitHub Custom Resource
npx cdk deploy
Configure the AWS SecretsManager Secret with the AuthOptions that will be passed to octokit.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:
// 👇Lookup your secret containing the AuthOptions
const secret = secrets_manager.Secret.fromSecretNameV2(stack, "Auth", "cdk-github/test");
// 👇This will send the secret arn to the custom resource handler
const authOptions = AuthOptions.appAuth(secret);
The custom resource handler will configure octokit.js with the createAppAuth
:
const getSecretValueResponse = await SSM.getSecretValue({ SecretId: secret }).promise();
const octokitOptions: OctokitOptions = {
authStrategy: createAppAuth,
auth: (auth = JSON.parse(getSecretValueResponse.SecretString)),
};
Supported through @octokit/auth-app
Just add your PAT to an SSM StringParameter
// 👇Lookup your parameter containing the TOKEN
const parameter = ssm.StringParameter.fromStringParameterName(stack, "Auth", "cdk-github/test");
// 👇This will send the parameter arn to the custom resource handler
const authOptions = AuthOptions.tokenAuth(parameter);
Supported through @octokit/auth-token
// 👇This will configure octokit without authentication
const authOptions = AuthOptions.unauthenticated();
@octokit/plugin-rest-endpoint-methods
const secret = secrets_manager.Secret.fromSecretNameV2(stack, "Auth", "cdk-github/test");
new GithubCustomResource(stack, "GithubRepo", {
onCreate: {
// https://octokit.github.io/rest.js/v19/#repos-create-in-org
endpoint: "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-get
endpoint: "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-delete
endpoint: "repos",
method: "delete",
parameters: {
owner: "pepperize",
repo: "cdk-github",
},
outputPaths: [],
},
authOptions: AuthOptions.appAuth(secret),
});