Ability to execute code from markdown
Proposal
Add the ability to execute code directly from GitLab Flavored Markdown.
The code to be executed could be written directly in markdown. The rendered markdown would show a checkbox or button; clicking it would execute the code.
Alternatively, the markdown could simply reference a job in the project's .gitlab-ci.yml
.
Code would be executed server-side using GitLab Runners.
Use cases
The most immediate use case is release orchestration. Release managers could build their release scripts using a GitLab issue; executing the release would be as simple as clicking through the various checkboxes/buttons in the issue. This would effectively be an "in house" alternative to using something like Jupyter Notebooks to manage releases (see #9427 (closed)).
Some other example use cases:
- Creating "mini features" that use GitLab's API, for example, a button that:
- moves all issues in the current milestone to a new milestone
- closes all issues older than 1 year
- creates a new release
- creates a new pipeline
- clones a project
- ... or anything else that can be done through the API
- Creating "help guides" to aid users in setting up their DevOps setup
- We'll market this as GitLab Recipes™. Naming credit goes to @mnichols1
😄 - For example, setting up environments or an npm package
- We'll market this as GitLab Recipes™. Naming credit goes to @mnichols1
- Anything else that can be automated with a script:
- Sending email notifications
- Sending texts using Twilio
- Turning on smart lights
- etc...
Intended users
Rachel (Release Manager) would be one of the first users to take advantage of this feature. However, this feature could be used by any user of GitLab.
Further details
Syntax
Stack Overflow does something similar with their "Stack Snippets", which allow code snippets to be embedded in questions/answers and run by an end user in their browser. They make use of a syntax like this:
<!-- begin snippet: js hide: false console: true babel: false -->
<!-- language: lang-js -->
console.log('Hello, world!');
<!-- language: lang-css -->
body {
background: orange;
}
<!-- language: lang-html -->
<h1>Hello, world!</h2>
<!-- end snippet -->
We could likely get away with a simpler syntax as we (probably) wouldn't need to embed multiple code files in a single snippet:
<!-- begin snippet: rb -->
puts "Hello, world!"
<!-- end snippet -->
Examples we would look to recreate:
- https://gitlab.com/gitlab-org/release/docs/-/blob/master/runbooks/sev-1-incident.md
- https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/release-candidates.md
Variables
When executing, a code snippet should have access to all CI/CD environment variables that are available to traditional pipelines.
Future direction
Some ideas for future work:
- Show code output in the rendered markdown. This would allow GitLab Flavored Markdown to behave similar to a Jupyter Notebook.
- Allow JavaScript code to be run in the user's browser, similar to Stack Snippets.
Permissions and Security
Executing code should only be available to users with Developer or higher permissions. This feature should not grant the user any additional abilities beyond what they already have access to through the GitLab interface or the API.
Documentation
We would need to update our GitLab Flavored Markdown page with details of how to create snippets through markdown.
Additionally, we could add practical examples of how to use this feature (for example, how to create a release management issue for automating releases).
Availability & Testing
Depending on the implementation, this feature has the potential to increase the load on our runners.
What is the type of buyer?
TBD, but most likely Core, as this would tie into our existing CI/CD system.