Prevent Cloud Agents from Auto-Merging PRs

Overview

Teams may require human review before pull requests updated by cloud agents are merged. Run the Formal Endpoint inside each agent to enforce this workflow by preventing auto-merge from being enabled. Cloud agent platforms mint short-lived OIDC tokens for their agents. The Endpoint exchanges these tokens for a Formal machine session and refreshes them automatically. Its transparent proxy evaluates each GitHub request against Formal policy. This guide covers Cursor Cloud Agents and Devin. The general setup is the same for both. Setup steps that differ are split into provider tabs.

Prerequisites

A Cursor Cloud Agent environment or a Devin environment
A Formal machine user for your cloud agents
Permission to create OIDC integrations, Permissions, and policies in Formal
Permission to edit the cloud agent environment

Configure the OIDC integration

Go to OIDC Integrations and click Create Integration. Select your provider’s preset, then select the machine user created for your cloud agents.

Cursor
Devin

Restrict the claim condition

Replace your-team-id in the Cursor preset claim condition. You can also restrict the integration to one repository:

claims.team_id == "<CURSOR_TEAM_ID>" &&
claims.repo_url == "github.com/<ORGANIZATION>/<REPOSITORY>"

Use claims.repo_urls when the environment checks out multiple repositories. See Cursor’s OIDC claim reference for all available claims.

Map the Cursor owner

Keep the preset End-User Email Expression:

claims.owner_email

This maps each agent action to the Formal human with the same email. Confirm every Cursor owner has a matching Formal user before activation.

Copy the integration ID

Copy the generated integrationoidc_... value. The Endpoint requests the audience oidc.formal.ai/<INTEGRATION_ID>.

Restrict the claim condition

Replace your-org-id in the Devin preset claim condition with your Devin organization ID:

claims.org_id == "<DEVIN_ORG_ID>"

See Devin’s OIDC documentation for all available claims, including devin_id.

Map the session requester

Keep the preset End-User Email Expression:

claims.requesting_user_email

This maps each agent action to the Formal human who ran the session. Confirm every Devin user has a matching Formal user before activation.

Copy the integration ID

Copy the generated integrationoidc_... value. The Endpoint requests the audience oidc.formal.ai/<INTEGRATION_ID>.

Restrict Control Plane access

The cloud agent machine user only needs the Endpoint authentication and logging flows. Create a Control Plane Permission that denies every other Formal API and console operation for that identity.

Copy the machine user ID

Open the machine user selected by the OIDC integration and copy its user_... ID.

Create the Permission

Go to Permissions and click Create Permission. Name it block-cloud-agent-control-plane and paste:

package formal.app

import future.keywords.if

default allow = true

allow = false if {
  input.user.id == "<CLOUD_AGENT_MACHINE_USER_ID>"
}

Replace <CLOUD_AGENT_MACHINE_USER_ID> with the copied ID.

Activate and verify

Set the Permission to Active. An API request authenticated as the cloud agent machine user should return HTTP 403 for Control Plane operations. The Formal Endpoint can still authenticate and send logs through its dedicated APIs.

Create the network rule

The Endpoint passes a connection through untouched unless a network rule matches it. Create a rule for GitHub so the Endpoint terminates TLS and evaluates policy. Restrict the rule to your agent machine users.

Web Console
Terraform

Navigate to Network Rules
Create a rule named github-cloud-agents
Match hostname github.com and api.github.com on the pre-TLS condition
Restrict the rule to your cloud agent machine users
Leave Forward to Connector unset
Save the rule and set it to Active

resource "formal_network_rule" "github_cloud_agents" {
  name        = "github-cloud-agents"
  description = "Intercept GitHub traffic from cloud agents"
  status      = "active"

  cel_expression = <<-EOT
    {
      "condition": {
        "pre_tls": (hostname == "github.com" || hostname == "api.github.com") &&
          user.id in ["<MACHINE_USER_ID>"],
        "post_tls": true
      },
      "outputs": {}
    }
  EOT
}

Interception happens on the Endpoint. This rule does not need a Formal , Connector listener, or Forward to Connector.

Configure the agent environment

Install the Endpoint while the environment image is built. If the environment restricts egress, allow api.joinformal.com, static-assets.formalcloud.net, and each governed destination.

Cursor
Devin

Cursor environment builds preserve installed files, but not running processes. Start the Endpoint again for every Cloud Agent run. The Cursor OIDC socket is local and does not require outbound access.

Cursor dashboard

Open the environment

Open Cloud Agents → Environments in Cursor. Create an environment or edit the environment used by your repository.

Start guided setup

Start Cursor’s environment setup flow. Give the setup agent these instructions:

Install the latest Formal Endpoint headless Debian package from:
https://static-assets.formalcloud.net/desktop-app/linux/formal-desktop-headless_latest_amd64.deb

