DEV Community: Cyrille Sepele

GitLab Runner Has Never Contacted This Instance: Every Cause and Fix

Cyrille Sepele — Tue, 08 Sep 2026 19:17:42 +0000

You created a runner, GitLab listed it, and next to it sits a grey warning:
This runner has never contacted this instance. Your pipeline sits pending, and nothing in the UI tells you why.

The good news is that this message is far more specific than it looks. It rules out most of what you might be about to check.

What the message actually means

GitLab runners poll. The runner process asks GitLab for work every few seconds (check_interval, three seconds by default). GitLab never pushes anything to the runner, and it never opens a connection to it.

So this warning means exactly one thing: a runner record exists in GitLab's database, and no runner process has ever polled it.

That splits the problem cleanly in two:

The runner record was created. Your token was valid at creation time, and GitLab can see the runner exists.
No process has ever reached the API. Either nothing is running, or something is running and cannot get to GitLab.

Every cause below is a variation on the second half. Notably, none of them are about your .gitlab-ci.yml, your tags, or your job configuration. Those cause different symptoms. Don't start there.

Cause 0: you haven't installed the runner yet

Since GitLab 16, you create a runner in the UI first, and it appears in the list immediately with an authentication token starting with glrt-. The runner row exists before any machine has been told about it.

This is by far the most common reason for the warning, and it is not a bug. The UI is showing you a runner you created but haven't installed. If you stopped after copying the token, that's the whole story.

Cause 1: the process isn't running

Check before assuming anything more interesting:

sudo systemctl status gitlab-runner    # package install
docker ps -a | grep gitlab-runner      # container install

A container that exited seconds after starting almost always means a malformed config.toml. Read the logs rather than restarting it:

sudo journalctl -u gitlab-runner -n 50 --no-pager
docker logs gitlab-runner

Cause 2: the service reads a different config.toml

This one wastes the most time, because everything looks correct.

gitlab-runner register writes to a config file that depends on which user ran it. The service reads a path that depends on how it was installed. When those disagree, registration genuinely succeeded and the running service genuinely never learned about it.

How you ran it	Config file used
`sudo gitlab-runner register`	`/etc/gitlab-runner/config.toml`
`gitlab-runner register` as your user	`~/.gitlab-runner/config.toml`
Docker	whatever you mounted, often `/srv/gitlab-runner/config`

Confirm which file the runner actually loaded, and confirm your runner is in it:

sudo grep -c '\[\[runners\]\]' /etc/gitlab-runner/config.toml

Zero means you registered into a different file. Re-register with sudo, or point the service at the file you already wrote.

Cause 3: the runner can't reach your GitLab URL

Registration and polling are the same API, so if registration worked from that
machine, the network path worked at least once. That makes this cause more likely when someone else registered the runner, when you copied a config.toml between hosts, or when the runner lives in a different network segment.

Test from the runner itself, not from your laptop:

curl -v https://gitlab.example.com/api/v4/version

For self-managed instances, the usual failure is a URL that only resolves in some networks. An internal hostname, a VPN-only address, or a private IP will work from your desk and fail from a runner in a different subnet or a cloud region. The url in config.toml has to be reachable from the runner, which is not always the same address you type into your browser.

Also check outbound egress. Plenty of hardened networks allow inbound HTTPS to
GitLab and quietly drop outbound traffic from build hosts.

Cause 4: TLS

Self-signed certificates and private CAs fail here constantly, and the error in the runner log is often a single line about certificate verification that scrolls past.

sudo gitlab-runner --debug run

Run it in the foreground and watch. If you see a certificate error, give the runner the CA explicitly:

[[runners]]
  url = "https://gitlab.example.com/"
  tls-ca-file = "/etc/gitlab-runner/certs/ca.crt"

The file has to be readable by the user the service runs as, which is often not the user that created it.

Cause 5: the token isn't what you think

A few variations, all of which produce a runner record that never polls:

The authentication token was copied from a different runner, so the process is happily polling as a runner you're not looking at
The token was revoked, or the runner was deleted and recreated in the UI, and the machine still holds the old one
No --url was passed during a non-interactive registration, so the runner defaulted to https://gitlab.com/ and is contacting the wrong instance

That last one is worth checking early on self-managed setups. Open
config.toml and read the url line before anything else.

Fast diagnostic order

Check	Command	Rules out
Is it installed at all?	`systemctl status gitlab-runner`	Cause 0, 1
Is your runner in the config?	`grep -c '\[\[runners\]\]' /etc/gitlab-runner/config.toml`	Cause 2
Is the URL right?	`grep url /etc/gitlab-runner/config.toml`	Cause 5
Can it reach GitLab?	`curl -v <url>/api/v4/version`	Cause 3
Does the token still work?	`sudo gitlab-runner verify`	Cause 4, 5

gitlab-runner verify is the fastest single test. It performs the same authenticated call that polling uses, and it prints the failure instead of burying it in a log.

When verify says "is valid" and GitLab still says never contacted

This is the combination that wastes the most time, because the one command everyone reaches for comes back clean:

Verifying runner... is valid                        runner=AbCdEfGh

And the runners page still says the runner has never contacted the instance.

Nothing is lying to you. verify and polling are not the same test. verify proves that a token in a config file is accepted by a GitLab that this shell can reach. Polling additionally requires that a service is alive, that it reads the same config file, and that the runner is not paused. Verify covers the credentials. It says nothing about the daemon.

So when both are true at once, check these, in this order:

Is the service actually running? sudo gitlab-runner verify works fine with the service stopped, because you are the one making the call. systemctl status gitlab-runner is the check that matters.
Did verify read the config the service uses? This is the trap. Run with sudo, verify reads /etc/gitlab-runner/config.toml. Run as your own user, it reads ~/.gitlab-runner/config.toml. If you registered without sudo and the service runs as root, you just verified a token the daemon has never seen. sudo gitlab-runner --config /etc/gitlab-runner/config.toml verify settles it.
Is the runner paused in the UI? A paused runner verifies perfectly and is never given a job.
Is the token for the runner you're looking at? Verify confirms a runner is valid, and prints its short token so you can tell which. If that token doesn't match the one on the runner page you have open, the process is polling happily as a different record.

The general rule: verify failing tells you something useful. verify passing only rules out causes 4 and 5, and sends you back to causes 1 and 2.

Why self-managed instances get hit hardest

On GitLab.com, the URL is public, the certificate is valid, and only one side of the connection is yours. Most of this list collapses to "is the runner running."

On a self-managed instance, you own both ends. The reverse proxy in front of GitLab, the external_url it was configured with, the certificate chain, the DNS split between internal and external views, and the egress rules on the build host are all yours to get right, and they only have to disagree slightly before the runner goes quiet without a useful error.

That's the real cost of self-hosting, and it rarely shows up in the plan. The server is cheap. The afternoon spent proving that a runner can reach your own
GitLab is not.

The takeaway

Work from the message outward. It already told you registration succeeded, so skip your CI config and check the five things above in order. Most of the time it's cause 0 or cause 2, and both are five-minute fixes once you stop looking at the pipeline.

If you'd rather not do this again, RocketRunner provisions the machine, installs the runner, and connects it to your GitLab for you, including self-managed instances. Dedicated, isolated, and destroyed when you delete it.

Start your free trial and skip the config.toml archaeology.

ESC/POS emulator: preview and debug receipts without a printer

Cyrille Sepele — Tue, 08 Sep 2026 12:53:18 +0000

Disclosure: I work on ESCPost and Receiptful, both mentioned below. ESCPost is Apache-2.0 and needs no account, so you can check every claim here yourself.

If you have ever wired up a thermal printer, you know the loop:

Move a column.
Print.
Squint at 58mm of paper.
The total is off, or the euro sign came out as ?.
Go back to 1.

Every round costs paper, a walk to the printer, and about ninety seconds. And when it comes out wrong, you still do not know why. You never see the bytes.

Two things fixed this for me. Both run on your machine, and neither needs a printer plugged in. They are part of ESCPost, our open-source Rust CLI. Apache-2.0, no account, works offline.

Draw the bytes on screen

ESC/POS is just bytes. If you know the printer's geometry, you can draw them on screen instead of on paper.

escpost render receipt.hex --profile REFERENCE --output-dir renderings

Logo, header, item columns, a double-height total, then a voucher with a QR code. It is drawn at the printer's own dot resolution, so the spacing you see is the spacing you get.

Two files came out because the job has a cut in it. You get one PNG per sheet plus a manifest listing them.

It reads stdin too:

generate-receipt | escpost render - --profile REFERENCE > receipt.png

Now your receipt code has a visual test. Three seconds a round instead of ninety. And since the render is deterministic, you can commit those PNGs and diff them in CI. That catches the refactor that shifted your tax column, before it reaches two hundred shops.

Become the printer

Most of the time the interesting bytes come from software you did not write. An ERP, a POS suite, some legacy Windows thing. You cannot see what it sends.

Nearly all of them print over RAW TCP on port 9100. So pretend to be the printer:

escpost serve --listen 127.0.0.1:9100 --web-listen 127.0.0.1:9000 --profile REFERENCE

Point the application at that address and hit print. Nothing reaches paper. The job opens in your browser instead.

Sheets on one side, the decoded commands on the other, in order, with byte offsets.

Down to the single character

Each text command shows the raw bytes, with the character each one printed underneath.

Point at a byte and ESCPost boxes that exact character on the paper and labels it with its hex value. Above, byte 46 is the F in CAFE. It works the other way round too. Point at a command and it outlines everything that command painted.

It even works for characters you cannot see. Point at a 20 and it boxes the blank space the printer held open for it.

The chips under each run show the printer state at that moment: font, bold, underline, alignment, character size, and the code page in use. So when the euro sign prints as ?, you stop guessing. Find the byte, read the code page sitting next to it, and you have your answer.

Pick the right profile

REFERENCE is a generic virtual printer. Real ones differ in ways that break layouts.

Printable width runs from 48mm to 80mm, or 384 to 640 dots. Columns tuned for one width reflow on another.
Most printers are 203 dpi. The Epson TM-T88 series is 180.
The wrong code page quietly corrupts currency symbols and accented names. Your test data was probably all ASCII, so you find out in production.

Render against the profile you actually ship to, and the surprise happens on your laptop instead of in the shop.

One limit worth stating: previews show geometry and dot placement, not paper texture or a vendor's exact built-in glyphs.

Try it

brew install receiptful/tap/escpost

There are no bottles yet, so it compiles from source on the first install. Linux x86-64 is verified end to end. macOS and Windows builds exist but have not been verified natively yet, and I would rather say so than let you find out.

Source and docs: github.com/receiptful/escpost

One ask

The catalog has 32 profiles. Exactly one, the Netum NT-5890K, is calibrated against a real printer. Thirty are synthesized from vendor datasheets, which are often optimistic, and the last is the synthetic REFERENCE. The catalog marks them: ✓ calibrated, ~ synthesized, ○ virtual. So you always know which is which.

