ci: add scripts for trusting PRs from forks to allow CI to run (#1512)

## Please verify the following:

- [x] `yarn build-and-test:local` passes
- [x] I have added tests for any new features, if relevant
- [x] `README.md` (or relevant documentation) has been updated with your
changes

## Describe your PR

### Summary
* adds the `ci:trust` script and  related docs. to the local repo
* CircleCI Changes:
* add the "trust-check" step, to ensure CI doesn't run on untrusted
forks
* Adds github workflows to:
* push PR changes to a trusted branch then clean up automatically after
2h
    * delete all temp trusted branches with matching branch names 

### Notes:

* Based on [this
article](https://circleci.com/blog/triggering-trusted-ci-jobs-on-untrusted-forks/),
this config prevents the build-docs action from running on untrusted
forks.
* CI will check if a branch is trusted before running CI 
* Once a branch is trusted, then CI will run
* The github workflow to create a temp branch will automatically clean
up the branch after a couple hours, and a separate action is provided to
manually delete all temp branches in case any get left behind.
* the `ci:trust` script will need to be cleaned up manually for now --
can maybe automate that with a cron job in github workflows

---------

Co-authored-by: Joshua Yoes <37849890+joshuayoes@users.noreply.github.com>

Author: trevor-coleman

.circleci/config.yml

@@ -12,7 +12,12 @@ parameters:
 # Anchors define reusable sections of YAML
 # See: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
 anchors:
-  # Defaults passed to all jobs
+
+  ### Executors
+  node_executor: &node_executor
+    name: node/default
+    resource_class: large
+  # Default Settings
   defaults: &defaults
     working_directory: ~/repo
   # Branch names used to trigger releases
@@ -198,9 +203,7 @@ commands:
 jobs:
   build_and_test:
     <<: *defaults
-    executor: &node_executor
-      name: node/default
-      resource_class: large
+    executor: *node_executor
     steps:
       - checkout
       - install-packages
@@ -222,6 +225,24 @@ jobs:
       - run:
           name: Typecheck
           command: yarn typecheck
+  trust_check:
+    executor: *node_executor
+    steps:
+      - run:
+          name: Check if branch is trusted
+          command: |
+            if [ -n "$CIRCLE_PR_NUMBER" ]; then
+              if [[ $CIRCLE_BRANCH == temp-ci-trusted-fork-* ]]; then
+                echo "Branch is trusted"
+                exit 0
+              else
+                echo "Branch is not trusted. Please use the trust process before merging."
+                exit 1
+              fi
+            else
+              echo "Not a PR from a fork, skipping trust check"
+              exit 0
+            fi
 
   release_tags:
     <<: *defaults
@@ -259,6 +280,7 @@ jobs:
             yarn release:artifacts $CIRCLE_TAG
 
   build_app_windows:
+    executor: *node_executor
     <<: *defaults
     docker:
       - image: electronuserland/builder:20-wine
@@ -329,24 +351,30 @@ jobs:
           command: yarn workspace reactotron-app release:artifacts $CIRCLE_TAG
 
 workflows:
-  pull_request:
-    # prevents the workflow from running when `force-publish-docs` is true
+  pull_request: # prevents the workflow from running when `force-publish-docs` is true
     when:
       and:
         - not: << pipeline.parameters.force-publish-docs >>
         - true  # Placeholder for correct YAML structure
     jobs:
+      - trust_check:
+          filters:
+            branches:
+              ignore: *release_branch_names
       - build_and_test:
+          requires:
+            - trust_check
           filters:
             branches:
               ignore: *release_branch_names
       - publish-docs/build_docs:
+          requires:
+            - trust_check
           <<: *ir_docs_config
           filters:
             branches:
               ignore: *release_branch_names
 
-
   # Allows for manual publishing of docs independent of deployment
   # Use the 'trigger pipeline' button in circle ci and set 'force-publish-docs' to 'true'
   force_publish_docs:
@@ -355,8 +383,7 @@ workflows:
       - publish-docs/publish_docs:
           <<: *ir_docs_config
 
-  release:
-    # prevents the workflow from running when `force-publish-docs` is true
+  release: # prevents the workflow from running when `force-publish-docs` is true
     when:
       and:
         - not: << pipeline.parameters.force-publish-docs >>
@@ -374,11 +401,19 @@ workflows:
               only: *release_branch_names
           requires:
             - build_and_test
+      - publish-docs/build_docs:
+          <<: *ir_docs_config
+          filters:
+            branches:
+              only:
+                - beta
+                - alpha
       - publish-docs/publish_docs:
           <<: *ir_docs_config
           filters:
             branches:
-              only: *release_branch_names
+              only:
+                - master
       - release_package:
           context:
             - infinitered-npm-package

.github/workflows/cleanup-all-temp-trusted-branches.yml

@@ -0,0 +1,40 @@
+name: Cleanup All Temp Trusted Branches
+
+on:
+  workflow_dispatch:
+
+jobs:
+  delete-branches:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Git
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+
+      - name: Find branches to delete
+        run: |
+          # Fetch all branches
+          git fetch --all
+          
+          # Find branches starting with 'temp-ci-trusted-fork-'
+          branches_to_delete=$(git branch -r | grep 'origin/temp-ci-trusted-fork-' | sed 's|origin/||')
+          
+          if [ -z "$branches_to_delete" ]; then
+            echo "No branches found to delete."
+            exit 0
+          fi
+
+          echo "Branches to delete:"
+          echo "$branches_to_delete"
+
+          # Delete each branch
+          for branch in $branches_to_delete; do
+            echo "Deleting branch: $branch"
+            git push origin --delete "$branch"
+          done

.github/workflows/trust-fork-pr-cleanup.yml

@@ -0,0 +1,37 @@
+name: Cleanup Trusted Branch
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch_to_delete:
+        description: 'Branch to delete'
+        required: true
+      delete_after:
+        description: 'Delete after (ISO 8601 date)'
+        required: true
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if it's time to delete
+        id: check_time
+        run: |
+          current_time=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          if [[ "$current_time" > "${{ github.event.inputs.delete_after }}" ]]; then
+            echo "::set-output name=should_delete::true"
+          else
+            echo "::set-output name=should_delete::false"
+          fi
+
+      - name: Delete branch
+        if: steps.check_time.outputs.should_delete == 'true'
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            github.rest.git.deleteRef({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: 'heads/${{ github.event.inputs.branch_to_delete }}'
+            });

.github/workflows/trust-fork-pr.yml

@@ -0,0 +1,75 @@
+name: Trust Fork PR
+
+on:
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to trust'
+        required: true
+
+jobs:
+  trust-fork:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate unique identifier
+        id: gen_uid
+        run: echo "::set-output name=uid::$(date +%s)-${{ github.run_id }}"
+
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Git
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+
+      - name: Fetch PR details
+        id: pr
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const pr = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: parseInt(context.payload.inputs.pr_number)
+            });
+            core.setOutput('head_repo', pr.data.head.repo.full_name);
+            core.setOutput('head_branch', pr.data.head.ref);
+
+      - name: Fetch and push to trusted branch
+        env:
+          FORK_REPO: ${{ steps.pr.outputs.head_repo }}
+          FORK_BRANCH: ${{ steps.pr.outputs.head_branch }}
+          UNIQUE_ID: ${{ steps.gen_uid.outputs.uid }}
+        run: |
+          git remote add fork https://github.com/${FORK_REPO}.git
+          git fetch fork ${FORK_BRANCH}
+          git push origin fork/${FORK_BRANCH}:temp-ci-trusted-fork-${UNIQUE_ID} --force
+
+      - name: Cleanup
+        if: always()
+        run: |
+          git remote remove fork
+
+      - name: Schedule branch deletion
+        if: success()
+        env:
+          UNIQUE_ID: ${{ steps.gen_uid.outputs.uid }}
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const deleteDate = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(); // 24 hours from now
+            github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'trust-fork-pr-cleanup.yml',
+              ref: 'main',
+              inputs: {
+                branch_to_delete: `temp-ci-trusted-fork-${process.env.UNIQUE_ID}`,
+                delete_after: deleteDate
+              }
+            });