Write ~/.formal/config.toml with:
- auth_mode = "oidc"
- oidc.provider = "cursor"
- oidc.integration_id = "integrationoidc_<INTEGRATION_ID>"
- transparent_proxy.enable = true
- transparent_proxy.enforce = true
- transparent_proxy.fail = "closed"

Configure the environment runtime to wait for CURSOR_AGENT_SOCKET and
then run: formal agent --headless

Replace <INTEGRATION_ID> before submitting the instructions. Use the arm64 package on an ARM environment.

Activate the build

Review the generated install and start configuration. Create a successful environment build, then make it active.

environment.json

Use the following repository-managed configuration when you want setup changes reviewed and versioned with the repository.

Create the install script

Add .cursor/install-formal-endpoint.sh:

#!/usr/bin/env bash
set -euo pipefail

arch="$(dpkg --print-architecture)"
case "${arch}" in
  amd64|arm64) ;;
  *) echo "Unsupported architecture: ${arch}" >&2; exit 1 ;;
esac

package="/tmp/formal-desktop-headless.deb"
curl --fail --silent --show-error --location \
  "https://static-assets.formalcloud.net/desktop-app/linux/formal-desktop-headless_latest_${arch}.deb" \
  --output "${package}"
sudo apt-get update
sudo apt-get install --yes "${package}"

mkdir -p "${HOME}/.formal"
cat >"${HOME}/.formal/config.toml" <<'EOF'
auth_mode = "oidc"

[oidc]
provider = "cursor"
integration_id = "integrationoidc_<INTEGRATION_ID>"

[transparent_proxy]
enable = true
enforce = true
fail = "closed"
EOF

Replace <INTEGRATION_ID> with the copied integration ID. Pin a versioned Endpoint package URL when your rollout process requires deterministic versions.

Create the runtime script

Add .cursor/start-formal-endpoint.sh:

#!/usr/bin/env bash
set -euo pipefail

: "${CURSOR_AGENT_SOCKET:?Cursor OIDC socket is unavailable}"

for attempt in $(seq 1 30); do
  if [[ -S "${CURSOR_AGENT_SOCKET}" ]]; then
    exec formal agent --headless
  fi
  sleep 1
done

echo "Cursor OIDC socket did not become available" >&2
exit 1

Cursor sets CURSOR_AGENT_SOCKET to /run/cursor/api.sock on managed Cloud Agent VMs. Do not hard-code this path because self-hosted workers use a different path. The retry handles the brief period before Cursor creates the socket during boot.

Make the scripts executable

chmod +x \
  .cursor/install-formal-endpoint.sh \
  .cursor/start-formal-endpoint.sh

Update the environment configuration

Add the install command and named terminal to .cursor/environment.json. Merge these fields into any existing environment configuration:

{
  "name": "Cursor Cloud with Formal Endpoint",
  "install": "./.cursor/install-formal-endpoint.sh",
  "terminals": [
    {
      "name": "formal-endpoint",
      "command": "./.cursor/start-formal-endpoint.sh",
      "description": "Runs the Formal Endpoint and transparent proxy"
    }
  ]
}

Commit all three files. New Cloud Agents use the repository-managed environment configuration.

Devin snapshots preserve installed files, the systemd user service, and lingering. The Endpoint package ships a user service, so you only configure the environment once. Every later session starts the Endpoint automatically.

Install the Devin OIDC helper

Add Cognition’s OIDC action to the initialize section of your environment blueprint:

initialize:
  - uses: github.com/CognitionAI/actions/setup-devin-oidc@main

The action installs the devin-oidc CLI, which exchanges the session token for an audience-scoped token. The Endpoint runs this CLI to authenticate.Verify:

command -v devin-oidc
# Expected: /usr/local/bin/devin-oidc

Install and configure the Endpoint

Add a step that installs the headless Debian package and writes the Endpoint configuration:

  - run: |
      set -euo pipefail

      arch="$(dpkg --print-architecture)"
      package="/tmp/formal-desktop-headless.deb"
      curl --fail --silent --show-error --location \
        "https://static-assets.formalcloud.net/desktop-app/linux/formal-desktop-headless_latest_${arch}.deb" \
        --output "${package}"
      sudo apt-get update
      sudo apt-get install --yes "${package}"

      mkdir -p "${HOME}/.formal"
      cat >"${HOME}/.formal/config.toml" <<'EOF'
      auth_mode = "oidc"

      [oidc]
      provider = "devin"
      integration_id = "integrationoidc_<INTEGRATION_ID>"

      [transparent_proxy]
      enable = true
      enforce = true
      fail = "closed"
      EOF

Replace <INTEGRATION_ID> with the copied integration ID. Pin a versioned Endpoint package URL when your rollout process requires deterministic versions.

Enable the systemd user service

The package installs a formal.service user unit that runs formal agent --headless. Enable lingering so systemd starts the unit without an interactive login:

  - run: |
      set -euo pipefail

      sudo loginctl enable-linger "$(id -un)"
      export XDG_RUNTIME_DIR="/run/user/$(id -u)"
      systemctl --user enable --now formal.service

