From acc171bb5e34cd76bf152307e562bb49e7743b94 Mon Sep 17 00:00:00 2001 From: Kudo Chien Date: Thu, 21 Sep 2023 00:40:58 +0800 Subject: [PATCH] feature: add readme for preview-build and fingerprint action (#232) following up with https://github.com/expo/expo-github-action/pull/231#pullrequestreview-1628540314 to add READMEs --------- Co-authored-by: Cedric van Putten --- fingerprint/README.md | 199 ++++++++++++++++++++++++++++++++++++++++ preview-build/README.md | 177 +++++++++++++++++++++++++++++++++++ 2 files changed, 376 insertions(+) create mode 100644 fingerprint/README.md create mode 100644 preview-build/README.md diff --git a/fingerprint/README.md b/fingerprint/README.md new file mode 100644 index 00000000..7cb2aed4 --- /dev/null +++ b/fingerprint/README.md @@ -0,0 +1,199 @@ +
+

fingerprint

+

Checking project fingerprinting for pull requests using @expo/fingerprint

+
+ +

+ + + + Latest release + + + + + + Workflow status + + +

+ +

+ Usage +   —   + Outputs +   —   + Examples +   —   + Caveats +   —   + Changelog +

+ +
+ +> **Warning** +> This sub action is experimental and might change without notice. Use it at your own risk + +## Overview + +`fingerprint` is a GitHub Action that checks project fingerprinting for pull requests using [`@expo/fingerprint`](https://www.npmjs.com/package/@expo/fingerprint). When a pull request is updated, you can use this action to check the fingerprint integrity. If a pull request is fingerprint compatible, it means there are no changes from native code and be Over-The-Air updates compatible. Otherwise, if fingerprint changed, it means the project has native code changes. + +This action is designed to be used in conjunction with the `@expo/fingerprint` package, which generates a unique fingerprint for each pull request based on the contents of the code. By using fingerprinting, this action can determine if a pull request has already been built, and reuse the existing build instead of creating a new one. + +## Usage + +To use this action, add the following code to your workflow: + +```yaml +on: + push: + # REQUIRED: push main(default) branch is necessary for this action to update its fingerprint database + branches: [main] + pull_request: + types: [opened, synchronize] + +jobs: + : + runs-on: + # REQUIRED: limit concurrency when pushing main(default) branch to prevent conflict for this action to update its fingerprint database + concurrency: fingerprint-${{ github.event_name != 'pull_request' && 'main' || github.run_id }} + permissions: + # REQUIRED: Allow comments of PRs + pull-requests: write # Allow comments on PRs + # REQUIRED: Allow updating fingerprint in acton caches + actions: write + + steps: + - name: Check fingerprint + uses: expo/expo-github-action/fingerprint@main +``` + +### Configuration options + +This action is customizable through variables defined in the [`action.yml`](action.yml). +Here is a summary of all the input options you can use. + +| variable | default | description | +| ---------------------------------- | ---------------- | ----------------------------------------------------------------------- | +| **working-directory** | - | The relative directory of your Expo app | +| **packager** | `yarn` | The package manager used to install the fingerprint tools | +| **github-token** | `github.token` | GitHub token to use when commenting on PR ([read more](#github-tokens)) | +| **fingerprint-version** | `latest` | `@expo/fingerprint` version to install | +| **fingerprint-installation-cache** | `true` | If the `@expo/fingerprint` should be cached to speed up installation | +| **fingerprint-db-cache-key** | `fingerprint-db` | A cache key to use for saving the fingerprint database | + +And the action will generate these [outputs](#available-outputs) for other actions to do something based on current project fingerprint + +### Available outputs + +In case you want to reuse this action for other purpose, this action will set the following action outputs. + +| output name | description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **fingerprint-diff** | The diff between the current and the previous fingerprint. It is a JSON array of fingerprint diff. If the fingerprint does not change in between, the result diff will be an empty array `[]` | + +## Example workflows + +Here's an example workflow that uses this action to comment pull requests and add `Fingerprint:compatible` and `Fingerprint:changed` labels + +```yaml +name: PR Labeler + +on: + push: + # REQUIRED: push main(default) branch is necessary for this action to update its fingerprint database + branches: [main] + pull_request: + types: [opened, synchronize] + +jobs: + fingerprint: + runs-on: ubuntu-latest + # REQUIRED: limit concurrency when pushing main(default) branch to prevent conflict for this action to update its fingerprint database + concurrency: fingerprint-${{ github.event_name != 'pull_request' && 'main' || github.run_id }} + permissions: + # REQUIRED: Allow comments of PRs + pull-requests: write # Allow comments on PRs + # REQUIRED: Allow updating fingerprint in acton caches + actions: write + + steps: + - name: 🏗 Setup repo + uses: actions/checkout@v3 + + - name: 🏗 Setup Node + uses: actions/setup-node@v3 + with: + node-version: 18.x + cache: yarn + + - name: 📦 Install dependencies + run: yarn install + + - name: Check fingerprint + id: fingerprint + uses: expo/expo-github-action/preview-build@main + + - uses: actions/github-script@v6 + if: ${{ github.event_name == 'pull_request' && github.steps.fingerprint.outputs.fingerprint-diff == '[]' }} + with: + script: | + try { + await github.rest.issues.removeLabel({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + name: ['Fingerprint:changed'] + }) + } catch (e) { + if (e.status != 404) { + throw e; + } + } + github.rest.issues.addLabels({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + labels: ['Fingerprint:compatible'] + }) + + - uses: actions/github-script@v6 + if: ${{ github.event_name == 'pull_request' && steps.fingerprint.outputs.fingerprint-diff != '[]' }} + with: + script: | + try { + await github.rest.issues.removeLabel({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + name: ['Fingerprint:compatible'] + }) + } catch (e) { + if (e.status != 404) { + throw e; + } + } + github.rest.issues.addLabels({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + labels: ['Fingerprint:changed'] + }) +``` + +This workflow listens for pull request events and generates a fingerprint for each pull request. Based on the `fingerprint-diff` output, the example then use GitHub API to add/remove labels based on fingerprint compatible state. + +## Caveats + +### GitHub tokens + +When using the GitHub API, you always need to be authenticated. +This action tries to auto-authenticate using the [Automatic token authentication][link-gha-token] from GitHub. +You can overwrite the token by adding the `GITHUB_TOKEN` environment variable or add the **github-token** input. + +
+
+ with :heart: Expo +
+
diff --git a/preview-build/README.md b/preview-build/README.md new file mode 100644 index 00000000..c7554863 --- /dev/null +++ b/preview-build/README.md @@ -0,0 +1,177 @@ +
+

preview-build

+

Checking project fingerprinting for pull requests using @expo/fingerprint

+
+ +

+ + + + Latest release + + + + + + Workflow status + + +

+ +

+ Usage +   —   + Outputs +   —   + Examples +   —   + Caveats +   —   + Changelog +

+ +
+ +> **Warning** +> This sub action is experimental and might change without notice. Use it at your own risk + +## Overview + +`preview-build` is a GitHub Action that creates new EAS Builds for pull requests using [`@expo/fingerprint`](https://www.npmjs.com/package/@expo/fingerprint). When a pull request is updated, you can use this action to check the fingerprint integrity. If a pull request is fingerprint compatible, it means there are no changes from native code and be EAS Update compatible. Otherwise, if fingerprint changed, it means native code changed and the action will create new EAS Builds. + +This action is designed to be used in conjunction with the `@expo/fingerprint` package, which generates a unique fingerprint for each pull request based on the contents of the code. By using fingerprinting, this action can determine if a pull request has already been built, and reuse the existing build instead of creating a new one. + +## Usage + +To use this action, add the following code to your workflow: + +```yaml +on: + push: + # REQUIRED: push main(default) branch is necessary for this action to update its fingerprint database + branches: [main] + pull_request: + types: [opened, synchronize] + +jobs: + : + runs-on: + # REQUIRED: limit concurrency when pushing main(default) branch to prevent conflict for this action to update its fingerprint database + concurrency: fingerprint-${{ github.event_name != 'pull_request' && 'main' || github.run_id }} + permissions: + # REQUIRED: Allow comments of PRs + pull-requests: write # Allow comments on PRs + # REQUIRED: Allow updating fingerprint in acton caches + actions: write + + steps: + - name: Setup EAS + uses: expo/expo-github-action@v8 + with: + eas-version: latest + token: ${{ secrets.EXPO_TOKEN }} + + - name: Create preview builds if fingerprint changed + uses: expo/expo-github-action/preview-build@main + with: + command: eas build --profile development --platform all +``` + +### Configuration options + +This action is customizable through variables defined in the [`action.yml`](action.yml). +Here is a summary of all the input options you can use. + +| variable | default | description | +| ---------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| **command** | - | EAS CLI command to run when creating builds | +| **comment** | `true` | If the action should summarize the EAS Update information as comment on a pull request | +| **comment-id** | _[see code][code-defaults]_ | unique id template to prevent duplicate comments ([read more](#preventing-duplicate-comments)) | +| **working-directory** | - | The relative directory of your Expo app | +| **packager** | `yarn` | The package manager used to install the fingerprint tools | +| **github-token** | `github.token` | GitHub token to use when commenting on PR ([read more](#github-tokens)) | +| **fingerprint-version** | `latest` | `@expo/fingerprint` version to install | +| **fingerprint-installation-cache** | `true` | If the `@expo/fingerprint` should be cached to speed up installation | +| **fingerprint-db-cache-key** | `fingerprint-db` | A cache key to use for saving the fingerprint database | +| **eas-build-message** | Will retrieve from the Git branch HEAD message | A short message describing the build that will pass to `eas build --message` | + +### Available outputs + +In case you want to reuse this action for other purpose, this action will set the following action outputs. + +| output name | description | +| --------------------- | ------------------------------------------------------------------------------------------------- | +| **projectId** | The resolved EAS project ID | +| **commentId** | The unique comment ID to prevent duplicate comments ([read more](#preventing-duplicate-comments)) | +| **comment** | The comment with information about the updates | +| **gitCommitHash** | Git commit hash that was found when creating this build | +| **androidBuildId** | EAS Build ID for Android | +| **androidLink** | Absolute URL to Android build on expo.dev | +| **androidAppVersion** | Version of the Android app | +| **iosBuildId** | EAS Build ID for iOS | +| **iosLink** | Absolute URL to iOS build on expo.dev | +| **iosAppVersion** | Version of the iOS app | + +## Example workflows + +Here's an example workflow that uses this action to comment pull requests and create EAS Builds if fingerprint changed + +```yaml +name: Build preview for pull requests + +on: + push: + # REQUIRED: push main(default) branch is necessary for this action to update its fingerprint database + branches: [main] + pull_request: + types: [opened, synchronize] + +jobs: + build: + runs-on: ubuntu-latest + # REQUIRED: limit concurrency when pushing main(default) branch to prevent conflict for this action to update its fingerprint database + concurrency: fingerprint-${{ github.event_name != 'pull_request' && 'main' || github.run_id }} + permissions: + # REQUIRED: Allow comments of PRs + pull-requests: write # Allow comments on PRs + # REQUIRED: Allow updating fingerprint in acton caches + actions: write + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: 🏗 Setup EAS + uses: expo/expo-github-action@v8 + with: + eas-version: latest + token: ${{ secrets.EXPO_TOKEN }} + + - name: Install dependencies + run: yarn install + + - name: Create preview builds if needed + uses: expo/expo-github-action/preview-build@main + with: + command: eas build --profile development --platform all +``` + +This workflow listens for pull request events and generates a fingerprint for each pull request. It then uses this action to create an EAS Build for the pull request, and deploys the build using another action. + +## Caveats + +### Preventing duplicate comments + +When automating these preview comments, you have to be careful not to spam a pull request on every successful run. +Every comment contains a generated **message-id** to identify previously made comments and update them instead of creating a new comment. + +### GitHub tokens + +When using the GitHub API, you always need to be authenticated. +This action tries to auto-authenticate using the [Automatic token authentication][link-gha-token] from GitHub. +You can overwrite the token by adding the `GITHUB_TOKEN` environment variable or add the **github-token** input. + +
+
+ with :heart: Expo +
+