CDK-GitHub

GitHub Constructs for use in AWS CDK .

This project aims to make GitHub's API accessible through CDK with various helper constructs to create resources in GitHub. The target is to replicate most of the functionality of the official Terraform GitHub Provider.

Internally AWS CloudFormation custom resources and octokit are used to manage GitHub resources (such as Secrets).

🔧 Installation

JavaScript/TypeScript: npm install cdk-github

Python: pip install cdk-github

Java

Maven:

<dependency>
  <groupId>io.github.wtfjoke</groupId>
  <artifactId>cdk-github</artifactId>
  <version>VERSION</version>
</dependency>

Gradle:

implementation 'io.github.wtfjoke:cdk-github:VERSION'

Gradle (Kotlin):

implementation("io.github.wtfjoke:cdk-github:VERSION")

C# See https://www.nuget.org/packages/CdkGithub

📚 Constructs

This library provides the following constructs:

ActionEnvironmentSecret - Creates a GitHub Action environment secret from a given AWS Secrets Manager secret.
ActionSecret - Creates a GitHub Action (repository) secret from a given AWS Secrets Manager secret.
GitHubResource - Creates an arbitrary GitHub resource. When no suitable construct fits your needs, this construct can be used to create most GitHub resources. It is an L1 construct.

🔓 Authentication

Currently the constructs only support authentication via a GitHub Personal Access Token. The token needs to be a stored in a AWS SecretsManager Secret and passed to the construct as parameter.

👩‍🏫 Examples

The API documentation and examples in different languages are available on Construct Hub. All (typescript) examples can be found in the folder examples.

ActionSecret

import { Secret } from 'aws-cdk-lib/aws-secretsmanager';
import { ActionSecret } from 'cdk-github';

export class ActionSecretStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const githubTokenSecret = Secret.fromSecretNameV2(this, 'ghSecret', 'GITHUB_TOKEN');
    const sourceSecret = Secret.fromSecretNameV2(this, 'secretToStoreInGitHub', 'testcdkgithub');

    new ActionSecret(this, 'GitHubActionSecret', {
      githubTokenSecret,
      repository: { name: 'cdk-github', owner: 'wtfjoke' },
      repositorySecretName: 'A_RANDOM_GITHUB_SECRET',
      sourceSecret,
    });
  }
}

ActionEnvironmentSecret

import { Secret } from 'aws-cdk-lib/aws-secretsmanager';
import { ActionEnvironmentSecret } from 'cdk-github';

export class ActionEnvironmentSecretStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const githubTokenSecret = Secret.fromSecretNameV2(this, 'ghSecret', 'GITHUB_TOKEN');
    const sourceSecret = Secret.fromSecretNameV2(this, 'secretToStoreInGitHub', 'testcdkgithub');

    new ActionEnvironmentSecret(this, 'GitHubActionEnvironmentSecret', {
      githubTokenSecret,
      environment: 'dev',
      repository: { name: 'cdk-github', owner: 'wtfjoke' },
      repositorySecretName: 'A_RANDOM_GITHUB_SECRET',
      sourceSecret,
    });
  }
}

GitHubResource

import { Secret } from 'aws-cdk-lib/aws-secretsmanager';
import { StringParameter } from 'aws-cdk-lib/aws-ssm';
import { GitHubResource } from 'cdk-github';


export class GitHubResourceIssueStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const githubTokenSecret = Secret.fromSecretNameV2(this, 'ghSecret', 'GITHUB_TOKEN');
    // optional
    const writeResponseToSSMParameter = StringParameter.fromSecureStringParameterAttributes(this, 'responseBody', { parameterName: '/cdk-github/encrypted-response' });

    new GitHubResource(this, 'GitHubIssue', {
      githubTokenSecret,
      createRequestEndpoint: 'POST /repos/WtfJoke/dummytest/issues',
      createRequestPayload: JSON.stringify({ title: 'Testing cdk-github', body: "I'm opening an issue by using aws cdk 🎉", labels: ['bug'] }),
      createRequestResultParameter: 'number',
      deleteRequestEndpoint: 'PATCH /repos/WtfJoke/dummytest/issues/:number',
      deleteRequestPayload: JSON.stringify({ state: 'closed' }),
      writeResponseToSSMParameter,
    });
  }
}

