aws-ia / cloudformation-github-resource-providers

GitHub CFN Registry resource

GitHub CloudFormation Resources

This collection of AWS CloudFormation resource types allow GitHub to be controlled using AWS CloudFormation.

Resource	Description	Documentation
GitHub::Git::Tag	This resource type manages a GitHub Git Tag	/GitHub-Git-Tag
GitHub::Organizations::Membership	This resource type manages a GitHub Organization Membership	/GitHub-Origanizations-Membership
GitHub::Repositories::Collaborator	This resource type manages a GitHub Repository Collaborator	/GitHub-Repositories-Collaborator
GitHub::Repositories::Repository	This resource type manages a GitHub Repository	/GitHub-Repositories-Repository
GitHub::Repositories::Webhook	This resource type manages a GitHub Repository Webhoo	/GitHub-Repositories-Webhook
GitHub::Teams::Membership	This resource type manages a GitHub Team Membership	/GitHub-Teams-Membership
GitHub::Teams::RepositoryAccess	This resource type manages a GitHub Team Repository Access	/GitHub-Teams-Repository-Access
GitHub::Teams::Team	This resource type manages a GitHub Team	/GitHub-Teams-Team
Github::Repositories::Secret	This resource type manages a Github Repositories Secret	/Github-Repositories-Secret
Github::Organizations::Secret	This resource type manages a Github Organizations Secret	/Github-Organizations-Secret

Prerequisites

• AWS Account
• AWS CLI
• GitHub Account and Access Token

AWS Management Console

To get started:

1. Sign in to the AWS Management Console with your account and navigate to CloudFormation.

2. Select "Public extensions" from the left hand pane and filter Publisher by "Third Party".

3. Use the search bar to filter by the "GitHub" prefix.

Note: All official GitHub resources begin with GitHub:: and specify that they are Published by GitHub.

4. Select the desired resource name to view more information about its schema, and click Activate.

5. On the Extension details page, specify:

• Extension name
• Execution role ARN
• Automatic updates for minor version releases
• Configuration

6. In your terminal, specify the configuration data for the registered GitHub CloudFormation resource type, in the given account and region by using the SetTypeConfiguration operation:

For example:

$ aws cloudformation set-type-configuration \
--region us-west-2 --type RESOURCE \
--type-name GitHub::Git::Tag \
--configuration-alias default \
--configuration '{"GitHubAccess": {"AccessToken": "{{resolve:ssm-secure:/cfn/github/accesstoken:1}}"}}'

7. After you have your resource configured, create your AWS stack that includes any of the activated GitHub resources.

For more information about available commands and workflows, see the official AWS documentation.

Supported regions

The GitHub CloudFormation resources are available on the CloudFormation Public Registry in the following regions:

Code	Name
us-east-1	US East (N. Virginia)
us-east-2	US East (Ohio)
us-west-1	US West (N. California)
us-west-2	US West (Oregon)
ap-south-1	Asia Pacific (Mumbai)
ap-northeast-1	Asia Pacific (Tokyo)
ap-northeast-2	Asia Pacific (Seoul)
ap-southeast-1	Asia Pacific (Singapore)
ap-southeast-2	Asia Pacific (Sydney)
ca-central-1	Canada (Central)
eu-central-1	Europe (Frankfurt)
eu-west-1	Europe (Ireland)
eu-west-2	Europe (London)
eu-west-3	Europe (Paris)
eu-north-1	Europe (Stockholm)
sa-east-1	South America (São Paulo)

Note: To privately register a resource in any other region, use the provided packages.

Examples

Setting up a new project in github with a repository, team, and external member with CloudFormation

---
AWSTemplateFormatVersion: '2010-09-09'
Description: Shows how to set up a new github based project

Parameters:
  RepoName:
    Type: String
    Description: |
      The name of the repo that is being created and configured
    Default: MyRepo

Resources:
  Membership:
    Type: GitHub::Organizations::Membership
    Properties:
      Organization: ACME-CloudFormation
      Username: ACME-cloudformation-test-user
      Role: member
  MyRepo:
    Type: GitHub::Repositories::Repository
    Properties:
      Org: ACME-CloudFormation
      Name: !Ref RepoName
      Description: Repo created by cloudformation example
      Homepage: https://GitHub.com
      Private: true
      Visibility: private
      HasIssues: true
      HasProjects: false
      HasWiki: true
      IsTemplate: false
      AutoInit: true
      GitIgnoreTemplate: Node
      LicenseTemplate: mit
      AllowSquashMerge: true
      AllowMergeCommit: true
      AllowRebaseMerge: true
      AllowAutoMerge: true
      DeleteBranchOnMerge: false
      Archived: false
  MyWebHook:
    Type: GitHub::Repositories::Webhook
    DependsOn: MyRepo
    Properties:
      Url: http://some.url.com
      Owner: ACME-CloudFormation
      Name: web
      Active: false
      Events:
        - push
      Repository: !Ref RepoName
  ExternalCollaborator:
    Type: GitHub::Repositories::Collaborator
    DependsOn: MyRepo
    Properties:
      Owner: ACME-CloudFormation
      Repository: !Ref RepoName
      Username: externaluser
      Permission: pull
  DemoTeam:
    Type: GitHub::Teams::Team
    Properties:
      Name: My Demo Team
      Organization: ACME-CloudFormation
      Description: My new Team
      Privacy: secret
  DemoTeamMemberMe:
    Type: GitHub::Teams::Membership
    Properties:
      Org: ACME-CloudFormation
      TeamSlug: !GetAtt DemoTeam.Slug
      Username: organisation-member
      Role: member
  DemoTeamAccessRepo:
    Type: GitHub::Teams::RepositoryAccess
    DependsOn: MyRepo
    Properties:
      Org: ACME-CloudFormation
      Team: !GetAtt DemoTeam.Slug
      Owner: ACME-CloudFormation
      Repository: !Ref RepoName
      Permission: pull

