https://github.com/unlyed/github-action-await-vercel
GitHub Action - Awaits a Vercel deployment to be ready
https://github.com/unlyed/github-action-await-vercel
Last synced: 9 months ago
JSON representation
GitHub Action - Awaits a Vercel deployment to be ready
- Host: GitHub
- URL: https://github.com/unlyed/github-action-await-vercel
- Owner: UnlyEd
- License: mit
- Created: 2020-11-27T15:20:56.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-11T12:26:39.000Z (about 2 years ago)
- Last Synced: 2025-09-15T00:39:59.938Z (9 months ago)
- Language: TypeScript
- Homepage: https://github.com/marketplace/actions/await-for-vercel-deployment
- Size: 29.7 MB
- Stars: 35
- Watchers: 3
- Forks: 9
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://codeclimate.com/github/UnlyEd/github-action-await-vercel/maintainability)
[](https://codeclimate.com/github/UnlyEd/github-action-await-vercel/test_coverage)
# GitHub Action - Await for a Vercel deployment (to be ready)
## Code snippet example (minimal example)
```yaml
jobs:
wait-for-vercel-deployment:
runs-on: ubuntu-latest
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
poll-interval: 1 # Wait for 1 second before each retry
- 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](#examples) for more advanced examples._
## What does this GitHub Action do?
It waits until a Vercel deployment domain is marked as "READY". _(See [`readyState === 'READY'`](https://vercel.com/docs/api#endpoints/deployments/create-a-new-deployment/response-parameters))_
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](https://www.cypress.io/))_.
> 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](https://vercel.com/docs/api#endpoints/deployments/get-a-single-deployment/response-parameters).
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`](https://github.com/mskelton/wait-for-vercel-action)
Before building our own GitHub Action, we tried using [`wait-for-vercel`](https://github.com/mskelton/wait-for-vercel-action), 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](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets)**.
Name | Description
--- | ---
`VERCEL_TOKEN` | Your [vercel token](https://vercel.com/account/tokens) is required to fetch the Vercel API on your behalf and get the status of your deployment. [See usage in code](https://github.com/UnlyEd/github-action-await-vercel/search?q=VERCEL_TOKEN)
> _**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)](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets)._
### 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`|Duration (in seconds) the action waits for the deployment status to reach either `READY` or `ERROR` state.
`poll-interval`|✖️|`1`|Duration (in seconds) the action waits in between polled Vercel API requests.
> **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.
> **Tip**: `poll-interval` prevents spamming Vercel's API such that the number of requests stays within their rate limits. [Vercel allows](https://vercel.com/docs/concepts/limits/overview#rate-limits) 500 deployment retrievals every minute, and the 1-second default value will allow for about 8 concurrent executions of this GitHub Action.
#### Outputs
This action forwards the [Vercel API response](https://vercel.com/docs/api#endpoints/deployments/get-a-single-deployment/response-parameters) as return value.
Name | Description
--- | ---
`deploymentDetails` | [JSON object](https://vercel.com/docs/api#endpoints/deployments/get-a-single-deployment/response-parameters). You can also use our [TS type](./blob/main/src/types/VercelDeployment.ts).
## 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.
1. **Step 2**: Then, we use the `UnlyEd/github-action-await-vercel@v1` GitHub Action, which waits for the deployment url to be ready.
1. **Step 3**: Finally, we show an example on how to read the deployment's information returned by the Vercel API (which have been forwarded).
```yaml
on:
pull_request:
push:
branches:
- main
jobs:
wait-for-vercel-deployment:
runs-on: ubuntu-latest
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`](https://vercel.com/docs/api#endpoints/deployments/get-a-single-deployment/response-parameters) contains.
### 2. Dynamically resolve the Vercel deployment url
This is a real-world use case example, from [Next Right Now](https://github.com/UnlyEd/next-right-now).
The workflow is a bit more complicated:
1. All Vercel deployments for the team are fetched dynamically.
1. Then the latest deployment url is extracted and used as `deployment-url` input by `github-action-await-vercel`.
1. Once the deployment is ready, the `run-2e2-tests` job is started (using Cypress).
[See code](https://github.com/UnlyEd/next-right-now/blob/v4.0.12-v2-mst-aptd-at-lcz-sty/.github/workflows/deploy-vercel-staging.yml#L174-L236)
---
# 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](https://github.com/actions/toolkit/blob/main/docs/action-debugging.md#step-debug-logs).
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**](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets), such as:
- `ACTIONS_STEP_DEBUG` of value `true`
Please see [the official documentation](https://github.com/actions/toolkit/blob/main/docs/action-debugging.md#how-to-access-step-debug-logs) 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](./CHANGELOG.md)
---
# 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](../../releases).
- `(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](./LICENSE)
---
# Vulnerability disclosure
[See our policy](https://github.com/UnlyEd/Unly).
---
# Contributors and maintainers
This project is being authored by:
- [Unly] Ambroise Dhenain ([Vadorequest](https://github.com/vadorequest)) **(active)**
- Hugo Martin ([Demmonius](https://github.com/demmonius)) **(active)**
---
# **[ABOUT UNLY]**
> [Unly](https://unly.org) 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?](https://jobs.zenploy.io/unly/about)
Tech tips and tricks from our CTO on our [Medium page](https://medium.com/unly-org/tech/home)!
# TECHFORGOOD #EDUCATIONFORALL