Guides

GitHub Action and GitLab CI

One file runs only the tests a change can reach, on GitHub's or GitLab's own runners, with no account. Free for open source.

The land GitHub Action puts land's recorder in front of the tests you already run, on GitHub's own runners. There is no account, no token and no land server in the loop, so pull requests from forks work and an open source project keeps its free GitHub minutes. Tests whose files a pull request didn't touch are carried from main instead of running again.

Add it

Name your repository and test commands, and GitHub opens with the workflow filled in for you to commit.

Opens GitHub with .github/workflows/land.yml filled in; you review and commit it. Add your setup steps (for example actions/setup-python) above the land step.

Or write the file yourself. Keep your usual setup steps above the land step:

name: land
on: [pull_request, push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install -r requirements.txt
      - uses: Ataraxy-Labs/land-action@v1
        with:
          run: |
            unit: pytest -q tests/unit
            api: pytest -q tests/api

How it decides

  1. On a green run on your main branch, land records every file each command reads, in the kernel, and keeps the record in your repository's Actions cache.
  2. On a pull request, a command whose recorded files are all unchanged is carried from main without running. Every other command runs as usual, and the job fails if any command fails.
  3. The job summary lists every command, whether it ran or was carried, and the reason.

A pull request can read main's record but never write it, so only your own main branch decides what counts as green. The action is open at github.com/Ataraxy-Labs/land-action.

When a command runs anyway

  • There is no green run on main yet: the first run records.
  • A file it read on main changed, appeared or disappeared, including a directory it listed.
  • It failed on main, or gave different results with the same files: it is never carried again.
  • land's recorder could not see everything it did.

A command is carried whole, so split a big suite into a few named lines (unit:, api:, …) to carry more of it.

Inputs

  • run (required): test commands, one per line, optionally name: command.
  • main: the branch whose green runs record; your default branch unless you say otherwise.
  • working-directory: where the commands run, relative to the repository root.

Linux runners only (ubuntu-*). Packages installed with pip install --user live in your home directory, which the recorder doesn't see: use actions/setup-python or install system-wide.

GitLab CI

The same recorder runs on GitLab.com's own hosted Linux runners. Include the template and name your commands in LAND_RUN, one per line.

# .gitlab-ci.yml
include:
  - remote: https://raw.githubusercontent.com/Ataraxy-Labs/land-action/v1/gitlab/land.gitlab-ci.yml

land:
  extends: .land
  image: python:3.12          # any Debian or Ubuntu image with your toolchain
  before_script:
    - pip install -r requirements-dev.txt
  variables:
    LAND_RUN: |
      core: python -m pytest -q tests/core
      api: python -m pytest -q tests/api
  • The record lives in GitLab's cache. Only a green pipeline on your default branch writes it, and merge request pipelines carry from it.
  • The commands run as an ordinary user that owns the checkout, so install packages system-wide in before_script (as root, which is the default there).
  • The summary of what ran and what was carried is saved with the job as land-summary.md.
  • It needs a privileged runner, which GitLab.com's hosted runners are. On your own runners, set privileged = true.

From here to land

The same recorder powers land itself, which adds faster machines, environments built once and kept warm, and merging several agents' branches with one test run. See Quickstart and Many agents at once.