How do we connect Speakeasy to GitHub so SDK updates are opened as pull requests on every spec change?

Quick Answer: Connect Speakeasy to GitHub by pointing your SDK repo in gen.yaml, authenticating GitHub, and wiring CI so every OpenAPI spec change runs speakeasy generate and opens a pull request with the updated SDK.

Frequently Asked Questions

How does Speakeasy open SDK update pull requests on every spec change?

Short Answer: Speakeasy watches your OpenAPI spec in CI, regenerates the SDK, and pushes changes as GitHub pull requests into your SDK repo whenever the spec changes.

Expanded Explanation:
The workflow is: your OpenAPI spec is the source of truth → a CI job runs speakeasy generate when that spec changes → Speakeasy updates the SDK code in your SDK repository → GitHub sees file changes and a bot user (or GitHub App/CI token) opens a pull request. You review, run tests, and merge like any other change.

This removes the “remember to update the SDK” tax. Instead of manually touching 3–7 language repos, you let Speakeasy do the regeneration and PR wiring so “APIs change fast. Your SDKs should too” is actually enforced in your release pipeline.

Key Takeaways:

• The trigger is a change to your OpenAPI spec, not manual SDK work.
• PRs are created by your CI using Speakeasy, targeting your existing GitHub SDK repo(s).

---

What’s the process to connect Speakeasy to GitHub for automated SDK PRs?

Short Answer: Configure your SDK repo in gen.yaml, authenticate GitHub access, and add a CI workflow that runs speakeasy generate and pushes branches/PRs on spec changes.

Expanded Explanation:
You connect Speakeasy to GitHub at two levels:

1. Configuration: In your API repo, you define how SDKs are generated and where they live (GitHub org/repo, paths, languages) using Speakeasy’s OpenAPI-native config (e.g., gen.yaml or similar). This tells Speakeasy how to turn your spec into code.
2. Automation: In CI (GitHub Actions, CircleCI, etc.), you run the Speakeasy CLI whenever your OpenAPI spec changes. The job regenerates the SDK, commits the diff, and uses a GitHub token to open a PR into your SDK repo.

From there, it’s a standard Git flow: reviewers, tests, branch protections. The only difference is that the changes are machine-generated and stay in lockstep with the spec.

Steps:

1. Install the Speakeasy CLI in your API repo (e.g., brew install speakeasy-api/tap/speakeasy) and run speakeasy quickstart to scaffold config from your OpenAPI spec.
2. Point generation at your GitHub SDK repo(s) in your config (e.g., define language targets, output paths, and repos; follow the “Github setup guide” to wire repo URLs, branches, and auth).
3. Add a CI workflow that:
   • Runs on OpenAPI spec changes.
   • Executes speakeasy generate (or equivalent).
   • Commits changes and opens/updates a pull request in GitHub with the regenerated SDK.

---

What’s the difference between local SDK generation and CI-based PR automation?

Short Answer: Local generation lets you iterate manually; CI-based PR automation turns every OpenAPI spec change into a reviewable GitHub pull request without manual steps.

Expanded Explanation:
When you run Speakeasy locally (e.g., via speakeasy quickstart or speakeasy generate), you’re in “craft” mode—experimenting with SDK output, trying overlays, and validating that the generator produces idiomatic, type-safe code for each language.

CI-based automation is “operations” mode. Once you’re happy with the SDK shape, you wire CI so that every push to your spec branch triggers generation and PR creation. No one has to remember to re-run the generator; it just happens on every change. That’s the gap between “we have a generator” and “we actually ship with every commit.”

Comparison Snapshot:

• Local-only: Manual speakeasy generate, SDKs updated when someone remembers. Good for initial tuning and experiments.
• CI-based PRs: Automatic runs triggered by spec changes, opening PRs in GitHub consistently. Good for ongoing maintenance and release hygiene.
• Best for: Teams that want SDKs to update reliably with the API, enforced by CI instead of tribal knowledge.

---

What do we need to implement GitHub PR automation with Speakeasy?

Short Answer: You need a clean OpenAPI spec, a GitHub-hosted SDK repo, the Speakeasy CLI plus config, and a CI workflow with a GitHub token that can push branches and open pull requests.

Expanded Explanation:
Speakeasy is OpenAPI-native, so it assumes your API is described in a spec file that you treat like code. From there, you configure where SDKs live and how they’re built, and your CI handles the “trigger on change, regenerate, open PR” loop. The only extra ingredient is authentication: CI needs a GitHub token (or App) with permissions to create branches and pull requests in your SDK repo.

Once that’s in place, you get a predictable pipeline:

• Update OpenAPI → CI runs Speakeasy → SDKs regen → GitHub PRs open → you review and merge.
• No bespoke scripts per language, no drift across SDKs, and no manual copy-paste of generated artifacts.

What You Need:

• A maintained OpenAPI spec checked into your repo (the source of truth for your API).
• GitHub repos for SDKs (one per language or mono-repo), configured following Speakeasy’s GitHub setup guide so generation targets are clear.
• CI environment (e.g., GitHub Actions) with:
  • Speakeasy CLI installed.
  • Access to your spec and SDK repos.
  • A GitHub token or App credentials that can open pull requests.

---

How does this strategy help our release process and developer experience?

Short Answer: By connecting Speakeasy to GitHub for auto-opened PRs, you get SDKs that always match your API, faster releases without manual boilerplate, and a consistent DX across languages.

Expanded Explanation:
Manual SDK work doesn’t scale: APIs change fast, and every language you support multiplies the maintenance tax. By wiring Speakeasy into GitHub so that every spec change creates a pull request, you’re essentially turning “keep SDKs up to date” into a CI-enforced invariant.

That shows up as real outcomes: teams report they “accelerated our release schedule without sacrificing code quality” because regeneration is automatic, but still gated by PR review and tests. You keep your existing workflows—branch protections, code owners, CI checks—while offloading generation to a tool that understands your OpenAPI and produces idiomatic, type-safe clients for TypeScript, Python, Go, Java, C#, PHP, and more.

Over time, this is how you avoid drift and broken integrations: one source of truth (the spec), one generator (Speakeasy), and GitHub PRs as the review surface for every change.

Why It Matters:

• Reduced maintenance tax: No more hand-maintaining SDKs; updates ride along with every spec change via PRs.
• Consistent, trustworthy SDKs: Developers can rely on SDKs being current and type-safe, which shortens integration time and reduces production bugs.

---

Quick Recap

Connecting Speakeasy to GitHub so SDK updates are opened as pull requests on every spec change is about operationalizing your OpenAPI spec. You configure generation (via gen.yaml and GitHub setup), wire CI to run Speakeasy on spec changes, and let GitHub PRs become the place where SDK evolution is reviewed and merged. The result: SDKs in multiple languages that stay in sync with your API, released on every commit instead of every few weeks when someone finds the time.

Next Step

Get Started