Manage GitHub resources like repositories, teams, members, integrations and workflows with the AWS CDK as Custom Resources in CloudFormation with [cdk-github](https://github.com/pepperize/cdk-github).
Project description
CDK Github
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.
Install
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>
Contributing
Contributions of all kinds are welcome :rocket: 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
Getting Started
-
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 :wink:
-
Import your secret
const secret = secrets_manager.Secret.fromSecretNameV2(stack, "Auth", "cdk-github/github-token");
-
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
Authentication
GitHub App or installation authentication
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/github-token");
// ๐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
Personal Access Token authentication
Just add your PAT to an SSM StringParameter
// ๐Lookup your parameter containing the TOKEN
const parameter = ssm.StringParameter.fromStringParameterName(stack, "Auth", "cdk-github/github-token");
// ๐This will send the parameter arn to the custom resource handler
const authOptions = AuthOptions.tokenAuth(parameter);
Supported through @octokit/auth-token
Unauthenticated
// ๐This will configure octokit without authentication
const authOptions = AuthOptions.unauthenticated();
Manage a GitHub Repository - Example
@octokit/plugin-rest-endpoint-methods
const auth = secrets_manager.Secret.fromSecretNameV2(stack, "Auth", "cdk-github/github-token");
const repo = 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(auth),
});
// ๐ This will return the created repository id as a CDK Token
repo.getAtt("id");
Manage GitHub Actions Secrets
Environment Secret
Manages an environment secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.
// ๐The GitHub API authentication secret
const auth = secrets_manager.Secret.fromSecretNameV2(scope, "Auth", "cdk-github/github-token");
// ๐The AWS SecretsManager Secret to configure as GitHub Action secret.
const secret = secrets_manager.Secret.fromSecretNameV2(scope, "Secret", "any-secret/example");
new GithubActionsSecretEnvironment(scope, "GithubRepo", {
// ๐The repository id, which you may lookup from the page source or via a custom resource
repositoryId: "558989134",
environmentName: "production",
// ๐The name of the created GitHub secret
secretName: "example",
// ๐The source AWS SecretsManager secret and JSON field to use
source: GithubActionsSecret.fromSecretsManager(secret, "some-json-field"),
authOptions: AuthOptions.appAuth(auth),
// ๐Whether to delete or retain the GitHub secret on resource removal
removalPolicy: RemovalPolicy.DESTROY,
});
You may retrieve the
repository_id
from the GitHub Repository page source's meta tag i.e.<meta name="octolytics-dimension-repository_id" content="558989134">
or from anotherGithubCustomResource
viagetAtt()
.
See GitHub Developer Guide, API Reference
Organization Secret
Manage an GitHib Actions organization secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.
// ๐The GitHub API authentication secret
const auth = secrets_manager.Secret.fromSecretNameV2(scope, "Auth", "cdk-github/github-token");
// ๐The AWS SecretsManager Secret to configure as GitHub Action secret.
const secret = secrets_manager.Secret.fromSecretNameV2(scope, "Secret", "any-secret/example");
new GithubActionsSecretOrganization(scope, "GithubRepo", {
organizationName: "pepperize",
// ๐The name of the created GitHub secret
secretName: "example",
// ๐The source AWS SecretsManager secret and JSON field to use
source: GithubActionsSecret.fromSecretsManager(secret, "some-json-field"),
visibility: Visibility.ALL,
authOptions: AuthOptions.appAuth(auth),
// ๐Whether to delete or retain the GitHub secret on resource removal
removalPolicy: RemovalPolicy.DESTROY,
});
See GitHub Developer Guide, API Reference
Repository Secret
Manage an GitHib Actions Repository secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.
// ๐The GitHub API authentication secret
const auth = secrets_manager.Secret.fromSecretNameV2(scope, "Auth", "cdk-github/github-token");
// ๐The AWS SecretsManager Secret to configure as GitHub Action secret.
const secret = secrets_manager.Secret.fromSecretNameV2(scope, "Secret", "any-secret/example");
new GithubActionsSecretRepository(scope, "GithubRepo", {
owner: "pepperize",
repositoryName: "cdk-github",
// ๐The name of the created GitHub secret
secretName: "example",
// ๐The source AWS SecretsManager secret and JSON field to use
source: GithubActionsSecret.fromSecretsManager(secret, "some-json-field"),
authOptions: AuthOptions.appAuth(auth),
// ๐Whether to delete or retain the GitHub secret on resource removal
removalPolicy: RemovalPolicy.DESTROY,
});
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pepperize.cdk-github-0.0.707.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a5e229c5b427a47b3678e83382772db8e43ec7c2eebe1254a52ef95a943c7e2c |
|
MD5 | fcd9242bba48c4f072ec505a2a1a6f9e |
|
BLAKE2b-256 | 5be19ae80802051b7faa45248a51b75535e27c60dfe4937afabfbe456c01b680 |
Hashes for pepperize.cdk_github-0.0.707-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e1c8cc1cec13bcf6ce7fed05e72a9389b3d94c83c5d18a56caa010ab563024a7 |
|
MD5 | ea6c00d7d47239dbc1e747d235f0b92e |
|
BLAKE2b-256 | 044b50340b97d6139bbb4aed64a0338868850899493bc2a75ecaaace0d294ac3 |