feat: customizable permissions in GitHubActionStep (#1017)

This PR adds configuration passthrough for the `permissions` object that `GitHubActionStep` uses under the hood. The default remains `contents: write`.

I have also added a snapshot test showing that the change works, and made a small modification to the README. 

Fixes #731

Author: a-bigelow

API.md

@@ -441,6 +441,9 @@ If you want to call a GitHub Action in a step, you can utilize the `GitHubAction
 
 The `jobSteps` array is placed into the pipeline job at the relevant `jobs.<job_id>.steps` as [documented here](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps).
 
+GitHub Actions Job permissions can be modified by passing the `permissions` object to `GitHubActionStep`.
+The default set of permissions is simply `contents: write`.
+
 In this example,
 
 ```ts
@@ -461,6 +464,10 @@ const pipeline = new GitHubWorkflow(app, 'Pipeline', {
 const stage = new MyStage(app, 'Beta', { env: BETA_ENV });
 pipeline.addStage(stage, {
   pre: [new GitHubActionStep('PreBetaDeployAction', {
+    permissions: {
+      idToken: JobPermission.WRITE,
+      contents: JobPermission.WRITE,
+    },
     jobSteps: [
       {
         name: 'Checkout',

README.md

@@ -832,7 +832,7 @@ export class GitHubWorkflow extends PipelineBase {
       definition: {
         name: step.id,
         ...this.renderJobSettingParameters(),
-        permissions: {
+        permissions: step.permissions ?? {
           contents: github.JobPermission.WRITE,
         },
         runsOn: this.runner.runsOn,

src/pipeline.ts

@@ -1,5 +1,5 @@
 import { Step } from 'aws-cdk-lib/pipelines';
-import { JobStep } from '../workflows-model';
+import { JobStep, JobPermissions } from '../workflows-model';
 
 export interface GitHubActionStepProps {
   /**
@@ -11,6 +11,12 @@ export interface GitHubActionStepProps {
    * Environment variables to set.
    */
   readonly env?: Record<string, string>;
+
+  /**
+   * Permissions for the GitHub Action step.
+   * @default The job receives 'contents: write' permissions. If you set additional permissions and require 'contents: write', it must be provided in your configuration.
+   */
+  readonly permissions?: JobPermissions;
 }
 
 /**
@@ -19,10 +25,12 @@ export interface GitHubActionStepProps {
 export class GitHubActionStep extends Step {
   public readonly env: Record<string, string>;
   public readonly jobSteps: JobStep[];
+  public readonly permissions?: JobPermissions;
 
   constructor(id: string, props: GitHubActionStepProps) {
     super(id);
     this.jobSteps = props.jobSteps;
     this.env = props.env ?? {};
+    this.permissions = props.permissions;
   }
 }