cdkgithub

README

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.

Documentation

Overview

AWS CDK Construct Library to interact with GitHub's API.

Index

• func ActionEnvironmentSecret_IsConstruct(x interface{}) *bool
• func ActionSecret_IsConstruct(x interface{}) *bool
• func GitHubResource_IsConstruct(x interface{}) *bool
• func NewActionEnvironmentSecret_Override(a ActionEnvironmentSecret, scope constructs.Construct, id *string, ...)
• func NewActionSecret_Override(a ActionSecret, scope constructs.Construct, id *string, ...)
• func NewGitHubResource_Override(g GitHubResource, scope constructs.Construct, id *string, ...)
• type ActionEnvironmentSecret
  • func NewActionEnvironmentSecret(scope constructs.Construct, id *string, props *ActionEnvironmentSecretProps) ActionEnvironmentSecret
• type ActionEnvironmentSecretProps
• type ActionSecret
  • func NewActionSecret(scope constructs.Construct, id *string, props *ActionSecretProps) ActionSecret
• type ActionSecretProps
• type GitHubResource
  • func NewGitHubResource(scope constructs.Construct, id *string, props *GitHubResourceProps) GitHubResource
• type GitHubResourceProps
• type IGitHubRepository

Functions

func ActionEnvironmentSecret_IsConstruct

func ActionEnvironmentSecret_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func ActionSecret_IsConstruct

func ActionSecret_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func GitHubResource_IsConstruct

func GitHubResource_IsConstruct(x interface{}) *bool

Checks if `x` is a construct.

Returns: true if `x` is an object created from a class which extends `Construct`. Deprecated: use `x instanceof Construct` instead.

func NewActionEnvironmentSecret_Override

func NewActionEnvironmentSecret_Override(a ActionEnvironmentSecret, scope constructs.Construct, id *string, props *ActionEnvironmentSecretProps)

Experimental.

func NewActionSecret_Override

func NewActionSecret_Override(a ActionSecret, scope constructs.Construct, id *string, props *ActionSecretProps)

Experimental.

func NewGitHubResource_Override

func NewGitHubResource_Override(g GitHubResource, scope constructs.Construct, id *string, props *GitHubResourceProps)

Experimental.

Types

type ActionEnvironmentSecret

