# Run Upseam without the App

The `upseam/action` Action runs the same detector as the App inside your own
workflow. It needs no App, no account and no model, and with the `contents: read`
right it can only read your repository.

## The workflow

```yaml title=".github/workflows/upseam.yml"
name: upseam
on:
  schedule:
    - cron: "17 6 * * 1"
  workflow_dispatch:
permissions:
  contents: read
jobs:
  upseam:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false
      - uses: upseam/action@v0
```

**You should see** a Markdown report on the page of each run, under
**Summary**: **API changes affecting this repository**, with the deadlines
first, then each finding as `file:line` linked to the scanned commit with the
named successor, then the behavior changes under **Needs you**, and a coverage
line. When nothing is found, the report says so.

## Optional: one issue

Add `issues: write` to `permissions` and `with: { issue: true }` to the step to
keep one issue, **Upseam watches this repository**, up to date. It is edited
only when the findings change.

## Optional: fix pull requests with your model

With `fix: true` and your model key, the Action sends a simple breaking
change and the matched files to your model and opens one pull request per run.
It needs `contents: write` and `pull-requests: write`. Pin the Action to a full
commit SHA in this mode. The inputs and the safeguards are in the
[Action reference](https://github.com/upseam/action#readme).

## What leaves the runner

- **The free report:** nothing. The detector and the change data run on the
  runner, and the step gets no token. The only network use is the
  `actions/setup-node` step, which may download Node.js 22.
- **With `issue`:** calls to the GitHub API of your repository.
- **With `fix`:** GitHub API calls to look up, push and open a pull request,
  and calls to the model vendor you chose, with the change and the matched
  files. Likely secrets in those files are masked first; see
  [Secrets in your files](security.md#secrets-in-your-files).

The Action sends nothing to Upseam. See [Trust and your data](trust.md) and
[Security model](security.md).

## Your model key stays with you

The model key lives in your repository secrets and goes to the step of your
workflow. It reaches only the model vendor you chose, and Upseam never sees it.
Pass it with the `model-key` input, which hands it to the generate step only.

## How this differs from the App

|                     | Action                                         | App                                                                                |
| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- |
| When it runs        | On your `schedule` or trigger                  | When a vendor changes, a repository is added, you push, or Dependabot bumps an SDK |
| Result              | A report on the run page, optionally one issue | A pull request, a dashboard issue, approval in Slack or the issue                  |
| Pull requests       | Only with `fix`, one per run, with your model  | Written by your model or your own agent, after approval or automatically           |
| Slack and dashboard | No                                             | Yes                                                                                |
| Install             | A workflow file                                | One link, no YAML                                                                  |

Freshness of the report equals the frequency of your `schedule`. To get
event-driven pull requests, install the App: [Install the GitHub App](install.md).