# shouldideploy.today gates your deploy pipeline on a day of the week

> baires/shouldideploy is the source behind shouldideploy.today, a Next.js service that answers whether you should deploy today, with a JSON API, a badge endpoint and a CLI endpoint that returns HTTP 425 to stop a pipeline. It is a joke with a real API contract, and the joke is the whole rule engine.

**baires/shouldideploy** — Source of shouldideploy.today

- Repository: https://github.com/baires/shouldideploy
- Website: https://shouldideploy.today/
- Stars: 550 · Forks: 89
- Language: TypeScript
- License: WTFPL
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/baires-shouldideploy

## A site that answers one question and a Next.js service behind it

shouldideploy.today tells you whether you should deploy today, and baires/shouldideploy is the source code for it. The repository describes itself simply as the source of shouldideploy.today, and the site is a public service with a public API rather than a library you import. The audience is software teams who want a light, shared ritual around releasing, and the tone is deliberately comic. The README shows the tone in the sample response body, where the message field reads "It's Friday, better not deploy today." That single string is the clearest statement of the rule engine: the decision comes from the calendar, and the reasoning is a joke about it. The repository itself is a conventional TypeScript web project. The top level listing includes pages/, component/, helpers/ and locales/ for the application, plus next.config.js, tsconfig.json, jest.config.ts, eslint.config.mjs, vercel.json, .gitpod.yml and .snyk. The locales directory is what makes the site multi-language, and the helpers directory is where the date and time logic lives.

## The /api endpoint returns four keys and accepts three parameters

The API contract is small and explicit. A response is a JSON object with four keys: timezone, which is the zone used when evaluating the date and time; date, given in ISO format as YYYY-MM-DDTHH:mm:ss.sssZ; shouldideploy, a boolean; and message, a string with the reason or explanation. An example body from the README looks like this:

```json
{
  "timezone": "UTC",
  "date": "2023-03-31T00:00:00.000Z",
  "shouldideploy": false,
  "message": "It's Friday, better not deploy today."
}
```

Three optional parameters shape the answer. The tz parameter selects the timezone used for evaluation and defaults to UTC, taking IANA names such as America/New_York or Europe/London. The date parameter takes a YYYY-MM-DD string and defaults to the current date, which makes the endpoint testable and lets you pin a verdict for a past or future day. The lang parameter selects the language, supporting base languages en, es and pt plus regional variants such as es-AR, and it falls back to the base language and then to English when a variant is not found. That fallback chain matters for a badge embedded in a README: an unknown regional code degrades to English rather than to an error.

## The CLI endpoint is what actually stops a deployment

The integration that matters for CI is the /api/cli endpoint, and the README is explicit about its contract. It returns the text [shouldideploy] YES: with a reason and HTTP 200 when it is safe to deploy, and [shouldideploy] NO: with a reason and HTTP 425 when it is not. Since curl --fail exits non-zero on 4xx and 5xx responses, a single command with && turns the verdict into a gate. The README gives the exact line:

```bash
curl --fail -s "https://shouldideploy.today/api/cli?tz=America/New_York" && ./deploy.sh
```

The endpoint supports the same tz and lang parameters as the JSON API, so a pipeline and a badge can agree on timezone and language. The 425 status code is a nice touch for anyone reading CI logs, since a failure to deploy and a failure to reach the service are different HTTP results and can be told apart by a monitoring system. What you do with that signal is your own code, and the community project list shows the range of options people have built on top of the service, including a GitHub action that stops deployments, a Discord bot, a Slack command and a Visual Studio Code extension.

## The badge endpoint reuses shields.io style names

The badge is the lowest friction integration, aimed at a README rather than a pipeline. The README shows the markdown you would paste:

```markdown
![Should I Deploy?](https://shouldideploy.today/api/badge?tz=America/New_York)
```

The badge endpoint takes tz and lang, and its appearance is controlled by a style parameter whose supported values are the same as the ones shields.io uses: flat as the default, then flat-square, plastic, for-the-badge and social. So a repository can go from the default flat badge to a larger for-the-badge variant by changing one query string, and the badge can be given the same timezone as the pipeline gate. The top of the README shows the site's own badge with a flat style and the America/New_York timezone, which is a reasonable model to copy. The FOSSA status badge sits alongside it, and the FOSSA large badge in the License section indicates that dependency licensing is being tracked by that service for this project.

## A Next.js 16 project with Jest, ESLint and a husky pre-commit hook

package.json describes the runtime in detail. The application runs on Next.js 16 with React 19 and React DOM 19, and @vercel/og appears in the dependency list, alongside the hosting platform that the vercel.json configuration file points at. Most of the scripts section is worth quoting:

