Gitea Actions cannot pull the job container image in CI

By Daniel Zoghalchali·Latchkey

In docker mode, act_runner pulls the image mapped to the job label before running steps. If the image name is wrong, the tag is missing, or the registry needs auth, the pull fails and the job never starts.

What this error means

Jobs fail during preparation with a manifest-not-found or pull-access-denied error naming the image, before any step runs.

Error response from daemon: manifest for node:20-bookwrom not found:
manifest unknown: manifest unknown
pull access denied for registry.example.com/ci, repository does not exist

Common causes

A wrong image name or nonexistent tag

A typo in the image or a tag that was never published makes the registry return manifest unknown.

A private registry that needs credentials

Pulling from a private registry without a docker login on the runner host returns pull access denied.

How to fix it

Correct the image reference in the label mapping

1. Verify the image and tag exist with a manual docker pull.
2. Fix the label mapping to the correct image:tag.
3. Restart the runner and re-run the job.

docker pull node:20-bookworm   # confirm it exists
--labels ubuntu-latest:docker://node:20-bookworm

Authenticate to a private registry on the runner host

Run docker login on the host so act_runner can pull private images for job containers.

docker login registry.example.com -u <user> -p <token>

How to prevent it

• Reference only image tags you have verified exist.
• Pre-authenticate the runner host to private registries.
• Pin explicit tags rather than mutable ones like latest.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions