DEV Community: Likhan Siddiquee

Fixing Gitea Actions on Synology Container Manager

Likhan Siddiquee — Thu, 29 Oct 2026 15:07:29 +0000

Gitea worked on my Synology NAS. Its CI jobs failed before they could check out a single file.

I was hosting Gitea and its Actions runner through Synology Container Manager's Docker Compose support. The server was running, but the runner could not create the container that would execute the workflow. None of the repository's code had run yet.

The fix was to stop running a second Docker daemon inside the runner and use Synology's existing daemon instead. That removed the failing nested mount. It also gave CI access to the same daemon managing the other containers on my NAS. Those are two consequences of the same change.

The Original Compose Configuration

This was the starting configuration. The server had its own persistent data directory, and the runner had both a registration directory and a volume for its inner Docker daemon. The registration token below is a placeholder, not a real credential.

version: "3.8"

networks:
  gitea:
    driver: bridge

services:
  server:
    image: docker.gitea.com/gitea:28.2.0
    container_name: gitea
    restart: always
    environment:
      GITEA_APP_INI: /data/gitea/conf/app.ini
      USER_UID: "1026"
      USER_GID: "100"
      TZ: Europe/Amsterdam
    networks:
      - gitea
    volumes:
      - /volume1/docker/gitea/data:/data
    ports:
      - "3000:3000"
      - "2222:2222"

  runner:
    image: docker.io/gitea/runner:5-dind
    container_name: gitea_runner
    restart: always
    privileged: true
    environment:
      GITEA_INSTANCE_URL: http://server:3000
      GITEA_RUNNER_REGISTRATION_TOKEN: "REPLACE_WITH_YOUR_REGISTRATION_TOKEN"
    depends_on:
      - server
    networks:
      - gitea
    volumes:
      - /volume1/docker/gitea/runner:/data
      - runner-docker:/var/lib/docker

volumes:
  runner-docker:

The 5-dind suffix matters here: that image runs a second Docker daemon inside the runner container. When a workflow needs a job container, the inner daemon creates it. In this setup, that extra Docker layer was where execution stopped.

Why CI Failed

I inspected the failed runs with the logged-in tea CLI:

tea actions runs logs 3

Both runs I inspected failed at the same boundary: creating the job container. There was no dependency problem or failing test to investigate yet. Checkout, installation, linting, builds, and tests had never started.

The decisive error was:

failed to create container:
failed to mount ... fstype: overlay ... err: no such device

The inner Docker daemon was using containerd's OverlayFS snapshotter. It tried to mount the job container's filesystem, and that nested mount failed with no such device.

The runner already had privileged: true. There was no missing privileged-mode switch to turn on, and privileges cannot supply a capability the host kernel lacks. The logs located the failure at the nested mount; they did not establish the exact Synology kernel limitation. I had enough evidence to change the Docker arrangement, not enough to name a specific kernel defect.

Using Synology's Docker Daemon Instead

I replaced gitea/runner:5-dind with gitea/runner:5, the basic runner image, and mounted Synology's Docker socket. Instead of asking an inner daemon to create job containers, the runner would ask the daemon already running on the NAS.

That removed the nested daemon and its filesystem mount from the execution path. It did not require a change to the Gitea server.

The changes were:

Switch the runner image to docker.io/gitea/runner:5.
Mount docker.sock.
Remove privileged: true.
Remove the inner /var/lib/docker volume mount.
Preserve the existing runner registration directory.

Security trade-off: removing privileged: true does not make this a low-authority runner. Docker socket access gives it extensive control over the NAS, including other containers. A workflow with that access is operating inside the NAS's trust boundary. Use this setup only for trusted repositories and workflows; a dedicated Linux VM provides stronger isolation from the NAS.

I covered a related placement decision in Deploying the gateway: containers, WSL, and your LAN: deciding where a service runs also means deciding what it can reach. Here, the Docker socket is the access that needs scrutiny.

Troubleshooting the Replacement

Changing the Docker arrangement removed one problem, but the replacement still needed a configuration file and the right network. A stale Container Manager entry added a separate distraction.

All commands below run through SSH on the Synology NAS, not on a development workstation.

Docker Socket Permissions

The first obstacle was inspecting Docker itself. My SSH user received:

permission denied while trying to connect to the Docker daemon socket

Using sudo let me inspect the containers and runner logs:

sudo docker ps -a --filter name=gitea_runner
sudo docker logs --tail 100 gitea_runner

