Push checker guide

Deploy your own push checker

Run the PulseQuay push checker on your own infrastructure when you want an outbound-only agent. The checker fetches its target list from PulseQuay and pushes results back, so you do not need to expose a public URL or open an inbound port.

View on Docker Hub

1 Register the push checker in the UI

You need workspace admin access in PulseQuay. Open Workspace → Checkers (/workspace/checkers) and use the Register a workspace checker form.

  1. Select Push as the checker type.
  2. Enter a human-readable Name such as branch-office-push.
  3. Choose a Miss threshold that defines how quickly PulseQuay should mark the checker unhealthy if heartbeats stop arriving.
  4. Click Register checker.
A banner appears with your one-time API_KEY. Click Copy key and store it securely before dismissing the banner. If you lose it, open the checker detail page and use Rotate key, then restart the container with the new value.

2 Copy the Checker ID

Click the checker name to open its detail page, then copy the Checker ID from the read-only ID row. You will need this UUID for the CHECKER_ID environment variable in Step 4.

3 Pull the push checker image

On the machine that will run the checker:

docker pull dzecevic/pulsequay-push-checker:latest

Pin to a specific version tag for production deployments. The Docker Hub page lists all available tags.

4 Start the push checker container

Use the CHECKER_ID from Step 2 and the one-time API_KEY from Step 1: 

docker run -d \
  --name pulsequay-push-checker \
  --restart unless-stopped \
  -e APP_ENV=production \
  -e LOG_LEVEL=info \
  -e APP_URL=https://<your-pulsequay-api-url> \
  -e CHECKER_ID=<paste-checker-id> \
  -e API_KEY=<paste-api-key> \
  -e ALLOW_PRIVATE_TARGETS=false \
  -e CONFIG_INTERVAL=15m \
  dzecevic/pulsequay-push-checker:latest
Variable Required Description
APP_URL required Base URL of your PulseQuay API, for example https://pulsequay.example.com.
CHECKER_ID required The Checker ID copied from the checker detail page in Step 2.
API_KEY required The one-time key shown immediately after registration in Step 1.
CONFIG_INTERVAL optional How often the checker refreshes its assigned target configuration. Default: 15m.
ALLOW_PRIVATE_TARGETS optional Set to true to allow checks against private/internal IP ranges. Default: false.
LOG_LEVEL optional debug, info, warn, error. Default: info.
APP_ENV optional production or development. Default: development.
Unlike the regular pull checker, this container does not expose an inbound HTTP endpoint. It makes outbound requests to PulseQuay for config sync and result delivery, which makes it a good fit for NAT, branch-office, and tightly firewalled environments.

5 Verify the push checker is working

On the checker machine:

docker logs -f pulsequay-push-checker

You should see startup and sync activity as the checker fetches configuration and begins processing assigned targets.

In PulseQuay, open Workspace → Checkers, click your checker, and confirm:

  1. Last config request updates within your CONFIG_INTERVAL.
  2. Last result push updates after the first assigned target check runs.
  3. The checker becomes healthy once both heartbeat timestamps are within the configured miss threshold.

6 Assign targets to the checker

When creating or editing a monitored target, select your push checker from the Checker dropdown. After the next config refresh, the checker will pick up the assignment and start reporting results back to PulseQuay.

Rotating the API Key

  1. Open Workspace → Checkers and click your push checker.
  2. Click Rotate key.
  3. Copy the new one-time key from the confirmation banner.
  4. Restart the container with the new API_KEY value.

Updating the push checker

docker pull dzecevic/pulsequay-push-checker:latest
docker stop pulsequay-push-checker && docker rm pulsequay-push-checker
# Re-run the docker run command from Step 4 with the same CHECKER_ID and current API_KEY

Viewing logs

docker logs -f pulsequay-push-checker