Skip to content

Latest commit

 

History

History
292 lines (198 loc) · 15.1 KB

README.md

File metadata and controls

292 lines (198 loc) · 15.1 KB
Raw

Unly logo Maintainability Test Coverage

GitHub Action integration test GitHub Action build test Update Code Climate test coverage

Updates

When updating this GitHub Action, in order for changes to take effect when the action runs, you must run yarn build:gha-runtime (and maybe yarn build:once) and check in the changes.

GitHub Action - Await for a Vercel deployment (to be ready)

Code snippet example (minimal example)

jobs:
  wait-for-vercel-deployment:
    runs-on: ubuntu-22.04
    steps:
      - uses: UnlyEd/github-action-await-vercel@v1 # TODO best practices recommend to use a fixed version instead of @v1 for production usage (i.e: @v1.2.32)
        id: await-vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        with:
          deployment-url: nextjs-bzyss249z.vercel.app # TODO Replace by the domain you want to test
          timeout: 10 # Wait for 10 seconds before failing

      - name: Display deployment status
        run: "echo The deployment at ${{ fromJson(steps.await-vercel.outputs.deploymentDetails).url }} is ${{ fromJson(steps.await-vercel.outputs.deploymentDetails).readyState }}"

See the Examples section for more advanced examples.

What does this GitHub Action do?

It waits until a Vercel deployment domain is marked as "READY". (See readyState === 'READY')

You must know the domain url you want to await for and provide it as deployment-url input.

Why/when should you use it?

If you're using Vercel to deploy your apps, and you use some custom deployment pipeline using GitHub Actions, you might need to wait for a deployment to be ready before running other processes (e.g: Your end-to-end tests using Cypress).

For instance, if you don't wait for the deployment to be ready, then you might sometimes run your E2E tests suite against the Vercel's login page, instead of your actual deployment.

If your GitHub Actions sometimes succeeds but sometimes fails, then you probably need to await for the domain to be ready. This action might help doing so, as it will wait until the Vercel deployment is really ready, before starting your next GitHub Action step.

What else does this action do?

This action automatically forwards the Vercel API response, which contains additional information about the deployment. This can be quite helpful if you need them, and will avoid for you to have yet to make another call to the Vercel API.

Considered alternatives

1. wait-for-vercel

Before building our own GitHub Action, we tried using wait-for-vercel, but it didn't handle our use case properly.

Part of the issue is that it fetches all deployments for a team/project, which leads to extra issues when you have multiple deployments running in parallel. (as it won't necessarily fetch the domain you expect, it's a bit random when multiple deployments are running in parallel)

If you are/were using wait-for-vercel, please note github-action-await-vercel works slightly differently, as it requires the deployment-url input, while wait-for-vercel didn't. But this ensures you await for the proper domain to be deployed, and is safe, even when multiple deployments are running in parallel.

Getting started

To get started with this GitHub Action, you'll need:

  • To configure a Vercel secret, for the GitHub Action to be authorized to fetch your deployments
  • To provide a few required options (like, the domain you want to await for)

GitHub project configuration

You should declare those variables as GitHub Secrets.

Name Description
VERCEL_TOKEN Your vercel token is required to fetch the Vercel API on your behalf and get the status of your deployment. See usage in code

N.B: You don't have to use a GitHub Secret to provide the VERCEL_TOKEN. But you should do so, as it's a good security practice, because this way the token will be hidden in the logs (encrypted).

Action's API

Inputs

Name Required Default Description
deployment-url ✅ Deployment domain (e.g: my-app-hfq88g3jt.vercel.app, my-app.vercel.app, etc.).
timeout ✖️ 10 How long (in seconds) the action waits for the deployment status to reach either READY or ERROR state.

Tip: You might want to adapt the timeout to your use case.

  • For instance, if you're calling this action right after having triggered the Vercel deployment, then it'll go through INITIALIZING > ANALYZING > BUILDING > DEPLOYING phases before reaching READY or ERROR state. This might take quite some time (depending on your project), and increasing the timeout to 600 (10mn) (or similar) is probably what you'll want to do in such case, because you need to take into account the time it'll take for Vercel to deploy.
  • The default of 10 seconds is because we assume you'll call this action after the deployment has reached BUILDING state, and the time it takes for Vercel to reach READY or ERROR from BUILDING is rather short.

Outputs

This action forwards the Vercel API response as return value.

Name Description
deploymentDetails JSON object. You can also use our TS type.

Examples

1. Manually set a hardcoded Vercel deployment url as deployment-url (as GitHub env variable)

In the below example, we show you how to:

  1. Step 1: Forward VERCEL_DEPLOYMENT_URL as an ENV variable, using >> $GITHUB_ENV" which stores the value into the GitHub Actions env vars. Of course, you might do it differently. It doesn't really matter as long as VERCEL_DEPLOYMENT_URL is set.
  2. Step 2: Then, we use the UnlyEd/github-action-await-vercel@v1 GitHub Action, which waits for the deployment url to be ready.
  3. Step 3: Finally, we show an example on how to read the deployment's information returned by the Vercel API (which have been forwarded).
on:
  pull_request:
  push:
    branches:
      - main

