Skip to main content

Getting started with Morph Actions

Morph Actions lets your team keep GitHub-native workflows and move execution onto Morph-managed runners without redesigning your CI process. Install the Morph GitHub App, let Morph generate the migration pull request that updates your runner labels, merge that PR in GitHub, then use Morph to start eligible runs and inspect them from one org-scoped Actions surface.

GitHub still owns workflow files, event triggers, and pull request review. Morph adds the setup flow, repository visibility sync, migration PR generation, run dispatch for workflow_dispatch workflows, live run details, and CI analytics.

If you are a developer or platform engineer trying to get to a first successful run quickly, the shortest path is:

  1. Open Actions in the correct Morph org.
  2. Install the Morph GitHub App for the repositories you want to run on Morph.
  3. Let Morph open the migration PR and merge it into the branch your workflow actually runs from.
  4. Start a workflow_dispatch run from Morph, or wait for the next normal GitHub trigger.
  5. Use Runs, Run Details, and Analytics to inspect what happened.

Useful links:

What this page helps you do​

This guide is written for developers who want a practical first-success path. It will help you:

  • connect the right Morph org to the right GitHub repositories
  • understand exactly what the migration PR changes
  • validate the first successful run with minimal guesswork
  • know which parts of the workflow stay in GitHub and which parts move into Morph
  • troubleshoot the most common reason a run never appears in Morph

Before you start​

Have these ready before you begin:

  • A Morph Cloud account and an active organization
  • GitHub permissions to install the Morph GitHub App on the repositories you want to run on Morph
  • At least one GitHub Actions workflow in .github/workflows
  • A repository where you can review and merge the migration PR
  • A workflow_dispatch workflow if you want to use Start New Run immediately after setup

If you are choosing a repository for a first validation, pick one with a small workflow and a branch you can safely merge into. The first goal is not to migrate every workflow at once. The first goal is to prove that Morph can claim and run one representative job successfully.

Quickstart​

  1. Open Actions and confirm the correct Morph org is active. Expected result: GitHub App setup, repository visibility, Runs, and Analytics are all scoped to the organization you want to configure.
  2. Install the Morph GitHub App from the setup flow. Expected result: after GitHub redirects back, Morph can sync repository visibility into the active org.
  3. Choose a repository and let Morph generate a migration PR. Expected result: GitHub opens a normal pull request that changes eligible jobs to use the Morph self-hosted label set.
  4. Review and merge the migration PR in GitHub. Expected result: the branch your workflow actually runs from now contains the Morph runner labels.
  5. Start a run or wait for the next normal GitHub trigger. Use Start New Run for workflow_dispatch workflows, or wait for triggers such as push, pull_request, or schedule.
  6. Open the run from Runs. Expected result: you can inspect metadata, lifecycle events, and logs from the same Actions surface while the run is active or after it finishes.
  7. Switch to Analytics when you want the org-level view. Expected result: you can inspect CI summary metrics such as failure rate, queue time, and duration trends across runs.

What the migration PR actually changes​

Morph rewrites eligible workflow jobs to use Morph runner labels. A typical migrated job looks like:

jobs:
  smoke:
    runs-on: [self-hosted, linux, x64, morph, medium]

If you enable toolchain snapshots during setup, Morph appends toolchain:

jobs:
  smoke:
    runs-on: [self-hosted, linux, x64, morph, medium, toolchain]

Current runner shapes map to:

  • small: 2 vCPU / 4 GB RAM / 40 GB disk (3 MCU/hr)
  • medium: 4 vCPU / 8 GB RAM / 80 GB disk (5 MCU/hr)
  • large: 8 vCPU / 16 GB RAM / 160 GB disk (10 MCU/hr)

The migration PR is important because it makes the change explicit and reviewable:

  • your workflow file still lives in GitHub
  • your existing GitHub triggers still decide when the workflow starts
  • Morph only claims a job after the merged workflow's runs-on labels match the Morph self-hosted label set
  • if the PR is merged into the wrong branch, or not merged at all, Morph will not see the run you expect

For a low-risk first validation, use a small workflow_dispatch smoke workflow. That lets you merge the migration PR and immediately start the run from Morph Actions.

name: Actions Runner V2 Smoke

on:
  workflow_dispatch:

jobs:
  smoke:
    runs-on: [self-hosted, linux, x64, morph, large]
    steps:
      - uses: actions/checkout@v4
      - run: |
          echo "runner_name=$RUNNER_NAME"
          echo "github_ref=$GITHUB_REF"
          echo "github_sha=$GITHUB_SHA"
          date -u

What a successful first run looks like:

  • the run appears in Runs
  • the run can be expanded into Run Details
  • the metadata, lifecycle events, and logs are available from the Morph UI
  • future push, pull_request, schedule, or workflow_dispatch runs follow the same migrated label path

If you already have a dispatchable workflow, you can use that instead. The point of the smoke job is just to remove ambiguity during first setup.

FAQ​

What stays in GitHub?​

GitHub remains the source of truth for workflow files, event triggers, and pull request review. You still edit .github/workflows in your repository, review diffs in GitHub, and rely on the same events that already exist in your workflow.

What does Morph manage?​

Morph manages the Actions setup flow, the GitHub App connection, repository visibility sync into the active org, migration PR generation, workflow_dispatch run starts from the Morph UI, run visibility, run details, and org-level analytics.

When can I use Start New Run?​

Use Start New Run when:

  • the workflow includes workflow_dispatch
  • the migration PR has already been merged
  • the merged workflow branch is the same branch the workflow actually runs from

If those conditions are not met, the button may not give you the result you expect, even if the repository is connected.

What can I inspect from the Actions UI?​

After setup, the main Actions surfaces are:

  • Setup state: confirms the GitHub App install is connected and the repository is visible in the org
  • Runs: summary-first run list for queued, active, and historical runs
  • Run Details: real run metadata, lifecycle events, and logs for the selected workflow
  • Analytics: org-scoped CI summary, failure rate, queue time, and duration trends

This is the main developer value of Morph Actions after setup: you do not just get a final pass/fail badge; you get the execution record in one place.

What if a run does not show up in Morph?​

Check these in order:

  1. The repository is visible in the Morph Actions setup flow.
  2. You completed the GitHub redirect back into Morph so repository visibility had a chance to sync.
  3. The migration PR was merged into the branch your workflow actually runs from.
  4. The job's runs-on labels still include the Morph self-hosted labels.
  5. The workflow was triggered after the migration landed.
  6. If you expected Start New Run to work, the workflow includes workflow_dispatch.

If the labels do not match, GitHub will keep routing the job somewhere else and Morph will not claim it.

Do I need to hand-edit every workflow before I can try Morph Actions?​

No. The preferred path is to let Morph propose the migration PR, review that diff in GitHub, and merge it once you are satisfied with the label changes.

How should I think about runner size?​

Runner size is part of the runs-on label set, so choosing a size is part of the workflow diff you review in the migration PR. Start with the size that matches the job you are testing, then use the actual run history and analytics to decide whether you should scale the shape up or down.

Next steps​