For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Authenticate to GitHub Copilot with a token from a Kubernetes Secret.

About

The Copilot LLM provider sends requests to the GitHub Copilot API with a token from a Kubernetes Secret. The provider sets the upstream endpoint and the protocol headers that the Copilot API expects.

In Kubernetes, configure ai.provider.copilot on an AgentgatewayBackend and supply the token through policies.auth.secretRef. The standalone backendAuth: copilot method discovers credentials on the gateway host. Kubernetes uses an explicit Secret instead.

Before You Begin

1. Install and set up an agentgateway proxy.

2. Set up an agentgateway proxy. The example uses the agentgateway-proxy Gateway.

3. Have a credential accepted by the Copilot API for an account with access to the model you want to use. Agentgateway does not obtain, exchange, or refresh this credential. An arbitrary GitHub personal access token might not work.

Configure Copilot Backend Authentication

1. Save your Copilot token in an environment variable.

   export COPILOT_TOKEN='<your-copilot-token>'

2. Create a Secret that holds the token. The default resolver reads the Authorization key.

   kubectl create secret generic copilot-token \
     --namespace agentgateway-system \
     --from-literal=Authorization="$COPILOT_TOKEN"

3. Create an AgentgatewayBackend that selects the Copilot provider and references the Secret.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayBackend
   metadata:
     name: copilot
     namespace: agentgateway-system
   spec:
     ai:
       provider:
         copilot: {}
     policies:
       ai:
         routes:
           /v1/chat/completions: Completions
           /v1/messages: Messages
           /v1/responses: Responses
       auth:
         secretRef:
           name: copilot-token
   EOF

   Review the following table to understand this configuration. For more information, see the API reference.

   Field	Description
   ai.provider.copilot	Selects the Copilot LLM provider. The default upstream is api.githubcopilot.com:443, with TLS verification.
   ai.provider.copilot.model	Optional model override. When omitted, the provider uses the model from the request.
   policies.ai.routes	Maps incoming paths to API formats. The example enables Chat Completions, Messages, and Responses.
   policies.auth.secretRef.name	Name of the credential Secret in the backend’s namespace.

   Copilot also works with an AgentgatewayModel. Set provider: Copilot and supply the Secret through spec.policies.auth.secretRef.

4. Create an HTTPRoute that forwards requests to the Copilot backend.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: copilot
     namespace: agentgateway-system
   spec:
     parentRefs:
     - name: agentgateway-proxy
     rules:
     - backendRefs:
       - group: agentgateway.dev
         kind: AgentgatewayBackend
         name: copilot
       matches:
       - path:
           type: Exact
           value: /v1/chat/completions
       - path:
           type: Exact
           value: /v1/messages
       - path:
           type: Exact
           value: /v1/responses
   EOF

5. Get the gateway address.

   Cloud Provider LoadBalancerPort-forward for local testing

   Tip

   Kind cluster? Kind does not support LoadBalancer services by default. To use this option with a Kind cluster, install and run cloud-provider-kind.

   The following command reads the LoadBalancer IP address or hostname, whichever your cloud provider assigns.

   export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system agentgateway-proxy \
     -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   
   echo "Gateway address: $INGRESS_GW_ADDRESS"

   After port-forwarding, the gateway is accessible at http://localhost:8080. Use localhost:8080 wherever the instructions reference $INGRESS_GW_ADDRESS.

   kubectl port-forward -n agentgateway-system svc/agentgateway-proxy 8080:80

6. Send a request with a model that your Copilot account can use. The following example uses gpt-4.1. For local testing, set INGRESS_GW_ADDRESS=localhost:8080 in the terminal where you send the request.

   curl --fail-with-body "http://$INGRESS_GW_ADDRESS/v1/chat/completions" \
     --header 'Content-Type: application/json' \
     --data '{
       "messages": [
         {
           "content": "Explain how AI works in simple terms.",
           "role": "user"
         }
       ],
       "model": "gpt-4.1"
     }'

   The route also accepts /v1/messages and /v1/responses with their corresponding request bodies. Choose an API format that the model supports. Set "stream": true in the request body for streaming.

The example uses the sample gateway’s HTTP listener. Configure client authentication and authorization before exposing it to other callers. Copilot requests use the existing LLM policies, metrics, and tracing. Configure caller identity separately for per-user attribution.

Where Agentgateway Finds the Token

The controller resolves policies.auth.secretRef in the namespace of the AgentgatewayBackend. It reads the Authorization key by default and sends the value as a bearer token. That key accepts a bare credential or one prefixed with Bearer .

To use another data key, set policies.auth.secretRef.key. Store the bare token under a custom key. Only the Authorization key strips an existing Bearer prefix before the gateway adds it again.

An explicit Secret takes precedence over credentials on the gateway host. A missing Secret, missing key, or empty credential reports a configuration error and keeps an explicit empty backend credential. Requests cannot fall back to environment variables, Copilot configuration files, or GitHub CLI credentials on the gateway host.

To revoke a credential, use its issuer’s revocation process. Deleting or invalidating the Secret prevents host-credential fallback after reconciliation. It does not revoke the credential at GitHub or cancel requests already in flight.

What Agentgateway Sends

The gateway writes the token to the Authorization header. The Copilot provider adds the following protocol headers after backend transformations and request-header modifiers.

The provider supplies these headers automatically. No manual header configuration is needed.

Troubleshoot

Inspect the backend status for configuration errors.

kubectl get AgentgatewayBackend copilot \
  --namespace agentgateway-system -o yaml