```json
  "scripts": {
    "precommit": "NODE_ENV=production lint-staged",
    "dev": "next -p 3000",
    "build": "next build",
    "start": "next start",
    "test": "jest",
    "lint": "eslint pages component helpers tests --fix"
  },
```

The lint script names the four source directories it covers, pages, component, helpers and tests, which is a fair map of the codebase, and a separate format script runs prettier-eslint across the project. Husky is configured with a pre-commit hook that runs format and then lint, and the test script runs Jest, with jest.config.ts and a tests/ directory in the tree. The project pins Node 22.x in its engines field, and TypeScript 6.0.2 is pinned through an overrides entry so that transitive dependencies cannot pull a different compiler. The.snyk file and the FOSSA badges point to a security and licence monitoring setup, and the licence itself is WTFPL.

## The limitation: a calendar heuristic, and a third party inside your release path

Two limitations deserve to be named plainly, and they come from different directions. The first is conceptual. The verdict is derived from the calendar and the timezone, nothing else. The API returns no information about your service, your change, your error rate or your last release, and the boolean is not a risk assessment in any sense. If a team starts treating a false as a signal that a release is unsafe, the tool is being used for something it does not do. The second is operational. Once you wire the CLI endpoint into a deploy job with curl --fail, the availability of a hosted third party becomes a precondition for your release process. If shouldideploy.today is unreachable, curl fails, the job fails, and a release is blocked by an outage of a joke website. That may be an acceptable trade for a team that wants the ritual, and an unacceptable one for a team whose release path must not depend on the public internet, and the decision is yours rather than the tool's. A related trap is the timezone parameter, since a wrong or missing tz shifts the evaluated day and can flip the verdict by a whole day.

## Calling the service versus computing the rule in your own pipeline

The alternative is to skip the service and implement the same check locally, either as a few lines in your pipeline script or as a small internal service. The difference in approach is straightforward. A local check has no external dependency, runs at full speed, cannot be affected by a third party outage and can be tailored to your own rules, for instance freezing releases on Friday afternoons only or blocking deploys on holiday dates. What it lacks is everything the hosted service gives you for free: a single shared definition of the rule across repositories, a public URL you can link from a wiki, a badge image, and a JSON API other tools can consume. The community project list shows how much value people find in that composability, since Discord, Slack, editor and CI integrations all build on the same public endpoint rather than reimplementing the rule. A sensible middle path for many teams is to keep the hosted service for the badge and the human-facing ritual, while the pipeline gate stays local so that a service outage cannot stop a release.

## Conclusion

Use shouldideploy.today when a team wants a shared, self-documenting rule about unlucky deploy days and a CI gate that fails with a clear reason, and when a hosted third party in the release path is acceptable. Do not use it as a risk signal for your service, and do not put it in a pipeline that must keep deploying during an outage of the site itself. Before wiring the CLI endpoint into a job, confirm that the timezone passed with ?tz= matches the calendar your team actually reasons about, because the whole verdict changes with that parameter.

## FAQ

### How do I block a deployment with shouldideploy.today?

The README gives a curl command against the /api/cli endpoint: curl --fail -s "https://shouldideploy.today/api/cli?tz=America/New_York" && ./deploy.sh. The endpoint returns HTTP 200 with a YES message when it is safe to deploy and HTTP 425 with a NO message when it is not, and curl --fail exits non-zero on that 4xx response.

### What parameters does the shouldideploy.today API accept?

The API accepts tz for the timezone used to evaluate the date, defaulting to UTC, date as a YYYY-MM-DD string defaulting to the current date, and lang for the response language, supporting en, es and pt plus regional variants such as es-AR and falling back to the base language or English.

### Can I embed a shouldideploy.today badge in my README?

Yes. The README shows the markdown image pointing at the badge endpoint with a tz parameter, and the badge supports a style parameter with the same values as shields.io, including flat as the default, flat-square, plastic, for-the-badge and social.

### How do I run shouldideploy locally for development?

The Getting Started section says to run npm i to install dependencies and npm run dev to start the dev server, and the dev script in package.json runs next -p 3000. A now dev command is offered if you need a local serverless function, and there is also an Open in Gitpod button for the repository.

## Sources

- [baires/shouldideploy on GitHub](https://github.com/baires/shouldideploy)
- [Issues](https://github.com/baires/shouldideploy/issues)
- [License: WTFPL](https://github.com/baires/shouldideploy/blob/master/LICENSE)
- [Project website](https://shouldideploy.today/)
- [README](https://github.com/baires/shouldideploy/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/baires-shouldideploy