kado-proxy

command module
v0.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2024 License: MIT Imports: 16 Imported by: 0

README

kado-proxy CI/CD codecov Go Report Card

kado-proxy

kado-proxy is a lightweight, Go-based proxy designed to sit between your tools and the GitHub API. It helps manage API rate limits and handles authentication, ensuring your applications can interact with GitHub more reliably and securely.

Features

  • Manages GitHub API rate limits
  • Supports both Personal Access Token and GitHub App authentication
  • Implements HTTPS for secure communication
  • Easy to deploy using Docker or Kubernetes
  • Can be integrated with various tools that interact with GitHub

Installation

Using Go
go get github.com/janpreet/kado-proxy
Using Docker
docker pull ghcr.io/janpreet/kado-proxy:latest

Usage

Running kado-proxy
Using Go
kado-proxy -cert=/path/to/cert.pem -key=/path/to/key.pem -port=8443
Using Docker
docker run -d -p 8443:8443 \
  -v /path/to/cert.pem:/etc/kado-proxy/cert.pem \
  -v /path/to/key.pem:/etc/kado-proxy/key.pem \
  ghcr.io/janpreet/kado-proxy:latest \
  -cert=/etc/kado-proxy/cert.pem \
  -key=/etc/kado-proxy/key.pem \
  -port=8443
Integrating with Your Project

To use kado-proxy in your project, set your GitHub API base URL to https://localhost:8443 (or wherever you're hosting kado-proxy) instead of https://api.github.com.

Authentication

kado-proxy supports two methods of authentication with GitHub: Personal Access Tokens (PAT) and GitHub Apps.

Personal Access Tokens

If you're using a Personal Access Token (PAT), configure your tool to use the token as usual. kado-proxy will forward the Authorization header containing the token to GitHub.

GitHub Apps

To use GitHub App authentication:

  1. Set the following environment variables when running kado-proxy:

    • GITHUB_APP_ID: Your GitHub App's ID
    • GITHUB_APP_PRIVATE_KEY: Your GitHub App's private key
    • GITHUB_INSTALLATION_ID: The installation ID for your GitHub App
  2. kado-proxy will automatically handle JWT generation and token exchange.

Certificate Setup

Self-Signed Certificates (for testing)
  1. Generate a self-signed certificate:

    openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
    
  2. Use these files with the -cert and -key flags when running kado-proxy.

Let's Encrypt (for production)
  1. Install certbot:

    sudo apt-get update
    sudo apt-get install certbot
    
  2. Obtain a certificate:

    sudo certbot certonly --standalone -d your-domain.com
    
  3. Use the generated certificates with kado-proxy:

    kado-proxy -cert=/etc/letsencrypt/live/your-domain.com/fullchain.pem \
               -key=/etc/letsencrypt/live/your-domain.com/privkey.pem
    
Kubernetes with cert-manager
  1. Install cert-manager in your cluster.

  2. Create an Issuer or ClusterIssuer.

  3. Create a Certificate resource:

    apiVersion: cert-manager.io/v1
    kind: Certificate
    metadata:
      name: kado-proxy-cert
      namespace: your-namespace
    spec:
      secretName: kado-proxy-tls
      issuerRef:
        name: your-issuer
        kind: Issuer
      commonName: kado-proxy.your-domain.com
      dnsNames:
      - kado-proxy.your-domain.com
    
  4. Update your kado-proxy Deployment to use this secret.

Cloud-Managed Certificates
Google Cloud (GKE)
  1. Create a managed certificate:

    apiVersion: networking.gke.io/v1
    kind: ManagedCertificate
    metadata:
      name: kado-proxy-cert
    spec:
      domains:
        - kado-proxy.your-domain.com
    
  2. Annotate your Ingress to use this certificate.

AWS (EKS)
  1. Request a certificate in AWS Certificate Manager.

  2. Use the ARN of this certificate in your Ingress or ALB Ingress Controller configuration.

Example: Using kado-proxy with Atlantis in Kubernetes

  1. Deploy kado-proxy:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kado-proxy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kado-proxy
  template:
    metadata:
      labels:
        app: kado-proxy
    spec:
      containers:
      - name: kado-proxy
        image: ghcr.io/janpreet/kado-proxy:latest
        args:
        - "-cert=/etc/kado-proxy-tls/tls.crt"
        - "-key=/etc/kado-proxy-tls/tls.key"
        - "-port=8443"
        ports:
        - containerPort: 8443
        volumeMounts:
        - name: kado-proxy-tls
          mountPath: "/etc/kado-proxy-tls"
          readOnly: true
        env:
        - name: GITHUB_APP_ID
          valueFrom:
            secretKeyRef:
              name: github-app-credentials
              key: app-id
        - name: GITHUB_APP_PRIVATE_KEY
          valueFrom:
            secretKeyRef:
              name: github-app-credentials
              key: private-key
        - name: GITHUB_INSTALLATION_ID
          valueFrom:
            secretKeyRef:
              name: github-app-credentials
              key: installation-id
      volumes:
      - name: kado-proxy-tls
        secret:
          secretName: kado-proxy-tls
---
apiVersion: v1
kind: Service
metadata:
  name: kado-proxy
spec:
  selector:
    app: kado-proxy
  ports:
    - protocol: TCP
      port: 443
      targetPort: 8443
  1. Configure Atlantis:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: atlantis
spec:
  template:
    spec:
      containers:
      - name: atlantis
        env:
        - name: ATLANTIS_GH_HOSTNAME
          value: "kado-proxy"
        - name: ATLANTIS_GH_URL
          value: "https://kado-proxy"

Security Considerations

  • Always use HTTPS in production environments.
  • Ensure that certificates and private keys are stored securely.
  • Regularly rotate GitHub App private keys and Personal Access Tokens.
  • Implement network policies in Kubernetes to restrict access to kado-proxy.

Contributing

Contributions to kado-proxy are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.

Documentation

The Go Gopher

There is no documentation for this package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL