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 wiring your SDK repo and OpenAPI spec into a Speakeasy workflow, then running the generated GitHub Actions (or your CI of choice). Every spec change triggers speakeasy generate, which opens an automated pull request with the updated SDK.

Frequently Asked Questions

How does Speakeasy open GitHub pull requests for SDK updates on every spec change?

Short Answer: Speakeasy uses your OpenAPI spec as the source of truth and a CI workflow (usually GitHub Actions) that runs speakeasy generate on changes, then automatically opens a pull request against your SDK repo.

Expanded Explanation:
The core pattern is: “spec changes in → SDK pull requests out.” You connect Speakeasy to your GitHub repos once, then let CI handle the loop. When your OpenAPI spec changes (in its own repo or in the same repo as your service), your CI workflow runs Speakeasy. Speakeasy regenerates the SDK code, docs, and supporting files, and your CI job commits those updates to a branch and opens a pull request.

That PR becomes the review surface for SDK changes. CI can run tests, your team can review diffs, and once merged, your SDK stays in lockstep with your API. No more manual “remember to update the SDK later” work; the pull request becomes the forcing function that keeps things honest.

Key Takeaways:

• Speakeasy watches your OpenAPI spec via CI, not by “polling” GitHub directly.
• A CI workflow runs speakeasy and opens a PR whenever the spec changes.

---

What’s the process to connect Speakeasy, GitHub, and my SDK repo?

Short Answer: Install the Speakeasy CLI, generate your SDK locally once, push it to GitHub, and then wire up a GitHub Actions workflow that regenerates and opens pull requests on every spec change.

Expanded Explanation:
You connect the dots in three layers: the Speakeasy CLI, your SDK repo, and CI. First, you install Speakeasy and run the quickstart against your OpenAPI spec to generate an SDK locally. That initial run creates the SDK structure plus a configuration file (gen.yaml or similar) that encodes how to build that artifact.

Next, you push the generated SDK to GitHub as its own repo (or as a directory in a mono-repo). Finally, you add a GitHub Actions workflow that runs speakeasy generate whenever the spec changes. The workflow commits any updated SDK code to a branch and opens a pull request. From that point on, your API engineers just merge spec changes; CI and Speakeasy handle the downstream SDK churn.

Steps:

1. Install the Speakeasy CLI
   • Example: brew install speakeasy-api/tap/speakeasy
2. Run the Speakeasy quickstart against your OpenAPI spec
   • Generate the SDK once locally and confirm it builds/tests.
3. Push the SDK to GitHub and add a CI workflow
   • Commit the generated SDK to a repo and configure GitHub Actions to run speakeasy generate and open PRs on spec changes.

---

Should my SDK live in the same repo as my API spec or in a separate GitHub repo?

Short Answer: Both work; Speakeasy supports mono-repos and split repos. Separate repos are cleaner for consumers, while mono-repos are convenient for tightly coupled services.

Expanded Explanation:
You choose the layout that matches your release model. In a mono-repo, your OpenAPI spec, service code, and SDK live together. A single GitHub Actions workflow can regenerate SDKs whenever the spec or implementation changes. This simplifies dependency management but can create noise if your app and SDK evolve on different cadences.

In a separate SDK repo, the SDK is versioned and released independently. Your main service repo can push spec changes or artifacts, and a dedicated workflow in the SDK repo (or a cross-repo workflow) regenerates and opens pull requests there. This matches how most consumers think about SDKs: as their own package with its own versioning and changelog.

Comparison Snapshot:

• Option A: Mono-repo (API + spec + SDK)
  Easier to wire initially; one repo, one workflow. Good when API and SDK release together.
• Option B: Separate SDK repo
  Cleaner for consumers, independent versioning, fewer unrelated diffs. Better for public SDKs.
• Best for:
  • Mono-repo: internal services and teams that own both API and SDK.
  • Separate repo: public/partner-facing SDKs and multi-team environments.

---

How do I actually implement the GitHub workflow so SDK updates open as pull requests?

Short Answer: Add a GitHub Actions workflow that runs on spec changes, executes speakeasy generate, commits the resulting SDK files, and uses a token (or GITHUB_TOKEN) to open a pull request against your main branch.

Expanded Explanation:
The implementation is mostly standard GitHub Actions plumbing with one Speakeasy-specific step. You configure the workflow to trigger when your OpenAPI spec (or spec directory) changes. Inside the job, you install the Speakeasy CLI, run the generator using your config, then check if anything changed in the SDK directory. If there are changes, the workflow creates a branch, commits the updated SDK, and opens a pull request using the GitHub REST API or an existing “create-pull-request” action.

The result: every time someone edits the spec, GitHub shows a new PR with the exact SDK changes that spec induced. You can layer on language-specific tests (TypeScript, Python, Go, Java, etc.) so the PR serves as a gate for both spec correctness and downstream interface quality.

What You Need:

• Speakeasy CLI and config:
  • speakeasy installed in CI (via Homebrew, script, or cache).
  • A gen.yaml (or equivalent) checked into the repo defining SDK generation.
• GitHub automation:
  • A workflow that:
    • Triggers on spec changes (e.g., paths: ['openapi/**', 'openapi.yaml']).
    • Runs speakeasy generate.
    • Commits changes and opens a PR using GITHUB_TOKEN or a PAT.

---

How do we make this a strategic, low-friction path to “ship SDKs with every commit”?

Short Answer: Treat “Speakeasy → GitHub PR” as part of your main CI/CD path, not a sidecar. Every spec commit should trigger generation, testing, and a pull request, so your SDKs evolve at the same speed as your API.

Expanded Explanation:
The real value isn’t just auto-PRs; it’s operationalizing change. When you wire Speakeasy into CI so that every spec update regenerates SDKs, Terraform providers, and CLIs, you turn a historically manual process into a predictable pipeline. API teams stop hand-writing language-specific clients and chasing drift; instead, they review automated diffs and focus on semantics.

On the business side, this closes the gap between “we shipped a new endpoint” and “customers can safely call it from TypeScript, Python, Go, Java, or Terraform.” It also gives you a clear review surface when agents enter the picture: the same OpenAPI-driven artifacts your SDK consumers rely on are what your MCP servers and Docs MCP tools use under the hood. One spec, many interfaces, governed through a single PR workflow.

Why It Matters:

• No drift between API and SDKs:
  • Every spec change yields a visible, reviewable SDK update instead of silent breakage or lag.
• Faster, safer releases:
  • Teams “ship with every commit” via CI-generated pull requests, preserving code quality while increasing release frequency.

---

Quick Recap

Connecting Speakeasy to GitHub so SDK updates are opened as pull requests on every spec change is a matter of wiring your OpenAPI spec into a repeatable CI workflow. You install the Speakeasy CLI, generate and commit your SDK once, then add a GitHub Actions (or other CI) pipeline that runs speakeasy generate on spec changes, commits any diffs, and opens a PR. Whether you keep SDKs in a mono-repo or separate repos, this pattern keeps SDKs, Terraform providers, CLIs, and agent-facing tools in sync with your API without manual upkeep.

Next Step

Get Started