Migrate CLA Process

.github/actions/check-for-CLA/README.md

@@ -0,0 +1,97 @@
+# CLA Check Automation
+
+This document explains the [Contributor License Agreement (CLA)](../../../CONTRIBUTING.md#contributor-license-agreement-cla) automation process used by CesiumJS CI.
+
+It covers:
+
+- the general CLA architecture,
+- when to update credentials,
+- and where maintainers can access the required credentials.
+
+## CLA Process Overview
+
+When a pull request is opened, the CLA workflow runs and checks whether the PR author has a signed CLA on file.
+
+- **Workflow**: [`.github/workflows/cla.yml`](../../workflows/cla.yml)
+- **Script**: [`.github/actions/check-for-CLA/index.js`](./index.js)
+
+The script looks up the GitHub username in Microsoft-hosted CLA data and then:
+
+- posts a confirmation comment when a CLA is found, or
+- posts CLA instructions and applies `PR - Needs Signed CLA` when a CLA is not found.
+
+## Architecture Summary
+
+### SharePoint Resources
+
+```text
+┌──────────────────┐      ┌──────────────────┐      ┌─────────────────────────┐
+│  Microsoft Forms │ ───> │  Power Automate  │ ───> │  Excel Workbook         │
+│      Survey      │      │     Flow         │      │  (SharePoint)           │
+└──────────────────┘      └──────────────────┘      └─────────────────────────┘
+```
+
+We use a **dedicated service account**, `cesium-cla-automation@bentley.com`, as the owner for both:
+
+1. [Microsoft Forms surveys](https://forms.office.com/)
+2. [Power Automate flow](https://make.powerautomate.com/)
+
+CLA data is stored in [Excel workbooks in OneDrive/SharePoint](https://bentley.sharepoint.com/:f:/r/sites/Platform/Shared%20Documents/CLAs)
+
+- Platform members and visitors can **view**
+- Limited teams/users (eg. CesiumJS and Cesium Native maintainers) can **edit**
+
+#### Power Automate Flow behavior
+
+1. Trigger: _When a new response is submitted_
+2. Action: _Get response details_
+3. Action: _Add a row into a table (Excel Online Business)_
+
+### GitHub Actions Script Access to SharePoint Resources
+
+```text
+┌──────────────────┐      ┌──────────────────┐      ┌─────────────────────────┐
+│  GitHub Actions  │ ───> │ Microsoft Graph  │ ───> │  Excel Workbook         │
+│                  │      │       API        │      │  (Microsoft SharePoint) │
+└──────────────────┘      └──────────────────┘      └─────────────────────────┘
+```
+
+The CI script accesses SharePoint data via the [Microsoft Graph REST API](https://learn.microsoft.com/en-us/graph/) using a Microsoft Entra app registration. The app credentials and workbook metadata are configured in a JSON string stored in a [GitHub Actions secret](https://github.com/CesiumGS/cesium/settings/secrets/actions).
+
+`MICROSOFT_GRAPH_INFO_JSON` contains the values required for Graph auth and workbook lookups, including:
+
+- `tenantId`
+- `clientId`
+- `clientSecret`
+- `siteId`
+- `driveId`
+- `individualWorkbookItemId`
+- `individualTableName`
+- `individualColumnName`
+- `corporateWorkbookItemId`
+- `corporateTableName`
+- `corporateColumnName`
+
+If a Sharepoint resource is migrated to a new location, or a workbook table or column name changes, `MICROSOFT_GRAPH_INFO_JSON` and [`.github/actions/check-for-CLA/index.js`](./index.js) must be updated to reflect changes.
+
+## Accessing Credentials
+
+Credential access is limited to maintainers with appropriate permissions.
+
+- **GitHub Actions secrets**: Accessable by users with the CesiumJS **maintainer** role in [**Repository settings / Actions secrets and variables**](https://github.com/CesiumGS/cesium/settings/secrets/actions). Backup copies are stored in Bitwarden.
+- **Sharepoint access**: Credentials are shared in Bitwarden.
+  - Dedicated service account for Forms/Flow ownership: `cesium-cla-automation@bentley.com`
+  - Graph credential entry: `CLA Automation - Microsoft Graph Credentials for GitHub CI`
+
+## Updating Credentials
+
+Entra app access credentials are configured to expire after one year. A yearly reminder workflow, [`.github/workflows/cla-rotation-reminder.yml`](../../workflows/cla-rotation-reminder.yml) creates a tracking issue on July 1.
+
+Follow process outlined in the issue to rotate the client secret in the Entra app:
+
+1. File a request with Bentley IT to rotate the client secret in the Entra app. Request token expiration be set to **August 1 the following year**.
+2. Update the value of `MICROSOFT_GRAPH_INFO_JSON` in GitHub Actions secrets.
+3. (Optional) Open a test PR or re-run the CLA workflow to validate behavior.
+   - Verify signed users are recognized.
+   - Verify unsigned users receive CLA instructions and label.
+4. Confirm backup credentials in Bitwarden are current.

.github/actions/check-for-CLA/index.js

@@ -1,7 +1,6 @@
 import { Octokit } from "@octokit/core";
-import { google } from "googleapis";
 import Handlebars from "handlebars";
-import fs from "fs-extra";
+import fs from "node:fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
@@ -13,50 +12,115 @@ const PULL_REQUST_INFO = {
   gitHubToken: process.env.GITHUB_TOKEN,
 };
 
-const GOOGLE_SHEETS_INFO = {
-  APIKeys: process.env.GOOGLE_KEYS,
-  individualCLASheetId: process.env.INDIVIDUAL_CLA_SHEET_ID,
-  corporateCLASheetId: process.env.CORPORATE_CLA_SHEET_ID,
+const parseMicrosoftGraphInfo = () => {
+  const configJson = process.env.MICROSOFT_GRAPH_INFO_JSON;
+  if (!configJson) {
+    throw new Error("MICROSOFT_GRAPH_INFO_JSON not found.");
+  }
+
+  let parsedConfig;
+  try {
+    parsedConfig = JSON.parse(configJson);
+  } catch {
+    throw new Error("MICROSOFT_GRAPH_INFO_JSON is not valid JSON.");
+  }
+
+  return {
+    tenantId: parsedConfig.tenantId,
+    clientId: parsedConfig.clientId,
+    clientSecret: parsedConfig.clientSecret,
+    siteId: parsedConfig.siteId,
+    driveId: parsedConfig.driveId,
+    individualWorkbookItemId: parsedConfig.individualWorkbookItemId,
+    individualTableName: parsedConfig.individualTableName ?? "CLA_Individual",
+    individualColumnName:
+      parsedConfig.individualColumnName ?? "GitHub Username",
+    corporateWorkbookItemId: parsedConfig.corporateWorkbookItemId,
+    corporateTableName: parsedConfig.corporateTableName ?? "CLA_Corporate",
+    corporateColumnName: parsedConfig.corporateColumnName ?? "Schedule A",
+  };
 };
 
+const MICROSOFT_GRAPH_INFO = parseMicrosoftGraphInfo();
+
 const CONTRIBUTORS_URL =
   "https://github.com/CesiumGS/cesium/blob/main/CONTRIBUTORS.md";
 
-const getGoogleSheetsApiClient = async () => {
-  const googleConfigFilePath = "GoogleConfig.json";
-  fs.writeFileSync(googleConfigFilePath, GOOGLE_SHEETS_INFO.APIKeys);
+const getGraphAccessToken = async () => {
+  const tokenUrl = `https://login.microsoftonline.com/${MICROSOFT_GRAPH_INFO.tenantId}/oauth2/v2.0/token`;
 
-  const auth = new google.auth.GoogleAuth({
-    keyFile: googleConfigFilePath,
-    scopes: ["https://www.googleapis.com/auth/spreadsheets"],
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: MICROSOFT_GRAPH_INFO.clientId,
+    client_secret: MICROSOFT_GRAPH_INFO.clientSecret,
+    scope: "https://graph.microsoft.com/.default",
   });
-  const googleAuthClient = await auth.getClient();
 
-  return google.sheets({ version: "v4", auth: googleAuthClient });
-};
+  const response = await fetch(tokenUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body,
+  });
 
-const getValuesFromGoogleSheet = async (sheetId, cellRanges) => {
-  const googleSheetsApi = await getGoogleSheetsApiClient();
+  if (!response.ok) {
+    throw new Error(
+      `Failed to obtain Microsoft Graph access token (${response.status}).`,
+    );
+  }
 
-  return googleSheetsApi.spreadsheets.values.get({
-    spreadsheetId: sheetId,
-    range: cellRanges,
+  const tokenResponse = await response.json();
+  return tokenResponse.access_token;
+};
+
+const getValuesFromTableColumnValues = async (
+  workbookItemId,
+  tableName,
+  columnName,
+) => {
+  const accessToken = await getGraphAccessToken();
+
+  const table = encodeURIComponent(tableName);
+  const column = encodeURIComponent(columnName);
+
+  const url =
+    `https://graph.microsoft.com/v1.0/sites/${MICROSOFT_GRAPH_INFO.siteId}` +
+    `/drives/${MICROSOFT_GRAPH_INFO.driveId}` +
+    `/items/${workbookItemId}` +
+    `/workbook/tables/${table}/columns/${column}/range`;
+
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: "application/json",
+    },
   });
+
+  if (!response.ok) {
+    throw new Error(`Failed to read Excel workbook range (${response.status})`);
+  }
+
+  const workbookResponse = await response.json();
+  return workbookResponse.values ?? [];
 };
 
 const checkIfIndividualCLAFound = async () => {
-  const response = await getValuesFromGoogleSheet(
-    GOOGLE_SHEETS_INFO.individualCLASheetId,
-    "D2:D",
+  const rows = await getValuesFromTableColumnValues(
+    MICROSOFT_GRAPH_INFO.individualWorkbookItemId,
+    MICROSOFT_GRAPH_INFO.individualTableName,
+    MICROSOFT_GRAPH_INFO.individualColumnName,
   );
 
-  const rows = response.data.values;
   for (let i = 0; i < rows.length; i++) {
     if (rows[i].length === 0) {
       continue;
     }
 
-    const rowUsername = rows[i][0].toLowerCase();
+    let rowUsername;
+    if (rows[i][0] && rows[i][0].length > 0) {
+      rowUsername = rows[i][0].toLowerCase();
+    }
     if (PULL_REQUST_INFO.username.toLowerCase() === rowUsername) {
       return true;
     }
@@ -66,12 +130,12 @@ const checkIfIndividualCLAFound = async () => {
 };
 
 const checkIfCorporateCLAFound = async () => {
-  const response = await getValuesFromGoogleSheet(
-    GOOGLE_SHEETS_INFO.corporateCLASheetId,
-    "H2:H",
+  const rows = await getValuesFromTableColumnValues(
+    MICROSOFT_GRAPH_INFO.corporateWorkbookItemId,
+    MICROSOFT_GRAPH_INFO.corporateTableName,
+    MICROSOFT_GRAPH_INFO.corporateColumnName,
   );
 
-  const rows = response.data.values;
   for (let i = 0; i < rows.length; i++) {
     if (rows[i].length === 0) {
       continue;
@@ -162,6 +226,20 @@ const main = async () => {
   let hasSignedCLA;
   let errorFoundOnCLACheck;
 
+  if (
+    !MICROSOFT_GRAPH_INFO.tenantId ||
+    !MICROSOFT_GRAPH_INFO.clientId ||
+    !MICROSOFT_GRAPH_INFO.clientSecret ||
+    !MICROSOFT_GRAPH_INFO.siteId ||
+    !MICROSOFT_GRAPH_INFO.driveId ||
+    !MICROSOFT_GRAPH_INFO.individualWorkbookItemId ||
+    !MICROSOFT_GRAPH_INFO.corporateWorkbookItemId
+  ) {
+    throw new Error(
+      "Missing required Microsoft Graph environment variables for CLA lookup.",
+    );
+  }
+
   try {
     hasSignedCLA = await checkIfUserHasSignedAnyCLA();
   } catch (error) {

.github/actions/check-for-CLA/package.json

@@ -4,8 +4,6 @@
     "main": "index.js",
     "dependencies": {
         "@octokit/core": "^6.1.2",
-        "fs-extra": "^11.2.0",
-        "googleapis": "^137.1.0",
         "handlebars": "^4.7.8"
     },
     "type": "module",

.github/workflows/cla-rotation-reminder.yml

@@ -0,0 +1,59 @@
+name: "CLA credential rotation reminder"
+
+on:
+  schedule:
+    # 12:00 UTC on July 1 every year
+    - cron: "0 12 1 7 *"
+  workflow_dispatch:
+
+jobs:
+  create-rotation-issue:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Create annual CLA rotation issue
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const year = new Date().getUTCFullYear();
+            const title = `Rotate CLA workflow credentials for ${year}`;
+            const label = "priority - next release";
+
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: "open",
+              per_page: 100,
+            });
+
+            const alreadyExists = issues.some((issue) => issue.title === title);
+            if (alreadyExists) {
+              core.info(`Issue already exists: ${title}`);
+              return;
+            }
+
+            const body = [
+              "## Annual CLA workflow credential rotation",
+              "",
+              "Rotate the Microsoft Graph credentials used by the CLA check workflow (`.github/workflows/cla.yml`).",
+              "Reference documentation: `.github/actions/check-for-CLA/README.md`",
+              "https://github.com/CesiumGS/cesium/blob/main/.github/actions/check-for-CLA/README.md",
+              "",
+              "### Checklist",
+              "- [ ] Rotate Azure app client secret used by `MICROSOFT_GRAPH_INFO_JSON`",
+              "- [ ] Update `MICROSOFT_GRAPH_INFO_JSON` GitHub secret with new credential values",
+              "- [ ] Validate `.github/actions/check-for-CLA/index.js` runs successfully in CI",
+              "- [ ] Confirm new PRs receive CLA check comment/label behavior",
+              "",
+              "_Created automatically on July 1._",
+            ].join("\n");
+
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title,
+              body,
+              labels: [label],
+            });
+            core.info(`Created issue with label: ${label}`);

.github/workflows/cla.yml

@@ -24,6 +24,4 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PULL_REQUEST_ID: ${{ github.event.number }}
-          GOOGLE_KEYS: ${{ secrets.GOOGLE_KEYS }}
-          INDIVIDUAL_CLA_SHEET_ID: ${{ secrets.INDIVIDUAL_CLA_SHEET_ID }}
-          CORPORATE_CLA_SHEET_ID: ${{ secrets.CORPORATE_CLA_SHEET_ID }}
+          MICROSOFT_GRAPH_INFO_JSON: ${{ secrets.MICROSOFT_GRAPH_INFO_JSON }}

.gitignore

@@ -39,6 +39,3 @@ yarn.lock
 .idea/workspace.xml
 .idea/tasks.xml
 .idea/shelf
-
-# Used in the CLA checking GitHub workflow
-GoogleConfig.json

CONTRIBUTING.md

@@ -55,8 +55,8 @@ We love pull requests. We strive to promptly review them, provide feedback, and
 
 Before we can review a pull request, we require a signed Contributor License Agreement. There is a CLA for:
 
-- [individuals](https://docs.google.com/forms/d/e/1FAIpQLScU-yvQdcdjCFHkNXwdNeEXx5Qhu45QXuWX_uF5qiLGFSEwlA/viewform) and
-- [corporations](https://docs.google.com/forms/d/e/1FAIpQLSeYEaWlBl1tQEiegfHMuqnH9VxyfgXGyIw13C2sN7Fj3J3GVA/viewform).
+- [individuals](https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=MpZ-Bkzq2U6ebeKUlW4oSwLq-QNnfjxPgQhu1KdM4KxUQk43SlM5Q1NWQ1dGTVoyWjMzT1dCSk5GSy4u) and
+- [corporations](https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=MpZ-Bkzq2U6ebeKUlW4oSwLq-QNnfjxPgQhu1KdM4KxURVVPRFNBRkFEV0JSR1hQR0Q4SkxDM01ROC4u).
 
 This only needs to be completed once, and enables contributions to all of the projects under the [CesiumGS](https://github.com/CesiumGS) organization, including CesiumJS. The CLA ensures you retain copyright to your contributions, and provides us the right to use, modify, and redistribute your contributions using the [Apache 2.0 License](LICENSE.md).