type ActionEnvironmentSecret interface {
	constructs.Construct
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

Experimental.

func NewActionEnvironmentSecret

func NewActionEnvironmentSecret(scope constructs.Construct, id *string, props *ActionEnvironmentSecretProps) ActionEnvironmentSecret

Experimental.

type ActionEnvironmentSecretProps

type ActionEnvironmentSecretProps struct {
	// The GithHub environment name which the secret should be stored in.
	// Experimental.
	Environment *string `field:"required" json:"environment" yaml:"environment"`
	// The AWS secret in which the OAuth GitHub (personal) access token is stored.
	// Experimental.
	GithubTokenSecret awssecretsmanager.ISecret `field:"required" json:"githubTokenSecret" yaml:"githubTokenSecret"`
	// The GitHub repository information (owner and name).
	// Experimental.
	Repository IGitHubRepository `field:"required" json:"repository" yaml:"repository"`
	// The GitHub secret name to be stored.
	// Experimental.
	RepositorySecretName *string `field:"required" json:"repositorySecretName" yaml:"repositorySecretName"`
	// This AWS secret value will be stored in GitHub as a secret (under the name of repositorySecretName).
	// Experimental.
	SourceSecret awssecretsmanager.ISecret `field:"required" json:"sourceSecret" yaml:"sourceSecret"`
	// The key of a JSON field to retrieve in sourceSecret.
	//
	// This can only be used if the secret stores a JSON object.
	// Default: - returns all the content stored in the Secrets Manager secret.
	//
	// Experimental.
	SourceSecretJsonField *string `field:"optional" json:"sourceSecretJsonField" yaml:"sourceSecretJsonField"`
}

Experimental.

type ActionSecret

type ActionSecret interface {
	constructs.Construct
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

Experimental.

func NewActionSecret

func NewActionSecret(scope constructs.Construct, id *string, props *ActionSecretProps) ActionSecret

Experimental.

type ActionSecretProps

type ActionSecretProps struct {
	// The AWS secret in which the OAuth GitHub (personal) access token is stored.
	// Experimental.
	GithubTokenSecret awssecretsmanager.ISecret `field:"required" json:"githubTokenSecret" yaml:"githubTokenSecret"`
	// The GitHub repository information (owner and name).
	// Experimental.
	Repository IGitHubRepository `field:"required" json:"repository" yaml:"repository"`
	// The GitHub secret name to be stored.
	// Experimental.
	RepositorySecretName *string `field:"required" json:"repositorySecretName" yaml:"repositorySecretName"`
	// This AWS secret value will be stored in GitHub as a secret (under the name of repositorySecretName).
	// Experimental.
	SourceSecret awssecretsmanager.ISecret `field:"required" json:"sourceSecret" yaml:"sourceSecret"`
	// The key of a JSON field to retrieve in sourceSecret.
	//
	// This can only be used if the secret stores a JSON object.
	// Default: - returns all the content stored in the Secrets Manager secret.
	//
	// Experimental.
	SourceSecretJsonField *string `field:"optional" json:"sourceSecretJsonField" yaml:"sourceSecretJsonField"`
}

Experimental.

type GitHubResource

type GitHubResource interface {
	constructs.Construct
	// The tree node.
	// Experimental.
	Node() constructs.Node
	// Returns a string representation of this construct.
	// Experimental.
	ToString() *string
}

Experimental.

func NewGitHubResource

func NewGitHubResource(scope constructs.Construct, id *string, props *GitHubResourceProps) GitHubResource

Experimental.

type GitHubResourceProps

type GitHubResourceProps struct {
	// 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'
	// “`.
	// Experimental.
	CreateRequestEndpoint *string `field:"required" json:"createRequestEndpoint" yaml:"createRequestEndpoint"`
	// 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'
	// “`.
	// Experimental.
	DeleteRequestEndpoint *string `field:"required" json:"deleteRequestEndpoint" yaml:"deleteRequestEndpoint"`
	// The AWS secret in which the OAuth GitHub (personal) access token is stored.
	// Experimental.
	GithubTokenSecret awssecretsmanager.ISecret `field:"required" json:"githubTokenSecret" yaml:"githubTokenSecret"`
	// 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'] })
	// “`.
	// Experimental.
	CreateRequestPayload *string `field:"optional" json:"createRequestPayload" yaml:"createRequestPayload"`
	// 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.
	// Experimental.
	CreateRequestResultParameter *string `field:"optional" json:"createRequestResultParameter" yaml:"createRequestResultParameter"`
	// 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' })
	// “`.
	// Experimental.
	DeleteRequestPayload *string `field:"optional" json:"deleteRequestPayload" yaml:"deleteRequestPayload"`
	// 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'
	// “`.
	// Experimental.
	UpdateRequestEndpoint *string `field:"optional" json:"updateRequestEndpoint" yaml:"updateRequestEndpoint"`
	// 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'] })
	// “`.
	// Experimental.
	UpdateRequestPayload *string `field:"optional" json:"updateRequestPayload" yaml:"updateRequestPayload"`
	// The response body of the last GitHub api request will be written to this ssm parameter.
	// Experimental.
	WriteResponseToSSMParameter awsssm.IParameter `field:"optional" json:"writeResponseToSSMParameter" yaml:"writeResponseToSSMParameter"`
}

Experimental.

type IGitHubRepository

type IGitHubRepository interface {
	// The GitHub repository name.
	// Experimental.
	Name() *string
	// Experimental.
	SetName(n *string)
	// The GitHub repository owner.
	// Default: - user account which owns the personal access token.
	//
	// Experimental.
	Owner() *string
	// Experimental.
	SetOwner(o *string)
}

Experimental.