Request access

Run GPU jobs from GitHub Actions

Use the nodelodge/run action to run a command on a GPU from a workflow, under a hard cost cap, and always stop the machine.

The nodelodge/run action runs a command on a Node Lodge Secure GPU machine from a GitHub Actions workflow. It launches the session, runs your command over SSH with its output in the job log, uploads an output directory as an artifact, and always stops the session, even when the job fails or is cancelled.

Before you start

  1. In the console, open Keys and create a key for the workflow with the scopes workloads:read and workloads:write.
  2. Set its Spending limits (per session and total). Node Lodge refuses any session that would go past one, whatever a workflow asks for.
  3. In your repository, add the key as a secret named NODELODGE_API_KEY (Settings, Secrets and variables, Actions).

A workflow

name: Fine-tune on a GPU

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  train:
    runs-on: ubuntu-latest
    timeout-minutes: 120
    steps:
      - uses: actions/checkout@v4

      - name: Train on Node Lodge
        id: gpu
        uses: nodelodge/run@v1
        with:
          api-key: ${{ secrets.NODELODGE_API_KEY }}
          max-cost-usd: '5'
          min-vram-gb: '48'
          image: pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime
          upload-dir: training
          command: |
            pip install -r requirements.txt
            python train.py --epochs 3 --out output/
          timeout-minutes: '60'
          output-dir: output
          artifact-name: model

The training folder of your repository is copied to the machine, the command runs there in the PyTorch container, and the output folder comes back as the model artifact of the run. The step’s outputs give the session id, the command’s exit code and what the session cost.

Inputs

Input
api-key Required. The key, from a secret.
max-cost-usd Required. The most the run may cost.
command Required. Runs with sh -c in the working directory.
offer, or gpu and min-vram-gb Which machine: an offer id, or the cheapest bookable machine that matches.
image Run the command in this container, with the working directory at /workspace. Without it, the command runs on the machine itself.
timeout-minutes The most the command may run (default 60).
upload-dir A folder of the repository to copy to the machine first.
output-dir, artifact-name The folder uploaded after the command, even when it fails, and its artifact name.
allow-cidr The address allowed to reach the machine over SSH. Default: the runner’s own address.

How the cost stays under your cap

  • max-cost-usd is the budget of the session, reserved on your credit at launch. Node Lodge checks it against your available credit and the limits of the key, and refuses the run before anything starts when it does not fit.
  • Billing follows the real time the machine runs, and Budget Guard stops the session before the budget is spent.
  • The command stops at timeout-minutes (exit code 124), and the session stops right after. You pay for the time it ran, and the rest of the budget is released.
  • A post step stops the session if the job was cancelled or the first stop failed. If that fails too, the job fails and its log names the session to stop in the console.

Security

  • The key is masked in the log. Keep it in a secret, and give each workflow its own key with tight limits.
  • The SSH key pair is made for the run and never leaves the runner. Only the runner’s address can reach the machine.
  • Stopping deletes the machine and its disk. Everything you need must be in output-dir.

For the API keys and their limits, see API quickstart. To drive sessions from an AI agent, see Use Node Lodge from an AI agent (MCP).

Last updated View as Markdown