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.
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.
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.
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.
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.
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 notegithub-action-await-vercelworks slightly differently, as it requires thedeployment-urlinput, whilewait-for-verceldidn't. But this ensures you await for the proper domain to be deployed, and is safe, even when multiple deployments are running in parallel.
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)
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).
| 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
timeoutto 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 > DEPLOYINGphases before reachingREADYorERRORstate. This might take quite some time (depending on your project), and increasing the timeout to600(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
10seconds is because we assume you'll call this action after the deployment has reachedBUILDINGstate, and the time it takes for Vercel to reachREADYorERRORfromBUILDINGis rather short.
This action forwards the Vercel API response as return value.
| Name | Description |
|---|---|
deploymentDetails |
JSON object. You can also use our TS type. |
In the below example, we show you how to:
- Step 1: Forward
VERCEL_DEPLOYMENT_URLas 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 asVERCEL_DEPLOYMENT_URLis set. - Step 2: Then, we use the
UnlyEd/github-action-await-vercel@v1GitHub Action, which waits for the deployment url to be ready. - 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.
This is a real-world use case example, from Next Right Now.
The workflow is a bit more complicated:
- All Vercel deployments for the team are fetched dynamically.
- Then the latest deployment url is extracted and used as
deployment-urlinput bygithub-action-await-vercel. - Once the deployment is ready, the
run-2e2-testsjob is started (using Cypress).
Learn how to enable logging, from within the
github-action-await-vercelaction.
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_DEBUGof valuetrue
Please see the official documentation for more information.
Enabling debugging using
ACTIONS_STEP_DEBUGwill also enable debugging for all other GitHub Actions you use that are using thecore.debugAPI.
We gladly accept PRs, but please open an issue first, so we can discuss it beforehand.
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_TOKENinstead, and use a dedicated Vercel account.
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.
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
@latestfor 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
@v1or@v1.2, but this is not always the best practice, see our explanations below.
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 theCOMMIT-SHAway, 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.
This project is being authored by:
- [Unly] Ambroise Dhenain (Vadorequest) (active)
- Hugo Martin (Demmonius) (active)
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 :
- https://twitter.com/UnlyEd
- https://www.facebook.com/UnlyEd/
- https://www.linkedin.com/company/unly
- Interested to work with us?
Tech tips and tricks from our CTO on our Medium page!
