{"id":14261768,"url":"https://github.com/pepperize/cdk-github","last_synced_at":"2025-07-08T23:32:54.547Z","repository":{"id":62227866,"uuid":"558989134","full_name":"pepperize/cdk-github","owner":"pepperize","description":"Manage GitHub resources like repositories, teams, members, integrations and workflows with the AWS CDK as Custom Resources in CloudFormation.","archived":false,"fork":false,"pushed_at":"2025-06-20T23:50:42.000Z","size":5695,"stargazers_count":16,"open_issues_count":8,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-20T23:56:12.632Z","etag":null,"topics":["aws","cdk","construct","custom-resources","github","octokit","repositories"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pepperize.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-28T19:01:52.000Z","updated_at":"2025-06-20T23:50:40.000Z","dependencies_parsed_at":"2024-02-01T01:24:56.126Z","dependency_job_id":"5e214e30-f70c-4dc7-b397-9ddc23415881","html_url":"https://github.com/pepperize/cdk-github","commit_stats":{"total_commits":382,"total_committers":5,"mean_commits":76.4,"dds":0.08638743455497377,"last_synced_commit":"544fc0751abfd943aed274385656b7c135cac6be"},"previous_names":[],"tags_count":1007,"template":false,"template_full_name":null,"purl":"pkg:github/pepperize/cdk-github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepperize%2Fcdk-github","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepperize%2Fcdk-github/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepperize%2Fcdk-github/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepperize%2Fcdk-github/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pepperize","download_url":"https://codeload.github.com/pepperize/cdk-github/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepperize%2Fcdk-github/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261589463,"owners_count":23181405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cdk","construct","custom-resources","github","octokit","repositories"],"created_at":"2024-08-22T13:01:21.434Z","updated_at":"2025-07-08T23:32:54.248Z","avatar_url":"https://github.com/pepperize.png","language":"TypeScript","readme":"[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)\n[![GitHub](https://img.shields.io/github/license/pepperize/cdk-github?style=flat-square)](https://github.com/pepperize/cdk-github/blob/main/LICENSE)\n[![npm (scoped)](https://img.shields.io/npm/v/@pepperize/cdk-github?style=flat-square)](https://www.npmjs.com/package/@pepperize/cdk-github)\n[![PyPI](https://img.shields.io/pypi/v/pepperize.cdk-github?style=flat-square)](https://pypi.org/project/pepperize.cdk-github/)\n[![Nuget](https://img.shields.io/nuget/v/Pepperize.CDK.Github?style=flat-square)](https://www.nuget.org/packages/Pepperize.CDK.Github/)\n[![Sonatype Nexus (Releases)](https://img.shields.io/nexus/r/com.pepperize/cdk-github?server=https%3A%2F%2Fs01.oss.sonatype.org%2F\u0026style=flat-square)](https://s01.oss.sonatype.org/content/repositories/releases/com/pepperize/cdk-github/)\n[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/pepperize/cdk-github/release.yml?branch=main\u0026label=release\u0026style=flat-square)](https://github.com/pepperize/cdk-github/actions/workflows/release.yml)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/pepperize/cdk-github?sort=semver\u0026style=flat-square)](https://github.com/pepperize/cdk-github/releases)\n[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod\u0026style=flat-square)](https://gitpod.io/#https://github.com/pepperize/cdk-github)\n\n# CDK Github\n\nManage 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).\n\n\u003e You configure the endpoint, method and parameters documented by [@octokit/rest](https://octokit.github.io/rest.js/v19) 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](https://docs.github.com/en/rest).\n\n[![View on Construct Hub](https://constructs.dev/badge?package=%40pepperize%2Fcdk-github)](https://constructs.dev/packages/@pepperize/cdk-github)\n\n## Install\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eTypeScript\u003c/strong\u003e\u003c/summary\u003e\n\n```shell\nnpm install @pepperize/cdk-github\n```\n\nor\n\n```shell\nyarn add @pepperize/cdk-github\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003ePython\u003c/strong\u003e\u003c/summary\u003e\n\n```shell\npip install pepperize.cdk-github\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eC#\u003c/strong\u003e\u003c/summary\u003e\n\n```\ndotnet add package Pepperize.CDK.Github\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eJava\u003c/strong\u003e\u003c/summary\u003e\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.pepperize\u003c/groupId\u003e\n  \u003cartifactId\u003ecdk-github\u003c/artifactId\u003e\n  \u003cversion\u003e${cdkGithub.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\u003c/details\u003e\n\n## Contributing\n\nContributions of all kinds are welcome :rocket: Check out our [contributor's guide](https://github.com/pepperize/cdk-github/blob/main/CONTRIBUTING.md).\n\nFor a quick start, [fork and check out](https://github.com/pepperize/cdk-github/fork) a development environment:\n\n```shell\ngit clone git@github.com:pepperize/cdk-github\ncd cdk-github\n# install dependencies\nyarn\n# build with projen\nyarn build\n```\n\n## Getting Started\n\n1. [Creating a GitHub App](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app)\n2. [Installing GitHub Apps](https://docs.github.com/en/developers/apps/managing-github-apps/installing-github-apps)\n3. [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)\n\n   ```json\n   {\n     \"appId\": \"123456\",\n     \"privateKey\": \"-----BEGIN RSA PRIVATE KEY-----\\nExample==\\n-----END RSA PRIVATE KEY-----\",\n     \"installationId\": \"12345678\"\n   }\n   ```\n\n4. Add [@pepperize/cdk-github](https://github.com/pepperize/cdk-github) to your project dependencies\n\n   ```shell\n   yarn add @pepperize/cdk-github\n   ```\n\n5. Add your `main.ts`\n\n   ```typescript\n   const app = new App();\n   const stack = new Stack(app, \"GithubCustomResources\");\n   ```\n\n   \u003e Just for simplicity, it's up to you how to organize your app :wink:\n\n6. Import your secret\n\n   ```typescript\n   const secret = secrets_manager.Secret.fromSecretNameV2(stack, \"Auth\", \"cdk-github/github-token\");\n   ```\n\n7. Configure GitHub App authenticate as an installation\n\n   ```typescript\n   const authOptions = AuthOptions.appAuth(secret);\n   ```\n\n8. Add your first GitHub Custom Resource with the AWS CDK\n\n   ```typescript\n   new GithubCustomResource(stack, \"GithubRepo\", {\n     onCreate: {\n       // 👇The endpoint of the GitHub API.\n       endpoint: \"repos\",\n       // 👇The method of the GitHub API.\n       method: \"createInOrg\",\n       // https://octokit.github.io/rest.js/v19/#repos-create-in-org\n       parameters: {\n         // 👇The request parameters to send.\n         org: \"pepperize\",\n         name: \"cdk-github\",\n       },\n       // 👇The object keys from the GitHub API response to return to CFN.\n       outputPaths: [\"id\", \"full_name\"],\n       // 👇This becomes the CFN Physical ID visible in the Console.\n       physicalResourceId: custom_resources.PhysicalResourceId.fromResponse(\"full_name\"),\n       // 👇Don't throw an error if message matching this regex.\n       ignoreErrorCodesMatching: \"name already exists on this account\",\n     },\n     // 👇The implemented authentication strategy.\n     authOptions: AuthOptions.appAuth(secret),\n   });\n   ```\n\n9. Deploy your first GitHub Custom Resource\n\n   ```shell\n   npx cdk deploy\n   ```\n\n## Authentication\n\n### GitHub App or installation authentication\n\nConfigure the AWS SecretsManager Secret with the AuthOptions that will be passed to `octokit.auth`. i.e. as an installation:\n\n```json\n{\n  \"appId\": \"123456\",\n  \"privateKey\": \"-----BEGIN RSA PRIVATE KEY-----\\nExample==\\n-----END RSA PRIVATE KEY-----\",\n  \"installationId\": \"12345678\"\n}\n```\n\nLookup the secret in your AWS CDK app:\n\n```typescript\n// 👇Lookup your secret containing the AuthOptions\nconst secret = secrets_manager.Secret.fromSecretNameV2(stack, \"Auth\", \"cdk-github/github-token\");\n// 👇This will send the secret arn to the custom resource handler\nconst authOptions = AuthOptions.appAuth(secret);\n```\n\nThe custom resource handler will configure [octokit.js](https://github.com/octokit/octokit.js) with the `createAppAuth`:\n\n```typescript\nconst getSecretValueResponse = await SSM.getSecretValue({ SecretId: secret }).promise();\nconst octokitOptions: OctokitOptions = {\n  authStrategy: createAppAuth,\n  auth: (auth = JSON.parse(getSecretValueResponse.SecretString)),\n};\n```\n\n\u003e Supported through [@octokit/auth-app](https://github.com/octokit/auth-app.js#readme)\n\n### Personal Access Token authentication\n\nJust add your PAT to an SSM StringParameter\n\n```typescript\n// 👇Lookup your parameter containing the TOKEN\nconst parameter = ssm.StringParameter.fromStringParameterName(stack, \"Auth\", \"cdk-github/github-token\");\n// 👇This will send the parameter arn to the custom resource handler\nconst authOptions = AuthOptions.tokenAuth(parameter);\n```\n\n\u003e Supported through [@octokit/auth-token](https://github.com/octokit/auth-token.js)\n\n### Unauthenticated\n\n```typescript\n// 👇This will configure octokit without authentication\nconst authOptions = AuthOptions.unauthenticated();\n```\n\n## Manage a GitHub Repository - Example\n\n[![Manage a GitHub Repository as custom CFN resource](https://raw.githubusercontent.com/pepperize/cdk-github/main/cloudformation-stack-github-custom-resource.png)](https://github.com/pepperize/cdk-github/blob/main/src/integ.default.ts)\n\n[@octokit/plugin-rest-endpoint-methods](https://github.com/octokit/plugin-rest-endpoint-methods.js/#usage)\n\n```typescript\nconst auth = secrets_manager.Secret.fromSecretNameV2(stack, \"Auth\", \"cdk-github/github-token\");\n\nconst repo = new GithubCustomResource(stack, \"GithubRepo\", {\n  onCreate: {\n    // https://octokit.github.io/rest.js/v19/#repos-create-in-org\n    endpoint: \"repos\",\n    method: \"createInOrg\",\n    parameters: {\n      org: \"pepperize\",\n      name: \"cdk-github\",\n    },\n    outputPaths: [\"id\", \"full_name\"],\n    physicalResourceId: custom_resources.PhysicalResourceId.fromResponse(\"full_name\"),\n    ignoreErrorCodesMatching: \"name already exists on this account\",\n  },\n  onUpdate: {\n    // https://octokit.github.io/rest.js/v19#repos-get\n    endpoint: \"repos\",\n    method: \"get\",\n    parameters: {\n      owner: \"pepperize\",\n      repo: \"cdk-github\",\n    },\n    outputPaths: [\"id\", \"full_name\"],\n    physicalResourceId: custom_resources.PhysicalResourceId.fromResponse(\"full_name\"),\n  },\n  onDelete: {\n    // https://octokit.github.io/rest.js/v19#repos-delete\n    endpoint: \"repos\",\n    method: \"delete\",\n    parameters: {\n      owner: \"pepperize\",\n      repo: \"cdk-github\",\n    },\n    outputPaths: [],\n  },\n  authOptions: AuthOptions.appAuth(auth),\n});\n\n// 👇 This will return the created repository id as a CDK Token\nrepo.getAtt(\"id\");\n```\n\n## Manage GitHub Actions Secrets\n\n### Environment Secret\n\nManages an environment secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.\n\n```typescript\n// 👇The GitHub API authentication secret\nconst auth = secrets_manager.Secret.fromSecretNameV2(scope, \"Auth\", \"cdk-github/github-token\");\n\n// 👇The AWS SecretsManager Secret to configure as GitHub Action secret.\nconst secret = secrets_manager.Secret.fromSecretNameV2(scope, \"Secret\", \"any-secret/example\");\n\nnew GithubActionsSecretEnvironment(scope, \"GithubRepo\", {\n  // 👇The repository id, which you may lookup from the page source or via a custom resource\n  repositoryId: \"558989134\",\n  environmentName: \"production\",\n  // 👇The name of the created GitHub secret\n  secretName: \"example\",\n  // 👇The source AWS SecretsManager secret and JSON field to use\n  source: GithubActionsSecret.fromSecretsManager(secret, \"some-json-field\"),\n  authOptions: AuthOptions.appAuth(auth),\n  // 👇Whether to delete or retain the GitHub secret on resource removal\n  removalPolicy: RemovalPolicy.DESTROY,\n});\n```\n\n\u003e You may retrieve the `repository_id` from the GitHub Repository page source's meta tag i.e. `\u003cmeta name=\"octolytics-dimension-repository_id\" content=\"558989134\"\u003e` or from another `GithubCustomResource` via `getAtt()`.\n\nSee [GitHub Developer Guide](https://docs.github.com/de/rest/actions/secrets#create-or-update-an-environment-secret), [API Reference](https://github.com/pepperize/cdk-github/blob/main/API.md)\n\n### Organization Secret\n\nManage an GitHib Actions organization secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.\n\n```typescript\n// 👇The GitHub API authentication secret\nconst auth = secrets_manager.Secret.fromSecretNameV2(scope, \"Auth\", \"cdk-github/github-token\");\n\n// 👇The AWS SecretsManager Secret to configure as GitHub Action secret.\nconst secret = secrets_manager.Secret.fromSecretNameV2(scope, \"Secret\", \"any-secret/example\");\n\nnew GithubActionsSecretOrganization(scope, \"GithubRepo\", {\n  organizationName: \"pepperize\",\n  // 👇The name of the created GitHub secret\n  secretName: \"example\",\n  // 👇The source AWS SecretsManager secret and JSON field to use\n  source: GithubActionsSecret.fromSecretsManager(secret, \"some-json-field\"),\n  visibility: Visibility.ALL,\n  authOptions: AuthOptions.appAuth(auth),\n  // 👇Whether to delete or retain the GitHub secret on resource removal\n  removalPolicy: RemovalPolicy.DESTROY,\n});\n```\n\nSee [GitHub Developer Guide](https://docs.github.com/de/rest/actions/secrets#create-or-update-an-organization-secret), [API Reference](https://github.com/pepperize/cdk-github/blob/main/API.md)\n\n### Repository Secret\n\nManage an GitHib Actions Repository secret. Will fetch the source AWS SecretsManager secret and encrypt it to store in GitHub.\n\n```typescript\n// 👇The GitHub API authentication secret\nconst auth = secrets_manager.Secret.fromSecretNameV2(scope, \"Auth\", \"cdk-github/github-token\");\n\n// 👇The AWS SecretsManager Secret to configure as GitHub Action secret.\nconst secret = secrets_manager.Secret.fromSecretNameV2(scope, \"Secret\", \"any-secret/example\");\n\nnew GithubActionsSecretRepository(scope, \"GithubRepo\", {\n  owner: \"pepperize\",\n  repositoryName: \"cdk-github\",\n  // 👇The name of the created GitHub secret\n  secretName: \"example\",\n  // 👇The source AWS SecretsManager secret and JSON field to use\n  source: GithubActionsSecret.fromSecretsManager(secret, \"some-json-field\"),\n  authOptions: AuthOptions.appAuth(auth),\n  // 👇Whether to delete or retain the GitHub secret on resource removal\n  removalPolicy: RemovalPolicy.DESTROY,\n});\n```\n\nSee [GitHub Developer Guide](https://docs.github.com/de/rest/actions/secrets#create-or-update-a-repository-secret), [API Reference](https://github.com/pepperize/cdk-github/blob/main/API.md)\n","funding_links":[],"categories":["aws"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpepperize%2Fcdk-github","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpepperize%2Fcdk-github","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpepperize%2Fcdk-github/lists"}