Verify:

XDG_RUNTIME_DIR="/run/user/$(id -u)" \
  systemctl --user is-active formal.service
# Expected: active

Read service logs with journalctl --user -u formal.service. Set XDG_RUNTIME_DIR first when your shell has no session bus.

Verify the setup

Start a new cloud agent session, then run:

formal auth whoami
formal transparent-proxy status
sudo env HOME="${HOME}" formal ca trust
curl -v https://api.github.com -o /dev/null

formal auth whoami should show the configured machine user. The transparent proxy status should be enabled. The verbose curl output should show:

subject: O=Formal; CN=Formal Desktop Certificate
issuer: C=US; ST=New York; L=New York; O=Formal; CN=Formal Desktop Local CA
SSL certificate verify ok.

GitHub’s own certificate means the network rule is not matching. The package watches for regenerated Endpoint certificates and updates the system trust store. Run formal ca trust again if a client reports an untrusted Formal CA.

Create the merge policy

GitHub merges pull requests through a GraphQL mutation or a REST endpoint. This policy parses the GraphQL request and blocks both paths:

package formal.v2

import future.keywords.contains
import future.keywords.if
import future.keywords.in

default request := {"action": "allow"}

blocked_mutations := {
  "enablePullRequestAutoMerge",
  "enqueuePullRequest",
  "mergePullRequest",
}

block := {
  "action": "block",
  "type": "block_with_formal_message",
  "reason": "Cloud agents cannot merge pull requests",
}

document := graphql.parse_query(input.http.json.query)

is_mutation if {
  some operation in document.Operations
  operation.Operation == "mutation"
}

# Selections also live in named and inline fragments, so walk the whole
# document instead of only the operation's top-level selection set.
selected_names contains name if {
  walk(document, [_, node])
  name := node.Name
}

request := block if {
  input.http.hostname == "api.github.com"
  input.http.path == "/graphql"

  is_mutation

  some name in selected_names
  name in blocked_mutations
}

request := block if {
  input.http.hostname == "api.github.com"
  input.http.method == "PUT"
  regex.match(`^/repos/[^/]+/[^/]+/pulls/[0-9]+/merge$`, input.http.path)
}

Create the policy in Draft or Dry-run first. Set it to Active after reviewing the matching requests.

Verify merging is blocked

Use a disposable pull request that does not already have auto-merge enabled:

pull_request_id="$(gh pr view <PULL_REQUEST_NUMBER> --json id --jq .id)"

gh api graphql \
  -f query='
    mutation($pullRequestId: ID!) {
      enablePullRequestAutoMerge(
        input: {
          pullRequestId: $pullRequestId
          mergeMethod: SQUASH
        }
      ) {
        pullRequest {
          number
        }
      }
    }
  ' \
  -F pullRequestId="${pull_request_id}"

The command should return HTTP 403 with a Formal policy, session, and request ID. Open Logs and confirm the blocked request contains enablePullRequestAutoMerge. The REST merge endpoint should be blocked as well:

gh api --method PUT \
  repos/<OWNER>/<REPO>/pulls/<PULL_REQUEST_NUMBER>/merge

Troubleshooting

The Cursor OIDC socket is unavailable

Start the Endpoint from the environment’s runtime command or terminals, not install. Install processes do not survive an environment build. Retry with a new Cloud Agent if the socket remains unavailable.

The Devin user service is not running

Confirm lingering is enabled with loginctl show-user "$(id -un)". Confirm devin-oidc is on the service’s PATH. Read failures with journalctl --user -u formal.service.

OIDC authentication fails

Confirm the integration is active. Its issuer should be https://api.cursor.com for Cursor and https://app.devin.ai for Devin. Verify every claim in the claim condition exists on the token. Confirm the configured integration ID has no oidc.formal.ai/ prefix.

TLS verification fails

Run:

sudo env HOME="${HOME}" formal ca trust

Then retry the request. Do not disable TLS verification.

The policy does not evaluate

Confirm the policy is Active and the transparent proxy is enabled. Confirm the GitHub network rule is Active and matches the agent’s machine user. Without a matching rule the Endpoint forwards the connection without inspecting it.

Next steps

Formal Endpoint

Review Endpoint authentication and connection options

OIDC Integrations

Configure claims and federated access

Policy Evaluation

Explore HTTP and agent policy inputs

Endpoint Logs

Review requests and policy decisions

​Overview

​Prerequisites

​Configure the OIDC integration

​Restrict Control Plane access

​Create the network rule

​Configure the agent environment

​Verify the setup

​Create the merge policy

​Verify merging is blocked

​Troubleshooting

​Next steps

Formal Endpoint

OIDC Integrations

Policy Evaluation

Endpoint Logs

Overview

Prerequisites

Configure the OIDC integration

Restrict Control Plane access

Create the network rule

Configure the agent environment

Verify the setup

Create the merge policy

Verify merging is blocked

Troubleshooting

Next steps