This was a permission error from my SSH user's Docker command. Using sudo was enough for that inspection; there was no need to make the Docker socket world-writable.

Missing Runner Configuration

The replacement runner then reported:

open config file "/data/config.yaml": no such file or directory

The Compose configuration pointed to a file I had not created. The bind mount made the NAS's runner directory appear as /data inside the container, so /data/config.yaml needed a corresponding file on the NAS:

/volume1/docker/gitea/runner/config.yaml

The Actual Docker Network Name

After creating the file, the next error was:

network gitea not found

I had used the Compose network key, gitea, as though it were the Docker network's name. The project was also named gitea, so Compose had created gitea_gitea. The runner was looking for a network that did not exist under the name I supplied.

I confirmed it with:

sudo docker inspect gitea \
  --format '{{range $name, $network := .NetworkSettings.Networks}}{{println $name}}{{end}}'

The runner's container.network setting needs the actual Docker network name, not the key in the Compose file. Putting the job containers on that network lets them reach Gitea at http://server:3000. The complete configuration below makes the name explicit so the two files agree.

Synology's Stale Container Entry

Meanwhile, Container Manager displayed an old prefixed runner name. Opening it returned "No such container", which made the state look worse than Docker's own output showed.

Docker showed the current containers correctly:

gitea_runner          gitea/runner:5
gitea                 docker.gitea.com/gitea:28.2.0
GITEA-ACTIONS-TASK-... docker.gitea.com/runner-images:ubuntu-latest

The long Actions name was a temporary job container, not another runner to clean up. Docker showed the current runner and server, plus the container doing the work. The stale DSM entry was a separate UI problem, not a reason to recreate a working runner.

Complete Working Configuration

This is the complete replacement Compose YAML, with the nested daemon removed and the network explicitly named gitea_gitea. The runner configuration below uses that same name.

Adjust the NAS paths, UID, GID, and ports for your installation. The Gitea server image is unchanged from the original setup; this fix does not require a server upgrade.

version: "3.8"

networks:
  gitea:
    name: gitea_gitea
    driver: bridge

services:
  server:
    image: docker.gitea.com/gitea:28.2.0
    container_name: gitea
    restart: always
    environment:
      GITEA_APP_INI: /data/gitea/conf/app.ini
      USER_UID: "1026"
      USER_GID: "100"
      TZ: Europe/Amsterdam
    networks:
      - gitea
    volumes:
      - /volume1/docker/gitea/data:/data
    ports:
      - "3000:3000"
      - "2222:2222"

  runner:
    image: docker.io/gitea/runner:5
    container_name: gitea_runner
    restart: always
    depends_on:
      - server
    environment:
      GITEA_INSTANCE_URL: http://server:3000
      GITEA_RUNNER_REGISTRATION_TOKEN: "REPLACE_WITH_YOUR_REGISTRATION_TOKEN"
      CONFIG_FILE: /data/config.yaml
      DOCKER_HOST: unix:///var/run/docker.sock
      TZ: Europe/Amsterdam
    networks:
      - gitea
    volumes:
      - /volume1/docker/gitea/runner:/data
      - /var/run/docker.sock:/var/run/docker.sock

Before deploying, create /volume1/docker/gitea/runner/config.yaml with:

container:
  network: gitea_gitea

For a new installation, obtain a runner registration token from the appropriate Gitea Actions settings and replace the placeholder. After successful registration, remove the token environment variable from Compose. The persisted .runner file retains the runner's registration credentials.

For an existing installation, keep the .runner file and the rest of the runner directory. Changing how the runner reaches Docker is not a reason to discard its registration. Do not delete the server data or the old Docker volume during troubleshooting. Rotate any registration token accidentally shared in screenshots, logs, or messages.

Deploying and Verifying

Apply the changes by updating and redeploying the existing project through Synology Container Manager. A restart is not enough: changing the image and mounts requires the runner container to be recreated from the updated Compose configuration.

Inspect the runner:

sudo docker logs --since 2m --tail 50 gitea_runner

Once it reports successful startup, rerun the failed workflow. Do not restart the runner while a job is active, because that can cancel the job.

In this case, registration succeeded, a job container appeared on Synology's Docker daemon, and CI began progressing. That was the evidence I needed for this fix: the runner had crossed the container-creation boundary where both inspected runs had stopped.

It was not proof of a green pipeline. Whether every build and test passes is a separate check. The original failure happened before the repository could run; now its workflow could start. The remaining decision is whether giving those workflows access to the NAS's Docker daemon is an acceptable place to run them.