Set up a repository secret

---
AWSTemplateFormatVersion: '2010-09-09'
Description: Sets up a repository secret
Resources:
  MySecret:
    Type: GitHub::Repositories::Secret
    Properties:
      Repository: example-repo
      Owner: ACME-CloudFormation
      SecretName: secret example
      SecretValue: example_secret123

Set up a organization secret

---
AWSTemplateFormatVersion: '2010-09-09'
Description: Sets up a Organization secret
Resources:
  MySecret:
    Type: GitHub::Organization::Secret
    Properties:
      Org: example-org
      SecretName: secret example
      SecretValue: example_secret123
      Visibility: selected
      SelectedRepositoryIds: 
        - 595653363

cloudformation-github-resource-providers's Issues

Move GitHubAccess to typeConfiguration

It would be nice if the GitHubAccess would not have to be part of the deployed template, but instead could be configured per-account.

See https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-model.html#resource-type-howto-configuration

I'm not sure how this would work with backward compatibility, but both as an example and for new users, this would be a better experience.

GitHub::Repositories::Collaborator create fails

Fails in both contract testing and stack creation. It creates the invitation successfully in the organization, but then immediately fails with AlreadyExists.

Resource handler returned message: "Error: Resource of type 'GitHub::Repositories::Collaborator' 
with identifier 'Collab' already exists." 
(RequestToken: 1ab35620-a3ea-bcec-6c21-478165ff5286, HandlerErrorCode: AlreadyExists)

GitHub::Repositories::Repository update handler should check for "Visibility" property changes before attempting to update

If your CFN template tries to update the "Visibility" property for GitHub::Repositories::Repository with the current value, the update will fail. For example, if your repo visibility is already private and your template specifies Visibility: Private, the update operation will fail.

Proposed fix: the handler code should contain a check to see if the Visibility property value needs to be changed before trying to execute the update.

Allow import of existing repository

Hello,

We would like to use the GitHub::Repositories::Repository resource on a repository that already exists so that we can make future changes from CloudFormation.

However, by doing so, we logically receive a 422 HTTP code (already exists).

Can we consider adding an option to authorize the import?

Either :

• via an additional property on the GitHub::Repositories::Repository resource
• in the configuration of the resource, add in the JSON, in addition to the access token, an option "allow import"?

The second option seems preferable in order to avoid changing the properties of GitHub::Repositories::Repository unnecessarily.

What do you think about it?

We'll be happy to help implement the feature if you think it's a good idea !

Changing the name of a repository creates a new repository and delete the old one

When changing the name of a repository, a new repository is created and the old one is deleted.

The expectation would be that only the name changes, while keeping its content.

Note that the "id" of the ressource remain the same.

Code:

new CfnRepository(this, `GithubRepositoryTestFromCdk`, {
    name: 'test-from-cdk-rename, // Changing this value
    organization: orgName,
  });

The CDK diff output also suggest that only the name of the repository would change and there's no indication of replacement.

[~] GitHub::Repositories::Repository GithubRepositorytest-with-cdk GithubRepositorytestwithcdk 
 └─ [~] Name
     ├─ [-] test-from-cdk
     └─ [+] test-from-cdk-rename

Feature request: ability to add secrets to organizations and repositories

It would be useful to be able to add secrets to orgs and repos:

• https://docs.github.com/en/rest/actions/secrets?apiVersion=2022-11-28#create-or-update-a-repository-secret
• https://docs.github.com/en/rest/actions/secrets?apiVersion=2022-11-28#create-or-update-an-organization-secret

Thanks!

Add rulesets resource

https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets

https://docs.github.com/en/rest/repos/rules?apiVersion=2022-11-28

GitHub::Repositories::Secret and GitHub::Organizations::Secret are not published in CloudFormation

Hello, while trying to activate the extensions, we noticed that two of them are not published yet.

The following extensions are not published in Cloudformation:

• GitHub::Repositories::Secret
• GitHub::Organizations::Secret

Also the GitHub::Organizations::Secret README title is incorrect because at the moment it's the README title of GitHub::Repositories::Webhook.