jobs:
  wait-for-vercel-deployment:
    runs-on: ubuntu-22.04
    steps:
      - name: Retrieve deployment URL (example on how to set an ENV var)
        run: "echo VERCEL_DEPLOYMENT_URL=nextjs-bzyss249z.vercel.app >> $GITHUB_ENV"

      - uses: UnlyEd/github-action-await-vercel@v1 # TODO best practices recommend to use a fixed version instead of @v1 for production usage (i.e: @v1.2.32)
        id: await-vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        with:
          deployment-url: ${{ env.VERCEL_DEPLOYMENT_URL }}
          timeout: 10 # Wait for 10 seconds before failing

      - name: Displays the deployment name (example on how to read information about the deployment)
        run: "echo The deployment at ${{ fromJson(steps.await-vercel.outputs.deploymentDetails).url }} is ${{ fromJson(steps.await-vercel.outputs.deploymentDetails).readyState }}"

Check the documentation to see what information deploymentDetails contains.

2. Dynamically resolve the Vercel deployment url

This is a real-world use case example, from Next Right Now.

The workflow is a bit more complicated:

  1. All Vercel deployments for the team are fetched dynamically.
  2. Then the latest deployment url is extracted and used as deployment-url input by github-action-await-vercel.
  3. Once the deployment is ready, the run-2e2-tests job is started (using Cypress).

See code

Advanced debugging

Learn how to enable logging, from within the github-action-await-vercel action.

How to enable debug logs

Our GitHub Action is written using the GitHub Actions native core.debug API.

Therefore, it allows you to enable logging whenever you need to debug what's happening within our action.

To enable debug mode, you have to set a GitHub Secret, such as:

  • ACTIONS_STEP_DEBUG of value true

Please see the official documentation for more information.

Enabling debugging using ACTIONS_STEP_DEBUG will also enable debugging for all other GitHub Actions you use that are using the core.debug API.

Contributing

We gladly accept PRs, but please open an issue first, so we can discuss it beforehand.

Working locally

Configuring local tests

You'll need to create a .env.test file based on .env.test.example. Then, you'll need to create and add your own Vercel token there (VERCEL_TOKEN), and change the VERCEL_DOMAIN being tested to a domain you own (any Vercel domain will do).

Local tests rely on the environment variable VERCEL_TOKEN, and must use your own Vercel account and credentials.

Integration tests (on GitHub) rely on the GitHub secret VERCEL_TOKEN instead, and use a dedicated Vercel account.

Changelog

Changelog

Releases versioning

We follow Semantic Versioning. (major.minor.patch)

Our versioning process is completely automated, any changes landing on the main branch will trigger a new release.

  • (MAJOR): Behavioral change of the existing API that would result in a breaking change.
    • E.g: Removing an input, or changing the output would result in a breaking change and thus would be released as a new MAJOR version.
  • (MINOR): Behavioral change of the existing API that would not result in a breaking change.
    • E.g: Adding an optional input would result in a non-breaking change and thus would be released as a new MINOR version.
  • Patch: Any other change.
    • E.g: Documentation, tests, refactoring, bug fix, etc.

Releases versions:

The examples above use an auto-updated major version tag (@v1). It is also possible to use the @latest tag. (RC stands for "Release candidate", which is similar to a Beta version)

While those options can be useful, we intend to give some "production-grade" best practices.

  • Do NOT use @latest for production, ever. While only "supposed-to-be-stable" versions will be tagged as @latest, it could harbor bugs nonetheless.
  • You can use auto-upgrading major version, such as @v1 or @v1.2, but this is not always the best practice, see our explanations below.

Special tags and best practices for production-grade apps

Here are a few useful options you can use to pin a more-or-less specific version of our GitHub Action, alongside some " production-grade" best practices.

  • @{COMMIT-SHA}, e.g: @1271dc3fc4c4c8bc62ba5a4e248dac95cb82d0e3, recommended for all production-grade apps, it's the only truly safe way to pinpoint a version that cannot change against your will (SAFEST)
  • @{MAJOR}-{MINOR}-{PATCH}, e.g: @v1.2.31, while not as safe as the COMMIT-SHA way, it's what most people use ( SAFER)
  • @{MAJOR}, e.g: @v1, can be used on production, but we do not advise to do so (SAFE-ISH)
  • @{MAJOR}-rc, e.g: @v1-rc, reserved for development mode, useful when debugging on a specific prerelease version (UNSAFE)
  • @{MAJOR}.{MINOR}, e.g: @v1.2, can be used on production, but we do not advise to do so (SAFE-ISH)
  • @{MAJOR}.{MINOR}-rc, e.g: @v1.2-rc, reserved for development mode, useful when debugging on a specific prerelease version (UNSAFE)
  • @latest, reserved for development mode, useful when debugging (UNSAFE)

"But, what is the issue with the @{MAJOR}-{MINOR}-{PATCH} way to pin a specific version"?

Well, if this repository gets hacked by a 3rd party, they can easily change all Git tags to a different commit, which could contain malicious code.

That's why pinning a specific commit SHA is the only truly safe option. This way, the code you're using cannot be changed against your will.

Most people won't care about this and will use a MAJOR version tag instead anyway, such as @v1. It's common, but not often the best practice.

It all comes down to the risks you're ready to take, and it's up to you to decide what's best in your situation.

License

MIT

Vulnerability disclosure

See our policy.

Contributors and maintainers

This project is being authored by:

[ABOUT UNLY] Unly logo

Unly is a socially responsible company, fighting inequality and facilitating access to higher education. Unly is committed to making education more inclusive, through responsible funding for students.

We provide technological solutions to help students find the necessary funding for their studies.

We proudly participate in many TechForGood initiatives. To support and learn more about our actions to make education accessible, visit :

Tech tips and tricks from our CTO on our Medium page!

TECHFORGOOD #EDUCATIONFORALL