DEV Community: Sebastian Tiedtke

ENV vars are like needles in a haystack, aren't they?

Sebastian Tiedtke — Wed, 11 Dec 2024 00:53:24 +0000

Owl Store: A Type System for Environment Variables to Specify, Resolve, and Verify Correctness

Sebastian Tiedtke ・ Dec 10

#programming #opensource #computerscience #devops

Owl Store: A Type System for Environment Variables to Specify, Resolve, and Verify Correctness

Sebastian Tiedtke — Tue, 10 Dec 2024 05:37:35 +0000

Tired of copying secrets into GitHub/Gitlab every other day? Chasing down correct values for newly introduced ENV vars after git pull? Today, we are making these problems go away. Don't believe me? Read on.

Introducing the 🦉 Owl Store, a concrete implementation of a Type System for Environment Variables that specifies, resolves, and verifies your environment's correctness.

Let's Start With A Demo

The demo is a Poor Sebastian’s Vercel to generate preview URLs for Runme's documentation. Here is what it does:

A Dagger module that leverages the Docusaurus build
To generate production-ready Nginx container image with the docs
Pushes the image to GCP’s artifact registry
Launches a Google Cloud Run instance and returns the Preview URL
Transparently uses the Owl Store to resolve the services accounts to auth the GCP operations

Check out this video:

> The 🦉 Owl Store makes sure the Dagger function runs inside a valid environment

You can run it yourself at home. It's self-contained using Dagger and requires minimal setup and a GCP account. It’s available inside Runme’s docs repo. All steps to get it up and running are documented in README.md, which is itself a Runme notebook. Be sure to switch to Runme's pre-release; otherwise, you won't see the Env Store panel.

Now, let's get into the details.

Why is this hard?

Getting environments “right” is no easy feat. Ask your developer: Docker, lock files, pipelines, and the elasticity of cloud computing resources have undoubtedly increased the reproducibility of environments across the software development lifecycle. Albeit with more tangible success in production(-like) environments. DevOps is all about the left shift; however, arguably, this shift is still miles apart from humans.

A tell-tale sign I often encounter when talking to engineers in the field is having separate engineers/teams owning Platform Engineering and DevX. The idea is to provide narrow git push interfaces to advance code out of development, which is resource-intensive enough to, at best, cover and support the critical path. It’s where uniformity of operational excellence (12factor) clashes with developers’ need for unconstrained creativity and experimentation.

Crossing the Dev vs. Ops Chasm

I have been pondering why we have yet to overcome the proverbial Dev vs. Ops chasm for several years now. During my time at Smallstep, I learned hands-on how powerful PKI-based strong identity (humans & workloads via OAuth & Workload Identity) is to moving to zero-trust security models (e.g., via mTLS or SSH certificates) that liberate us from reliance on the of space-bound perimeters (Hi, VPCs!) to enforce secure computing in the cloud-native age.

> ENV-edition of the Draw the Owl meme

I have come to the firm belief that Configuration and Secrets Management is what's holding us back. This is not because we haven’t made strides with Sealed Secrets, CloudKMS, Vault, and a slew of Cloud-certified Secret Managers that provide sophisticated ACLing mechanisms.

It’s because we create JIRA tickets to generate, copy, and paste credentials to resources into GitHub/Gitlab or—close your 🙈 eyes and 🙉 ears now—paste them into Slack channels or Zoom chats. The available solutions aren’t rooted in strong cryptographic identity. They don't work the same for humans and workloads, which, if they did, would massively increase reproducibility and portability—unlocking Single Sign-On for Environments.

GitHub/Gitlab: Take My Bargaining Chips

This isn’t just time-intensive and error-prone; it makes third parties like GitHub, Gitlab, etc., our system of record. That’s something they love: more usage and more vendor lock-in. What an excellent way to give up all our bargaining chips. And now, we still haven’t solved the problem for developers in their environments, which requires bespoke solutions or running clusters locally. We wind up with spotty “project onboarding instructions,” which leave us with the challenge of figuring out how to draw the rest of the owl on our own—every time.

Enter the Owl Store 🦉

As a bourbon-drinking armchair Computer Scientist myself, I spent quite some time dreaming up a solution to switch into building it earnestly well over a year ago. While still experimental, it’s closer to a beta than an alpha. There is an immense amount of ground to cover, so delivering an end-to-end experience was more important to me than going deep on any particular part. There will be bugs!

> The Owl's simple CLI to inspect stores

While the Owl Store is fully integrated into Runme’s DevOps notebooks (which works well for demos), it’s remarkably self-contained. Given enough interest, I would love to spin it out as a standalone project. It's got a rudimentary CLI interface, which even lets you source a session's ENV vars into a running terminal session:

> Source the Owl store snapshot into a terminal session

A Complete Solution That's Unfinished

Please note that the Owl is a work in progress. While it illustrates a complete solution, it’s far from finished. Building it has helped unpack the series of unsolved problems along the way. The code is very pragmatic, prioritizing making it work and then making it right before making it concise/scaleable.

A warning: If you expect another “Kubernetes API”, the Owl Store isn’t that. However, I’d love a Kubernetes Admission Controller that mounts secrets downstream. Get in touch. I have also looked at various technologies, including DirEnv, Nix, Infisical, Doppler Labs, Vault, Chezmoi, Teller, Cuelang, and Pulumi, all solving parts of the problem, to name a few. My main objection (applicable to end-to-end solutions) is that users have to adopt them wholesale, more often than not, handing over custody of their secrets and/or requiring SDKs that circumvent the treasured environment altogether.

Blobs of KEY=VALUE Strings Running the World

Configuration and Secret Management are a “death by papercuts” issue. It’s not “just” secrets; it’s all of configuration. While secrets are exponentially more complex, they are still "configured". Nothing works if your configuration is wrong. This is why the Owl Store gets to the mother of all configuration management challenges: The Correctness of Environment Variables. Blobs of KEY=VALUE Strings are running the world!

> Whoza self-hosted Supabase, so many vars

Before debriefing the Owl’s implementation details, let's jump into an example. The goal is to paint a picture of how it works from a user’s perspective, using a sysadmin mindset and focusing on the Owl Store's visible parts that concern users.

Good Luck Running a Monolith Locally

Below is Stateful's Git repository containing the monolith running our Cloud product. With many third-party API integrations, the amount of environment configuration is substantial. However, 57 environment variables are actually on the low end for a monolith.

❌ Invalid Environment

The Owl Store's UX clearly identifies how “incomplete” my environment’s variables are.

> The Owl's Env Store pane will display invalid variables first

More importantly, it does so securely, making me comfortable publishing screenshots. Concisely identifying the correctness gap in your environment variables is a tremendous boost in help.

> The same 'Env Store' snapshot is available via the CLI

Even better, the Owl’s Env Store UI isn’t locked into a VS Code panel. Thanks to the Owl’s local-only APIs secured by mTLS, the same information is available on the CLI. Looking at this screenshot now, makes me want to color the invalid entries ❌ red. It's on the todo list.

✅ Valid Environment

Now, if your keen eye detected the commented-out resolution path in the upper left editor (above screenshots), let’s return those lines, reset the session (the Owl is a fully managed ENV store), and notice the difference.

> Specifying a resolution path for the Environment

Magic 🧙! Within seconds, there are no more unresolved ENV variables. The Owl Store now automatically resolved variables via GCP’s secret manager (see [gcp:secrets]) using my Application Default Credentials (as in auth: ADC) in the platform-staging-413816 project, which I previously put in place completing GCP’s OAuth flow. It does so quickly by applying simple transformations (see: expr: [...] key | lower()) to the variable keys.

> Based on the resolution path, the Owl will resolve unresolved variables

It'd be easy to add triggering GCP's OAuth flow if no valid user credentials are available and/or resolve any other prerequisites that aren't met. Here are a few things to understand. Frankly, GCP's Secret Manager is very much low-hanging fruit. We are using it internally, and it is demoing well. Outside of it, though, AWS, Vault, webhooks, etc., or chaining any of these is possible. There is a lot of ground to cover. However, all the same principles apply.

Desired State: Description of Environment Variables

This example vastly simplifies The Owl Store’s capabilities for demonstration purposes. We chose to reuse DotEnv conventions to meet engineers where they are already.

> Env Spec declarations leaned on commonplace .env.example or .env.sample