Would you let trusted CI workflows share your NAS's Docker daemon, or move the runner into a dedicated VM? Which repository trust boundary or isolation requirement would change your choice?

Architectural Debt is the New Technical Debt

Likhan Siddiquee — Thu, 01 Oct 2026 11:03:29 +0000

Imagine a request to show payment status on an order page. An agent finds the order endpoint, adds a paymentStatus column to the orders table, copies a field from the billing response, and updates the UI. The tests pass. The ticket closes.

Which service owns the truth when a refund happens tomorrow?

If billing owns payments but orders stores a second status, someone now has to define how those values converge. A retry, an out-of-order event, or a partial failure can show a paid order as unpaid. The added code may be tidy. The decision about ownership is not.

That is architectural debt: the cost of a missing or compromised boundary, paid on every later change that crosses it. AI makes it easier to incur while making local code cleanup cheaper. The scarce skill is deciding what a system means and which part is allowed to say so.

The marginal cost of code fell, not the cost of change

Generating a handler, test, and migration takes less typing than it used to. An agent can also rewrite an awkward function, remove duplication, and fill in boilerplate quickly. Those are useful gains. They do not make the output free: someone still has to review behavior, migrate data, deploy the change, and support it when production disagrees with the test fixture.

Lint errors and duplicate code still matter, especially when they obscure a bug. But a clean lint report says nothing about whether paymentStatus belongs on an order. The local quality of the patch and the global shape of the system are different questions. Faster patching shifts attention toward the question that cannot be answered by rewriting a file.

I wrote about the velocity microphone: AI amplifies unclear intent and returns the consequences faster. Here the consequence is not a conspicuously broken function. It is a plausible new source of truth.

The easy path crosses the wrong boundary

An agent asked to make the order page show payment status will search for the code that renders the order page. The shortest path may be to extend the order model, because that is where the current request is being handled. No malicious reasoning is required. The task, the nearby code, and the tests all point at a local completion condition.

Then another feature reads orders.paymentStatus to decide whether to ship. A third updates it after a chargeback. Each change is defensible within its own ticket. Together they turn a display shortcut into a domain rule, and now neither orders nor billing can change its state model without coordinating with the other.

The same failure takes other forms: a shared database table becomes an unofficial integration API; a frontend duplicates an authorization rule; a "temporary" mapping layer becomes the place where two services disagree about customer identity. Generated code does not create these traps. It makes the easy path fast enough to take repeatedly before the coordination cost becomes visible.

Guard the contract before generating the patch

For the order-page request, I would first ask: is payment status a billing fact or an order fact? Suppose billing owns it. The order page can request a billing-owned view or consume a deliberately defined projection. If it caches a projection, the contract must name its source, update mechanism, failure behavior, and acceptable staleness. Orders should not become an independent authority for the same status.

That decision changes the agent's task. Instead of "add payment status to orders," the request becomes: "display billing's payment status on the order page; do not add a writable payment field to the orders model; specify what the page shows when billing is unavailable." The constraint is small enough to review and concrete enough to test. A contract test can catch an unauthorized write or a missing unavailable state. It cannot choose the domain owner on its own.

For any domain boundary, put the contract in the instructions the coding agent actually receives: AGENTS.md or copilot-instructions.md for repository-wide rules, or a scoped *.instructions.md for the code it governs. Name who owns each fact and state transition, how other domains may read it, which writes and dependencies are forbidden, and what happens when the owner is unavailable. Before editing, have the agent identify the relevant owners and explain how its proposed change crosses their boundary. If the instructions are missing or conflict with the code, or the request needs a new owner or exception, it should stop and ask the user to decide. It must not treat the nearest model as permission.

Instructions make a boundary visible; checks make violations harder to ship. Where possible, add dependency rules, schema ownership checks, and contract tests for the allowed exchange and its failure path. Have the agent run those checks and report what they cover. They cannot prove that the domain model is correct, so a person still has to judge new ownership and consistency tradeoffs.

This is the boundary guardian's work: name who owns a fact, define the permitted exchange, and make violations visible in scoped instructions, tests, APIs, and review. The goal is not to forbid every cross-service dependency. It is to give an agent a durable constraint it can follow and a check it cannot wave away, so the next change does not silently invent a second model.

The same reasoning applies to planning. I argued that sprint plans still point at an old bottleneck. When implementation is faster, it is tempting to queue more small features. Before calling one small, check whether it adds a new owner, projection, or consistency rule. A one-line field can be the most expensive part of the feature.