No team can buy every thermal printer. But between all of us, we already own them. If you have one on your desk, calibrating it turns a guess into something everyone shipping to that model can rely on.

ESCPost covers the local half: rendering, capturing, and debugging on your own machine. When receipts need to reach a printer in a shop you cannot SSH into, that is what Receiptful is for. The free tier covers 20 receipts a month.

I made my Next.js app print a real receipt

Cyrille Sepele — Tue, 01 Sep 2026 19:00:22 +0000

My Next.js app could charge a card, email a confirmation, and update inventory. It could not put a piece of paper in somebody's hand.

That is a real thermal printer on a real counter, and this is the entire integration:

await fetch(`https://api.receiptful.io/v1/printers/${printerId}/jobs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RECEIPTFUL_API_KEY}`,
    "Content-Type": "text/html",
  },
  body: `<h1>Order #1284</h1><p>Total: $18.40</p>`,
});

One fetch. No print server, no drivers, no SDK, and no ESC/POS bytes assembled by hand.

The rest of this post is getting from that snippet to a receipt you would actually hand a customer: the layout rules that matter, how to know it really printed, and what to do when the printer is switched off.

Why you cannot just print

Briefly, because you have probably already hit it. Browsers cannot cut paper or open a cash drawer. WebUSB needs a user gesture, HTTPS, a Chromium browser, and the printer cabled to that exact machine, and Bluetooth printers are out entirely. Your server cannot reach the printer either, because it is behind somebody else's router speaking a protocol from the 1990s.

So something local has to talk to the printer, and your backend has to reach that local thing. Everything below is wiring.

What you need before the code

A thermal printer. Mine is a 58mm Bluetooth one that cost about \$40.
An Android phone or tablet near it, running the Receiptful app, paired once. This is the local piece. A retired phone in a drawer is fine.
An API key from the console. It looks like rf_ followed by 64 hex characters and is shown once.

Setup takes a couple of minutes, and the getting started guide has screenshots of every screen, so I am not repeating it here.

# .env.local
RECEIPTFUL_API_KEY=rf_3f9c...

That is the only thing you configure. The app will find the printer itself, which is the next step.

Step 1: the order

Your orders have more fields than this. This is enough to print something useful:

// lib/types.ts
export interface LineItem {
  name: string;
  quantity: number;
  unitPriceCents: number;
}

export interface Order {
  id: number;
  items: LineItem[];
  placedAt: Date;
}

Money in cents, formatted only at the edge. A receipt total that is one cent off because of float arithmetic is a bug a customer notices immediately, and you never do.

Step 2: the receipt, as HTML

This is the part I expected to be miserable and was not. You send HTML, and it gets rendered to ESC/POS for your specific printer model, so you lay out a receipt with tags you already know instead of assembling byte codes.

// lib/receipt.ts
import type { Order } from "./types";

const money = (cents: number) => "$" + (cents / 100).toFixed(2);

export function renderReceipt(order: Order): string {
  const total = order.items.reduce(
    (sum, i) => sum + i.quantity * i.unitPriceCents,
    0,
  );

  const rows = order.items
    .map(
      (i) => `<tr>
        <td>${i.quantity}x ${i.name}</td>
        <td align="right">${money(i.quantity * i.unitPriceCents)}</td>
      </tr>`,
    )
    .join("");

  return `
    <h1>Order #${order.id}</h1>
    <p>${order.placedAt.toLocaleString()}</p>
    <hr />
    <table width="100%">${rows}</table>
    <hr />
    <table width="100%">
      <tr><td><b>TOTAL</b></td><td align="right"><b>${money(total)}</b></td></tr>
    </table>
    <p align="center">Thank you</p>
  `;
}

One rule that matters more than any other: a 58mm roll is about 32 characters wide. Two columns are the maximum that stays readable; there is exactly one ink colour, and anything delicate turns to mush. I wrote up the full set of 58mm layout constraints separately, but "two columns, big type, no backgrounds" gets you 90% of the way.

Step 3: find the printer

Print jobs go to a specific printer, so something has to say which one. You can copy the ID out of the console, but then it is one more thing to configure, and I would rather the app just asked:

// lib/printer.ts
export const API = "https://api.receiptful.io/v1";

export async function firstReadyPrinter() {
  const res = await fetch(`${API}/printers`, {
    headers: { Authorization: `Bearer ${process.env.RECEIPTFUL_API_KEY}` },
    cache: "no-store",
  });

  const printers = await res.json();
  const ready = printers.find((p: { is_logged_in: boolean }) => p.is_logged_in);

  if (!ready) throw new Error("No printer with the app connected.");
  return { id: ready.id as number, label: ready.label as string };
}

is_logged_in is the useful bit: a printer that exists but has no app running next to it cannot print, and you want to find that out here rather than from a failed job.

Grabbing the first ready printer is a demo shortcut, and worth being honest about. A real deployment stores the printer ID next to the location it belongs to, so the till in Lyon prints in Lyon. But for getting to paper today, this removes a setup step.

Step 4: The route handler

// app/api/print/route.ts
import { NextResponse } from "next/server";
import { renderReceipt } from "@/lib/receipt";
import { API, firstReadyPrinter } from "@/lib/printer";
import type { Order } from "@/lib/types";

