Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

The p-pii-checker pipeline checks a deposit’s data files for PII with an LLM. To keep the data away from outside LLM services, the step runs on a machine we control, through a Bitbucket self-hosted runner, and asks the Ollama instance on that machine. This page sets up such a runner. It is done once per machine, by a Bitbucket workspace admin with sudo (or docker group) rights on the machine.

How it fits together

1. Check the machine

Bitbucket asks for a 64-bit Linux host with at least 8 GB of RAM and Docker 19.03 or later. Ollama needs memory for the model as well: gemma4:26b uses about 17 GB, in GPU memory, RAM, or both.

docker version --format '{{.Server.Version}}'   # 19.03 or later
free -g                                         # RAM
nvidia-smi                                      # optional: GPUs available to Ollama

Atlassian recommends turning swap off (vm.swappiness = 1) on runner hosts, because swapping makes builds slow and unpredictable. On a machine that also serves Ollama and other things, weigh that against those uses.

2. Make Ollama reachable from containers

Step containers cannot use localhost to reach the host. Ollama has to listen on an address they can reach:

If a firewall (for example ufw) is active, allow port 11434 from the Docker networks. Then check from a throwaway container:

docker run --rm curlimages/curl -s http://172.17.0.1:11434/api/tags | head -c 300

You should see a JSON list of models. If 172.17.0.1 is not the bridge address on this machine, find it with ip -4 addr show docker0.

Pull the model the pipeline uses by default:

ollama pull gemma4:26b                                 # Ollama as a service
docker exec <ollama-container> ollama pull gemma4:26b  # Ollama in Docker

3. Register the runner in Bitbucket

  1. In Bitbucket, open the workspace that holds the aearep-NNNN repositories, then the settings cog > Workspace settings > Workspace runners (under Pipelines).

  2. Select Add runner.

  3. Under System and architecture, choose Linux Docker (x86_64).

  4. Give it a name that identifies the machine, for example pii-<hostname>.

  5. Under Labels, keep the default labels (self.hosted, linux) and add the custom label pii. The pipeline only runs on a runner that has all three.

  6. Select Next. The Run step shows a docker container run ... command. It contains the runner’s OAuth client secret, which Bitbucket shows only once. Copy the whole command now, and treat it like a password.

4. Start the runner

Pull the current runner image first:

docker pull docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner:1

The command from step 3 looks like this (values elided):

docker container run -it \
  -v /tmp:/tmp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/containers:/var/lib/docker/containers:ro \
  -e ACCOUNT_UUID={...} -e RUNNER_UUID={...} \
  -e RUNTIME_PREREQUISITES_ENABLED=true \
  -e OAUTH_CLIENT_ID=... -e OAUTH_CLIENT_SECRET=... \
  -e WORKING_DIRECTORY=/tmp \
  --name runner-... \
  docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner:1

Run it as Bitbucket gave it, with one change: replace -it with -d --restart unless-stopped, so that it runs in the background and comes back after a reboot or a Docker restart. Keep everything else, including the volume mounts.

Then watch the log until the runner reports itself online:

docker logs -f runner-...    # should end with the runner reporting itself online

The runner’s status in Workspace runners should change to Online.

5. Optional settings

6. Test from a branch

  1. Create a test repository from the template branch that carries p-pii-checker (with aeagit-create, giving it the branch), or use an existing aearep-NNNN repository whose bitbucket-pipelines.yml has the pipeline.

  2. Make sure config.yml names the deposit (openicpsr, zenodo, dataverse or worldbank), or run 1-populate-from-icpsr first, which fills it in. p-pii-checker downloads the deposit itself.

  3. In the repository, go to Pipelines > Run pipeline, pick the branch, choose custom: p-pii-checker, and set jiraticket (leave PiiModel and PiiCheckerRef at their defaults).

  4. Check that:

    • the step ran on the self-hosted runner (the step details name the runner; docker ps on the machine shows a python:3.12 container while it runs);

    • the log shows run_pii_checker: loading gemma4:26b on http://... followed by pii-checker’s progress;

    • the Jira ticket has a “started” and a “completed” comment with the counts;

    • the commit added generated/pii_checker_results-nodetails.xlsx and generated/pii_checker_summary.txt;

    • the step’s Artifacts tab offers pii-checker-full/pii_checker_results.xlsx, and that file is not in the repository.

Troubleshooting

SymptomCause and fix
The step fails at once, saying no runner matchesNo runner with self.hosted, linux and pii is online. Check the runner’s status and docker logs runner-....
The step waits in the queueThe runner is busy with another step. Steps run one at a time per runner. Bitbucket gives up on a queued step after about 2.5 hours.
could not load gemma4:26b on http://172.17.0.1:11434: ... Connection refusedOllama is not reachable from containers (section 2), or the gateway is not the host. Set OLLAMA_ENDPOINTS.
could not load ...: HTTP Error 404The model is not pulled. Pull it (section 2) or set PiiModel to a model that is.
pii-checker did not run: gemma4:26b generated at most ... tokens/sThe model stayed mostly on the CPU for PiiWaitMinutes, because the GPU memory was in use (the message lists other loaded models, for example from Open WebUI). Run the pipeline again once the GPU is free, choose a smaller PiiModel, or lower PiiMinTokensPerSec to accept the slower run.
The step runs for hours, and llama-server uses many CPU coresThe model is mostly on the CPU. If PiiMinTokensPerSec is 0, nothing stops this: cancel the step, unload the model (docker exec <ollama container> ollama stop gemma4:26b), and run the pipeline again.
pii-checker did not write ...pii-checker failed on the package. Its log above the message says why (for example, a .rar archive, or no files).
The step stops after 360 minutesA very large deposit. Raise max-time (up to 720) in bitbucket-pipelines.yml.

Security notes

Sources