Code generation has changed what I can finish in an afternoon. It has not removed the need to decide where a fact belongs. If I skip that decision, faster implementation means I can accumulate architectural debt faster too.

Where have you seen a tidy local change create a second owner for the same fact? What boundary would have caught it?

https://www.likhansiddiquee.com/blog/architectural-debt-ai/

Task state is a call stack for agent work

Likhan Siddiquee — Mon, 31 Aug 2026 20:19:20 +0000

I was one hero image away from publishing a post about sprint planning. Generate it, wire the manifest, build the route. Three steps, then done.

I opened the image prompt for one last look and found it arguing with itself. It named colours in the same prompt that told the generator to avoid them. I asked why. That small question pulled us out of publishing and into an audit of every image instruction in the repository.

The corrected render arrived as a 1.63 MB PNG. I asked another small question: is that normal? Now we were comparing existing heroes, JPEG quality, chroma sampling, and edge artifacts. A second investigation had opened inside the first task.

The agent did not start either tangent. I did. On another day the agent spots the neighboring defect and asks whether to follow it. The risk is the same: the original task falls out of active context while one of us follows the more interesting question.

At the bottom of this stack, the post still needed its manifest entry, route build, and removal of a forward link to an unpublished part two.

We returned to all three because the task had a return address.

Task state is a call stack

A to-do list records what remains. A call stack records more: the current frame, its local variables, and the address where execution should return when a nested call finishes.

That is what .local/scratch/task-state.md does for my agent work.

In the analogy, the current frame is the immediate question. Its local variables are the working hypothesis, evidence, rejected paths, blockers, and decisions made so far. Its return address is the next step still waiting in the ledger.

Before either of us changes focus, the instruction tells the agent to checkpoint the ledger. The tangent becomes the current work while the unfinished task remains recorded beneath it. When the tangent closes, we update its result and resume the waiting next step.

In call-stack terms, the publishing task can be read like this:

publish sprint-planning post
  -> create hero
     -> I notice excluded colours inside the positive prompt
        -> we inspect the prompt rules
        -> return: corrected sidecar
     -> I question the 1.63 MB render
        -> we audit the export settings
        -> return: normalized hero
  -> wire manifest
  -> remove unpublished forward link
  -> build and inspect route shell

The stack did not stop us from going deep. It made the deep dive reversible.

The tangent can start on either side

Most descriptions of agent drift make the agent sound like the only source. It chases a neighboring bug, reads too many files, or turns a local fix into an architecture review.

I interrupt the plan too. I notice a strange output and ask how it happened. I challenge an assumption halfway through implementation. I open a related file while the agent is running and bring a new concern back into chat. Sometimes the side question is more useful than the task that
exposed it.

From the work's point of view, ownership of the tangent does not matter. Focus changed while a parent task remained unfinished. The parent needs a snapshot before the new question consumes the active context.

This is why task state has to be shared. It is not the agent's private plan, and it is not my private set of browser tabs. It is the handoff surface between our two attention streams.

The internal todo tracker is not enough

An agent's internal todo tracker is useful. It can decompose the requested work, mark steps in progress, and show whether the current turn is moving.

I do not treat it as durable task memory.

It belongs to the active agent session. It may not survive context compaction, a new chat, an editor restart, or a switch to another agent. More importantly, it cannot see a branch that starts in my head. If I inspect an image, question a design choice, or return after lunch with a different hypothesis, the internal plan does not know until I explain the change.

A todo item also tends to preserve the action while losing the state around it. "Normalize hero" does not say which settings were tested, why one candidate failed, what still needs visual judgment, or where publishing resumes afterward.

The local task-state file is visible to both of us. I can correct it. The agent can update it. A new session can read it before reconstructing the task from Git and a partial transcript. Because it lives in the workspace rather than the chat, the work does not depend on one session remaining alive.

How I keep the stack

I do not rely on remembering to take a snapshot once the tangent has become interesting. This repository's always-on context-persistence instructions carry the protocol. Copilot reads that file as repository guidance, so the checkpoint triggers arrive with each new session rather than remaining in the chat that may disappear.

The instruction is explicit:

For any non-trivial, multi-step task, ensure .local/scratch/task-state.md exists before the first edit. Create it only when absent.
If it already exists, read and reconcile it with the request and working tree. Preserve unfinished state; never truncate the file to start a new task.
Record the current focus, in-flight items and their status, the next step, open threads, and key findings.
Checkpoint before switching focus or deep-diving, when a new sub-issue appears, and after a meaningful step completes.
Re-read and reconcile the file when resuming.
When completed history makes the active file hard to scan, move it to .local/scratch/task-state-completed.md and promote any durable finding into tracked documentation in the same pass.

