Skip to main content

Getting started with Morph Actions

Morph Actions runs eligible GitHub Actions jobs on Morph-managed ephemeral runners. GitHub remains the source of truth for workflows, triggers, and pull request review. Morph provides repository onboarding, a reviewable runner-label migration, dispatch for workflow_dispatch, and run evidence.

Choose a setup path:

Read Security and exact verification before installing the App. The supported launch boundary is a private repository with trusted workflow authors. Public repositories and untrusted fork pull requests are blocked unless Morph introduces a separately reviewed opt-in.

Prerequisites​

You need:

  • a Morph organization and an administrator for its GitHub setup;
  • a GitHub owner or repository administrator who can grant the Morph GitHub App access to the exact private repository;
  • permission to review and merge a workflow pull request; and
  • a private repository with trusted workflow authors.

Do not add Morph API keys or runner registration tokens to the repository.

UI quickstart​

  1. Open Morph Actions and verify the active Morph organization.
  2. Start GitHub setup. The browser follows a short-lived Morph handoff bound to that organization and repository.
  3. In GitHub, install or update the Morph App and select the exact repository. Return to Morph. If linking was interrupted, preserve the installation and follow Troubleshooting.
  4. Select the repository and ask Morph to analyze its workflows.
  5. Review the proposed migration pull request. Morph performs supported runs-on label rewrites; it does not prove that the workflow is safe. Check triggers, token permissions, secret use, third-party actions, containers/privileges, and every changed label set. Unsupported jobs remain unchanged for manual review.
  6. Merge the reviewed pull request into the exact ref you will dispatch.
  7. Dispatch a bounded workflow_dispatch smoke.
  8. Wait for Verified on the selected repository. A run merely appearing in the list is not completion.

Minimal first-run workflow​

Use a dependency-free smoke so the first result tests assignment rather than checkout or package infrastructure:

name: Morph Actions smoke

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  smoke:
    runs-on: [self-hosted, linux, x64, morph, small]
    timeout-minutes: 10
    steps:
      - name: Confirm the runner environment
        shell: bash
        run: |
          set -euo pipefail
          test "$RUNNER_OS" = "Linux"
          test -n "$RUNNER_NAME"
          printf 'repository=%s run_id=%s job=%s\n' \
            "$GITHUB_REPOSITORY" "$GITHUB_RUN_ID" "$GITHUB_JOB"

Commit and merge this workflow through your normal review path. Dispatch only the merged ref. small is the intended first-run shape; choose a different shape later from measured workload needs. Current plan and usage information in the Morph console is the billing source of truth; this guide makes no comparative pricing claim.

What Morph migration proves—and does not prove​

The analyzer recognizes supported Linux/x64 runs-on forms and proposes the Morph label set. Dynamic, reusable, incompatible, or otherwise unsupported jobs stay unchanged. The result can warn about detectable triggers, permissions, secrets, mutable action references, and unsupported labels, but those warnings are not an exhaustive security review.

Before merging, inspect:

  • pull_request and especially pull_request_target trust boundaries;
  • GITHUB_TOKEN permissions and all secrets used by each changed job;
  • third-party actions and whether immutable commit pinning is appropriate;
  • service containers, Docker, sudo, network destinations, and privileged commands; and
  • every old and new runs-on value, including jobs Morph left unchanged.

Exact first-run success​

Onboarding is verified only when all of these refer to the selected repository and job:

  • the Morph run status is succeeded;
  • assignment state is verified;
  • the expected GitHub job id is non-null;
  • the actual GitHub job id is non-null and exactly equal to the expected id;
  • GitHub reports that same job completed successfully.

The UI distinguishes pending, mismatch, orphaned, failed, and verified states. An unrelated run—even a successful verified run elsewhere in the Morph organization—cannot complete setup for the selected repository.

Next steps​