Automating API Mocks in Your CI Pipeline with proxymock
To mock HTTP dependencies in GitHub Actions, run proxymock with recorded responses, route the application’s clients through it, and make the test job check what the application returns. Starting a mock server alone gives CI nothing to pass or fail.
The outerspace-go demo makes this small enough to inspect. Its numbers endpoint returns a frozen fact about 42; its launch endpoint returns a synthetic mission. Both still make outbound HTTPS requests, which proxymock can record and then answer locally.
Keep the demo, use its current backend
The original video uses outerspace-go with public Numbers and SpaceX APIs:
The current demo uses frozen synthetic data at https://demo-api.trafficreplay.com/outerspace. These responses aren’t current SpaceX or NASA data. Use the commands below with that version; the video’s upstreams and CLI screens reflect the earlier setup.
For a new application, the record, mock and replay walkthrough follows the same process with mock-lab and includes a committed recording.
Build and record outerspace-go
You’ll need Go 1.23.1 or newer, Git, curl and an activated proxymock installation. The CI response check below also uses Python 3. Follow the installation guide; on macOS, the Homebrew command is:
brew install speedscale/tap/proxymock
Run proxymock init for a new workstation, or reuse a valid configuration. Non-interactive CI requires proxymock Pro or Speedscale Enterprise. Local activation alone does not grant CI access.
Clone the demo and check out the version used here:
git clone https://github.com/speedscale/outerspace-go.git
cd outerspace-go
git checkout ef8c1d5118b0a1b3a73f5669033c04b438d7c965
go test ./...
go build -o outerspace-go .
From that directory, start the recorder with the application:
proxymock record \
--app-port 8080 \
--out proxymock/tutorial-recording \
-- ./outerspace-go
Leave it running. In a second terminal, send these requests through the inbound proxy on port 4143:
curl --fail --silent --show-error http://localhost:4143/
curl --fail --silent --show-error http://localhost:4143/api/numbers
curl --fail --silent --show-error http://localhost:4143/api/latest-launch
Stop the recorder with Ctrl-C. This captures three inbound exchanges under localhost and two outbound exchanges under demo-api.trafficreplay.com. The root route lists endpoints without calling a dependency.
Use a fresh proxymock/tutorial-recording directory for this capture. The demo’s older committed SpaceX, Numbers and NASA recordings target different hosts. Mixing them into this test won’t make them match the new backend.
For your own service, choose representative requests and review the recording before committing it. Apply and verify DLP rules when traffic can contain credentials or personal data.
LLM prompt for this step
Prepare the pinned outerspace-go example, run its Go tests, and build the binary. Start proxymock recording the app on port 8080 into proxymock/tutorial-recording. Exercise each curl endpoint listed in this section through port 4143 and verify both inbound and outbound traffic was recorded.
Serve the recorded dependencies
From the same demo directory, run:
proxymock mock \
--in proxymock/tutorial-recording \
--no-passthrough \
--out proxymock/results/tutorial-mocked \
-- ./outerspace-go
The wrapper launches the app with proxy configuration for its outbound calls. Send requests directly to the application on port 8080:
curl --fail --silent --show-error http://localhost:8080/api/numbers
curl --fail --silent --show-error http://localhost:8080/api/latest-launch
The recorded bodies should contain "number":42 and "name":"Demo mission two". --no-passthrough returns an error for an unmatched proxied request instead of forwarding it to the backend. It doesn’t block connections that bypass the proxy.
Stop this local run with Ctrl-C before starting the CI check below.
LLM prompt for this step
Run outerspace-go with recorded dependencies from proxymock/tutorial-recording and passthrough disabled. Save output to proxymock/results/tutorial-mocked and request /api/numbers and /api/latest-launch on port 8080. Compare the responses with the recorded expectations and report unmatched dependencies.
Check responses in the CI job
Commit the reviewed recording with the app. In your CI job, install proxymock using the current CI instructions and build the application before starting the mock. Use an ephemeral runner with ports 8080, 4140 and 50053 available.
Store SPEEDSCALE_API_KEY in the CI secret store. Initialize the fresh runner without editing its shell startup files:
proxymock init --api-key "$SPEEDSCALE_API_KEY" --yes --no-rcfile-update
Only give that key to code you’ve reviewed. GitHub withholds ordinary secrets from fork pull requests; a skipped secret-bearing job is not a passing replay. The existing GitHub Actions example includes a protected environment, pinned tools and cleanup. Use that workflow for its mock-lab example, or adapt its setup to your repository.
For outerspace-go, save this response check as ci/mock-check.sh and run bash ci/mock-check.sh after initialization and the build:
#!/usr/bin/env bash
set -euo pipefail
mkdir -p proxymock/results
proxymock mock \
--in proxymock/tutorial-recording \
--no-passthrough \
--out proxymock/results/ci-mocked \
-- ./outerspace-go > proxymock/results/ci-mock.log 2>&1 &
mock_pid=$!
trap 'kill "$mock_pid" 2>/dev/null || true; wait "$mock_pid" 2>/dev/null || true' EXIT
python3 - <<'PY'
import json
import time
import urllib.error
import urllib.request
base = "http://localhost:8080"
for attempt in range(30):
try:
with urllib.request.urlopen(base + "/", timeout=1):
break
except (urllib.error.URLError, TimeoutError):
time.sleep(1)
else:
raise SystemExit("Application did not become ready")
for path, field, expected in [
("/api/numbers", "number", 42),
("/api/latest-launch", "name", "Demo mission two"),
]:
with urllib.request.urlopen(base + path, timeout=5) as response:
body = json.load(response)
if body.get(field) != expected:
raise SystemExit(f"{path}: expected {field}={expected!r}, got {body.get(field)!r}")
print("Both application response checks passed")
PY
An HTTP error, invalid JSON or wrong selected field fails this job. The shell trap stops the mock process and its wrapped application when the check exits. Preserve proxymock/results/ci-mock.log for diagnosis. Keep fixture values under review; for your service, replace these two demo expectations with its required behavior.
This check exercises the application’s HTTP clients against recorded dependency responses. It checks two fields. It does not compare every response field or replay the captured inbound requests.
LLM prompt for this step
Adapt the article's CI script to this repository. Initialize proxymock from the SPEEDSCALE_API_KEY secret without printing it, run the app with recorded dependencies and passthrough disabled, check actual response contents, bound startup waits, and clean up the child process on failure as well as success. Demonstrate a deliberately wrong expectation fails.
Add the existing replay gate when you need it
The CI tutorial’s local proof shows the broader comparison. It uses eight synthetic mock-lab requests. Changing the project total from 24 to 25 still returns HTTP 200, but introduces a body mismatch and makes the explicit replay gate exit 3. Restoring the handler returns exit 0.

Use that tutorial’s script and reviewed baseline for its mock-lab recording. For your application, establish its own baseline and explicit goals; don’t copy a baseline from another service. The replay verdict reference explains --baseline and --fail-on-new-mismatch.
Keep a real integration check for the dependency’s current contract. A recording can hold CI steady while the provider changes, so refresh fixtures when that check or an intentional API change calls for it.
Run this workflow with an LLM
Give this prompt to a coding assistant with access to your project and this article. Supply environment-specific values it cannot discover.
Whole-workflow LLM prompt
Read https://speedscale.com/blog/automating-api-mocks-in-your-ci-pipeline-with-proxymock/ and inspect my project instructions first. Use outerspace-go at commit ef8c1d5118b0a1b3a73f5669033c04b438d7c965 to record the tutorial endpoints and serve their recorded dependencies with passthrough disabled. Add the article's CI checks using a secret environment variable, separate result directories, bounded startup, and reliable process cleanup. Prove that an incorrect response fails the job. Check installed tool help before adapting commands. Report the checks actually run, their results, and anything you could not verify.
Frequently asked questions
How do I authenticate proxymock in a headless runner?
Use a proxymock Pro or Speedscale Enterprise account. Store its API key in the CI platform's secret store, then initialize the fresh runner with proxymock init --api-key "$SPEEDSCALE_API_KEY" --yes --no-rcfile-update. Keep the configuration and key out of source control.
How should a failed replay fail the pipeline?
Use explicit test goals or compare candidate responses with a reviewed baseline using --baseline and --fail-on-new-mismatch. Preserve the verdict and propagate the command's exit status. Starting a mock server alone does not check the application's responses.
When should I refresh the committed recordings?
Refresh them for an intentional contract change or a new test case, and when a real integration check reveals stale fixtures. Review fixture and baseline changes separately from the candidate they will judge. Sanitize captured data before sharing it.