Getting Started

Requirements

Requirement	Notes
`docker` or `podman`	Auto-detected; Docker preferred
Admin kubeconfig	Needs cluster-admin to provision RBAC
`GH_TOKEN` env var	Fine-grained PAT with `copilot_requests: write`
GitHub Copilot subscription	Required to use the Copilot CLI
`cosign` (optional)	For image signature verification — use `--insecure-image` to skip

Installation

Homebrew

brew tap qjoly/tap
brew install kpil

Krew

kubectl krew install --manifest-url=https://raw.githubusercontent.com/qjoly/kpil/main/kpil.yaml

Pre-built binary

Download from the Releases page and place the binary in your PATH.

From source

git clone https://github.com/qjoly/kpil.git
cd kpil
go build -o kpil .

Usage

1. Set your GitHub token

Create a fine-grained PAT with copilot_requests: write (see GitHub Token):

export GH_TOKEN=github_pat_xxxxxxxxxxxx

2. Run

kpil

kpil will:

Connect to your current KUBECONFIG cluster
Create a ServiceAccount, ClusterRole (no secrets), and ClusterRoleBinding
Issue a 24h token and write ./ro-kubeconfig
Pull and start the container with the read-only kubeconfig mounted
On exit, delete all RBAC resources and the kubeconfig

How it works

    sequenceDiagram
    participant U as You
    participant K as kpil
    participant C as Kubernetes cluster
    participant D as Container

    U->>K: kpil
    K->>C: Create ServiceAccount, ClusterRole, ClusterRoleBinding
    K->>C: Request 24h token
    C-->>K: Token issued
    K->>K: Write ./ro-kubeconfig (mode 0600)
    K->>D: docker run -v ro-kubeconfig -e GH_TOKEN
    D-->>U: gh copilot (interactive session)
    U->>D: exit
    K->>C: Delete ClusterRoleBinding, ClusterRole, ServiceAccount
    K->>K: Delete ./ro-kubeconfig

Flags