docs/contributing/ci.md

@@ -0,0 +1,46 @@
+---
+name: Running Tests on Untrusted Forks
+sidebar_position: 99
+---
+
+# Running CI Scripts on Untrusted Forks
+
+Untrusted forks could contain malicious code to mine cryptocurrency, steal secrets, or otherwise harm the CI server.
+
+For PRs from untrusted forks, to run the CI scripts, we need to:
+
+1. Review the code to ensure that it is safe to run on the CI server.
+2. If the code is safe, run the `ci:trust` script to push the commits to a branch on the main repository, where the CI scripts can be run.
+3. Once the tests have run, the status of the PR will be updated automatically (because the commits are the same).
+
+## How to run the CI scripts on untrusted forks:
+
+1. Copy the name of the branch from the PR.
+   <img src="./images/ci-copy-fork-branch.png" alt="ci-copy-fork-branch" width="400"/>
+2. From your local clone of the main repository, run the `ci:trust` script.
+    ```bash
+    yarn ci:trust <branch-name>
+    ```
+3. The branch will be pushed and the tests will run
+   <img src="./images/ci-tests-running.png" alt="ci-tests-running" width="400"/>
+
+## What does ci:trust do?
+
+The `ci:trust` script does the following:
+
+1. Adds and fetches the untrusted fork as a temporary remote in your local repository.
+2. Pushes the specific branch from the untrusted fork to a designated temporary branch in your original repository.
+3. Pushing to a local branch triggers the continuous integration (CI) tests on the commits of the branch.
+4. Because the commits are the same, the status of the PR will be updated automatically.
+
+### Notes
+
+1. The ci:trust script will only work if you have write access to the main repository. This prevents malicious users from running the script on the main repository.
+2. The ci:trust script pushes the commits to a branch called `temp-ci-trusted-fork`.
+
+::: warning
+
+The `temp-ci-trusted-fork` branch will be deleted and recreated if it already exists. This allows the script to
+clean up its own temporary branches.
+
+:::

