[LC-895] - Feat: Generate OpenAPI SDK clients Git Action

[Custard7]

trafficstars

Overview

🎟 Relevant Jira Issues

LC-895

📚 What is the context and goal of this PR?

This PR introduces a new GitHub Action workflow that automatically generates OpenAPI client SDKs for the LearnCard Network (LCN) brain-service, and creates or updates a pull request with the generated clients. The goal is to ensure that our client SDKs for various languages (currently Python and Java - we can add more after test these two) are always up-to-date with the latest API changes, improving developer experience and reducing manual maintenance.

⚡️ How does it work?

The new workflow (open-api-generator.yml) is designed as a reusable workflow, triggered via workflow_call. It is invoked only after a successful deployment of the brain-service in the main deploy.yml workflow.

The deploy workflow checks which services were affected by the latest changes using Nx, and only triggers the OpenAPI generator if the brain-service was deployed.

The generator workflow checks out the repo, generates client SDKs for each language in a matrix (currently Python and Java), and creates or updates a PR with the new clients using the peter-evans/create-pull-request action.

🚦 When does the generator run?

Only when the Deploy workflow for the brain-service succeeds.

This ensures that SDKs are only generated and updated when there are actual, deployed changes to the brain-service API, preventing unnecessary noise and keeping the SDKs in sync with production.

💡 Feature Breakdown

• Adds a reusable workflow to generate OpenAPI client SDKs (Python, Java, easily extendable).
• Automatically opens or updates a PR with the latest generated clients.
• Keeps SDKs in the packages/open-api-lcn-clients/ directory, organized by language.
• Ensures SDK updates are only triggered by real, deployed changes to the brain-service.
• Uses Nx to detect affected services and minimize unnecessary runs.

🛠 Important tradeoffs made

Pros:

• Eliminates manual steps in keeping SDKs up-to-date.
• Reduces risk of SDK drift from deployed API.
• Extensible to more languages as needed.

Cons:

• Slightly increased CI runtime after brain-service deploys.
• PRs for SDK updates may be frequent if the brain-service API changes often.

🔍 Types of Changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] Chore (refactor, documentation update, etc)

💳 Does This Create Any New Technical Debt? ( If yes, please describe and add JIRA TODOs )

• [x] No
• [ ] Yes

Testing

🔬 How Can Someone QA This?

This one is kind of hard to test without merging it in, because the key thing to test is whether it correctly runs post-brain-network deploy.

But, I ran the action manually for the python client, and it opened this PR: https://github.com/learningeconomy/LearnCard/pull/658

So, if all looks groovy, we can merge and monitor! 🚀

📱 🖥 Which devices would you like help testing on?

🧪 Code Coverage

Documentation

📜 Gitbook

📊 Storybook

✅ PR Checklist

• [ ] Related to a Jira issue (create one if not)
• [ ] My code follows style guidelines (eslint / prettier)
• [ ] I have manually tested common end-2-end cases
• [ ] I have reviewed my code
• [ ] I have commented my code, particularly where ambiguous
• [ ] New and existing unit tests pass locally with my changes
• [ ] I have made corresponding changes to gitbook documentation

🚀 Ready to squash-and-merge?:

• [ ] Code is backwards compatible
• [ ] There is not a "Do Not Merge" label on this PR
• [ ] I have thoughtfully considered the security implications of this change.
• [ ] This change does not expose new public facing endpoints that do not have authentication

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: bb37f450203ac7031c5db5a0d0b38367de1af897

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@learncard/network-brain-service	Patch
@learncard/network-brain-client	Patch
@learncard/network-plugin	Patch
@learncard/init	Patch
@learncard/chapi-example	Patch
@learncard/create-http-bridge	Patch
@learncard/cli	Patch
@learncard/react	Patch
learn-card-discord-bot	Patch
@learncard/snap-chapi-example	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify[bot]]

✅ Deploy Preview for learn-card-chapi-example canceled.

Name	Link
🔨 Latest commit	bb37f450203ac7031c5db5a0d0b38367de1af897
🔍 Latest deploy log	https://app.netlify.com/sites/learn-card-chapi-example/deploys/680fdc0b952d8e00089f57c3

[netlify[bot]]

✅ Deploy Preview for learncarddocs canceled.

Name	Link
🔨 Latest commit	bb37f450203ac7031c5db5a0d0b38367de1af897
🔍 Latest deploy log	https://app.netlify.com/sites/learncarddocs/deploys/680fdc0b240fe000082a3d08

[gitstream-cm[bot]]

✨ PR Review

General Feedback

This PR adds a well-structured GitHub workflow for automatically generating OpenAPI client SDKs for the LearnCard Network brain-service. The implementation is clean and efficient, triggering only when the brain-service is deployed, which prevents unnecessary SDK updates. The workflow is also designed to be extensible, currently supporting Python and Java clients with room to add more languages in the future. The PR includes appropriate changeset files and a minimal README for the new packages directory.

File: .github/workflows/deploy.yml Bug - Invalid Reference

Details

Problem: Invalid Reference - The workflow file is using an incorrect syntax to reference the open-api-generator.yml workflow. The @v1 tag is not valid in this context and would cause the workflow to fail when executed. Fix: Remove the @v1 tag when referencing the local workflow file Why: When referencing a local reusable workflow with the 'uses' keyword, you shouldn't include a version tag (@v1) as this syntax is only valid for workflows from the marketplace or other repositories.

- name: Generate new Open API SDK clients for brain service
        if: contains(env.AFFECTED, 'network-brain-service')
-       uses: ./.github/workflows/open-api-generator.yml@v1
+       uses: ./.github/workflows/open-api-generator.yml

File: .github/workflows/open-api-generator.yml Security - Token Permission

Details

Problem: Token Permission - The workflow is using the default GITHUB_TOKEN which might not have sufficient permissions to create pull requests. This could prevent the workflow from working as expected, especially when attempting to create or update PRs. Fix: Either use a personal access token with workflow permissions or explicitly define token permissions in the workflow Why: The default GITHUB_TOKEN might have limited permissions depending on repository settings, potentially causing the create-pull-request action to fail due to insufficient permissions.

on: workflow_call

+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
env:
    working-directory: packages/open-api-lcn-clients

Generated by LinearB AI and added by gitStream. _{AI-generated content may contain inaccuracies. Please verify before using. We’d love your feedback! 🚀}

[gitstream-cm[bot]]

🥷 Code experts: TaylorBeeston

TaylorBeeston has most 👩‍💻 activity in the files. TaylorBeeston, Custard7 have most 🧠 knowledge in the files.

See details

.github/workflows/deploy.yml

Activity based on git-commit:

	TaylorBeeston
APR	0 additions & 13 deletions
MAR	3 additions & 3 deletions
FEB	6 additions & 0 deletions
JAN
DEC	1 additions & 0 deletions
NOV

Knowledge based on git-blame: TaylorBeeston: 89% Custard7: 10%

To learn more about /:\ gitStream - Visit our Docs