# Set up Upseam in this repository These are instructions for a coding agent, such as Claude Code or Codex, working in a user's repository. Follow them in order. - Explain each step to the user and ask before you create, change or commit any file. - Do not download or run anything from the internet. Every step reads files in this repository or writes small text files in it. - Never ask the user to paste an API key or other secret into the chat. Upseam is a GitHub App. It watches the vendor APIs this repository calls and, optionally, API contracts this repository publishes. When one of them changes, it opens a pull request with the fix for mechanical changes and flags the rest. A person reviews and merges every pull request. Most setup happens in GitHub and on the Upseam settings page; the repository needs at most one config file and, for one of the two generation methods, one workflow. ## 1. Inspect the repository Tell the user what you find. - **Languages.** Upseam reads JavaScript, TypeScript and Python: SDKs declared in `package.json`, `requirements*.txt`, `pyproject.toml` or `Pipfile`; lockfiles give the versions. - **Vendor SDKs Upseam supports.** Look for these packages: | Provider id | JavaScript / TypeScript | Python | | ----------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `stripe` | `stripe` | `stripe` | | `shopify` | `@shopify/shopify-api`, `@shopify/shopify-app-react-router`, `@shopify/shopify-app-remix`, `@shopify/admin-api-client` | `ShopifyAPI` | | `openai` | `openai`, `@ai-sdk/openai`, `@langchain/openai` | `openai`, `langchain-openai` | | `anthropic` | `@anthropic-ai/sdk`, `@ai-sdk/anthropic`, `@langchain/anthropic` | `anthropic`, `langchain-anthropic` | | `gemini` | `@google/genai`, `@google/generative-ai`, `@ai-sdk/google`, `@langchain/google-genai` | `google-genai`, `google-generativeai`, `langchain-google-genai` | | `mistral` | `@mistralai/mistralai`, `@ai-sdk/mistral`, `@langchain/mistralai` | `mistralai`, `langchain-mistralai` | | `hubspot` | `@hubspot/sdk`, `@hubspot/api-client` | `hubspot-sdk`, `hubspot-api-client` | | `github` | `octokit`, `@octokit/rest`, `@octokit/core`, `@octokit/graphql`, `@octokit/request` | `PyGithub` | | `twilio` | `twilio` | `twilio` | - **MCP servers Upseam supports.** Look in the MCP configs at the repository root (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.gemini/settings.json`, `.codex/config.toml`, `opencode.json` and similar) for these servers: | Provider id | Server | Recognised by | | --------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- | | `github-mcp` | GitHub MCP server | URL `https://api.githubcopilot.com/mcp` or a path under it, image `ghcr.io/github/github-mcp-server`, command `github-mcp-server` | | `microsoft-learn-mcp` | Microsoft Learn MCP server | URL `https://learn.microsoft.com/api/mcp` | A server also counts when its URL appears in source code of a repository that depends on an MCP SDK (`@modelcontextprotocol/sdk` in `package.json`, or the Python `mcp` package). For these servers Upseam checks tool names in the MCP configs, in Claude Code permission rules, in agent instructions (`AGENTS.md`, `CLAUDE.md` and similar) and in MCP SDK calls. - **API contracts this repository publishes.** OpenAPI files (`.yaml`, `.yml` or `.json`) and GraphQL schemas (`.graphql`, `.graphqls`, `.gql`) that describe an API other repositories call. If you find none of these, tell the user that Upseam has nothing to watch in this repository yet, and stop. ## 2. Write `.github/upseam.yml` only if it is needed Upseam works without this file. Create it only when the user wants one of the two settings below. The file accepts exactly two top-level fields, `internal` and `ignore`; any other field is an error. ```yaml internal: - spec: api/openapi.yaml consumers: [acme/web, acme/mobile] ignore: providers: [twilio] paths: [legacy/**, "**/*.test.ts"] ``` - **`internal`**, only if this repository publishes a contract. `spec` is the path of one contract file relative to the repository root (no wildcards). `consumers` lists 1 to 10 repositories as `owner/repo` that call this API. Ask the user for them; do not guess. They must be installed in the same Upseam installation. When the contract changes on the default branch, Upseam opens a pull request in each affected consumer. - **`ignore.providers`**: provider ids from the tables above that Upseam should not watch here. - **`ignore.paths`**: up to 20 path patterns relative to the repository root. `*` and `?` match within one path segment, `**` as a whole segment matches any depth, and a directory name ignores everything below it. Negation with `!`, `[]`, `{}`, a leading or trailing `/`, and `.` or `..` segments are errors. Show the user the complete file and explain each entry before you commit it. Approval mode, model and Slack are not set in this file. ## 3. Choose how fixes are written Upseam writes a fix with a model the user chooses. Ask the user which of the two methods they want. **(a) Upseam calls your model.** Nothing more is needed in the repository. After installing the App, the user connects a model on the Upseam settings page: Anthropic, OpenAI or any OpenAI-compatible endpoint. The key is entered there by the user, not in the repository or the chat. **(b) Your GitHub Actions write the fix.** The model key stays in the repository's Actions secrets. Add this workflow as `.github/workflows/upseam-generate.yml` on the default branch: ```yaml name: upseam-generate on: repository_dispatch: types: [upseam-generate] permissions: contents: write concurrency: upseam-generate-${{ github.event.client_payload.group }} jobs: generate: runs-on: ubuntu-latest steps: - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0 with: ref: ${{ github.event.client_payload.sha }} - uses: upseam/action@<40-character commit SHA> # v0.x env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ``` - Pin `upseam/action` to the full commit SHA of a published release that the user confirms, never to a branch or a tag. If no release of `upseam/action` is published yet, tell the user that method (b) is not available yet and use method (a) or stop here. - The Action uses Anthropic by default. For an OpenAI or OpenAI-compatible model, add `with:` `vendor: openai`, `model: ` and, for a compatible endpoint, `base-url: `, and use `OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}` instead. The vendor and model must match what the user names on the settings page. - The user adds the secret themselves in the repository settings on GitHub (Settings → Secrets and variables → Actions). Do not ask for its value. - On the Upseam settings page the user then chooses "Generate in my GitHub Actions" and names the vendor (`anthropic` or `openai`) and the model. - Upseam sends this workflow only the group key, commit ids, the proposal id and change ids, never code or keys. Contract changes of this repository's own APIs are not generated this way. ## 4. Tell the user what is left A coding agent cannot do these steps. List them for the user: 1. Install the Upseam GitHub App and choose this repository: https://github.com/apps/app-slug-tbd/installations/new 2. GitHub then opens the Upseam setup page. From there, open the settings. 3. Connect a model (method a) or choose GitHub Actions generation (method b). 4. Optionally connect Slack and pick a channel for reports and approvals. New repositories start in "ask" mode: Upseam reports what it found and waits for approval, in Slack or in its dashboard issue, before it writes a fix. The user can switch a repository to "auto" on the settings page.