docs/contributing/images/ci-copy-fork-branch.png

@@ -66,6 +66,7 @@
     "lint": "npx nx run-many --target lint",
     "test": "npx nx run-many --target test",
     "ci:test": "npx nx run-many --target ci:test",
+    "ci:trust": "sh ./scripts/git-clone-fork-to-trusted-branch.sh",
     "typecheck": "npx nx run-many --target typecheck",
     "format:write": "npx nx run-many --target format:write",
     "format:check": "npx nx run-many --target format:check",

docs/contributing/images/ci-tests-running.png

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+################################################################################
+# This script is used to clone a forked repository and push a branch to a
+# trusted branch in the reactotron repository, so the CI scripts can.run
+# tests on the forked branch. This prevents unreviewed code from being run
+# in the CI pipeline.
+#
+# Usage: ./scripts/git-clone-fork-to-trusted-branch.sh <fork_username>:<fork_branchname>
+#
+# Example: ./scripts/git-clone-fork-to-trusted-branch.sh "infinitered:temp-branch-to-test-fork"
+#
+###############################################################################
+
+set -eo pipefail
+
+: "${GPF_REACTOTRON_BRANCH:=temp-ci-trusted-fork}"
+
+REACTOTRON_REPO="git@github.com:infinitered/reactotron.git"
+BRANCH_SPEC=$1
+NUM_COLONS=$(echo "$BRANCH_SPEC" | awk -F: '{print NF-1}')
+
+if [ "$#" -ne 1 ] || [ "$NUM_COLONS" -ne 1 ] ; then
+    echo "Usage: <fork_username>:<fork_branchname>"
+    exit 1
+fi
+
+SOURCE_GH_USER=$(echo "$BRANCH_SPEC" | awk -F: '{print $1}')
+SOURCE_BRANCH=$(echo "$BRANCH_SPEC" | awk -F: '{print $2}')
+REPO_NAME=$(git remote get-url --push origin | awk -F/ '{print $NF}' | sed 's/\.git$//')
+
+# Check if 'fork-to-test' remote exists and then remove it
+if git config --get "remote.fork-to-test.url" > /dev/null; then
+    git remote remove fork-to-test
+    echo "Removed remote fork-to-test"
+else
+    echo "Remote fork-to-test does not exist, no need to remove it"
+fi
+
+git remote add fork-to-test "git@github.com:$SOURCE_GH_USER/$REPO_NAME.git"
+
+git fetch --all
+git push --force "$REACTOTRON_REPO" "refs/remotes/fork-to-test/$SOURCE_BRANCH:refs/heads/$GPF_REACTOTRON_BRANCH"
+git remote remove fork-to-test || echo "Removed new remote fork-to-test"
+
+cat <<EOF
+Forked branch '$BRANCH_SPEC' has been pushed to branch '$GPF_REACTOTRON_BRANCH'
+EOF