export async function POST(request: Request) {
  const order: Order = await request.json();
  const printer = await firstReadyPrinter();

  const res = await fetch(`${API}/printers/${printer.id}/jobs`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RECEIPTFUL_API_KEY}`,
      "Content-Type": "text/html",
      // a receipt nobody collected in 5 minutes is not worth printing
      "X-Lifetime-Seconds": "300",
    },
    body: renderReceipt({ ...order, placedAt: new Date(order.placedAt) }),
  });

  if (!res.ok) {
    const detail = await res.text();
    console.error("print failed", res.status, detail);
    return NextResponse.json({ error: "print failed" }, { status: 502 });
  }

  const job = await res.json();
  return NextResponse.json({
    jobId: job.id,
    printerId: printer.id,
    status: job.status,
  });
}

That is the whole integration. One fetch. No SDK, no driver, no print server, no bytes.

Step 5: the screen that triggers it

The route handler will print for anything that can POST to it, but the demo in the GIF at the top is a page with one button. The part that matters is the status: you click, and the label changes from "Sent to the printer" to "Printed" while the paper is actually coming out.

// app/checkout.tsx
"use client";

import { useState } from "react";

const LABELS: Record<string, string> = {
  created: "Sent to the printer...",
  notification_received: "Printer picked it up...",
  printing: "Printing...",
  completed: "Printed",
  expired: "The printer never came back. Job expired.",
};

export default function Checkout({ order }: { order: Order }) {
  const [status, setStatus] = useState<string | null>(null);

  async function print() {
    setStatus("created");
    const res = await fetch("/api/print", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(order),
    });
    const { jobId, printerId } = await res.json();

    // poll until the job reaches a terminal state
    for (let i = 0; i < 20; i++) {
      await new Promise((r) => setTimeout(r, 1000));
      const s = await fetch(`/api/status?printerId=${printerId}&jobId=${jobId}`);
      const { status: next } = await s.json();
      setStatus(next);
      if (["completed", "failed", "expired"].includes(next)) break;
    }
  }

  return (
    <>
      <button onClick={print}>Print receipt</button>
      <p>{status ? LABELS[status] ?? status : ""}</p>
    </>
  );
}

The /api/status route is four lines around the same GET /v1/printers/{id}/jobs/{jobId} call, forwarding only the status so the API key never reaches the browser.

Reporting real status instead of a spinner is worth the extra route. "Printed" is a fact you can show someone. A spinner that stops is a guess.

Step 6: watch paper come out

curl -X POST http://localhost:3000/api/print \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1284,
    "placedAt": "2026-09-01T10:24:00Z",
    "items": [
      { "name": "Flat White", "quantity": 2, "unitPriceCents": 450 },
      { "name": "Croissant",  "quantity": 1, "unitPriceCents": 350 }
    ]
  }'

{ "jobId": 90210, "printerId": 42, "status": "created" }

Or click the button. Either way, the printer wakes up a moment later. Median time from the call to paper is under a second and a half in my testing, which is fast enough that it feels like the same action as clicking the button.

Step 7: what the statuses mean

status: "created" means accepted, not printed. If you are printing from a background job with no UI to poll from, the same wait works server-side:

// lib/confirm.ts
const TERMINAL = ["completed", "failed", "expired"];

export async function waitForPrint(printerId: number, jobId: number) {
  for (let attempt = 0; attempt < 10; attempt++) {
    const res = await fetch(
      `https://api.receiptful.io/v1/printers/${printerId}/jobs/${jobId}`,
      { headers: { Authorization: `Bearer ${process.env.RECEIPTFUL_API_KEY}` } },
    );
    const job = await res.json();
    if (TERMINAL.includes(job.status)) return job.status;
    await new Promise((r) => setTimeout(r, 1000));
  }
  return "timeout";
}

A job walks through created, notification_sent, notification_received, printing, then completed. If the printer is off, it sits and waits, and when the TTL runs out, it goes to expired rather than printing a stale order later.

That last behaviour is worth designing around deliberately. A receipt that shows up 40 minutes late is worse than one that never showed up at all, because now somebody has to work out which order it belongs to.

Gotchas that cost me time

A space between two tags is not a space. My first version was <b>TOTAL</b> <b>$15.50</b> and it printed as TOTAL$15.50, jammed together. Whitespace-only text between tags gets normalised away, so if you want two things on one line with a gap, put them in a table row. That is why the total above is a table and not a paragraph, and it right-aligns to match the line items as a bonus.

That is the actual paper from the first run. Two takes, and you can read the bug on both.

Never call the printing API from the client. NEXT_PUBLIC_ on that key ships it to every visitor. The route handler exists so the key stays on the server.

Do not await the print in your checkout path. Return the order to the user, print in the background. A printer that is briefly offline should not turn into a failed checkout.

Test with the printer off. It is the state you will actually hit in production, and you want to know what your code does before a customer finds out.

32 characters. I keep saying it because I keep forgetting it. Three columns look fine in Chrome and print as noise.

Why not QZ Tray, or a print server?

Both are real answers, and I looked at both.

QZ Tray is free, open source, and works offline, which is genuinely better than what I built here if you have a person sitting at the machine every time something prints. It stopped fitting because it connects a browser tab to a printer on the same machine. My end-of-day summary prints at 2 am with nobody logged in, and no configuration makes a browser bridge do that.

Your own print server gives you total control. It also gives you agent packaging for three operating systems, auto-update, retries, VPN or tunnel management, and a pager for when a store's printer stops responding on a Saturday. Worth it if printing is your product. Not worth it for one feature.

That is the whole thing

Every file is in this post, so you can paste it straight into a fresh Next.js app. Receiptful is free to start with no card, so if you have a printer in a drawer somewhere, you can have this working today. Disclosure: I built it, which is also why the example uses it.