The Owl will look for .env.example, .env.sample, or .env.spec in the code repository's root, which declares the variable’s keys, a description, and an env spec (aka type). This is a slight variation of how .env.example files are already being used, but the payoff is worth the while. We'll debrief this soon.

Flexible Configuration Frontends

In this example, the Owl’s configuration uses a Custom-Resource-Definition-like configuration frontend we usually see in the Kubernetes-world. However, internally the Owl uses a graph representation independent of any configuration frontend. I built the CRDs in a few hours, and they are far from final. Declarative YAML seemed a sensible choice for this example. It would be possible to give Javascript folks a package.json way to do this, Rubyists a DSL, Golang folks a TOML file, or SDKs for any language platform to configure any aspect of the Owl Store. More on this further below.

Multiple Resolution Paths & Mechanisms

In this example, outside of built-in .env. or .env.local resolution (non-sensitive config), the CRD-specified value as per path requires a hard-coded project: platform-staging-413816. However, with the capability of the “rearrangeable” internal graph, it’s possible to have preceding nodes in the graph match a human or workload identity (e.g., GCP user or service-account) to a set of metadata, including project, which downstream is used to resolve secrets in GCP’s secret manager.

> Specify a resolution path for the Owl; GCP Secrets in this case

Instead of specifying a single path, running multiple in parallel is possible, and either the one that succeeds first wins or overwrites the other in a defined sequence. It's also possible to consider configuration backends, not just secret managers. What do you need?

Variable Visibility and Validation

Your keen eyes have probably already identified a crucial part of what makes the Owl Store work: Spec Types, e.g., # Secret! Every Variable acquires a type. Unless specified otherwise, it defaults to Opaque, which means it’s neither fully visible nor entirely hidden. One-click reveals the value in the UI. Other atomic spec types are Secret, Password, and Plain. When describing environment variables, you almost always focus on a small yet significant subset. And even without full coverage, secret keys in your shell profile are guarded sufficiently by defaulting to Opaque.

> CRD-style Env Spec definition laying validation over visibility

The Spec types Secret and Password are particular. Clear text values are never available in Owl's UI/UX. There is no API to expose them; they are intentionally masked, and the Owl makes no exceptions. Outside of the atomic spec types, it is possible to define custom types to layer validation on top of visibility for built-in security hygiene. More on that below.

Lifecycle over Time

Another detail I wouldn’t want to be overlooked is the Owl Store's Source column. There is a reason why the Owl’s CLI command to inspect the session’s store is called ... store snapshot: An Owl session’s internal graph stores the entire lifecycle of how a single variable is loaded, resolved, verified, mutated, removed, etc., over time.

> The Owl store retains the entire lifecycle of variables, 'Source' shows the last recent mutation

The store’s UI effectively nets a snapshot. The Source column in this UI shows the last recent mechanism that mutated a value. This capability is essential because, unlike workloads, humans are interactive. Occasionally, it makes sense to manually provide the last unresolved value, e.g., the "god password," for the master database.

Interactive Resolution

For instance, a last-resort resolution could be to prompt the user for input when a variable remains unresolved. Runme does precisely that. When it happens, the Owl Store will retain that variable $XYZ was unresolved and transition to resolved when and by what mechanism. Moreover, if you ran unset XYZ in a Runme notebook cell, it would record a deletion.

Of course, if we'd run resolution for a workload, not a human, any variable's unresolved value would be considered an irrecoverable error and exit.

Takeaways

Based on what’s covered in the example above, I will stipulate that Owl’s approach, with human ergonomics first, not just equips it with everything required to configure developer environments but workloads, e.g., CI/CD job, Services running in Kubernetes clusters, too. Running resolution for workloads is a vast simplification since "interactivity" in, e.g., a pipeline makes little sense. Of course, more development effort is required to expand Owl’s graph and integration capabilities to truly unlock this.

I will also claim that Owl’s principles should be extended further up and downstream, e.g., by providing SDKs that, in code, provide type safety while generating Env Spec type declarations instead of maintaining them by hand. Or, Admission Controllers and GitHub Actions that would enable fully reproducing environments anywhere using identity and, at most, an environment identifier, e.g., team5-staging-us-central1. This would make every developer's and operator's life much easier. Win-win!

We need a full-featured tooling ecosystem around “Typed Environments”. The Owl Store 🦉 is precisely that.

Let's look under the hood.

Under the 🦉 Owl Store’s Hood

The Owl Store brings type safety to the 1970s concept of ENV Vars. Remember the skeptics who thought Javascript didn’t need Typescript? Fair enough; don’t use it. The Owl Store is very similar. The Owl in a nutshell:

A smart Environment Store toolchain for humans and workloads
Specify, validate, and resolve environment variables anchored in strong identity
Built-in security hygiene to make the right things easy and the wrong things hard
Formal verification of “correctness” and opening doors for better tooling ecosystem
All without requiring remote servers, backend APIs, or taking custody of your secrets

We took inspiration from the SSH Agent and the type system behind Typescript, which brings gradual type safety to Javascript. Despite using it daily, for the longest time, I had no clue how the SSH Agent worked.

> Local SSH Agent listing the loaded keys

In the SSH Agent, once a private key is loaded, the only APIs available are signing, verifying, encrypting, and decrypting messages and signatures. Keys loaded in plain text can not be extracted as such; it's a one-way door. I can’t blame you if you don’t want to know how the SSH Agent works. It just does; you don’t have to. That’s the killer feature.

Skipping a pro/con discussion about strong typing, TypeScript's key feature that inspired us is its ability to be adopted gradually. In the Owl's case, any workload's focus is only ever on a subset of the most important environment variables. Use as much of it as you want—no more, no less.

The Importance of Strong Identity

Anchoring Environments and their resolution on strong human/workload identity (OAuth, workload identity federation, etc.) allows us to decouple from third-party providers. Paired with containers, it makes switching public cloud resource providers (GitHub, AWS, GCP, etc) and/or secret backends (Vault, AWS/GCP Secret Manager, Cloud KMS, etc.) possible, enabling the Owl to stay out-of-band of secrets lifecycles. It unlocks free portability of both human and workload Environments (e.g. my laptop, a CDE in Codespaces, a CI/CD job, Kubernetes clusters running pods).

The closest comparable technology I've seen is Pulumi's ESC. However, it comes from an Infrastructure Management (IaC) angle and mandates Pulumi's proprietary backend. That's not bad per se; it's just different from the Owl Store's principles.

Redefining the Relationship between Workload, Repo, and Environment

Looking at the ordinary lifecycle of any one ENV variable, they start existing by the sheer force of being used. Some programs, workloads/services, and scripts validate better and provide more documentation than others. However, when we are asked to provide values based on blank variable keys, it’s usually left up to the environment and its user. Either you copied the proper values into GitHub/Gitlab, specified them in a Kubernetes/Compose manifest, or had enough -e KEY=VAL in your docker run calls.

Being a wise bird, the Owl wants a formal description of environment variables to become an essential part of every code repository. Outside of what the Owl does, this would reap the apparent benefits of Git workflows to track the evolution of environment specs.

🦉 This is very important: Without the indirection of a code repository colocated Environment Specification, we would merely perpetuate the practice of coupling environments to humans (.dotfiles) or workloads (paste config into your pipelines/orchestrators). Docker decoupled app/runtime and system dependencies from machines. Let's finish the job by doing the same for Configuration and Secrets.

> Golden triangle: Workload, Repo, and Environment

Whether or not leaning on .env.example is the best solution here is debatable. However, these files are everywhere and effectively mirror what developers are already doing. And the Owl Store is neutral to how Env Specs are inserted into the graph. Currently, the only implementation is to declare variables in .env.example using spec type annotations. I hope that Copilot or my future bespoke AI model can auto-complete the annotations for you. Optionally, to elevate the importance, one can rename .env.example to .env.spec to send a message that its role has been upgraded.

> Anatomy of Env Spec declarations

It’s not inconceivable to allow multiple ways, e.g., a CRD or an SDK, to declare ENV variables and reconcile them on Git pre-push. If ENV access from code used an Owl SDK, it’s not impossible to detect and/or generate missing spec type definitions and declarations accordingly. Better tooling, yay!

Declare Variables Spec Types via Annotations in `.env.example`

