GitHub Actions

A job in GitHub Actions can use your Proxmint proxies without a proxy password in its repository secrets. GitHub signs a short-lived OIDC token for every job that names the repository it runs in. The job sends that token to Proxmint and gets back a proxy line of the account linked to the repository.

Use it to run end-to-end tests from real residential IPs, check how your site behaves in another country, or test geo-restricted features before they ship. Traffic through the proxy counts against your pack, like any other request.

• Install the Proxmint GitHub App on your account or organization, for all repositories or only the ones that need proxies. It asks for no permissions beyond reading their names.
• GitHub sends you back to Proxmint to link the installation to your account. You can also link it later under Settings, GitHub Actions.
• Add the setup-proxy action to a workflow, and give the job id-token: write.

jobs:
  geo-test:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # lets the job ask GitHub for its OIDC token
      contents: read
    steps:
      - uses: actions/checkout@v5
      - id: proxy
        uses: proxmint/setup-proxy@v1
        with:
          product: residential   # optional: the first product on the account
          country: de            # optional
      - run: npm test
        env:
          HTTPS_PROXY: ${{ steps.proxy.outputs.url }}
          HTTP_PROXY: ${{ steps.proxy.outputs.url }}

The action masks the password in the log and returns the line as url. Pass it only to the steps that need it: set as HTTPS_PROXY for the whole job, it would also send checkouts, caches and artifact uploads through your proxy. Its export-env: true input does exactly that, for jobs where every request should go out through the proxy.

Any step can make the same call itself:

TOKEN=$(curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
  "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://proxmint.com" | jq -r .value)

curl -sS -X POST https://proxmint.com/api/github/proxy \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product": "residential", "country": "us", "session": "sticky"}'

Every field is optional. The answer is one line, in the same format as the dashboard:

{
  "product": "residential",
  "status": "active",
  "host": "gw.proxmint.com",
  "port": 823,
  "username": "…__cr.us;sessid.4f1c2a9e07b3;sessttl.30",
  "password": "…",
  "url": "http://…:…@gw.proxmint.com:823"
}

• Only jobs in repositories the app is installed on, and only while that installation is linked to your account. Unlink it in Settings, or uninstall the app on GitHub, and the next request is refused.
• Anyone who can run a workflow in those repositories can get the line, the same as with a repository secret. Pull requests from forks get no OIDC token, so they cannot ask. Workflows triggered by pull_request_target can, so never run code from a fork in one with id-token: write.
• An installation is linked through GitHub sign-in, which proves you can reach it. One installation belongs to one Proxmint account.
• The token is only good for Proxmint: it carries our audience, https://proxmint.com, and expires within minutes. If a proxy password leaks anyway, change it from the dashboard.

• It works on GitHub-hosted and self-hosted runners on github.com. GitHub Enterprise Server, and enterprises that set their own OIDC issuer, are not supported yet.
• The gateway forwards to the usual web ports only; see port access. Some sites are never reachable: blocked websites.
• Scripts outside GitHub read the same credentials with an API key: customer API.