chore: publish toolkit-lib docs to s3

Author: mrgrain

.github/workflows/release.yml

@@ -6,6 +6,7 @@ import { BundleCli } from './projenrc/bundle';
 import { CodeCovWorkflow } from './projenrc/codecov';
 import { ESLINT_RULES } from './projenrc/eslint';
 import { JsiiBuild } from './projenrc/jsii';
+import { S3DocsPublishing } from './projenrc/s3-docs-publishing';
 
 // 5.7 sometimes gives a weird error in `ts-jest` in `@aws-cdk/cli-lib-alpha`
 // https://github.com/microsoft/TypeScript/issues/60159
@@ -1112,6 +1113,13 @@ const toolkitLib = configureProject(
   }),
 );
 
+new S3DocsPublishing(toolkitLib, {
+  docsStream: 'toolkit-lib',
+  artifactPath: 'docs.zip',
+  bucketName: '${{ vars.DOCS_BUCKET_NAME }}',
+  roleToAssume: '${{ vars.PUBLISH_TOOLKIT_LIB_DOCS_ROLE_ARN }}',
+});
+
 // Eslint rules
 toolkitLib.eslint?.addRules({
   '@cdklabs/no-throw-default-error': ['error'],
@@ -1180,9 +1188,19 @@ for (const tsconfig of [toolkitLib.tsconfigDev]) {
   }
 }
 
-toolkitLib.addTask('docs', {
+const toolkitLibDocs = toolkitLib.addTask('docs', {
   exec: 'typedoc lib/index.ts',
+  receiveArgs: true,
+});
+toolkitLib.packageTask.spawn(toolkitLibDocs, {
+  // the nested directory is important
+  // the zip file needs to have this structure when created
+  args: ['--out dist/docs/cdk/api/toolkit-lib'],
 });
+toolkitLib.packageTask.exec('zip -r ../docs.zip cdk ', {
+  cwd: 'dist/docs',
+});
+
 toolkitLib.addTask('publish-local', {
   exec: './build-tools/package.sh',
 });

.projenrc.ts

@@ -0,0 +1,118 @@
+import { Monorepo, TypeScriptWorkspace } from 'cdklabs-projen-project-types/lib/yarn';
+import { Component, github } from 'projen';
+
+export interface S3DocsPublishingProps {
+  /**
+   * The docs stream to publish to,
+   */
+  readonly docsStream: string;
+
+  /**
+   * The path to the artifact in the dist folder
+   */
+  readonly artifactPath: string;
+
+  /**
+   * The role arn (or github expression) for OIDC to assume to do the actual publishing.
+   */
+  readonly roleToAssume: string;
+
+  /**
+   * The bucket name (or github expression) to publish to.
+   */
+  readonly bucketName: string;
+}
+
+export class S3DocsPublishing extends Component {
+  private readonly github: github.GitHub;
+  private readonly props: S3DocsPublishingProps;
+
+  constructor(project: TypeScriptWorkspace, props: S3DocsPublishingProps) {
+    super(project);
+
+    const gh = (project.parent! as Monorepo).github;
+    if (!gh) {
+      throw new Error('This workspace does not have a GitHub instance');
+    }
+    this.github = gh;
+
+    this.props = props;
+  }
+
+  public preSynthesize() {
+    const releaseWf = this.github.tryFindWorkflow('release');
+    if (!releaseWf) {
+      throw new Error('Could not find release workflow');
+    }
+
+    const safeName = this.project.name.replace('@', '').replace('/', '-');
+
+    releaseWf.addJob(`${safeName}_release_docs`, {
+      name: `${this.project.name}: Publish docs to S3`,
+      environment: 'releasing', // <-- this has the configuration
+      needs: [`${safeName}_release_npm`],
+      runsOn: ['ubuntu-latest'],
+      permissions: {
+        idToken: github.workflows.JobPermission.WRITE,
+        contents: github.workflows.JobPermission.READ,
+      },
+      steps: [
+        {
+          name: 'Download build artifacts',
+          uses: 'actions/download-artifact@v4',
+          with: {
+            name: `${this.project.name}_build-artifact`,
+            path: 'dist',
+          },
+        },
+        {
+          name: 'Authenticate Via OIDC Role',
+          id: 'creds',
+          uses: 'aws-actions/configure-aws-credentials@v4',
+          with: {
+            'aws-region': 'us-east-1',
+            'role-duration-seconds': 14400,
+            'role-to-assume': '${{ vars.AWS_ROLE_TO_ASSUME_FOR_ACCOUNT }}',
+            'role-session-name': 'releasing@aws-cdk-cli',
+          },
+        },
+        {
+          name: 'Assume the publishing role',
+          id: 'publishing-creds',
+          uses: 'aws-actions/configure-aws-credentials@v4',
+          with: {
+            'aws-region': 'us-east-1',
+            'role-duration-seconds': 14400,
+            'role-to-assume': this.props.roleToAssume,
+            'role-session-name': 's3publishing@aws-cdk-cli',
+            'role-chaining': true,
+          },
+        },
+        {
+          name: 'Publish docs',
+          env: {
+            BUCKET_NAME: this.props.bucketName,
+            DOCS_STREAM: this.props.docsStream,
+          },
+          run: [
+            '::add-mask::$BUCKET_NAME', // always hide bucket name
+
+            // setup paths
+            `echo "S3_PATH=$DOCS_STREAM/${safeName}-v$(cat dist/version.txt).zip" >> "$GITHUB_ENV"`,
+            'echo "S3_URI=s3://$BUCKET_NAME/$S3_PATH" >> "$GITHUB_ENV"',
+            `echo "LATEST=latest-${this.props.docsStream}" >> "$GITHUB_ENV"`,
+
+            // create the latest marker
+            'echo $S3_PATH > $LATEST',
+
+            // check if the target file already exists and upload
+            '(! aws s3 ls --human-readable $S3_URI \\',
+            `&& aws s3 cp --dryrun dist/${this.props.artifactPath} $S3_URI \\`,
+            '&& aws s3 cp --dryrun $LATEST s3://$BUCKET_NAME/$LATEST) \\',
+            '|| (echo "Docs artifact already published, skipping upload")',
+          ].join('\n'),
+        },
+      ],
+    });
+  }
+}