This is how I ensure snapshotting happens at the transition, not as cleanup after context is lost. It is still an instruction, not a transactional runtime guarantee. Its advantage is that the rule survives the session, the artifact is visible to both of us, and a missed checkpoint is reviewable.

The storage choice is part of the same instruction. This repository explicitly lists .local/ in .gitignore because the contents are local until promoted. A current hypothesis, unfinished frame, or rejected path should not be pushed to every contributor as project guidance.

Gitignored does not mean disposable. The devcontainer bind-mounts the repository workspace from the host. Rebuilding the container replaces the environment, not .local/scratch/task-state.md inside that workspace. The stack is still there when the new container opens.

I do not use VS Code chat memory as that recovery layer. A transcript may remain visible, but a new chat is not guaranteed to load it as working context; compaction can also remove the detail needed to resume. The task-state file has a stable path that the repository instruction tells the next session to read.

The ledger has no fixed schema. This run uses Current focus, Ledger, Chosen metadata, and Boundaries; older states also use Key findings, Remaining, and Gotchas. The headings follow the work.

There is no literal stack API or required Return field. I read in-progress as the top frame, a pending item plus its next step as the return address, and open threads and findings as the state needed to resume. Completing the tangent and returning to that pending item behaves like a pop. Finished history moves into task-state-completed.md; reusable findings are distilled into their tracked owner.

I ask the session what remains

Most of the time I do not open the task-state file myself. I ask the session:

What are my pending items?

The agent reads the ledger, reconciles it with the working tree, and gives me the unfinished items with their current status. I choose one. That item becomes the current work, and the session already has the findings, blockers, and next step recorded around it.

The question works in the same chat, after a context compaction, or in a new session because the answer comes from the workspace artifact. I am not asking the model to recall an old conversation. I am asking it to query shared state, then continue from the item I select.

This is a protocol, not a file format

Markdown under .local/ is how I implement the idea in these repositories. It is not the only way. An issue, worktree note, session database, or orchestration system can carry the same state.

The direction matters more than the storage choice:

The state is shared between the human and the agent.
It survives longer than one chat or internal plan.
A tangent records its parent return address before consuming the context.
Resume begins by loading that state, not reconstructing it from the current diff.
Completed frames leave the active stack.

Without those properties, changing the filename does not solve the handoff problem.

Shared memory makes curiosity affordable

I wrote about AI acting as a
velocity microphone: it amplifies unclear intent and returns the consequences faster. It also makes investigation cheap. A side question can become a twenty-file audit before either of us feels the cost.

I do not want to remove that curiosity from the workflow. I want a reliable way back.

The ledger preserves the parent task's return address through context compaction, agent changes, and my own detours.

The velocity microphone: AI amplifies unclear intent

Likhan Siddiquee — Mon, 24 Aug 2026 09:45:38 +0000

Twenty minutes prompting. Three days repairing.

That story is often used as proof that AI writes bad software.

Sometimes it does. Models invent APIs, miss edge cases, and make poor design choices.

But another failure is hiding inside that complaint: the classic tree-swing problem, compressed to machine speed.

The engineer knows they want a swing. The brief asks for a “dynamic, scalable outdoor kinetic relaxation mechanism.” The model fills the gaps with a plausible direction. Nobody challenges the assumption.

Twenty minutes later, the first real integration is also the first real test.

A hallucinated API is a model failure.

A coherent implementation of an unspoken assumption is an agreement failure.

AI did not remove requirements engineering. It removed the waiting that used to expose weak requirements before they became architecture.

The response is not one perfect prompt. It is a governance stack:

• Durable repository instructions that preserve architectural intent

• Specialized agent and workflow files that define the job

• Task briefs with boundaries and acceptance evidence

• Scoped tools and permissions that limit the blast radius

• Hooks, tests, lint, schemas, security scans, and CI

• Human review and release gates for the remaining uncertainty

Instructions steer.
Permissions constrain.
Checks reject.
Humans own the release.

AI is a velocity microphone. It amplifies the signal, the ambiguity, and the consequences.

I wrote about how to keep that speed useful:

https://www.likhansiddiquee.com/blog/velocity-microphone/

AgenticAI #SoftwareEngineering #AIGovernance #DeveloperExperience