Guides

CI and GitHub Actions

Run land where there is no browser, with a token, or let a workflow land every branch an agent pushes.

Tokens

Where there's no browser to sign in, make a token on your dashboard for the repositories it may use, and set it as LAND_TOKEN. land merge then works in a fresh checkout with no login.

LAND_TOKEN=$LAND_TOKEN land merge "$BRANCH" --onto main --json

A token can merge and nothing else. It can't add repositories or change a test command, and you can revoke it any time from the dashboard.

GitHub Actions

With this workflow, an agent only has to push a branch named land/anything. The job merges it, checks it and pushes the result with GitHub's own token, so land still never gets access to your repository.

  1. Connect the repository once with land add, see Quickstart.
  2. Save a token for this repository as the repository secret LAND_TOKEN.
  3. Commit this file.
# .github/workflows/land.yml
# Runs when an agent pushes a branch named land/...
name: land
on:
  push:
    branches: ["land/**"]
permissions:
  contents: write
concurrency: land
jobs:
  land:
    runs-on: ubuntu-latest
    env:
      LAND_TOKEN: ${{ secrets.LAND_TOKEN }}
      BRANCH: ${{ github.ref_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: |
          curl -fsSL https://useland.dev/install | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: |
          git branch -f "$BRANCH" "origin/$BRANCH"
          while :; do
            land merge "$BRANCH" --onto main --json > verdict.json; code=$?
            [ "$code" = 3 ] || break   # 3 means still running, the same command waits
          done
          cat verdict.json
          if [ "$(jq '.landed | length' verdict.json)" -gt 0 ]; then
            sh -c "$(jq -r .local.push verdict.json)"
          fi
          exit $code

If main is protected, allow GitHub Actions to push to it, or change the last step to push to a branch and open a pull request.

Cloud agents

Agents that run in the cloud, such as Codex cloud tasks or Claude Code on the web, work the same way. Give the environment LAND_TOKEN as a secret and install land in its setup step, or have the agent push a land/ branch and let the workflow above land it.