💖 Contributing

Contributions of all kinds are welcome! Check out our contributing guide.

API Reference

Constructs

ActionEnvironmentSecret

Initializers

import { ActionEnvironmentSecret } from 'cdk-github'

new ActionEnvironmentSecret(scope: Construct, id: string, props: ActionEnvironmentSecretProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`ActionEnvironmentSecretProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: ActionEnvironmentSecretProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { ActionEnvironmentSecret } from 'cdk-github'

ActionEnvironmentSecret.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

ActionSecret

Initializers

import { ActionSecret } from 'cdk-github'

new ActionSecret(scope: Construct, id: string, props: ActionSecretProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`ActionSecretProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: ActionSecretProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { ActionSecret } from 'cdk-github'

ActionSecret.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

GitHubResource

Initializers

import { GitHubResource } from 'cdk-github'

new GitHubResource(scope: Construct, id: string, props: GitHubResourceProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`GitHubResourceProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: GitHubResourceProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { GitHubResource } from 'cdk-github'

GitHubResource.isConstruct(x: any)

Checks if x is a construct.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

Structs

ActionEnvironmentSecretProps

Initializer

import { ActionEnvironmentSecretProps } from 'cdk-github'

const actionEnvironmentSecretProps: ActionEnvironmentSecretProps = { ... }

Properties

Name	Type	Description
`environment`	`string`	The GithHub environment name which the secret should be stored in.
`githubTokenSecret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	The AWS secret in which the OAuth GitHub (personal) access token is stored.
`repository`	`IGitHubRepository`	The GitHub repository information (owner and name).
`repositorySecretName`	`string`	The GitHub secret name to be stored.
`sourceSecret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	This AWS secret value will be stored in GitHub as a secret (under the name of repositorySecretName).
`sourceSecretJsonField`	`string`	The key of a JSON field to retrieve in sourceSecret.

`environment`^Required

public readonly environment: string;

Type: string

The GithHub environment name which the secret should be stored in.

`githubTokenSecret`^Required

public readonly githubTokenSecret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

The AWS secret in which the OAuth GitHub (personal) access token is stored.

`repository`^Required

public readonly repository: IGitHubRepository;

Type: IGitHubRepository

The GitHub repository information (owner and name).

`repositorySecretName`^Required

public readonly repositorySecretName: string;

Type: string

The GitHub secret name to be stored.

`sourceSecret`^Required

public readonly sourceSecret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

This AWS secret value will be stored in GitHub as a secret (under the name of repositorySecretName).

`sourceSecretJsonField`^Optional

public readonly sourceSecretJsonField: string;

Type: string
Default: returns all the content stored in the Secrets Manager secret.

The key of a JSON field to retrieve in sourceSecret.

This can only be used if the secret stores a JSON object.

ActionSecretProps

Initializer

import { ActionSecretProps } from 'cdk-github'

const actionSecretProps: ActionSecretProps = { ... }

Properties

Name	Type	Description
`githubTokenSecret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	The AWS secret in which the OAuth GitHub (personal) access token is stored.
`repository`	`IGitHubRepository`	The GitHub repository information (owner and name).
`repositorySecretName`	`string`	The GitHub secret name to be stored.
`sourceSecret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	This AWS secret value will be stored in GitHub as a secret (under the name of repositorySecretName).
`sourceSecretJsonField`	`string`	The key of a JSON field to retrieve in sourceSecret.

`githubTokenSecret`^Required

public readonly githubTokenSecret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

The AWS secret in which the OAuth GitHub (personal) access token is stored.

`repository`^Required

public readonly repository: IGitHubRepository;

Type: IGitHubRepository

The GitHub repository information (owner and name).

`repositorySecretName`^Required

public readonly repositorySecretName: string;

Type: string

The GitHub secret name to be stored.

`sourceSecret`^Required

public readonly sourceSecret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

This AWS secret value will be stored in GitHub as a secret (under the name of repositorySecretName).

`sourceSecretJsonField`^Optional

public readonly sourceSecretJsonField: string;

Type: string
Default: returns all the content stored in the Secrets Manager secret.

The key of a JSON field to retrieve in sourceSecret.

This can only be used if the secret stores a JSON object.

GitHubResourceProps

Initializer

import { GitHubResourceProps } from 'cdk-github'

const gitHubResourceProps: GitHubResourceProps = { ... }

Properties

Name	Type	Description
`createRequestEndpoint`	`string`	The GitHub api endpoint url for creating resources in format: `POST /repos/OWNER/REPO/issues`.
`deleteRequestEndpoint`	`string`	The GitHub api endpoint url to delete this resource in format: `POST /repos/OWNER/REPO/issues`.
`githubTokenSecret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	The AWS secret in which the OAuth GitHub (personal) access token is stored.
`createRequestPayload`	`string`	The GitHub api request payload for creating resources. This is a JSON parseable string.
`createRequestResultParameter`	`string`	Used to extract a value from the result of the createRequest(Endpoint) to be used in update/deleteRequests.
`deleteRequestPayload`	`string`	The GitHub api request payload to delete this resource. This is a JSON parseable string.
`updateRequestEndpoint`	`string`	The GitHub api endpoint url to update this resource in format: `POST /repos/OWNER/REPO/issues`.
`updateRequestPayload`	`string`	The GitHub api request payload to update this resources. This is a JSON parseable string.
`writeResponseToSSMParameter`	`aws-cdk-lib.aws_ssm.IParameter`	The response body of the last GitHub api request will be written to this ssm parameter.

`createRequestEndpoint`^Required

public readonly createRequestEndpoint: string;

Type: string

The GitHub api endpoint url for creating resources in format: POST /repos/OWNER/REPO/issues.

This is called when the GitHubResource is created.

Example:

const createRequestEndpoint = 'POST /repos/octocat/Hello-World/issues'

`deleteRequestEndpoint`^Required

public readonly deleteRequestEndpoint: string;

Type: string

The GitHub api endpoint url to delete this resource in format: POST /repos/OWNER/REPO/issues.

This is called when the GitHubResource is deleted/destroyed.

Example:

const deleteRequestEndpoint = 'PATCH repos/octocat/Hello-World/issues/1'

If you want to use the @see {@link GitHubResourceProps#createRequestResultParameter}, you can use the following syntax (assuming you have set createRequestResultParameter to "number"):

const deleteRequestEndpoint = 'PATCH repos/octocat/Hello-World/:number'

`githubTokenSecret`^Required

public readonly githubTokenSecret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

The AWS secret in which the OAuth GitHub (personal) access token is stored.

`createRequestPayload`^Optional

public readonly createRequestPayload: string;

Type: string

The GitHub api request payload for creating resources. This is a JSON parseable string.

Used for @see {@link GitHubResourceProps#createRequestEndpoint}.

Example:

const createRequestPayload = JSON.stringify({ title: 'Found a bug', body: "I'm having a problem with this.", assignees: ['octocat'], milestone: 1, labels: ['bug'] })

`createRequestResultParameter`^Optional

public readonly createRequestResultParameter: string;

Type: string

Used to extract a value from the result of the createRequest(Endpoint) to be used in update/deleteRequests.

Example: "number" (for the issue number)

When this parameter is set and can be extracted from the result, the extracted value will be used for the PhyscialResourceId of the CustomResource. Changing the parameter once the stack is deployed is not supported.

`deleteRequestPayload`^Optional

public readonly deleteRequestPayload: string;

Type: string

The GitHub api request payload to delete this resource. This is a JSON parseable string.

Used for @see {@link GitHubResourceProps#deleteRequestEndpoint}.

Example:

const deleteRequestPayload = JSON.stringify({ state: 'closed' })

`updateRequestEndpoint`^Optional

public readonly updateRequestEndpoint: string;

Type: string

The GitHub api endpoint url to update this resource in format: POST /repos/OWNER/REPO/issues.

This is called when the GitHubResource is updated.

In most of the cases you want to either omit this or use the same value as createRequestEndpoint.

Example:

const updateRequestEndpoint = 'PATCH repos/octocat/Hello-World/issues/1'

If you want to use the @see {@link GitHubResourceProps#createRequestResultParameter}, you can use the following syntax (assuming you have set createRequestResultParameter to "number"):

const updateRequestEndpoint = 'PATCH repos/octocat/Hello-World/:number'

`updateRequestPayload`^Optional

public readonly updateRequestPayload: string;

Type: string

The GitHub api request payload to update this resources. This is a JSON parseable string.

Used for @see {@link GitHubResourceProps#createRequestEndpoint}.

Example:

const updateRequestPayload = JSON.stringify({ title: 'Found a bug', body: "I'm having a problem with this.", assignees: ['octocat'], milestone: 1, state: 'open', labels: ['bug'] })

`writeResponseToSSMParameter`^Optional

public readonly writeResponseToSSMParameter: IParameter;

Type: aws-cdk-lib.aws_ssm.IParameter

The response body of the last GitHub api request will be written to this ssm parameter.

Protocols

IGitHubRepository

Implemented By: IGitHubRepository

Properties

Name	Type	Description
`name`	`string`	The GitHub repository name.
`owner`	`string`	The GitHub repository owner.

`name`^Required

public readonly name: string;

Type: string

The GitHub repository name.

`owner`^Optional

public readonly owner: string;

Type: string
Default: user account which owns the personal access token

The GitHub repository owner.

Files

API.md

Latest commit

History

API.md

File metadata and controls

CDK-GitHub

🔧 Installation

📚 Constructs

🔓 Authentication

👩‍🏫 Examples

ActionSecret

ActionEnvironmentSecret

GitHubResource

💖 Contributing

API Reference

Constructs

ActionEnvironmentSecret

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

Static Functions

isConstruct

xRequired

Properties

nodeRequired

ActionSecret

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

Static Functions

isConstruct

xRequired

Properties

nodeRequired

GitHubResource

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

Static Functions

isConstruct

xRequired

Properties

nodeRequired

Structs

ActionEnvironmentSecretProps

Initializer

Properties

environmentRequired

githubTokenSecretRequired

repositoryRequired

repositorySecretNameRequired

sourceSecretRequired

sourceSecretJsonFieldOptional

ActionSecretProps

Initializer

Properties

githubTokenSecretRequired

repositoryRequired

repositorySecretNameRequired

sourceSecretRequired

sourceSecretJsonFieldOptional

GitHubResourceProps

Initializer

Properties

createRequestEndpointRequired

deleteRequestEndpointRequired

githubTokenSecretRequired

createRequestPayloadOptional

createRequestResultParameterOptional

deleteRequestPayloadOptional

`scope`^Required

`id`^Required

`props`^Required

`toString`

`isConstruct`

`x`^Required

`node`^Required

`scope`^Required

`id`^Required

`props`^Required

`toString`

`isConstruct`

`x`^Required

`node`^Required

`scope`^Required

`id`^Required

`props`^Required

`toString`

`isConstruct`

`x`^Required

`node`^Required

`environment`^Required

`githubTokenSecret`^Required

`repository`^Required

`repositorySecretName`^Required

`sourceSecret`^Required

`sourceSecretJsonField`^Optional

`githubTokenSecret`^Required

`repository`^Required

`repositorySecretName`^Required

`sourceSecret`^Required

`sourceSecretJsonField`^Optional

`createRequestEndpoint`^Required

`deleteRequestEndpoint`^Required

`githubTokenSecret`^Required

`createRequestPayload`^Optional

`createRequestResultParameter`^Optional

`deleteRequestPayload`^Optional

`updateRequestEndpoint`^Optional

`updateRequestPayload`^Optional

`writeResponseToSSMParameter`^Optional

`name`^Required

`owner`^Optional