Proxy agent

The Swarmia proxy agent allows you to securely connect Swarmia with your on-premise or network-restricted GitHub Enterprise, GitLab and Jira instances. This enables organizations with strict security policies to use Swarmia's full capabilities without exposing their development tools to the public internet.

What it's for

The proxy agent is designed for enterprise organizations that have:

• Strict security policies

• GitHub, GitLab or Jira instances behind corporate firewalls

• A requirement to keep development tools isolated from public internet access

If you have been unable to use Swarmia because your GitHub Enterprise or Jira instances are not publicly accessible, the integration proxy provides a secure solution to connect them into Swarmia.

How it works

The proxy consists of a lightweight agent that you deploy within your own infrastructure. This agent acts as a secure relay for data between your systems and Swarmia. Its primary functions are:

• Forwarding webhooks: The agent listens for webhooks from your internal Jira, GitLab and GitHub instances, captures the payload data, and securely forwards it to Swarmia's backend.

• Proxying API requests: When Swarmia needs to fetch information from your systems (e.g., pull request details or issue data), it sends a request to a dedicated gateway. The agent, which maintains an outbound connection to this gateway, picks up the request, queries your internal system, and sends the response back to Swarmia.

This entire process works exclusively through secure outbound connections initiated from within your network. No inbound connections to your infrastructure are required, ensuring your security boundaries are maintained.

How to use it

Getting started with the proxy agent involves a setup process guided by our team. To begin, contact our team at [email protected]. We will evaluate your needs, discuss the implementation details, and provision the necessary infrastructure on our end, including a unique API token for your installation.

Requirements

The agent needs to be deployed to a network with access to the origin systems it integrates with (such as on-prem Jira, or GitHub Enterprise Server), and vice versa.

Additionally, the agent requires egress to the following two internet addresses:

• https://integration-proxy.swarmia.com

• https://hook.swarmia.com

Agent installation

You can find the docker image from our public container registry gcr.io/swarmia-production/integration-proxy-agent

The agent starts an internal HTTP server to which you can connect webhooks from the services you're using to relay them towards Swarmia.

Configuration

The agent is configured using environment variables.

Required environment variables:

• GATEWAY_API_TOKEN: The secret API token provided to you by the Swarmia team. This token is unique to your installation and should be kept confidential.

Optional environment variables:

• PORT: The port the agent listens on. Defaults to 11443

• LOG_LEVEL: Controls the verbosity of logs. Can be set to info (default), debug, or error.

• ALLOWED_ORIGINS: A comma-separated list of URLs to restrict requests to specific origin servers (e.g., https://internal.jira.example.com). If not set, the agent can make requests to any server in your cluster.

• HTTP_PROXY / HTTPS_PROXY: If the agent needs to go through a proxy to reach the internet, you can configure it using these standard environment variables.

Deployment

Sample kubernetes manifest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: swarmia-proxy-agent
  labels:
    app: swarmia-proxy-agent
spec:
  # Can be horizontally scaled if necessary
  replicas: 1
  selector:
    matchLabels:
      app: swarmia-proxy-agent
  template:
    metadata:
      labels:
        app: swarmia-proxy-agent
    spec:
      containers:
      - name: swarmia-proxy-agent
        env:
          # In which port to start internal HTTP server
          PORT: 11443
          # Token that the proxy agent will use to authenticate with the gateway
          GATEWAY_API_TOKEN: '<secret>' 
        image: gcr.io/swarmia-production/integration-proxy-agent:latest
        ports:
        - containerPort: 11443
          protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: swarmia-proxy-agent
spec:
  selector:
    app: swarmia-proxy-agent
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 80
      targetPort: 11443

Running in HTTPS mode

By default, the agent listens for connections using the HTTP protocol.

You can specify following environment variables to configure HTTPS:

• CERT_FILE: Providing a path to a PEM file in this variable changes the protocol to HTTPS

• CERT_KEY_FILE: PEM private key file

Your origin systems (such as on-prem Jira, or GitHub Enterprise Server) must be also configured to trust this certificate, when sending webhooks

Finalization

Once the agent is deployed and has successfully connected to our gateway, you can proceed with the standard setup instructions for your on-premise Jira or GitHub integration. The networking prerequisites mentioned in those guides can be ignored, as the agent handles the connection.

Our team will guide you through the final steps to ensure a smooth integration