What are you printing? I am curious whether people are hitting this for receipts, kitchen tickets, or shipping labels, because the constraints are surprisingly different for each.

Build a POS receipt printer in Node.js

Cyrille Sepele — Sun, 16 Aug 2026 12:27:34 +0000

Disclosure: I build Receiptful, the printing API used in this tutorial. The Node and Express parts apply whatever you print with.

You have orders coming into your point of sale, and you want each one to print on the thermal printer at the counter. This is a complete walkthrough of a small Node service that does exactly that. By the end you will have an endpoint you can POST an order to and watch paper come out.

There is nothing to install next to the printer for this tutorial to work, and no ESC/POS to write by hand. You send HTML, Receiptful prints it.

Before you start

You need two things from the console:

A paired printer, which gives you a printer ID. If you have not done this yet, the getting started guide walks through it in a couple of minutes.
An API key (the rf_live_… value), created under API keys and shown only once.

On the code side you need Node 18 or newer, so that fetch is available globally with no extra dependency. We will use TypeScript, but the same code works in plain JavaScript if you drop the types.

Put your credentials in the environment rather than in the source:

export RECEIPTFUL_API_KEY="rf_live_3f9c…"
export RECEIPTFUL_PRINTER_ID="42"

Step 1: model the order

Start with the shape of an order. Yours will have more fields, but this is enough to print a useful receipt:

interface LineItem {
  name: string;
  quantity: number;
  unitPrice: number; // in cents, to avoid float rounding
}

interface Order {
  id: number;
  items: LineItem[];
  placedAt: Date;
}

Keeping money in cents and formatting only at the edges saves you from the classic floating point rounding bugs that show up as a receipt total that is one cent off.

Step 2: render the order as HTML

This is the part that decides how the receipt looks. Receiptful converts the HTML you send into ESC/POS for your specific printer, so you get to lay a receipt out with tags you already know instead of byte codes.

function money(cents: number): string {
  return "$" + (cents / 100).toFixed(2);
}

function renderReceipt(order: Order): string {
  const lines = order.items
    .map((item) => {
      const total = money(item.unitPrice * item.quantity);
      return `<tr><td>${item.quantity}x ${item.name}</td><td align="right">${total}</td></tr>`;
    })
    .join("");

  const grandTotal = money(
    order.items.reduce((sum, i) => sum + i.unitPrice * i.quantity, 0),
  );

  return `
    <h1 style="text-align:center">CAFE MILA</h1>
    <p style="text-align:center">Order #${order.id}</p>
    <hr>
    <table width="100%">${lines}</table>
    <hr>
    <table width="100%">
      <tr><td><b>TOTAL</b></td><td align="right"><b>${grandTotal}</b></td></tr>
    </table>
    <p style="text-align:center">Thank you</p>
  `;
}

Receipt paper is narrow, so keep the layout to a single column and let text wrap. There is more to say about designing for a 58mm roll, but this is enough to print something clean.

Step 3: send it to the printer

Now POST the HTML to the printer's job endpoint. One authenticated request creates the job:

const API = "https://api.receiptful.io/v1";
const KEY = process.env.RECEIPTFUL_API_KEY!;
const PRINTER = process.env.RECEIPTFUL_PRINTER_ID!;

async function printReceipt(order: Order): Promise<number> {
  const res = await fetch(`${API}/printers/${PRINTER}/jobs`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "text/html",
    },
    body: renderReceipt(order),
  });

  if (!res.ok) {
    const detail = await res.text();
    throw new Error(`Print request failed (${res.status}): ${detail}`);
  }

  const job = await res.json();
  return job.id as number;
}

The response is the job that was created, and a second or so later the receipt prints:

{
  "id": 9281,
  "printer_id": 42,
  "status": "created",
  "lifetime_seconds": 600,
  "created_at": "2026-07-16T10:24:01Z",
  "expires_at": "2026-07-16T10:34:01Z",
  "status_updated_at": "2026-07-16T10:24:01Z"
}

Step 4: wrap it in an endpoint

Put that behind a route so your checkout can call it. Here it is with Express:

import express from "express";

const app = express();
app.use(express.json());

app.post("/orders/:id/print", async (req, res) => {
  try {
    const order: Order = req.body;
    const jobId = await printReceipt(order);
    res.status(202).json({ jobId });
  } catch (err) {
    console.error(err);
    res.status(502).json({ error: "Could not queue receipt" });
  }
});

app.listen(3000);

Returning 202 Accepted is deliberate. The job is queued, not yet confirmed printed, and that distinction matters at a busy counter. The next step is how you close that gap.

Step 5: confirm it actually printed

A receipt endpoint that returns success the moment the request is accepted will happily report a print that never reached paper, because the printer was off or out of range. If it matters that the receipt printed, poll the job until it reaches a final state:

async function waitForPrint(jobId: number, timeoutMs = 15000): Promise<string> {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`${API}/printers/${PRINTER}/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    const job = await res.json();

    if (["completed", "failed", "expired"].includes(job.status)) {
      return job.status;
    }
    await new Promise((r) => setTimeout(r, 1000));
  }
  return "timeout";
}

A job moves through created, notification_sent, notification_received, printing, and then completed. If the printer never answers, the job expired instead of printing a stale order, which is exactly what you want at closing time. How you react to failed or expired, whether that means a retry, an on-screen alert, or a reprint button for staff, depends on your counter, so it is worth deciding on purpose rather than by default.

That is the whole thing

Roughly sixty lines and you have order to paper, with a real status check rather than a hopeful fire and forget. No print server, no drivers, no ESC/POS.

The first 20 receipts each month are free, no card required, so you can build this against a real printer today.

Open the console to grab a printer ID and key, or read the API docs for every field.

GitLab CE Comes Without a Runner: Why Nothing Executes Your Pipelines

Cyrille Sepele — Wed, 12 Aug 2026 21:31:26 +0000

You installed GitLab Community Edition, pushed a .gitlab-ci.yml, and watched
the pipeline sit at pending until it went grey. No error, no failed job,
nothing in the logs worth reading.

Nothing is broken. Your instance has no runners, and it never had any.

Why a fresh instance has none

GitLab is two things that people assume are one thing. There is the application:
repositories, issues, merge requests, the CI/CD system that reads your
.gitlab-ci.yml and builds a pipeline out of it. And there is GitLab Runner: a
separate program, on a separate machine, that actually executes jobs.

The Omnibus package installs the first. It does not install the second, and it
does not come with any machines to run it on.

The confusion comes from GitLab.com, where shared runners are switched on by
default and most people's first experience of CI is that it simply works. That
shared fleet is hardware GitLab owns and operates as part of their hosted
service. It is not part of the software you downloaded, so it does not come
across when you run your own instance.

So on a self-managed install, GitLab will happily accept your pipeline
definition, parse it, create the jobs, and queue them. Then it waits for a
runner to ask for work. If no runner ever asks, the jobs wait indefinitely.

Confirming it in thirty seconds

Go to Admin Area → CI/CD → Runners on your instance. If the list is empty,
that is your answer.

For a single project, Settings → CI/CD → Runners shows the same thing scoped
narrower. A fresh instance shows nothing in either place.

From the command line on the GitLab server:

sudo gitlab-rails runner "puts Ci::Runner.count"

If that prints 0, no runner has ever been registered against this instance.

One thing worth ruling out at the same time: a job can also sit pending when
runners do exist but none of them match the job's tags. If your runner list is
not empty, check whether your jobs specify tags: that no runner carries. That
is a different problem with a different fix, and it is the second most common
cause after this one.

Your three ways out

Install a runner yourself

The traditional answer. Take a machine, install the gitlab-runner package,
register it against your instance with a token from the runners page, and pick
an executor. The Docker executor is the usual choice because it gives each job a
clean container.

This is genuinely the cheapest option on day one, and if you have a spare server
and one project that never changes, it may stay that way. Budget an afternoon
for the first one, less if you have done it before.

The cost arrives later, and it arrives quietly. Runner versions drift out of
support. Disks fill with old build caches until a job fails for reasons that
look nothing like a disk problem. The machine accumulates undocumented local
changes, and eventually nobody is quite sure how to rebuild it. None of this is
hard, exactly. It is just permanent.

Build a runner fleet

At real scale you stop managing machines individually and start managing a
system: the Kubernetes executor, or Docker Machine autoscaling, defined in
Terraform, with runners created and destroyed on demand.

If you already run Kubernetes, this is probably the right answer and you should
skip the rest of this post. It is worth being clear-eyed that it is a platform
project rather than a task, with a platform project's ongoing maintenance. Teams
regularly underestimate this by a factor of several because the first working
version comes together quickly.

Rent a dedicated runner

Someone else provisions the machine, installs the runner, registers it against
your instance, and keeps it patched. You get a single-tenant VM that behaves
like any other runner on your runners page.

The trade you are making: you stop owning the machine's lifecycle, and you
accept that build compute runs outside your network. Which brings us to the part
that matters most.

The requirement nobody mentions upfront

If you rent runners, your GitLab instance has to be reachable from that runner
over the public internet, on https, with a valid certificate.

That is not a vendor preference, it is how the protocol works. The runner polls
your instance for jobs, and registration calls your instance's API. Both need a
public hostname that resolves to a public address.

That covers most self-managed instances at companies and agencies, which sit on
a real domain behind a real certificate. It does not cover an air-gapped
instance, a VPN-only instance, or one bound to a private network. If that is
you, the answer is a runner inside your perimeter, and no hosted service can
change that.

Better to know in paragraph twenty than after signing up.

Being straight about what a runner sees

A runner clones your source in order to build it. That is true of every runner
ever created, including one you install yourself on your own hardware. Anyone
implying otherwise is selling something.

So the useful question is not whether build compute touches your code. It is
what kind of machine touches it, and who else is on that machine.

A shared runner is multi-tenant. You did not choose the hardware, you cannot see
what ran on it before your job, and you cannot point at it in an audit. A
dedicated VM is yours alone, in a region you picked, destroyed when you delete
it. That is a posture you can describe to a client security review, which a
shared runner never was.

Which one is actually right for you

If you self-host GitLab because a policy requires source to stay inside your
network, and that policy extends to build compute, install your own runners.
That is the whole answer and the rest is noise.

If you self-host for the more common reasons, keeping control of your data,
avoiding SaaS lock-in, satisfying a client contract about where the repository
lives, then the repository decision and the build compute decision are separate,
and most teams only ever made the first one deliberately.

Agencies feel this hardest, because the problem repeats per client. Eight
clients on their own instances means eight runner setups, eight sets of
credentials, eight machines to patch, and an awkward question at the end of
every engagement about what is still sitting on that box.

The short version

Your pipelines are pending because a self-managed GitLab ships with no runners,
by design. Install one, build a fleet, or rent one, and pick based on how much
of your attention you want the choice to keep asking for after the first green
pipeline.

If renting sounds right, runners for self-hosted GitLab explains
how connecting your own instance works, including what stays on your side.

We Cut Our GitLab Build Time by 59% With One Change

Cyrille Sepele — Sat, 16 May 2026 20:58:07 +0000

You know the feeling. You push a one-line fix, open the pipeline, and watch your runner spend two minutes downloading node_modules. Again. The same node_modules it downloaded ten minutes ago. On the last push. That was also a one-line fix.

Shared runners have the memory of a goldfish. And you're paying for it in build minutes.

The problem: shared runners forget everything

GitLab's shared runners are ephemeral by design. Each job gets a clean machine. Great for isolation. Terrible for your afternoon.

Every single job:

Docker pulls your base images from scratch
npm install / pip install / bundle install downloads every dependency again
Docker-in-Docker builds re-download every layer, every time
Your test suite can't reuse compilation artifacts from the previous run

"But there's the cache: keyword!" Sure. It uploads a tarball to object storage and downloads it on the next run. In practice:

Uploading and downloading a 500MB archive takes its own sweet time
Cache misses are silent and frequent (good luck debugging that)
Docker image layers? The cache: keyword can't help you there. You end up in a rabbit hole of registry-based workarounds and BuildKit inline caching

For small projects, whatever. For anything with real dependencies or Docker builds, you feel it on every push.

What happens when the cache actually sticks around

When your runner lives on a dedicated machine that doesn't self-destruct after each job, things get better fast:

Docker layer cache just works. Your FROM node:20 isn't pulled every run. Your RUN apt-get install layer is already built. Docker's native caching does what it was designed to do. No config, no tricks.

The /cache volume persists between jobs. GitLab runners support a local cache directory mounted as a Docker volume. On a shared runner, that volume dies with the VM. On a dedicated machine, it stays. Your cache: directive in .gitlab-ci.yml writes to local disk instead of round-tripping through S3.

Docker-in-Docker benefits the most. If you're building container images in CI, a persistent Docker daemon means every subsequent build reuses layers from previous builds. No registry hacks. No BuildKit configuration. Just Docker doing its thing.

None of this is magic. It's just what happens when your runner isn't destroyed after every job.

Proof: same job, same project, very different numbers

Here's our build app job:

Same job. Same codebase. 59% faster. And that's a warm cache. The first run is comparable to a shared runner. Every run after that benefits from Docker layers and dependencies already sitting on disk.

The queue time drop matters too. Shared runners serve everyone on GitLab.com, so your job waits in line behind strangers. A dedicated runner picks up your job immediately because it has nothing better to do.

Now multiply that by 50 pipeline runs a day.

"I'll just self-host a runner."

You can. And if you have a dedicated ops person, or you genuinely enjoy debugging Docker daemon crashes on a Saturday morning, go for it.

For everyone else:

Provisioning the server and keeping it updated
Installing and configuring Docker + GitLab Runner
Monitoring disk space (those Docker layers add up quietly)
Rotating tokens, managing SSH keys
Getting paged at 2 am because the runner went offline

The cache benefits of a persistent runner are real. The Sunday afternoon you lose figuring out why /var/lib/docker filled up the disk is also real.

What we built instead

This is why RocketRunner exists.

You get a dedicated VM. Real hardware, not a shared slice. Docker and the GitLab runner are installed and registered with your project automatically. Because it's your machine running your Docker daemon, all caching works natively.

You don't configure any of this. It's a side effect of having a runner that doesn't get thrown away after every job.

What this looks like in your `.gitlab-ci.yml`

Typical Node.js setup:

build:
  stage: build
  image: node:20
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  script:
    - npm ci
    - npm run build

On a shared runner, npm ci downloads everything every time. The cache round-trip to S3 often takes longer than the install itself. Ironic.

On RocketRunner, that cache lives on a local volume. First run populates it. Second run reads from disk. Done.

For Docker builds, the gap gets embarrassing:

build-image:
  stage: build
  image: docker:24.0.5
  services:
    - docker:24.0.5-dind
  script:
    - docker build -t myapp:latest.

Shared runner: pulls docker:24.0.5, pulls every layer in your Dockerfile, every time. A 3-minute build that should take 20 seconds. You go make coffee. You come back. It's still pulling.

RocketRunner: Docker daemon is already running. Base images are cached. Unchanged layers are skipped. It finishes before you can alt-tab away.

When this matters (and when it doesn't)

Good fit:

Projects with Docker-in-Docker builds
Monorepos with large dependency trees
Teams running 20+ pipelines per day
Anything where npm install takes longer than your actual tests

Probably overkill:

Small projects with minimal dependencies
Pipelines that only run linters or simple scripts
Teams running fewer than a handful of pipelines per week

Try it

RocketRunner starts with a 48-hour free trial. Setup takes about 2 minutes. Connect your GitLab account, pick a server size, choose a region, and your runner is live.

Smallest plan runs at $0.018/hr with a $10.59/month cap. Most teams pay between $1-10/month.

If your pipelines spend more time downloading dependencies than running your actual code, a persistent cache might be all you need.

Cheap Dedicated CI/CD Runners for GitLab: Shared vs Self-Hosted vs Rented

Cyrille Sepele — Sat, 09 May 2026 21:01:17 +0000

If your GitLab pipelines are slow, flaky, or eating into your SaaS bill, you've probably looked at your runner setup. There are three ways to run GitLab CI jobs, and the cost difference between them is bigger than most people realise.

The shared runner problem

GitLab's shared runners are the path of least resistance. You don't set anything up, and they work. Until they don't.

The issues show up gradually:

Jobs queuing behind other users' workloads
Inconsistent build times
No control over the hardware
Shared filesystem state that causes flaky tests you can't reproduce locally
No pipeline caching — every job starts cold, every time
Limited CI minutes on the Free tier (400 min/month on GitLab.com)
Extra minutes cost $10 per 1,000 if you exceed your allowance

If you're running Docker-in-Docker or anything that needs real isolation, shared runners are a constant source of friction.

For a solo project or a weekend hack, shared runners are fine. For a team shipping to production, the unpredictability gets expensive fast.

Self-hosting: more control, more overhead

The obvious answer is to run your own runner on a VPS. Full control, no queuing, dedicated hardware. A Hetzner CX23 (4GB RAM) costs about €3.99/month on paper — hard to beat.

The catch is everything else:

Provision the server
Install Docker and the GitLab runner binary
Register it with your project or group (get the token, run the register command, handle the config)
Keep it updated
Monitor it
Remember to destroy it when you're done, or keep paying for it

The real cost of self-hosting isn't the €3.99/month server. It's the engineer who updates the runner binary when it falls behind, debugs the registration token when it expires, and gets paged when the disk fills up. If that's 30 minutes a month at a $50/hr developer rate, you've already spent more than the server costs.

For a team that already owns and operates infrastructure, this overhead is absorbed. For a solo developer, a startup, or anyone who just wants pipelines to work, it's babysitting you didn't sign up for.

Renting a dedicated runner by the hour

There's a third option that most people haven't considered: renting a dedicated runner, billed hourly, with zero setup.

The model works like this:

You sign in with GitLab
Pick a server size and region
The runner is provisioned and registered with your project automatically. No SSH, no config files
You pay only while the runner exists
Delete it, and billing stops immediately

RocketRunner does this. A Small runner (4GB RAM, 2 vCPUs) costs $0.018/hr, or about $10.59/month maximum if you run it 24/7. Most teams pay far less because they only run it when they need it.

The actual cost comparison

Option	Monthly cost	Setup time	Isolation
GitLab shared runners	Included (with limits)	0 min	None
Self-hosted on Hetzner CX23	~$4.71/month + engineering time	30–60 min	Full
Rented dedicated runner	$0.018/hr (~$1–10/month typical)	2 min	Full

The self-hosted option has the lowest server bill if you run jobs 24/7. But once you factor in the engineering time to set it up and keep it running, renting by the hour is cheaper for most teams.

When renting makes sense

You're a solo developer or small team that doesn't want to maintain infrastructure
You need full VM isolation (Docker-in-Docker, privileged containers, clean state per run)
Your pipeline load is unpredictable, and you don't want to pay for idle compute
You want runners in a specific region (EU or US) for compliance or latency reasons
You're prototyping and want something live in 2 minutes, not 45

The bottom line

Shared runners are free but unreliable. Self-hosting is cheap on paper but comes with hidden ops overhead. Renting a dedicated runner by the hour sits in between: full isolation, no setup, and a cost that scales with actual usage — no engineer babysitting required.

If you've been putting up with slow or flaky GitLab pipelines, it's worth trying a dedicated runner. With a 48-hour free trial and no contracts, the cost of finding out is zero.

Spin up a dedicated GitLab runner in 2 minutes

👉 Get started at rocketrunner.io — card required, no charge for 48 hours.

DEV Community: Cyrille Sepele

GitLab Runner Has Never Contacted This Instance: Every Cause and Fix

What the message actually means

Cause 0: you haven't installed the runner yet

Cause 1: the process isn't running

Cause 2: the service reads a different config.toml

Cause 3: the runner can't reach your GitLab URL

Cause 4: TLS

Cause 5: the token isn't what you think

Fast diagnostic order

When verify says "is valid" and GitLab still says never contacted

Why self-managed instances get hit hardest

The takeaway

ESC/POS emulator: preview and debug receipts without a printer

Draw the bytes on screen

Become the printer

Down to the single character

Pick the right profile

Try it

One ask

I made my Next.js app print a real receipt

Why you cannot just print

What you need before the code

Step 1: the order

Step 2: the receipt, as HTML

Step 3: find the printer

Step 4: The route handler

Step 5: the screen that triggers it

Step 6: watch paper come out

Step 7: what the statuses mean

Gotchas that cost me time

Why not QZ Tray, or a print server?

That is the whole thing

Build a POS receipt printer in Node.js

Before you start

Step 1: model the order

Step 2: render the order as HTML

Step 3: send it to the printer

Step 4: wrap it in an endpoint

Step 5: confirm it actually printed

That is the whole thing

GitLab CE Comes Without a Runner: Why Nothing Executes Your Pipelines

Why a fresh instance has none

Confirming it in thirty seconds

Your three ways out

Install a runner yourself

Build a runner fleet

Rent a dedicated runner

The requirement nobody mentions upfront

Being straight about what a runner sees

Which one is actually right for you

The short version

We Cut Our GitLab Build Time by 59% With One Change

The problem: shared runners forget everything

What happens when the cache actually sticks around

Proof: same job, same project, very different numbers

"I'll just self-host a runner."

What we built instead

What this looks like in your .gitlab-ci.yml

When this matters (and when it doesn't)

Try it

Cheap Dedicated CI/CD Runners for GitLab: Shared vs Self-Hosted vs Rented

The shared runner problem

Self-hosting: more control, more overhead

Renting a dedicated runner by the hour

The actual cost comparison

When renting makes sense

The bottom line

What this looks like in your `.gitlab-ci.yml`