Migration guide

Migrate GitHub Actions to Runnable, one workflow at a time

Keep GitHub as your source of truth while Runnable runs Actions-compatible YAML through its own scheduler and Linux machines. Start with one small CI workflow, compare both systems, then move the checks your team relies on.

Choose a safe first workflow

Start with a Linux build or test workflow that has a clear pass or fail result. Leave deployments and required branch checks for later in the pilot.

Check	What to verify before migrating
Runner	The job uses Linux x64. Runnable does not currently run Windows, macOS, ARM, or native job `container:` syntax.
Actions	Checkout, cache, and artifact actions have native support. Other JavaScript, composite, and Docker actions need their referenced metadata and runtime checked.
Credentials	List every secret, variable, and OIDC audience the job needs. Configure matching scopes in Runnable before the first live run.
GitHub permissions	The GitHub App installation must grant the scopes requested by the workflow. Runnable does not silently widen a job token.

Paste the existing YAML into the free compatibility checker for an initial verdict. A pasted file cannot resolve every local or remote action. The connected-repository scan checks the action metadata and reusable workflows at their referenced revisions.

The first change can be the file location

Runnable discovers .yml and .yaml files under .runnable/workflows on the repository default branch. Begin with familiar Actions syntax, then change only constructs called out by the compatibility report.

.runnable/workflows/ci.ymlYAML

name: CI
on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  checks: write

jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: npm test

For this example, copy the contents of .github/workflows/ci.yml to .runnable/workflows/ci.yml. Keep the original file during the pilot. Both providers can run on the same push and pull request, producing separate checks for comparison.

A valid YAML file is not a complete compatibility verdict

Expressions, local actions, reusable workflows, permissions, and external services may require repository context. Resolve every Partial, Runtime-dependent, or Unsupported diagnostic before relying on the migrated workflow.

Let the migration assistant make a reviewable pull request

The assistant scans .github/workflows on the default branch and copies only eligible workflows. It leaves the original GitHub Actions files in place.

1
Connect the repository
Install the Runnable GitHub App, select the repository, and let workflow discovery finish. See GitHub setup for the required grants.
2
Run the compatibility scan
Open the repository in Runnable and scan its GitHub Actions workflows. Review each diagnostic; only Full candidates are eligible for the migration pull request.
3
Review the proposed files
Create the migration PR and check the new files under .runnable/workflows. Confirm triggers, runner labels, requested permissions, secrets, and any environment approvals before merging.
4
Merge one small workflow
Merge the PR. Runnable discovers the new definition from the default branch; the existing .github/workflows file remains active.

You can also copy a workflow manually. The same compatibility and credential checks still apply. See the workflow reference for supported syntax and explicit limits.

Run both systems and compare the evidence

A parallel pilot shows whether the migrated job behaves as expected before you change required checks or disable the GitHub Actions copy.

Compare	What to look for
Triggers	A push, pull request, or manual dispatch creates the expected Runnable run; filters admit the same intended changes.
Result	Compare the job conclusion and step logs, including failure behavior and reruns.
Outputs	Check artifacts, cache behavior, test reports, deployment URLs, and any downstream job outputs the team uses.
Authority	Confirm requested GitHub permissions, fork behavior, secrets, and environment approvals before moving a privileged workflow.

An outage boundary has limits

Runnable does not use GitHub Actions to plan or run jobs. GitHub-backed repositories still need GitHub source and installation APIs for new events, checkout, and Check Runs. A GitHub-wide API or Git outage can delay those paths.

Switch required checks only after a successful pilot

Move one workflow at a time so the team always has a known working path.

1
Choose the authoritative check
After representative runs agree, update branch protection and deployment gates to require the Runnable check you verified.
2
Avoid duplicate work
Narrow or remove the matching GitHub Actions trigger only after the new required check is stable. Keep the original file available until the cutover is complete.
3
Rollback if needed
Restore the previous branch protection rule and GitHub Actions trigger, then inspect the Runnable run and diagnostics before trying again.

NextCompare Runnable and GitHub ActionsSee the operational boundary, supported platforms, and cost of an independent CI path.