The anatomy of an environment variable’s Spec type and the resulting triplet is not unusual if you are no stranger to typing. The ! declares variables as required, which will both throw errors when unresolved and consider the variable for resolution (if they aren't Secret or Password). While not final, this is merely an implementation detail and felt suitable for demonstration purposes.

> Anatomy of a single ENV var triplet

The Owl allows defining Custom Spec types which allow both grouping of atomic variables, e.g. Redis = REDIS_HOST! + REDIS_PORT! + REDIS_PASSWORD, and overlay validation on the atomic-level. E.g. making sure a variable’s value is valid base64, json, jwt, fqdn, etc. To forgo full turing-completeness (security) in validation, Golang's tag validator library and its baked-in tag validators are used. Below are more ideas on how to make validations more powerful and Env Spec types shareable.

By the way, validation is not limited to "compile-time". It’s absolutely conceivable to check, e.g. a connection to a Redis instance, with a single click in the Owl Store UI or TUI. Effectively delivering "runtime" checks on the edge of workloads, services, and scripts. Wouldn’t that be a great feather in the better tooling cap?

> Proposed CRD-style config to define custom Env Spec types

The idea behind these environment variable declarations is simple: Once you have two (name and spec type) out of the triplet, can you find the third? The demo shows this is possible based on contexts like authentication, authorization, metadata, the runtime machine/device/cluster, etc., and running down a resolution path in its respective graph.

> Demystifying validation errors

Needless to say, it’s powerful to have immediate feedback if a value is absent, invalid, or an error occurs, accompanied by a descriptive error message. Since the Owl Store is fully local, feedback is immediate, making it a perfect fit for an engineer's inner loop while guarding direct access to sensitive values.

The Graph Inside Out 🦉

At the core of the Owl Store is a GraphQL-based graph. Now, forget everything you have ever heard about GraphQL APIs, specifically the latter part. The Owl Store leverages GraphQL for its capabilities to express typed graphs, it’s got an integral type system that transcends the boundaries of language platforms with clients available in every language, and it is battle-tested.

I looked at all sorts of graph libraries, but GraphQL is the only one that checks all the boxes. I even have a rudimentary prototype of the Owl running on React—Preact, to be precise. It just wasn't as language platform neutral, and, let's be honest, how many frontend engineers do you see writing Environment Resolution React components? I'm still not "over" using JSX as a configuration frontend, but even my days only have 24 hours, and again, are people going to use it?

I have to admit what ultimately pushed GraphQL over the edge for me was getting wind of the folks at Dagger pushing forward on using GraphQL for Cloak & Dagger. Wisdom of crowds! I had PoC’d the Owl Store in Javascript’s Apollo first but ultimately decided to implement it inside Runme’s Golang kernel. I'm not a strong Golang developer, so please apply puppy protection to my code. Copilot wrote all the error messages 🤖.

So, if any of what comes next makes no sense to you, that’s totally okay. I won’t stop you from using the Owl Store. We will now look behind the Owl Store's curtains for those interested in the inner workings. I will also skip how Runme gets hold of Environment Variables since the concept of a managed Env Store is integral to Runme's markdown-based notebooks and universal task runner, with or without Owl Store.

GraphQL but no “Data API”

Again, The Owl Store is no GraphQL API. It doesn’t even have a GraphQL endpoint to send queries to. It’s entirely air-gapped and only runs queries programmatically inside the core. Queries are exclusively generated.

Unless you work on the Owl’s core, you never have to look, write, or understand the monstrosity of a serialized query against this graph. If you care about the abstract science behind it, all you need to know is that it works like a massive map-reduce operation where a map of key/specs, key/values, and contextual information such as e.g. GCP auth state is being passed down to every node traversing a query.

The serialized queries (visually fantastic for debugging) grow infinitely to the right since nested nodes execute serially in a predictable sequence. It's just like calling what looks like "infinitely" nested Javascript callbacks. But again, there is no API for human consumption unless you are working on the core.

> String-rendered Owl snapshot query

These queries are monstrous because I decided to err on making the Owl’s graph maximum expressive. For instance, unlike a GraphQL data API where errors usually happen "on the edges" processing data queries or mutations, the Owl store needs to represent “unresolved values” as defined "error states" inside the graph, not as an exception of data ingress or egressing. If an error happens on the GraphQL-level, something more fundamental went wrong, very likely a bug or an unhandled edge case.

Space + Time + Chaining

Space-time blows up the graph's size. The key/value and key/spec maps (not anywhere visible in the serialized queries; passed as GQL variables) can ingress and egress the graph to be fully de/-serialized in between. As mentioned, the Owl Store stores every mutation to ENV vars state and its metadata over time.

This is like double-entry bookkeeping, where you can "net" a snapshot at any given point in time on a timeline. This allows us to answer other questions, such as about the lifecycle of how a variable was used. For instance, if a Runme notebook cell exports a variable export NEW_VAR=123, the Owl Store will store a reference to the respective cell in its metadata.

The capability to egress/ingress the graph makes it possible to chain infinite operations while collapsing the graph state into a snapshot and then ingressing the snapshot into a new graph. The resulting snapshots are virtually identical, and the new graph will no longer have access to previously collapsed history and start writing its own.

A downside, which eventually needs refactoring, is that the GraphQL definitions are relatively simple when using GraphQL types (lots of String no Interfaces, etc.) and have not yet been fully modeled. It's easier to iterate on functionality before going deep on normalization. Strings are easy to de-/serialize.

> String-rendered Owl resolve query

To illustrate how egressing the graph to ingress the snapshot produced into a new graph, let's consider "resolution". Resolution is a query that runs upon constructing a new session and looks very similar to a regular snapshot with running validation twice (before and after) and a few extra nodes in between. Remember, programming the graph is a matter of rearranging its nodes in a different way that’s still valid. It's programmable.

Query Construction & Execution

One aspect of modeling The Owl store around GraphQL fundamentals that’s been tremendously helpful is that it makes it possible to compartmentalize error state into a series of tiny steps and provide high-fidelity error message as opposed to a wholesale bootstrap-all.sh that will attempt to do stand up an environment but randomly exits with error: exit 1 or something similar unhelpful. It’s what I call the AST-fication of complexity into tiny, explainable units.

Remember, no queries in the Owl Store (unless for unit tests), are hand-written. Any query is an output of "mapping and reducing" an input into an output encoding, whether it's a CRD-like YAML or a GraphQL query or GraphQL produces another GraphQL query.

> DotEnv loading expressed as example string-rendered query

For instance, instead of hard-coding the sequence of how a DotEnv loads, why not express it in a graph where the “client” can easily rearrange the nodes to change its behavior? Any error can be addressed as a distinct "unit of work".

It's not unusual to have GraphQL queries return queries. I suppose what I’m describing here are the benefits of strongly-typed contracts. However, what's uniquely powerful in expressing the Owl Store's capabilities through a graph is a strikingly healthy balance between declarative abstractions and programmability. Anyways, I don't want to bore you.

What's Next

Let us know what you think! The Owl Store is super early. It needs usage and more work to grow into its big promises. Get involved! The owl's code is here. Let's say the code is a bit chaotic. I'm more of a creative who likes solving painful problems than a 10x Golang engineer. Pull Requests are welcome, but more than anything, please try it out!

Here are open questions that are on our minds:

What do you like? What don't you like?
What configuration frontends resonate? Declarative, SDKs, Queries?
Are env spec declarations always the same across all Environments?
Custom Env Spec type definitions are relatively new and are shoe-horned into the code. Refactor pending!
We'd love to leverage Cuelang to define Spec types, validate them, and consider sharing via its module system
Perhaps Cuelang can also play a role in layering overwrites commonplace in env configs?

Get Involved

Whoa, that was a lot.

If you haven't used Runme yet, it's executable Notebooks for DevOps: Click here to launch a DevOps Notebook inside your browser. Easier experienced than explained.

Again, let us know if any of this interests you. You can find us on Runme’s Discord. Thank you!

AWS/GCP/Azure Consoles, Embedded inside Your Docs

Sebastian Tiedtke — Wed, 03 Jul 2024 16:38:54 +0000

Today, the team is thrilled to release Runme v3.6, a significant milestone integrating the remaining crucial layer of DevOps and Infrastructure Operations. With Runme v3.6, you now have direct access to AWS/GCP/Azure Cloud Consoles inside your Markdown docs.

If you don't know Xzibit's TV show and the meme, watch this video (totally worth it)

Yes, you read that right. Instead of having to log into your respective Public Cloud’s walled garden and find the resources you’re looking for, you can now make the Console UIs come to you whether you’re documenting an overview or specific VMs, NICs, VPCs, Services, or Clusters, you just “deep-link” the resource in your docs, which will render widgets for the Cloud resources fresh at the time of reading. You can even launch into everyday troubleshooting actions such as SSH sessions, start/stop VMs, pull up associated logs, or skim deployment manifests.

No need to log into AWS or GCP consoles: interactive cloud resources directly in your docs

Best of ClickOps Without Downsides

The vertical integration of the terminal, editor, and browser with remote-hosted cloud resources makes Runme a perfect fit for documenting and operating your DevOps workflows through its intuitive notebook, editor, and command-line interfaces—all without the additional cost of running separate infrastructure and maintenance. Runme runs entirely locally; servers are optional. And, of course, it’s 100% compatible with your Infra As Code and GitOps.

How It Works

The idea is as simple as it is powerful. Go ahead and drop the cloud console’s URL/URI to a resource into a cell, click ▶️ and that’s it.

Drop a cloud resource’s URI/URL into a cell to render an interactive widget

Runme’s Cloud-Native Bash Kernel runs cells containing Shell, Javascript, Python, Lua, PHP, etc., anything you could traditionally run via a shebang (e.g., #!/usr/bin/ruby). However, what makes Runme specifically “Cloud-Native” is the capability to allow the deep-linking and real-time rendering of resources in AWS, GCP, Azure, etc., as interactive widgets inside your docs.

These notebook cell-based widgets are W3C-standard Web Components, which make them reusable, extensible, and highly interactive, just like any web app. The resource’s information in the widget is never stale. At the minimum, it’s fresh from when the cell last ran, and where it makes sense, it even updates in real time.

Cloud resources widgets are built using Web Components (open W3C standard)

Access control to your Cloud accounts is entirely enforced by the respective Public Cloud’s officially published SDK. If you’re already using, let’s say, the AWS or GCP’s CLIs, you have no additional setup to get going.

Navigating Cloud Resources in Docs

Of course, cloud deployments aren’t just a single resource. Instead, they are a cobweb of interlinked resources: VMs, NICs, VPCs, LBs, images, containers, pods, etc. Moreover, most resources provide heaps of metadata, operations one can perform (start, stop, login, backup, etc), and event and time-series logs. In the general UX, we strive to find a pragmatic balance between linking back to the Cloud Console and providing first-class UX support. This is a work in progress, and we’re looking for feedback.

There are three general types of cloud resource widget interactions.

Expanding of Listings

What’s excellent about rendering widgets for your cloud resources is that you can highly contextualize your docs. When you provide a listing of e.g. clusters or VMs, traversing into details is a single click away if they are e.g. part of a task or workflow description.

Add the detail view of a cluster with a single click

Follow-up Actions on Resources

Wherever it makes sense, the widgets will provide follow-up actions. Those are super handy for opening associated event logs and metrics, SSH-ing into machines, or starting/stopping VMS. The widgets largely mimic what’s available in the respective cloud console. Let us know if any resource is missing a desired action.

Easily navigate the cloud's cobweb of resources and associated actions

Zooming in and Out of Details

Not every follow-up action expands into a new cell. Wherever it makes sense, it’s possible to navigate back and forth between listings/overviews and their details. Web Components allow for web app-like behavior, including routing between views.

Intuitively flip back and forth between overview and details

Interpolation & Variables for Generic Docs

While it’s powerful to deep-link concrete resources, sometimes you do want to distribute generic and parametrized docs. The cloud resource widgets transparently handle environment variables. Let’s say you wanted to generically list all VMs inside GCE in whatever project is currently set for your gcloud CLI. Just use a shell expression to do that:

https://console.cloud.google.com/compute/instances?project=$(gcloud config get project)

Needless to say, you can use variables set in previous cells in your ENV here for AWS EC2:

https://$AWS_REGION.console.aws.amazon.com/ec2/home?region=$AWS_REGION#InstanceDetails:instanceId=$EC2_INSTANCE_ID

That’s all you need to know to get started. However, we put together an end-to-end example to illustrate the power of runnable docs built with Markdown.

Example Workflow Docs with Runme & Terramate

Our friends at Terramate have built a suite of tools to enable operating OpenTofu & Terraform IaCs at scale. We wanted to use the opportunity to showcase how IaC and DevOps notebooks perfectly combine to provide robust workflow documentation. The example repository, located at stateful/runme-terramate-example, is super easy to run yourself. Just follow the instructions running the README.md. Here’s a quick video to illustrate how it works:

Unleash workflows with runnable & interactive documentation built with Markdown: https://github.com/stateful/runme-terramate-example

Try It Now – Feedback Welcome

While “Cloud Resources” could conceivably be anything from a Kubernetes cluster, a Vercel site, a Netlify deploy, a GitHub Actions workflow, a Supabase database, or anything running in OpenStack, we wanted to start with the most popular public cloud use cases. However, please don’t hesitate to let us know what your Cloud/DevOps heart desires.

Today’s release comes with beta support for a sub-selection of AWS & GCP cloud resources. Namely EC2 and EKS for AWS and GCE, GKE, and Cloud Run for GCP. We’re working on adding experimental Azure support right now. Needless to say, there is a lot of ground to cover, and existing renderers still need details to be fleshed out and overall polished. However, we wanted your feedback early, so we decided to release it now. Runme’s canonical examples are a good way to keep an eye on coverage as we continue unlocking better renderers. Please read the docs and check out:

Before you go, please give Runme a ⭐️ Star on GitHub and join Runme's Discord to let the Runme team know what you think. Thank you!

Runme Gist: A Pastebin for Terminals Inside Your Docs

Sebastian Tiedtke — Tue, 23 Apr 2024 16:29:21 +0000

Pastebins make me nostalgic. I’m told they existed well before the web in the IRC days. The first notable one I remember, Pastebin.com, was created in 2002 by Paul Dixon, introducing features like syntax highlighting and private pastes. Believe it or not, it’s still going strong today. The latest incarnation I remember using recently was PostBin (clever: Pastebin for Webhooks). It made testing “web callbacks” remarkably easy.

Link: https://pastebin.com/raw/HE0EcLUB

Of course, if you are using Git, you know GitHub’s Gist, which launched back in 2008. Despite technological advancements, Pastebin's core purpose remains the same: to share text or code snippets online. However, it has had its share of security lapses, particularly when unsuspecting users pasted credentials to share a public link via private channels. Just a heads up: Don't do that!

💡 Search runme in VS Code extension to install.

Runme Gists Are Masked 🎭 By Default

Today, Runme unlocks the concept of a Pastebin for terminals inside your docs. Instead of reinventing wheels, we just combined GitHub Gists, which you likely already use, trust, and love, with Runme’s capabilities to run your Markdown documentation, capture outputs, and mask (best effort) sensitive data. No copy & paste and no other third party required.

WYSIWYG-editing ahead of Gist creation. Masked Gist: https://gist.github.com/sourishkrout/5129f07b3acc00f44b7b04e741308298

Whether you’re running Bash commands, Python snippets, visualizing VMs running in us-east-1, or running a query inside BigQuery, Runme can securely capture masked (default; optional) “carbon copies” of working notebook sessions. These are incredibly useful for sharing with your team or for keeping a personal record.

By default, Runme creates "Secret Gists" (aka unlisted) with best-effort masking enabled. Although masking can be easily toggled and manual redaction is supported ahead of Gist creation, we still advise you to be cautious when sharing your Gist links.

🤖 No Copy & Paste and No Other Third Party

Let’s see Runme Gists hosted inside your GitHub in action.

The demo video’s artifacts:

Notebook: https://github.com/stateful/vscode-runme/blob/main/examples/gist.md

Masked: https://gist.github.com/sourishkrout/5129f07b3acc00f44b7b04e741308298

Unmasked: https://gist.github.com/sourishkrout/b175b3ed48715b3157a17b037add3282

💡 Search runme in VS Code extension to install.

🚀 How It Works

Runme’s Gist feature seamlessly integrates into the notebook workflow. Activate Auto-Save to capture outputs and run your notebook cells. Be sure to upgrade to Runme for VS Code v3.4.0.

Session Outputs won’t show up unless Auto-Save is enabled

Complete running cells and be sure to finally save the notebook file whenever the file is marked unsaved. This will make sure to synchronize both the original notebook as well as the Session Outputs files. Click Session Outputs to inspect the locally recorded session before, after, or in between, notebook runs. If you’re looking to record distinct sessions be sure to click Reset Session in between.

Toggle between Masked and Unmasked Session Outputs

Decide if you want your Session Outputs to be optionally unmasked. The default is to mask sensitive information on a best-effort basis using the open-source data-guardian library. Since the library might not catch "everything," and you likely have specific criteria for what needs redaction, feel free to edit the Session Outputs file as necessary.

Please note that the purpose of editing Session Outputs is to generate a Gist. Subsequent runs of the same session will overwrite manual edits, so use the Reset Session function if you want to preserve prior results. Creating a GitHub Gist now is as simple as clicking on Generate Gist.

Link to Gist: https://gist.github.com/sourishkrout/9c079a68fc0801a6bf7fe8a71366dd63

Runme will first prompt you to log into your GitHub account and grant write access to your Gists. After successful login, it will display a notification containing a link to the Runme Gist hosted inside your GitHub.

💡 Search runme in VS Code extension to install.

Runme Gist 🤩 Inside Your GitHub

The link is generated as "Secret Gist" which, as long as you keep the link private, will stay private. As always, think twice before sharing.

Link to Gist: https://gist.github.com/sourishkrout/9c079a68fc0801a6bf7fe8a71366dd63

That’s it 💪

Congrats! Save, share, and collaborate with your team. Needless to say, it is also entirely possible to keep the Session Output files offline and local. Read about it here. While you're here, please give Runme a ⭐️ Star on GitHub.

If you desire tighter control to govern access and visibility for these useful DevOps workflows and artifacts features inside your teams, please check out Stateful, the platform built around Open Source Runme.

💡 Search runme in VS Code extension to install.

BranchGPT: The AI-Powered Solution to Personalized Branch Names

Sebastian Tiedtke — Mon, 15 May 2023 17:36:14 +0000

💡 TL;DR: Yes, BranchGPT is an attempt to -Tongue-in-cheek- take AI over the top. However, while its utility is questionable, it is enjoyable, like a game. If that's not for you: fair enough. You don't have to use it.

“There are only two hard things in Computer Science: Cache invalidation, naming things, and off-by-1 errors”. Whoever originally coined this quote wasn’t particularly exhaustive, but undoubtedly speaks the truth. It’s incredible how seemingly easy tasks turn out to be the hardest.

Why BranchGPT?

Experimentation with OpenAI's API led us to experiment with branch naming. A repo’s branch namespace is global, so giving a git branch a descriptive name is no exception. Issue trackers often provided shortcuts to generate branch names from JIRA or GitHub issue titles but with questionable success. The results are perhaps remarkable for uniformity but often generate comically long names wrapping multiple lines.

Jump right in with: $ runme branchGPT (install via Homebrew or Scoop)

So what is a good, high-quality branch name? Do they matter since more contextual metadata goes into Pull Requests? In my mind, that’s a wildly subjective question. Here are some conventions devs are using:

The Prolific Prefixer 🤓

Prefixes come in different flavors. Work type description of what goes into a branch or nickname prefix to reduce ambiguity. Using a forward-slash / as a separator is an established convention. Some examples: admc/graph-colors, seb/exp-prophet, feat/replace-tink-with-cryptography, chore/upgrade-deps-for-next-lts, chore/eslint, hotfix/631-prod. Using multiple prefixes, e.g., seb/experiment/prophet, is not unheard of.

The Tireless Terser 💂‍♀️

Ideally, just one word, but no more than two. Examples are: fastapi, ingress, sharing, rollups, score-break, gtag-fix, vanilla, demo. You get the point. Keep it short and straightforward. Likely this convention won’t scale in a large mono-repo and without recycling the same branch name numerous times.

The Ruthless Referencer 🥷

Dependabot loves doing this. Stick as much referentially information, like JIRA or GitHub issue IDs, full titles, version numbers, etc., into the branch name. No matter how bulky. Humans do it too; look at these 277-update-breaks-score-contributor-to-be-consistent-with-others, ENG-422-open-vsx-stable-release, CORE-13128-retry-screen-for-password-recovery-flow-loops-endlessly. While the shorter ones are more common, folks don’t hesitate to generate branch names that easily exceed 150 characters.

Close to Home is Better

There are even more. However, here’s the kicker: there is no universally best convention to branch names!

You could argue that the right balance between minimum descriptive, not too short, and not too long is the way to go. However, it inevitably depends on your repos, team, and personal preferences. What universally holds is that the best branch names are the ones that feel natural and familiar to you.

If you had your Pull Requests merged before, you might already be recording information in your git log so that a Transformer AI model, namely GPT, can harness to suggest branch names for you. A merge commit is just about perfect (see further below) to seed the layout of your branches.

Enter BranchGPT

This is why we’ve built this handy integration between your branches and OpenAI’s GPT3/4 for you. Perhaps call it BranchGPT… for no apparent reason 😉. Yes, I am trying to take AI over the top.

The idea is simple and surprisingly effective. Just enter a free-flow description of what you’re working on and let BranchGPT come back with some suggestions. If you can’t think of a good example for testing. There’s always @iamdevloper on Twitter to help you out:

Tweet here: https://twitter.com/iamdevloper/status/1609848459489599489

It’s May 2023, so it's just about the “last call” to update the website’s 2022 footer! Drop the loose description into BranchGPT, and voilà, you’ll be presented with a list of suggestions that should ideally look strangely familiar. Check out this demo below; $ runme branch will do if you find branchGPT too long.

💡 By the way, runme will prompt you to log in with your GitHub to create an account (privacy policy)

Both length and seb/<description-goes-here> feel familiar using my usual layout.

Adding Some Polish

Suppose the suggestions aren’t quite ready. It’s straightforward to toggle the prefix in the branchGPT terminal UI, just hit t to toggle prefixes. Similarly, the e key will transition the selected entry into edit mode to allow putting the final touches on it.

Toggle prefixes with t and edit the selected entry with e.

How It Works

Under the hood, BranchGPT processes the context repo’s Merge Commits. Starting with the configured git users’ personal merge commits. If there aren’t any, it will fall back to all available merge commits in the repo before using a fixed list. The latter will produce suggestions that will feel the least personalized.

Why Merge Commits? Check out the example listing below. You will recognize how commit messages encode branch names (with GitHub org prefix) alongside textual descriptions. Just about perfect for seeding data for a GPT prompt backed by OpenAI’s curie engine. Curie provides a fair tradeoff between capabilities and cost.

The list is usually longer; however, shortened for brevity

Outside of authentication, basic rate-limiting, pre- and post-processing, and checking all implementation boxes on OpenAI’s API guidelines, that’s it. We hope you’ll like it.

The Wishlist

BranchGPT came out of experimentation, and I'd consider it alpha software. A few things I wish we could have added in this version but time's limited:

Close the feedback loop on suggestion edits. We chose to keep it simple and treat all data as ephemeral.
A fine-tuned model for generic branch suggestions that lack a list of personal/repo merge commits.
Leverage models that derive branch names from code diffs. It’s too common to come up with a branch name after coding and when ready to create the PR—been meaning to look into https://carper.ai/diff-models-a-new-way-to-edit-code/ and other models.
Choose the GitHub issue to be copied into the prompt from a list of issues assigned to you.
UX Integration into Runme’s VS Code Extension. Let us know if this is something you want.
Experiment with a chat-like UX. We had built this experiment before the release of chatGPT’s APIs.

Now, go ahead and take BranchGPT for a spin. Please be a good citizen. The APIs are running under our OpenAI account (including footing the bill), and we intend to continue making BranchGPT available to the community with our best efforts. Thank you!

$ scoop bucket add stateful https://github.com/stateful/scoop-bucket.git # on Windows
$ scoop install stateful/runme; runme branchGPT
  # or
$ brew install stateful/tap/runme && runme branchGPT # on macOS (homebrew)

Full install instructions here. Note that runme branch and runme branchGPT are the same.

Closing Thoughts

Writing this post, one question I wish I had more color on: Do Merge Commits have a bad rep? Most folks I have asked sorted into the Squash & Merge™️ or Rebase & Merge™️ camps. Who else appreciates Merge Commits? Just me? Tell us on Discord or ask about a feature request. For more content like this, please subscribe to our email updates.

Hopefully, BranchGPT will make you like Merge Commits more 😆.

Extension to directly run code blocks from your markdown editor

Sebastian Tiedtke — Thu, 27 Apr 2023 19:54:35 +0000

Makes it straightforward to execute blocks directly inside the editor. And, what's even more convenient is that any changes made to the environment stay with successive runs.

💡 Search "runme" in the Extensions tab or install here

Let me know what you think! Read more about the feature in the docs: https://runme.dev/docs/features#run-a-command-block.

Visually explore OpenAI's Image APIs without coding custom UI

Sebastian Tiedtke — Wed, 19 Apr 2023 01:56:39 +0000

While chatGPT has been all the craze, OpenAI’s underlying APIs offer much more. Outside of GPT4, the core piece to chatGPT, OpenAI provides AI Image-Generation APIs under the DALL-E umbrella.

💡 OpenAI’s description: DALL·E 2 is an AI system that can create realistic images and art from a description in natural language. 👉 https://openai.com/product/dall-e-2

These APIs are plain amazing…! They allow you to take an existing image and describe in words what edits you’d like the AI to make for you. It's like magic!

🙌 No UI Coding Required

Edit a ball pit into the image? Easy!

You can learn how to use DALL-E's APIs without writing custom code. We'll showcase this using Runme, which lets you create Markdown notebooks with interactive Shell commands, similar to Jupyter for Python.

🛠 Please give Runme a spin, install here or search runme inside VS Code

My dog Luna 🐕 offered to help us make our point! Right below, you’ll see Luna at a doggy friend’s birthday party in real life. All we’re using is a simple scene prompt: “a happy german shepherd dog surrounded by cheeseburgers”:

Unedited image of Luna

No way Luna would sit this calmly if those cheeseburgers were real 🤭

👩‍💻 Try It Yourself

Head to https://platform.openai.com/ to get an API key and follow our Runme notebook. Depending on how much you plan on using the API, OpenAI puts a limit on its free tier.

The repo with the notebook is available here: https://github.com/sourishkrout/loon

🖥 Skip The Notebook, Use The CLI

If you live in the terminal, use the Runme CLI instead. After you clone the repo, drop your OPENAI_API_KEY=<super secret> into your environment. Then, do this:

$ runme run --filename AI.md install-deps
$ runme run --filename AI.md run-scene | jq -r ".data[0]" # btw, output URL expires
{
  "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/org-tm5BAbynhBsE9Lzy1HTD6sk0/user-7A9nqIQ8tVXN7epnIqZs6fca/img-Hc1KHk6lkJegAkMqUWSL9D0i.png?st=2023-04-18T13%3A56%3A07Z&se=2023-04-18T15%3A56%3A07Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=6aaadede-4fb3-4698-a8f6-684d7786b067&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2023-04-18T11%3A36%3A32Z&ske=2023-04-19T11%3A36%3A32Z&sks=b&skv=2021-08-06&sig=9oEyq1os4zwf6rvb67W1rPDkTsPd%2BZ%2B1VHi/gWaz17M%3D"
}

Most terminal emulators will allow you to click the URL to open it in a browser. That's it!

🌠 Make Your Own

We've explained how to use your images within the Runme notebook. The originals are also included with the notebook in the repository. Interestingly, the more background you mask (let the AI know what not to preserve), the more drastically the AI morphs the scene. Let us know what you think. You can find us on Discord. Please drop by and share one of your own DALL-E impressions!

Thank you.

Integration testing docs in GitHub Actions

Sebastian Tiedtke — Thu, 30 Mar 2023 01:53:32 +0000

Learn how to test your docs in CI/CD with Runme's latest v1.0 release, which comes with new cool features you can utilize to deliver seamless developer experience. We will leverage Runme's new kernel architecture enabling seamless interoperability between notebook and terminal UX.

⏯ Never heard of Runme before? It's an open source toolkit that let's you run your README.md and other markdown docs in both terminal and as runnable notebook inside VS Code. Check it out.

Integration testing docs in GitHub Actions

Let's See How

Let's jump right into a showcase. A “thank you” goes out to our friends at Buoyant (creators of Linkerd, the open-source service mesh), who openly maintain Linkerd’s docs in Markdown. That same Markdown generates static HTML on their website for developers to copy commands into the terminals. It turns out that Linkerd’s Getting Started Guide makes a great real-world example illustrating how to harness Runme in CI/CD (with minimal to no edits).

Markdown docs are everywhere describing Developer Experience

The End-to-End Demo

While you could watch the GitHub Action running in real-time, we can’t guarantee that the GitHub Action is running at all times, so we created a video. The time-lapse video (eventual consistency in Kubernetes takes time) illustrates side-by-side what’s going on when testing Linkerd’s Getting Started guide and Kubernetes cluster state. This exact setup will be executed inside a CI/CD job.

Full end-to-end demo as time-lapse video

Inside of GitHub Actions

Once packaged up in a Github Action workflow, running on every commit is just a matter of configuration. Go ahead and send a PR to follow along in real time! It’s all public:

Live at https://github.com/stateful/linkerd-website/actions/workflows/dx.yml

For the curious ones, you can find the details of how we wired up the GitHub Action’s workflow with GCP and Runme inside the repo. The hard part’s done. Now, in about 5min after a commit, you will have assurance (watch out for that 🟢 light!) whether or not the Getting Started Guide still works and your Developer Experience remains intact.

Breaking It Down

Before getting into improvements, let’s take a closer look at the moving pieces of this demo. Linkerd (version 2) is a Kubernetes-native service mesh. We will need a functioning cluster to test the Getting Started Guide via the Linkerd CLI. There are many permutations of CI/CD and cluster setups/provider combos. We won’t be covering them.

Tools and Infrastructure

Instead, we’ve chosen well-known and established ingredients to keep it simple. The setup:

Standard Kubernetes Cluster in Google’s GKE: 3 nodes with 2 CPUs & 2 GB memory each
Bats (Bash Automated Testing System) plus assertion libraries for kubectl
GitHub Action that handles scheduling/queuing of subsequent jobs against shared cluster

Anatomy of a Test Case

The idea is as simple as compelling. Runme’s CLI allows referencing code snippets by name (explicitly defined in command block annotations for clarity). This mirrors precisely what’s being presented to developers on the website’s Getting Started section to copy & paste into their terminals. It goes without saying that Runme’s UX is much more elegant than copy & paste.

Asserting Test Conditions

Inside our Bats files, we replicate the sequence of steps and the contained instructions as test cases. We can define pre-conditions, execute the Markdown command block, and check post-conditions for returned exit code, output, and desired Kubernetes cluster state. The Bats DETIK assertion library does a phenomenal job of expressing Kubernetes assertions fluently. Bats is also capable of handling the setup and teardown of a test suite. Feel free to ask us about the details.

@test "Verify linkerd injection (step 4)" {
  DETIK_CLIENT_NAMESPACE="emojivoto"
  run "runme run kubectl-get"
  assert_line -p "deployment \"emoji\" injected"
  assert_line -p "deployment \"vote-bot\" injected"
  assert_line -p "deployment \"voting\" injected"
  assert_line -p "deployment \"web\" injected"
  try "at most 10 times every 30s to get pods named 'emoji' and verify that 'status' is 'running'"
  try "at most 10 times every 30s to get pods named 'vote-bot' and verify that 'status' is 'running'"
  try "at most 10 times every 30s to get pods named 'voting' and verify that 'status' is 'running'"
  try "at most 10 times every 30s to get pods named 'web' and verify that 'status' is 'running'"
  assert_success
}

While Bats will support parallel execution, we want these test cases to run serially in a predetermined order. Humans run one command at a time. And, in stateful nature, downstream execution results depend on completing prior commands. While your run-unit-tests-in-parallel-self might object at first, this is, in fact, a good thing. It replicates how developers consume software docs in reality.

The same idea is transferrable to e.g., internal repos that house libraries, apps, or services. Imagine every repo’s README.md, BUILD.md, or DEPLOY.md being tested this way.

Let Us Know What You Think

While we’re happy with our demo’s results, there is much room for improvement. Here are some items we have discussed and would love your feedback on:

Leverage notebook-serialized cell output for test assertions? The idea is to record cell outputs stored alongside the inputs and provide the functionality to define common assertions, e.g., substrings, expected exit code, or fuzzy threshold diffing.
Runme-integrated test-harness? While Bats fits the demo’s use case well, it is likely desirable to use Runme’s notebook parser and structural awareness to maintain a test suite inside of notebooks instead of describing them separately, in this case, *.bats files.
Provide an official Runme Github Action for easy integration? Significantly reduce boilerplate, ideally where the workflow auto-detects Runme-enabled Markdown files inside of the repo and runs the associated test suite.

The common theme in the ideas above is to absorb commonly required capabilities to express test cases into Runme and minimize overhead. Unlock docs testing value faster. The better we understand your use cases, the more effectively we can evolve Runme following this philosophy. Please, we urge you, get in touch!

Get Involved

Outside of CI/CD-related features, the team is currently heads-down working through Runme's final touches of the Notebook Terminal output UX (experimentally available for non-interactive and background tasks) directly inside your READMEs. Beyond that, our roadmap is full of UX improvements, big and small, to continue streamlining the daily workflows of developers.

Now go try it out and help us prioritize! We’d love to hear what you think. If you run into any problems, please don’t hesitate to report them as a GitHub issue or talk to us on Discord.

Happy Docs Testing 🤩!

Runme: Road to Testable Docs

Sebastian Tiedtke — Wed, 21 Dec 2022 02:35:09 +0000

Today, we are excited to ship Runme v0.4 adding notebook authoring capabilities. The first intermediate step on the road to v1.0. Make changes to your existing READMEs, execute your commands, save and share with your fellow developers. Or, just create a brand new Runme notebook from scratch, saving changes as you go. Runme notebooks are 100% markdown-compatible and the best choice to document your repo’s development environment. Here’s how:

Open source toolkit for reliable docs

If you haven’t used Runme yet, it is really neat. It will let you open your README (any markdown file really) as an interactive notebook. Stay focused and save time by clicking ▶️ next to commands to intuitively execute the commands and forget about copy & paste. All open source. No changes required to your markdown, install, open README.md, and go! Keep reading to learn more about this release and what’s planned for Runme v1.0.

No More Broken Docs 👉 Roadmap to v1.0

Runme’s vision is to provide a flexible - open source - toolkit to deliver testable docs.

More at https://runme.dev/

In Runme’s initial release a few weeks back, we decide to forgo “full notebook editing” to ship faster and learn from users. We've done our homework and came up with a plan. For Runme's v1.0, to achieve testable docs, we are planning the following:

Full editing inside ✍️ of Runme notebooks (v0.4 ✓)
Shared session-state 💻 between notebook & terminal
Elevate ergonomics 👩‍💻 inside notebook UX

Read more about the detailed breakdown of above's line items at https://www.stateful.com/blog/runme-road-to-reliable-docs as well as GitHub Projects boards to track progress. ETA for v1.0 is planned for February/March 2023.

Check it out!

If you haven’t yet, now is a good time to give Runme a spin at https://runme.dev/. You’ll be surprised how quickly it will replace your old markdown editor and associated habits.

Stay tuned! Thank you.

But it works on MY machine! Debugging GitHub Workflows with VS Code

Sebastian Tiedtke — Mon, 21 Nov 2022 20:17:11 +0000

Any developer is probably familiar with the “flip the table” moment, when the well crafted test that you’re ready merge into main fails with an error related to the CI environment. Why why why.

Please don't try this at home, seriously don't

Generally unit tests are less susceptible to this kind of failure, but as you add more layers of abstraction around your application or for integration testing things become increasingly brittle. Especially end-to-end tests are sensitive to the often absent GPU in CI workflows. The added complexity and the remote nature of CI jobs make the process of debugging difficult, slow, and cumbersome.

This problem is particularly important to us in our development experience at Stateful, because we are constantly pushing the boundaries of VS Code extensions and want end-to-end confidence when shipping every release. While our extensions tests technically run in a consistent “VS Code environment”, the reality is that VS Code can behave very differently depending on how it’s being used, particularly when running as Electron as opposed to a browser-based webapp on consumer hardware, data center servers, or, what’s even more likely, inside a container leveraging a virtual frame buffer (e.g. xvfb).

👉 Use via Github Marketplace

Attach VS Code to your running Github workflow

Fortunately, a great solution just became available that utilizes VS Code’s ability to connect to remote workspaces. Using the Visual Studio Code Server you can configure your Github workflow to start a VS Code server process that makes it easy connecting to the remote workflow execution to debug the problem. Yes, this sounds slightly mind-bending, however, you will indeed be able to use a hosted VS Code instance to tap into a running GitHub workflow. The VS Code Server leverages tunneling to connect both remote instances, the running workflow and the hosted VS Code web UX, transparently. Here’s how we made this super easy for you:

We created the stateful/vscode-server-action GitHub action to take advantage of a Github Action’s lifecycle hook to just trigger a VS Code session when your tests fail. This action provides you with a configurable time window how long after tests failed you will be able to connect to the machine. If you don’t connect in time, the workflow continues. Here is an example how you can apply it in your workflow:

jobs:
 test:
   name: Test
   runs-on: ubuntu-latest
   permissions:
     actions: read
     contents: read
   steps:
   - ...
   - name: 🧪 Test
     run: yarn run test
   - name: 🐛 Debug Build
     uses: stateful/vscode-server-action@v1
     if: failure()

In the event of a failed build the action attempts to start a VS Code Server on the build machine and requests your authorization:

To grant access to the server, please log into https://github.com/login/device and use code 0328-F81A

If you don't authorize the machine until the timeout is hit, the build just continues. However if you do, a VS Code Server is started and it prints an URL to connect to, e.g.:

Open this link in your browser https://insiders.vscode.dev/+ms-vscode.remote-server/myMachine/github/workspace

You can also connect to it through your local VS Code application. Just open the URL, open the command palette and enter Open in VS Code. And voilà you are connected to GitHubs machine and can start debugging your tests:

Try this at home instead: Fully integrated demo of the Github Action

This little action has helped us tremendously when it came to drilling into issues that only seem to occur in Github's CI. It's probably not hard to adapt the approach for other CI/CD platforms and serves as a poster-child how convenient and powerful VS Code remote debugging is.

👉 Use via Github Marketplace

One caveat is that bringing up the VS Code Server is currently coupled to Docker which does not allow it to be used with Windows and Mac runners (yet). We’re tracking an issue to unlock support for non-Docker environments.

Thanks for reading! Happy debugging and let us know how it goes. Either join Discord or file an issue on Github.

Run your README.md like a notebook in VS Code

Sebastian Tiedtke — Thu, 20 Oct 2022 01:21:00 +0000

💡 TLDR; Runme's project website's got the cliff notes for you: https://runme.dev/

In our ongoing efforts to make documentation more reliable and less susceptible to bit-rot, we released the runme CLI (renamed from rdme) back in August. The CLI lets you effortlessly execute shell blocks inside your README.md docs from the terminal. We’ve been pleasantly surprised how well it was received. Thank you all for the comments and feedback!

Zero-changes required to turn your README.md into a runnable notebook

Today we want to take Runme a step further and break out of the confides of the terminal. Anecdotally (yet not the sole motivator) one of the more notable comments in response to the runme CLI (renamed from rdme) was this:

💡 Install Runme from the VS Code marketplace or search runme inside of the Extension Panel

The point’s well taken! We wholeheartedly agree that it’s important to READ your README.md before running the commands it describes. With today’s Runme release, this just got a whole lot easier:

Literally execute your README.md by simply clicking play buttons

Breaking Out of the Terminal

We wanted to expand beyond Runme’s CLI implementation to:

Enable contributors to both learn about and interactively run docs
Empower maintainers to control and curate the developer execution experience
Encourage contributors to make suggestions about the Readme experience

We took a good look around and found inspiration in the Data Science Community: DS loves Jupyter Notebooks! Notebooks elegantly interleave code, computations, numbers, and narrative to lean on the dynamic where scientists prepare notebooks that can be consumed without much fuss by anybody.

Longer clip at https://www.codecademy.com/article/introducing-jupyter-notebook

A notebooks inherent ability to reevaluate (literally run) every paragraph (input & output cells), in a low-code fashion, naturally aids a reader’s comprehension of the information laid out in front of them. This enables improvements to notebooks to be easily upstreamed using Pull Requests as notebooks live in version-tracked repos.

Bingo 💡! It turns out that repo maintainers and contributors have a similar relationship to the DS community when it comes to technical documentation.

From README to RUNME

After a fair amount of experimentation, we decided to build a VS Code Extension UX on top of the Runme parser. This extension will now make your README.md (onboarding and runbook docs) available within a VS Code powered Notebook Experience requiring zero changes to the underlying markdown. To showcase an end-to-end example, we’ve assembled a repo https://github.com/stateful/runme.dev (backing https://runme.dev) using Deno’s Fresh web framework, a CMS, testing, and deployment. Here we go:

💡 Install Runme from the VS Code marketplace or search runme inside of the Extension Panel

Execution Controls and More

Runme transparently parses README.md files into its constituents sequences (arbitrary markdown) and executable blocks (e.g. shell) that describe your apps and services.

Leveraging VS Code’s Notebook APIs (that underpin notebook rendering) Runme displays your README.md (or any other markdown file) as an input & output cell in a notebook.

Forgo tedious copy & paste with notebook-style run controls

These notebook entries enable:

Per block execution controls
Shell support & terminal integration
Basic ENV support across notebook cells

Curate Your Notebook Experience

Attributes let maintainers control various aspects of the Developer Experience via simple annotations (full list available here) inside your README’s code blocks. Ordinary markdown viewers will just ignore them. Sharing and merging in notebook changes is just a git clone, git push or a pull request away.

Annotate your fence code blocks to curate your shell execution

Beyond Shell and Terminal

To provide broad compatibility with existing READMEs and their potential usage of CLI tooling we chose to first unlock shell execution in Runme Notebooks. However, just like Jupyter has first-class integrations with plotting libraries and other rich visual renderers, we saw an opportunity to enrich the UX by going beyond the text representation and bring in rich web experiences.

To showcase how this will work, we started with our friends at Deno 🦕:

Deploy to both Deno's preview and production with ease

We are envisioning a world where instead of logging into dispersed cloud web consoles (made available by service providers), you could just drop a web component into a cell that exposes a programmable UX for different parts of their APIs inside of your Runme Notebook. We believe that this approach has lots of potential to lead to a more concise and maintainable way to document full stack applications and services.

What do you think?

Interoperability With the CLI

While we believe that Runme Notebooks will provide a much better onboarding experience for new contributors, we understand that maintainers and power contributors may want to skip ahead. The same is true for execution inside of CI/CD, which is why we designed Runme to function in a headless way via the runme CLI.

Interoperability with CLI

We are still experimenting with UX and deciding where to draw runme's architectural boundaries and working to achieve broader interoperability (e.g handling ENV vars in the CLI). One of our goals is to maintain a symbiosis between CLI and Notebook implementations to achieve the best possible Developer Experience for reliably runnable documentation.

💡 Install Runme from the VS Code marketplace or search runme inside of the Extension Panel

Get Involved

We chose to release Runme early as an invitation to the dev community to participate in it’s on-going development. Both the extension and CLI are still under heavy development and haven’t yet undergone extensive battle testing. Please send us bug reports and feature requests if anything gets in your way.

Here are a few known limitations you should be aware of in this alpha release:

Notebooks are currently read-only, to modify your notebook please edit the underlying Markdown/README.md as text file. We absolutely want to support bidirectional editing in the future.
Be cautious with environment variables interleaved within code blocks. The stateful execution of the notebooks (shell/bash-only; no PowerShell on Windows yet) leverages a naive implementation where the VS Code extension prompts for ENV var values and attempts to expand them. In essence, it does not match an interactive bash/shell session (yet).
We continue experimenting with aspects of user/developer experience including the passing of information/variables from cell to cell, ENV var handling that more closely matches shell a session, and more robust markdown handling.

Come find us and let’s chat about Runme (here’s my email or join discord), we are excited to hear your thoughts!

Thank you.

Go for the streak and celebrate progress 🏆: Strava for VS Code

Sebastian Tiedtke — Thu, 29 Sep 2022 02:49:23 +0000

Athletes use exercise watches and apps like Strava (or Runkeepr) to measure and challenge themselves to grow, and we’ve been experimenting with ways to unlock similar kinds of value for developers. Think of your codebase or projects as the roads you’re running, VS Code as the Apple or Garmin watch, and Stateful as the Strava that helps make your data organized and easily digestible.

Go for the streak and celebrate progress 🏆

As you code you will unlock milestones, enter streaks (language usage, scores, ratings and more) and have the opportunity to high-five yourself and others.

Pace yourself with the real-time score 🔥

Your score is based on best practices and customizable contributors. Keep an eye on your score to understand how your coding day is going and change course if needed.

Unpack your metrics, and setup the next day 📈

Dive into your coding metrics, including: activity, score, self ratings and forecasted “ideal” coding blocks. As your day is wrapping up, Stateful will effortlessly prompt you to reflect on the day, select your star rating and jot down a few notes as reminder for where to pick things up tomorrow.

Check in with yourself 📃

Explore daily, weekly and monthly summaries of your coding activity. No-brainer standup reports are delivered via notification just in time for your team meeting. Standup reports bring together rolled up progress since your last meeting, git tree activity, and the notes / todos you created right from the code editor.

Maximize your focus time 🤫

Stateful can automatically mute Slack notifications when your editor activity indicates that you are focused. Let others know where you are focused by sharing a custom coding status inside Slack.

Connect and motivate your network ✌️

When you and someone else on Stateful are working on the same repo, we encourage you to follow each other and give kudos to support their achievements.

Try it out!

You can install the extension by searching for stateful in the VS Code extensions panel, or through the VS Code Marketplace. It only requires that you authenticate with Github and within 15 minutes you will have access to your dashboard.

What do you think?!

We would like to hear from you. Do you like this? What do you want to see more or less of? What could we build to help you be more efficient, productive or happy?

Join our Discord and let us know please.

Thanks for reading.

DEV Community: Sebastian Tiedtke

ENV vars are like needles in a haystack, aren't they?

Owl Store: A Type System for Environment Variables to Specify, Resolve, and Verify Correctness

Sebastian Tiedtke ・ Dec 10

Owl Store: A Type System for Environment Variables to Specify, Resolve, and Verify Correctness

Let's Start With A Demo

Why is this hard?

Crossing the Dev vs. Ops Chasm

GitHub/Gitlab: Take My Bargaining Chips

Enter the Owl Store 🦉

A Complete Solution That's Unfinished

Blobs of KEY=VALUE Strings Running the World

Good Luck Running a Monolith Locally

❌ Invalid Environment

✅ Valid Environment

Desired State: Description of Environment Variables

Flexible Configuration Frontends

Multiple Resolution Paths & Mechanisms

Variable Visibility and Validation

Lifecycle over Time

Interactive Resolution

Takeaways

Under the 🦉 Owl Store’s Hood

The Importance of Strong Identity

Redefining the Relationship between Workload, Repo, and Environment

Declare Variables Spec Types via Annotations in .env.example

The Graph Inside Out 🦉

GraphQL but no “Data API”

Space + Time + Chaining

Query Construction & Execution

What's Next

Get Involved

AWS/GCP/Azure Consoles, Embedded inside Your Docs

Best of ClickOps Without Downsides

How It Works

Navigating Cloud Resources in Docs

Expanding of Listings

Follow-up Actions on Resources

Zooming in and Out of Details

Interpolation & Variables for Generic Docs

Example Workflow Docs with Runme & Terramate

Try It Now – Feedback Welcome

Runme Gist: A Pastebin for Terminals Inside Your Docs

Runme Gists Are Masked 🎭 By Default

🤖 No Copy & Paste and No Other Third Party

🚀 How It Works

Runme Gist 🤩 Inside Your GitHub

That’s it 💪

BranchGPT: The AI-Powered Solution to Personalized Branch Names

Why BranchGPT?

The Prolific Prefixer 🤓

The Tireless Terser 💂‍♀️

The Ruthless Referencer 🥷

Close to Home is Better

Enter BranchGPT

Adding Some Polish

How It Works

The Wishlist

Closing Thoughts

Extension to directly run code blocks from your markdown editor

Visually explore OpenAI's Image APIs without coding custom UI

🙌 No UI Coding Required

👩‍💻 Try It Yourself

🖥 Skip The Notebook, Use The CLI

🌠 Make Your Own

Integration testing docs in GitHub Actions

Let's See How

The End-to-End Demo

Inside of GitHub Actions

Breaking It Down

Tools and Infrastructure

Anatomy of a Test Case

Asserting Test Conditions

Let Us Know What You Think

Get Involved

Runme: Road to Testable Docs

No More Broken Docs 👉 Roadmap to v1.0

Check it out!

But it works on MY machine! Debugging GitHub Workflows with VS Code

Run your README.md like a notebook in VS Code

Declare Variables Spec Types via Annotations in `.env.example`