feat: Custom GitHubActionRole subject claims

README.md

@@ -213,6 +213,30 @@ new MyGitHubActionRole(app, 'MyGitHubActionRole');
 app.synth();
 ```
 
+Specifying a `repos` array grants GitHub full access to the specified repositories.
+To restrict access to specific git branch, tag, or other
+[GitHub OIDC subject claim](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims),
+specify a `subjectClaims` array instead of a `repos` array.
+
+```ts
+class MyGitHubActionRole extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const provider = new GitHubActionRole(this, 'github-action-role', {
+      subjectClaims: [
+        'repo:owner/repo1:ref:refs/heads/main',
+        'repo:owner/repo1:environment:prod',
+      ],
+    });
+  }
+}
+
+const app = new App();
+new MyGitHubActionRole(app, 'MyGitHubActionRole');
+app.synth();
+```
+
 Note: If you have previously created the GitHub identity provider with url
 `https://token.actions.githubusercontent.com`, the above example will fail
 because you can only have one such provider defined per account. In this

src/oidc-provider.ts

@@ -20,10 +20,21 @@ export interface GitHubActionRoleProps {
    * A list of GitHub repositories you want to be able to access the IAM role.
    * Each entry should be your GitHub username and repository passed in as a
    * single string.
+   * An entry `owner/repo` is equivalent to the subjectClaim `repo:owner/repo:*`.
    *
    * For example, `['owner/repo1', 'owner/repo2'].
    */
-  readonly repos: string[];
+  readonly repos?: string[];
+
+  /**
+   * A list of subject claims allowed to access the IAM role.
+   * See https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
+   * A subject claim can include `*` and `?` wildcards according to the `StringLike`
+   * condition operator.
+   *
+   * For example, `['repo:owner/repo1:ref:refs/heads/branch1', 'repo:owner/repo1:environment:prod']`
+   */
+  readonly subjectClaims?: string[];
 
   /**
    * The name of the Oidc role.
@@ -110,7 +121,7 @@ export class GitHubActionRole extends Construct {
       provider.openIdConnectProviderArn,
       {
         StringLike: {
-          [`${rawEndpoint}:sub`]: formatRepos(props.repos),
+          [`${rawEndpoint}:sub`]: formatRepos(props.repos ?? []).concat(props.subjectClaims ?? []),
         },
       },
       'sts:AssumeRoleWithWebIdentity',

test/oidc-provider.test.ts

@@ -39,7 +39,7 @@ describe('GithubActionRole construct', () => {
     });
   });
 
-  test('basic configuration with multiple repos', () => {
+  test('basic configuration with multiple repos and subject claims', () => {
     // GIVEN
     const stack = new Stack();
 
@@ -50,6 +50,10 @@ describe('GithubActionRole construct', () => {
         'myuser/myrepo2',
         'myuser/myrepo3',
       ],
+      subjectClaims: [
+        'repo:owner/repo1:ref:refs/heads/branch1',
+        'repo:owner/repo1:environment:prod',
+      ],
     });
 
     // THEN
@@ -69,6 +73,8 @@ describe('GithubActionRole construct', () => {
                   'repo:myuser/myrepo:*',
                   'repo:myuser/myrepo2:*',
                   'repo:myuser/myrepo3:*',
+                  'repo:owner/repo1:ref:refs/heads/branch1',
+                  'repo:owner/repo1:environment:prod',
                 ],
               },
             },