Auto-Magically Sync to ReadMe With GitHub Actions 🎩
2 min read
Kanad Gupta

Developer Advocate & API Engineer

Developer Advocate & API Engineer (he/him)

Auto-Magically Sync to ReadMe With GitHub Actions 🎩

Happy Halloween, y’all! As you probably know by now, developer experience is core to how we build at ReadMe. Part of that is meeting engineering teams where they’re at and integrating into their existing workflows. Since many teams (including ours!) already use GitHub to manage their APIs and their docs, we are continually investing in our GitHub Actions support to ensure that teams using both GitHub and ReadMe have the smoothest experience possible.

After releasing the rdme GitHub Action earlier this year, we’ve got another exciting announcement: we’re officially a GitHub partner! Together, we’ll ensure that developers on GitHub can quickly and easily integrate with ReadMe 🤝

A few new tricks 🪄

Promotional image for rdme@8.0. Install it with `npm install -g rdme` and run `rdme openapi` to get started!

As part of this announcement, we’re shipping [email protected], which includes a few new tricks:

  • Improved logging in GitHub Actions runners 🪵
  • Automatic detection of your OpenAPI / Swagger definition (regardless of what the file name is) 🔍
  • A new GitHub Actions onboarding experience that auto-magically generates a GitHub Actions workflow file for you ✨

Let’s demo this new onboarding experience below:

In the above example, the following takes place:

  • An OpenAPI definition is located and validated using rdme openapi:validate ✅
  • The CLI detects that the working directory is a GitHub repository 🕵️
  • … and a few key-presses later, we’ve created a GitHub Actions workflow file! ✨

Once the workflow file is pushed to GitHub, the validation workflow runs with every push to the main branch. Setting up GitHub Actions workflows with rdme has never been easier!

Making the magic happen ✨

To make this syncing magic happen for your ReadMe project, first make sure you have Node.js installed and install rdme via npm:

npm install -g rdme

For any rdme command that you wish to run via a GitHub Actions workflow (e.g., syncing and/or validating an OpenAPI definition, syncing a directory of Markdown, etc.), add the new --github flag to the end of your command. This will bypass the GitHub repository auto-detection and run the onboarding process for creating a new workflow file. See below for an example command that you can run to sync an OpenAPI definition to ReadMe:

rdme openapi:validate --github

The CLI will first locate and validate your OpenAPI definition and walk you through a few quick prompts before creating a new GitHub Actions workflow file for you. Push the file to GitHub and you’ll be syncing in no time 🔄

But wait, there’s more! 🍬

The tricks and treats don’t stop there — the v8.0 release of rdme includes a bunch of other goodies, including:

  • A vastly simplified rdme login experience 🔑
  • A smoother prompts experience when interacting with the CLI 🎙️
  • Even more tooling to help you manage your OpenAPI / Swagger definition, including a new reducer tool 📦
  • And much more — check out the full v8.0 release notes to get the details 🚀

We’re ecstatic to see what you build with rdme and GitHub Actions. Happy Halloween and Happy Workflowin’, y’all! 🎃

Further reading 👻