From 521de724fcb79235773c077e870d7c2293ab51cb Mon Sep 17 00:00:00 2001 From: Cedric van Putten Date: Thu, 13 Jan 2022 20:06:19 +0100 Subject: [PATCH] docs: update readme and contributing guides --- CONTRIBUTING.md | 6 +- README.md | 175 ++++++++++-------------------------------------- action.yml | 2 +- 3 files changed, 41 insertions(+), 142 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3c424d5..1bcab659 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,16 +10,16 @@ ## ๐ŸŽ๏ธ Running a custom version -To try out your changed with GitHub Action, you have [to reference your fork and/or branch or commit reference](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions) in the workflow you want to try. After that, you have two options: +To try out your changes with GitHub Action, you have [to reference your fork and/or branch or commit reference](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions) in the workflow you want to try. After that, you have two options: 1. Run the workflow in GitHub Actions itself by triggering your workflow. 2. Run the workflow locally with [nektos/act](https://github.com/nektos/act). -## โœ… Testing +## ๐Ÿงช Testing Testing is done using [Jest](https://jestjs.io/https://jestjs.io/). Run `yarn test` to run Jest. -In CI we are running tests on multiple Node versions using Windows, Linux, and MacOS. Make sure they are passing for your PR. +If your PR is ready, run the **test** workflow to test the workflows on all supported OS system. ## ๐Ÿ“ Writing a Commit Message diff --git a/README.md b/README.md index aae01fb4..7022ef9e 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ ## What's inside? -With this Expo action, you have full access to [Expo CLI][link-expo-cli] and [EAS CLI][link-eas-cli] itself. -It allows you to fully automate the `expo publish` or `expo build` process, leaving you with more time available for your project. +With this Expo action, you have full access to [Expo CLI][link-expo-cli] and [EAS CLI][link-eas-cli]. +It allows you to fully automate the `expo publish` or `eas build` process, leaving you with more time available for your project. There are some additional features included to make the usage of this action as simple as possible, like caching and authentication. ## Configuration options @@ -34,21 +34,17 @@ There are some additional features included to make the usage of this action as This action is customizable through variables; they are defined in the [`action.yml`](action.yml). Here is a summary of all the variables that you can use and their purpose. -| variable | default | description | -| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------ | -| `expo-version` | - | [Expo CLI](https://github.com/expo/expo-cli) version to install, skips when omitted. | -| `expo-cache` | `false` | If it should use the [GitHub actions (remote) cache](#using-the-built-in-cache). | -| `expo-cache-key` | - | An optional custom (remote) cache key. _(**use with caution**)_ | -| `eas-version` | - | [EAS CLI](https://github.com/expo/eas-cli) version to install, skips when omitted. (`latest` is recommended) | -| `eas-cache` | `false` | If it should use the [GitHub actions (remote) cache](#using-the-built-in-cache). | -| `eas-cache-key` | - | An optional custom (remote) cache key. _(**use with caution**)_ | -| `packager` | `yarn` | The package manager to use. _(e.g. `npm`)_ | -| `token` | - | The token of your Expo account _(e.g. [`${{ secrets.EXPO_TOKEN }}`][link-actions-secrets])_ | -| `username` | - | The username of your Expo account _(e.g. `bycedric`)_ | -| `password` | - | The password of your Expo account _(e.g. [`${{ secrets.EXPO_CLI_PASSWORD }}`][link-actions-secrets])_ | -| `patch-watchers` | `true` | If it should [patch the `fs.inotify.` limits](#enospc-errors-on-linux). | - -> Never hardcode `expo-token` or `expo-password` in your workflow, use [secrets][link-actions-secrets] to store them. +| variable | default | description | +| ---------------- | ------- | ------------------------------------------------------------------------------------ | +| `expo-version` | `''` | [Expo CLI](https://github.com/expo/expo-cli) version to install, skips when omitted. | +| `expo-cache` | `false` | If it should use the [GitHub actions cache](#using-the-built-in-cache). | +| `eas-version` | `''` | [EAS CLI](https://github.com/expo/eas-cli) version to install, skips when omitted. | +| `eas-cache` | `false` | If it should use the [GitHub actions cache](#using-the-built-in-cache). | +| `packager` | `yarn` | The package manager to use. _(e.g. `yarn` or `npm`)_ | +| `token` | `''` | The token of your Expo account | +| `patch-watchers` | `true` | If it should [patch the `fs.inotify.` limits](#enospc-errors-on-linux). | + +> Never hardcode `expo-token` in your workflow, use [secrets][link-actions-secrets] to store them. > Using `latest` for `eas-version` is recommened, you should always have the latest version of this CLI installed. @@ -58,12 +54,9 @@ Before you dive into the workflow examples, you should know the basics of GitHub You can read more about this in the [GitHub Actions documentation][link-actions]. 1. [Publish on any push to main](#publish-on-any-push-to-main) -2. [Cache Expo CLI for other jobs](#cache-expo-cli-for-other-jobs) -3. [Creating a new EAS build](#creating-a-new-eas-build) -4. [Test PRs and publish a review version](#test-prs-and-publish-a-review-version) -5. [Test PRs on multiple nodes and systems](#test-prs-on-multiple-nodes-and-systems) -6. [Test and build web every day at 08:00](#test-and-build-web-every-day-at-0800) -7. [Authenticate using credentials](#authenticate-using-credentials) +2. [Creating a new EAS build](#creating-a-new-eas-build) +3. [Test PRs and publish a review version](#test-prs-and-publish-a-review-version) +4. [Test PRs on multiple nodes and systems](#test-prs-on-multiple-node-versions-and-systems) ### Publish on any push to main @@ -72,55 +65,22 @@ The workflow listens to the `push` event and sets up Node 14 using the [Setup No It also auto-authenticates when the `token` is provided. ```yml -name: Expo Publish -on: - push: - branches: - - main -jobs: - publish: - name: Install and publish - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 - with: - node-version: 14.x - - uses: expo/expo-github-action@v6 - with: - expo-version: 4.x - token: ${{ secrets.EXPO_TOKEN }} - - run: yarn install - - run: expo publish -``` - -### Cache Expo CLI for other jobs - -Below you can see a slightly modified version of the example above. -In this one, we enabled the built-in cache that will reuse a previously installed Expo CLI. -It skips the installation part and extracts the files directly, boosting the performance of your workflow. - -> You can [read more about the cache here](#using-the-built-in-cache) - -```yml -name: Expo Publish on: push: branches: - main jobs: publish: - name: Install and publish runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: - node-version: 14.x + node-version: 16.x + cache: yarn - uses: expo/expo-github-action@v6 with: - expo-version: 4.x - expo-cache: true + expo-version: 5.x token: ${{ secrets.EXPO_TOKEN }} - run: yarn install - run: expo publish @@ -135,20 +95,19 @@ Both the `token` and `username`/`password` is shared between both Expo and EAS C > We recommend using `latest` for `eas-version` to always have the most up-to-date version. ```yml -name: EAS build on: push: branches: - main jobs: build: - name: Create new build runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: - node-version: 14.x + node-version: 16.x + cache: yarn - uses: expo/expo-github-action@v6 with: eas-version: latest @@ -164,31 +123,33 @@ To make this easier, you can publish the edited version of the PR using a [relea Below you can see an example of a workflow that publishes and comments on te PR when the app is published. ```yml -name: Expo Review on: [pull_request] +env: + projectOwner: bycedric + projectSlug: use-expo jobs: publish: - name: Install and publish runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: - node-version: 14.x + node-version: 16.x + cache: yarn - uses: expo/expo-github-action@v6 with: - expo-version: 4.x + expo-version: 5.x token: ${{ secrets.EXPO_TOKEN }} - run: yarn install - run: expo publish --release-channel=pr-${{ github.event.number }} - - uses: unsplash/comment-on-pr@master + - uses: unsplash/comment-on-pr@v1.1.1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: - msg: App is ready for review, you can [see it here](https://expo.dev/@bycedric/use-expo?release-channel=pr-${{ github.event.number }}). + msg: App is ready for review, you can [see it here](https://expo.dev/@${{ env.projectOwner }}/${{ env.projectSlug }}?release-channel=pr-${{ github.event.number }}).\n\n ``` -### Test PRs on multiple nodes and systems +### Test PRs on multiple node versions and systems With GitHub Actions, it's reasonably easy to set up a matrix build and test the app on multiple environments. These matrixes can help to make sure your app runs smoothly on a broad set of different development machines. @@ -196,102 +157,42 @@ These matrixes can help to make sure your app runs smoothly on a broad set of di > If you don't need automatic authentication, you can omit the `token` variables. ```yml -name: Expo CI on: [pull_request] jobs: ci: - name: Continuous Integration runs-on: ${{ matrix.os }} strategy: matrix: os: [ubuntu-latest, macOS-latest, windows-latest] - node: [10, 12, 13] + node: [14.x, 16.x] steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: node-version: ${{ matrix.node }} + cache: yarn - uses: expo/expo-github-action@v6 with: - expo-version: 4.x + expo-version: 5.x - run: yarn install - run: yarn test - run: expo doctor ``` -### Test and build web every day at 08:00 - -You can also schedule jobs by using the cron syntax. -It can help to minimize the number of updates your users have to install. - -```yml -name: Expo Daily CI -on: - schedule: - - cron: 0 8 * * * -jobs: - ci: - name: Daily Continuous Integration - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 - with: - node-version: 14.x - - uses: expo/expo-github-action@v6 - with: - expo-version: 4.x - - run: yarn install - - run: yarn test - - run: expo build:web -``` - -### Authenticate using credentials - -Instead of using an access token, you can also authenticate using credentials. -This is only possible when Expo CLI is installed. - -```yml -name: Expo Publish -on: - push: - branches: - - main -jobs: - publish: - name: Install and publish - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 - with: - node-version: 14.x - - uses: expo/expo-github-action@v6 - with: - expo-version: 4.x - username: ${{ secrets.EXPO_CLI_USERNAME }} - password: ${{ secrets.EXPO_CLI_PASSWORD }} - - run: yarn install - - run: expo publish -``` - ## Things to know ### Automatic Expo login You need to authenticate for some Expo commands like `expo publish` and `expo build`. -This action gives you configuration options to keep your workflow simple. -You can choose if you want to authenticate using an `EXPO_TOKEN` or account credentials. -Under the hood, it uses the [`EXPO_CLI_PASSWORD`][link-expo-cli-password] environment variable to make credentials authentication as secure as possible. +This action can export the `EXPO_TOKEN` variable to access it in every step. -> Note, this action only uses your token or credentials to authenticate with Expo. It doesn't store these anywhere. +> Note, this action does not store the token anywhere. For every seperate job, you need to setup the token. ### Using the built-in cache You can opt-in to caching the installation, making it a lot faster. -Under the hood, it uses the [`@action/cache`][link-actions-cache-package] package to restore the Expo CLI installation. +Under the hood, it uses the [`@actions/cache`][link-actions-cache-package] package to restore the Expo CLI installation. This action generates a unique cache key for the OS, used packager, and exact version of the Expo CLI. -If you need more control over this cache, you can define a custom cache key with `expo-cache-key`. > Note, this cache will count towards your [repo cache limit][link-actions-cache-limit]. The Expo and EAS CLI are stored in different caches. @@ -312,11 +213,9 @@ You can disable this patch by setting the `patch-watchers` to `false`. [link-actions]: https://help.github.com/en/categories/automating-your-workflow-with-github-actions [link-actions-cache-limit]: https://github.com/actions/cache#cache-limits -[link-actions-cache-package]: https://www.npmjs.com/package/@actions/cache +[link-actions-cache-package]: https://github.com/actions/toolkit/tree/main/packages/cache [link-actions-node]: https://github.com/actions/setup-node [link-actions-secrets]: https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets [link-expo-cli]: https://docs.expo.dev/workflow/expo-cli/ -[link-expo-cli-password]: https://github.com/expo/expo-cli/blob/master/packages/expo-cli/src/accounts.ts#L88-L90 [link-expo-release-channels]: https://docs.expo.dev/distribution/release-channels/ [link-eas-cli]: https://github.com/expo/eas-cli#readme -[link-semver-playground]: https://semver.npmjs.com/ diff --git a/action.yml b/action.yml index 9534c812..a4e7c40f 100644 --- a/action.yml +++ b/action.yml @@ -1,7 +1,7 @@ --- name: Expo GitHub Action author: Cedric van Putten -description: Expo and EAS in GitHub Actions +description: Publish, build or manage your Expo app with GitHub Actions branding: icon: terminal color: gray-dark