> ## Documentation Index
> Fetch the complete documentation index at: https://developers.reintersect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Action

> Deploy from GitHub with reintersect/deploy@v1. It authenticates with OIDC, so your repository stores no Reintersect secret, and deploys previews for pull requests and production from the default branch.

> Reintersect apps are in developer preview. Names and limits can still change before general
> release.

The `reintersect/deploy@v1` Action checks and deploys your app. It authenticates with GitHub's OpenID
Connect token, so your repository holds no Reintersect secret.

| Run | What the Action does |
| - | - |
| Pull request | Checks, deploys a preview and comments on the pull request with a playground link. |
| Push to the default branch, or a tag | Checks and deploys a production version. |
| Manual run (`workflow_dispatch`) | Production on the default branch or a tag; a preview anywhere else. |
| Pull request from a fork | Posts a notice and skips the deploy: GitHub gives forks no OIDC token. |

For a hosted app a deploy uploads the bundle. For a self-hosted app it syncs the manifest and
endpoint; deploy your server in the same workflow, before this step.

## Set up

<Steps>
  <Step title="Trust the repository">
    In **Settings → Developer → Apps → your app → Versions → Deploy from GitHub**, add the repository
    (`owner/name`). Optionally limit it to a branch or tag (a branch name, or a full ref such as
    `refs/tags/v1.2.0`), a GitHub environment, or both. An app trusts up to 10 repositories.

    Reintersect only issues deploy tokens to workflow runs from a trusted repository that match its
    ref and environment, when set. For pull requests, the ref is the pull request's base branch.
    If the repository isn't visible to your workspace's GitHub connection, the dashboard warns that
    anyone who can push to it can deploy the app, and asks you to confirm.
  </Step>

  <Step title="Add the workflow">
    Projects created with `npm create reintersect@latest` already include
    `.github/workflows/reintersect.yml`:

    ```yaml .github/workflows/reintersect.yml theme={null}
    name: Reintersect

    on:
      push:
        branches: [main]
      pull_request:
      workflow_dispatch:

    permissions:
      contents: read
      id-token: write
      pull-requests: write

    concurrency:
      group: reintersect-${{ github.ref }}
      cancel-in-progress: ${{ github.event_name == 'pull_request' }}

    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v6
          - uses: actions/setup-node@v6
            with:
              node-version: 24
              cache: ${{ hashFiles('package-lock.json') != '' && 'npm' || '' }}
          - if: hashFiles('package-lock.json') != ''
            run: npm ci
          - if: hashFiles('package-lock.json') == ''
            run: npm install
          - uses: reintersect/deploy@v1
            with:
              app-id: ${{ vars.REINTERSECT_APP_ID }}
    ```

    This is the npm version; the pnpm and Bun versions install the same way. Dependencies install
    frozen to the lockfile when one exists (`npm ci`, `pnpm install --frozen-lockfile`,
    `bun install --frozen-lockfile`), and unfrozen when there is none yet, so the first push of a new
    project works.

    Set the repository variable `REINTERSECT_APP_ID` to your app's id. `id-token: write` lets the job
    request a GitHub OIDC token, which the Action exchanges for a deploy token that lasts 15 minutes.
    `pull-requests: write` lets it comment. The Action runs the `reintersect` CLI from your project's
    dependencies, so install them first.
  </Step>

  <Step title="Set environment values">
    Set environment values for the preview and production environments with `reintersect env set` or
    in **Settings → Developer → Apps → your app → Environment**. A deploy fails if a required variable
    has no value in the target environment.
  </Step>
</Steps>

## Inputs

| Input | Required | Default | Description |
| - | - | - | - |
| `app-id` | Yes | none | The app id from Settings → Developer → Apps. |
| `working-directory` | No | `.` | The folder that holds the app's `package.json`, relative to the repository root. |
| `preview` | No | `auto` | `auto` deploys production for pushes and manual runs on the default branch or a tag, and a preview otherwise. `true` always deploys a preview. `false` asks for production on any push or manual run, and Reintersect accepts it only from the branch or tag pinned on the repository's trust (without a pin, the default branch and tags). Other events fail. |
| `base-url` | No | `https://api.reintersect.com` | The Reintersect API origin, also the audience of the OIDC token. |
| `comment` | No | `"true"` | Comment the preview's playground link on pull requests. |
| `github-token` | No | `${{ github.token }}` | Token for the pull request comment. Needs `pull-requests: write`. |

## Outputs

| Output | Description |
| - | - |
| `version-id` | The id of the deployed version. |
| `playground-url` | The playground link for the version. Empty when there is none. |

## When a run may deploy production

Reintersect decides on its side, from the OIDC token, and the Action can't override it:

* Only `push` and `workflow_dispatch` runs can deploy production. Pull request runs are always
  previews.
* With a branch or tag pinned, only that exact ref deploys production.
* Without a pinned ref ("Any branch"), only the repository's default branch and tags deploy
  production; other branches get previews. If Reintersect can't tell the default branch, the
  repository is preview-only.
* The rule is checked again every time the deploy token is used.

A run that asks for production but may only deploy previews fails with a message that says so.

## Pull request previews

Every pull request push deploys a preview version and updates one comment on the pull request with
the version, its status and a link to the playground. Pull request previews never move any install,
including development installs; reviewers open the link and pick **Run vN** in the playground to try
it on their own development install. See [Previews and versions](/hosting/previews).

## What the Action checks

Before deploying, the Action runs `reintersect check --json` signed in with the deploy token, so the
full validator runs. Errors fail the job and every finding becomes an annotation on the file and line
it points at. See [`reintersect check`](/reference/cli#check) for the list.

## Production deploys

A production deploy publishes the new version. Installs move to it when it asks for no more access
than they approved; otherwise they wait for an admin, and the Action's log says some installs need
review. See [Publishing new versions](/concepts/install-and-consent#publishing-new-versions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.