Migrate from GitHub Actions

.loha.yml is intentionally close to GitHub Actions syntax. Most workflows port over with no structural changes, just a few keyword and action substitutions.

Keyword and action mapping

GitHub Actions	Loha
`runs-on: ubuntu-latest`	`resource_class: small` (or larger)
`actions/checkout@v4`	`loha/git-clone@v1`
`actions/cache@v4`	`loha/cache@v1`
`actions/upload-artifact@v4`	`artifacts.paths` on the job (no step)
`actions/download-artifact@v4`	nothing: a job receives the files of the jobs in its `needs:`
`docker/build-push-action@v5`	`loha/buildah-build@v1`
`aquasecurity/trivy-action`	`loha/trivy-scan@v1`
`${{ secrets.FOO }}` (env injection)	`secrets: [FOO]` on the step
`${{ github.sha }}`	`${COMMIT_SHA}` (or `${SHORT_SHA}`)
`${{ github.ref_name }}`	no equivalent: filter on the trigger instead
`if:` on a job	`if:` on the job, written by hand: the translator removes a job's `if:` with a warning. Loha's `if:` compares only `branch`, `event`, `github.ref` and `github.event_name` with `==` / `!=`
`strategy.matrix`	`strategy.matrix`
`strategy.max-parallel`	`strategy.max_parallel`
`${{ matrix.node }}`	`${{ matrix.node }}` (unchanged) or `$MATRIX_NODE` in a `run:` script

${{ ... }} is matrix-only in Loha

Loha substitutes three tokens, and only inside with: values: ${COMMIT_SHA}, ${SHORT_SHA}, ${REPO_URL}. The one exception is ${{ matrix.<axis> }}, which works inside a job that declares a matrix. Any other ${{ ... }} copied over from a GitHub workflow is not rejected; it is passed through as literal text. See Context tokens.

Artifacts between jobs

GitHub Actions passes files between jobs with actions/upload-artifact in one job and actions/download-artifact in another. Loha has the same idea as a block on the job, artifacts:, and the translator converts it:

actions/upload-artifact becomes artifacts.paths on the job, with no step. The path: input is split one entry per line. An entry Loha cannot express, such as a negation (!dist/*.map), an absolute path, a .. path or one containing a ${{ ... }} expression, is dropped with a warning. More than 20 entries are cut to 20 with a warning. The name:, retention-days and if-no-files-found inputs have no equivalent: a declared path that matches no files fails the job.
actions/download-artifact becomes nothing. Every job that lists another job in needs: receives that job's files at the same paths, and a job needing a matrix job receives every shard's. The translator only warns when the job has no needs:, because then there is nothing for it to receive: add needs: [<job>].

.github/workflows/build.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build
      - name: Save dist
        uses: actions/upload-artifact@v4
        with: { name: dist, path: dist/ }
  test:
    needs: [build]
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Get dist
        uses: actions/download-artifact@v4
        with: { name: dist }
      - name: Test
        run: npm test

Becomes:

.loha.yml
jobs:
  build:
    steps:
      - name: Checkout
        uses: loha/git-clone@v1
      - name: Build
        run: npm ci && npm run build
    artifacts:
      paths: [dist/]
  test:
    needs: [build]
    steps:
      - name: Checkout
        uses: loha/git-clone@v1
      - name: Test
        run: npm test

If the upload was meant as a download for people (a release binary, a test report) rather than input for a later job, use loha/upload-artifact instead.

What doesn't port over (yet)

Matrix builds port, with limits. The translator converts a strategy.matrix of plain value lists into Loha's strategy.matrix (1–5 axes, at most 20 values per axis and 20 combinations, values are strings), maps max-parallel to max_parallel, and leaves ${{ matrix.<axis> }} references as they are. It warns and drops fail-fast, include: and exclude:, which have no equivalent: without exclude: the excluded combinations run. A matrix built from an expression (${{ fromJSON(...) }}), an axis of objects, or one over the limits is dropped with a warning, and the job runs once until you rewrite the matrix by hand. A matrix value in runs-on: does not change the runner: every instance runs in ubuntu:latest, so vary container.image instead.
Reusable workflows / extends: are planned for v0.7.0.
Approval gates / manual triggers between jobs are planned for v0.7.0.
OIDC token publishing to AWS / GCP / Azure is planned for v0.8.0.

If your workflow depends on any of these, the roadmap tells you when to expect parity.

Worked example

A common Node.js workflow:

.github/workflows/build.yml
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm test
      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

Equivalent .loha.yml:

.loha.yml
version: '1'
on:
  push:
    branches: [main]
jobs:
  build:
    resource_class: small
    steps:
      - name: Checkout
        uses: loha/git-clone@v1
      - name: Install and test
        image: node:20
        run: |
          npm ci
          npm test
      - name: Build and push image
        uses: loha/buildah-build@v1
        with:
          IMAGE: registry.example.com/acme/web:${COMMIT_SHA}

Two differences worth noting. Every step needs a name:, which is how steps are identified in the build log. And there's no setup-node equivalent: pick the runtime with the step's image: instead of installing it at run time.

Keyword and action mapping​

Artifacts between jobs​

What doesn't port over (yet)​

Worked example​

Keyword and action mapping

Artifacts between jobs

What doesn't port over (yet)

Worked example