Integrations

Previously, you learned the basic editing tools for creating and editing README files.

In this guide, you'll be exposed to a few ways you can integrate Runme with different environment or 3rd party services.

Embedding GitHub Actions

💡 Be sure to install Runme for VS Code first

GitHub Actions provides a robust and flexible continuous integration and continuous delivery (CI/CD) platform for automating various tasks within your development lifecycle (build, test and deployment), ultimately empowering you to focus more on writing code and less on repetitive manual processes. One building block of GitHub actions is Workflows, a YAML file describing an automated process that will run one or more jobs.

Workflow types

• Events that occur in your workflow's repository
• Events that occur outside of GitHub and trigger a repository_dispatch event on GitHub
• Scheduled times
• Manual

Currently, Runme only supports manual workflows; they are helpful to trigger jobs on demand, some common use cases are:

• Targeted releases: Deploy specific versions of artifacts to specific environments (production, testing, staging) on demand or after thorough testing or approval.
• Overwrite a scheduled task workflow: Sometimes, you may want to override the schedule and trigger the workflow manually.
• Trigger a testing pipeline: Initiate specific code or infrastructure verification testing workflows. This allows developers or quality assurance teams to trigger comprehensive tests when needed, ensuring adequate coverage.
• Incident response: Reduce risk during an incident by triggering an incident response workflow. It helps mitigate the problem by including diagnostic scripts, notifying the immediate response team, or initiating remedial action.
• User Interaction Workflows: GitHub Actions can be triggered manually to facilitate user interactions, such as starting a build or initiating a specific process based on user input. Useful for workflows involving user requests, feedback, or custom actions.
• Experimental or One-off Tasks: Sometimes, you may need to run a workflow for an experimental or one-off task that doesn't require automation or a predefined trigger. Manually triggering the workflow provides flexibility in executing such tasks.

In general, being able to run a GitHub Action manually gives you control over workflows by adding an extra layer of flexibility to your CI/CD and automation processes.

How to use it

Use the workflow_dispatch event to specify your manually triggered workflow, you can optionally specify inputs that are passed to the workflow. The triggered workflow receives the inputs in the inputs context

See an example of a manually triggered workflow:

name: My manual worfklow
on:
  workflow_dispatch:
    inputs:
      releaseVersion:
        description: "Runme release version"
        required: true
        type: string
        default: latest
      releaseType:
        description: "Release Type"
        required: true
        type: choice
        default: "patch"
        options:
          - patch
          - minor
          - major
      releaseChannel:
        description: "Release Channel"
        required: true
        type: choice
        default: stable
        options:
          - stable
          - edge
      publishMarketplace:
        description: "Publish on Visual Studio Marketplace?"
        required: true
        type: choice
        default: "yes"
        options:
          - "yes"
          - "no"
      publishOpenVSX:
        description: "Publish on Open VSX Registry?"
        required: true
        type: choice
        default: "yes"
        options:
          - "yes"
          - "no"

jobs:
  release:
    runs-on: ubuntu-latest
    env:
      REPOSITORY: runme
    steps:
      - name: Print inputs
        run: |
          echo "${{ toJSON(github.event.inputs) }}"

The above YAML file, specifies a simple manual triggered workflow file with inputs: releaseVersion, releaseType, releaseChannel, publishMarketplace, publishOpenVSX, and a job that prints the values for each input in JSON format.

Use Runme to trigger a manual workflow

Currently, there are two ways to indicate Runme to run a GitHub Action:

• GitHub repository source URL https://github.com/organization/repository/blob/main/.github/workflows/workflow.yml
• GitHub workflow URL https://github.com/organization/repository/actions/workflows/workflow.yml

If you paste an URL following any of those formats in any markdown file, Runme will understand you want to run a manually triggered GitHub Action. If the file specifies inputs, a convenient form is displayed to specify the values, they will be displayed according to the type of input:

• Choice: Drop-down list
• String: Input text

To execute the action, you need access to the repository and sign in using your GitHub account by authorizing Runme from within VS Code

Once you are authenticated, you should be able to see the workflow file like the following:

In the above example, we have a workflow action with inputs, once you specify them, you can click Run Workflow to trigger the action. Once you trigger the action, you will see in real-time the status of the execution of the workflow, just like the original GitHub action interface.

If you click Open workflow run, a browser window will be opened with the detailed logs of the triggered workflow

Sidenote

In a future version of Runme, we plan to display workflow run details in real-time. We think Runme is a great companion of the official GitHub Actions extension.

Fresh App on Deno Cloud

The first example is in the fresh folder and sets up a fresh service with deno. You can manually check out this example by opening it with Runme.

Local Environment

Runme makes setting up your local environment a breeze! Here, you can see a few install scripts that will set everything up:

Sidenote

In a future version of Runme, we plan on only showing installers relevant to your current operating system/environment. Stay tuned!

Environment Variables

Runme can also be used to establish local environment variables for the current session.

Warning!

Environment variable support in Runme is currently a work in progress. We have a lot planned for supporting the environment/secrets in the future, so stay tuned!

Deploying

For a deploy script, such as the one below, running as a Background task is a great idea, since it is a long-running script.

Next.js App on Vercel

This example can be found in the vercel sub-folder. You can manually check out this example by opening it with Runme.

Setup/Environment

Similar to the last example, we can do our setup, starting, and opening of the web browser using Runme:

Sidenote

In a future version of Runme, we'd like to support "execution groups," so that you can execute all of the above scripts in one go!

Authentication

Interactive terminals are perfect for providing a CLI login to the user:

List Projects

Remember, cells can capture the output of commands in non-interactive mode!

In this case, this can be used to get a list of the user's current registered projects with the Vercel platform.

GitHub Action for Workflows

Runme provides a GitHub action that allows you to seamlessly use the tool in CI/CD. It enables to re-use the workflows that your contributor use in CI/CD and therefore verifies that your contributing guidelines are still up to date.

Setup

In .github/workflows/test.yaml create a new file with the following contents:

name: Test Changes

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Clone Repository
        uses: actions/checkout@v2
      - name: Setup Node version
        uses: actions/setup-node@v2
        with:
          node-version: 18.x
      - name: Install dependencies
        run: npm ci
      # execute workflows through Runme
      - name: Build / Test Project
        uses: stateful/runme-action@v2
        with:
          workflows: |
            build
            test

Now, you can define what should be done for building and testing your project in e.g. a CONTRIBUTING.md and have your contributors be able to run the same flows through the CLI, e.g. via: runme run build test.