PullRequest Creation¶

This example demonstrates how to use the PullRequest resource to create GitHub pull requests automatically with files generated from Kubernetes resources.

Prerequisites¶

Git Change Operator installed in your cluster
GitHub repository with write access
GitHub Personal Access Token with repo and pull_request permissions

Setup GitHub Authentication¶

Create a Secret with your GitHub token:

kubectl create secret generic github-token \
  --from-literal=token=ghp_your_personal_access_token_here

Required Token Permissions: - repo - Repository access - pull_request - Create and manage pull requests

Basic PullRequest Example¶

apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: config-update-pr
spec:
  repository:
    url: "https://github.com/your-username/app-configs.git"
    baseBranch: "main"  # Branch to create PR against

  auth:
    secretName: "github-token"

  pullRequest:
    title: "Automated Configuration Update"
    body: |
      ## Automated Update from Kubernetes

      This pull request contains configuration updates exported from the production cluster.

      ### Changes:
      - Updated application properties
      - Refreshed database configuration
      - New environment variables

      ### Review Checklist:
      - [ ] Verify configuration values are correct
      - [ ] Check for sensitive data exposure
      - [ ] Test in staging environment

      **Generated by**: Git Change Operator
      **Timestamp**: 2023-10-01T10:00:00Z

    branchPrefix: "config-update"

  files:
    - path: "config/application.properties"
      content: |
        # Application Configuration - Updated via Operator
        server.port=8080
        server.host=0.0.0.0

        # Database Configuration
        database.url=jdbc:postgresql://prod-db:5432/myapp
        database.pool.size=20

        # Cache Configuration
        redis.host=redis-cluster.prod.svc.cluster.local
        redis.port=6379

PullRequest with Resource References¶

Combine static files with Kubernetes resource exports:

apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: cluster-config-sync
spec:
  repository:
    url: "https://github.com/your-username/k8s-configs.git"
    baseBranch: "main"

  auth:
    secretName: "github-token"

  pullRequest:
    title: "Sync Kubernetes Configuration - $(date +%Y%m%d)"
    body: |
      ## 🔄 Kubernetes Configuration Sync

      Automated synchronization of production cluster configuration.

      ### 📦 Resources Included:
      - Production ConfigMaps
      - Application secrets (non-sensitive data only)
      - Environment-specific configurations

      ### 🔍 Review Required:
      Please verify all configuration values before merging.

      ---

      **Cluster**: production-east-1  
      **Namespace**: production  
      **Generated**: {{ .Timestamp }}

    branchPrefix: "k8s-sync"

  files:
    # Metadata about the sync
    - path: "sync-metadata.yaml"
      content: |
        sync:
          timestamp: "2023-10-01T10:00:00Z"
          cluster: "production-east-1"
          namespace: "production"
          operator_version: "v1.0.0"

  resourceReferences:
    # Export application configuration
    - name: "app-config"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "production"
      strategy: "fields"
      output:
        path: "environments/production/config/"

    # Export database configuration  
    - name: "database-config"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "production"
      strategy: "dump"
      output:
        path: "resources/configmaps/database-config.yaml"

    # Export specific API endpoint
    - name: "api-config"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "production"
      strategy: "single-field"
      field: "api.endpoint"
      output:
        path: "external-systems/api-endpoint.txt"

Multi-Environment PullRequest¶

Create PRs for different environments:

apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: staging-to-prod-promotion
spec:
  repository:
    url: "https://github.com/your-username/deployment-configs.git"
    baseBranch: "production"  # Target production branch

  auth:
    secretName: "github-token"

  pullRequest:
    title: "🚀 Promote Staging Configuration to Production"
    body: |
      ## Environment Promotion

      This PR promotes tested configuration from staging to production.

      ### 🔄 Configuration Changes:
      - Database connection strings updated
      - API keys rotated
      - Resource limits adjusted for production scale

      ### ✅ Pre-Deployment Checklist:
      - [x] All staging tests passed
      - [x] Performance benchmarks validated
      - [x] Security scan completed
      - [ ] Production deployment approved
      - [ ] Rollback plan confirmed

      ### 📊 Impact Assessment:
      - **Downtime**: Zero (rolling update)
      - **Risk Level**: Low
      - **Rollback Time**: < 5 minutes

    branchPrefix: "staging-to-prod"

  resourceReferences:
    # Production database configuration
    - name: "prod-db-config"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "staging"  # Source from staging
      strategy: "fields"
      output:
        path: "production/database/"

    # Production API configuration
    - name: "api-config-staging"
      apiVersion: "v1"
      kind: "ConfigMap" 
      namespace: "staging"
      strategy: "single-field"
      field: "production.api.endpoint"
      output:
        path: "production/api/endpoint.txt"

Automated Documentation Updates¶

Use PullRequests to update documentation automatically:

apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: docs-update
spec:
  repository:
    url: "https://github.com/your-username/api-documentation.git"
    baseBranch: "main"

  auth:
    secretName: "github-token"

  pullRequest:
    title: "📚 Update API Documentation"
    body: |
      ## Automated Documentation Update

      This PR updates API documentation based on current service configuration.

      ### Updates Include:
      - Service endpoints and ports
      - Authentication requirements  
      - Rate limiting configuration
      - Health check endpoints

      ### Generated From:
      - Kubernetes Services
      - ConfigMaps
      - Ingress resources

    branchPrefix: "docs-update"

  files:
    - path: "docs/api-overview.md"
      content: |
        # API Overview

        Last updated: 2023-10-01T10:00:00Z

        ## Service Endpoints

        This documentation is automatically generated from Kubernetes cluster state.

  resourceReferences:
    # Export service configuration
    - name: "api-service-config"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "default"
      strategy: "single-field"
      field: "openapi.yaml"
      output:
        path: "docs/openapi-spec.yaml"

    # Export rate limiting config
    - name: "rate-limit-config"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "default"
      strategy: "fields"
      output:
        path: "docs/rate-limits/"

Security-Focused PullRequest¶

Handle sensitive configuration updates with extra care:

apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: security-config-update
spec:
  repository:
    url: "https://github.com/your-username/secure-configs.git"
    baseBranch: "main"

  auth:
    secretName: "github-token"

  pullRequest:
    title: "🔒 Security Configuration Update"
    body: |
      ## ⚠️ Security Configuration Update

      This PR contains security-related configuration changes.

      ### 🔐 Security Review Required:
      - [ ] No sensitive data exposed in plain text
      - [ ] All credentials properly masked
      - [ ] Access controls reviewed
      - [ ] Compliance requirements met

      ### 🛡️ Changes Include:
      - Certificate rotation schedules
      - Authentication provider settings
      - Network security policies
      - Audit logging configuration

      **⚡ Priority**: High  
      **👥 Required Reviewers**: @security-team @platform-team

    branchPrefix: "security-update"

  files:
    - path: "security/audit-policy.yaml"
      content: |
        # Audit Policy Configuration
        # Generated from cluster security settings
        apiVersion: audit.k8s.io/v1
        kind: Policy
        rules:
        - level: Metadata
          namespaces: ["production", "staging"]

  resourceReferences:
    # Export network policies (non-sensitive)
    - name: "network-policies"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "security"
      strategy: "dump"
      output:
        path: "policies/network-policies.yaml"

    # Export certificate configuration (metadata only)
    - name: "cert-config"
      apiVersion: "v1"
      kind: "ConfigMap"
      namespace: "security"
      strategy: "single-field"
      field: "cert-rotation-schedule"
      output:
        path: "certificates/rotation-schedule.txt"

Monitoring PullRequest Status¶

Check PullRequest Resource Status¶

# List all PullRequests
kubectl get pullrequests

# Get detailed status
kubectl describe pullrequest config-update-pr

# Check conditions and PR URL
kubectl get pullrequest config-update-pr -o yaml | grep -A 20 status:

Expected Status Output¶

status:
  conditions:
  - type: Ready
    status: "True"
    lastTransitionTime: "2023-10-01T10:05:00Z"
    reason: "PullRequestCreated"
    message: "Successfully created pull request"
  pullRequestURL: "https://github.com/your-username/app-configs/pull/42"

Automated Branch Management¶

The operator automatically manages branches:

Branch Creation: Creates branches with format {branchPrefix}-{timestamp}
Conflict Resolution: Handles existing branches by creating new ones
Content Updates: Pushes files and commits to the branch
PR Creation: Creates the pull request targeting the base branch

Example Branch Names¶

config-update-20231001100000
k8s-sync-20231001103015  
staging-to-prod-20231001110530

Advanced PullRequest Features¶

Custom Branch Names¶

While you can't specify exact branch names, you can control the prefix:

pullRequest:
  branchPrefix: "feature/automated-config"
  # Results in: feature/automated-config-20231001100000

PR Templates Integration¶

Your repository's PR templates will be used if available:

# .github/pull_request_template.md in your repo
## Description
<!-- Automatically populated by operator -->

## Type of Change
- [x] Configuration update
- [ ] Bug fix  
- [ ] New feature

## Testing
- [x] Configuration validated
- [ ] Integration tests passed

Multiple PRs from One Resource¶

Create separate PRs for different purposes:

# PR for configuration updates
apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: config-pr
spec:
  # ... configuration-focused PR

---
# PR for documentation updates  
apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: docs-pr
spec:
  # ... documentation-focused PR

Troubleshooting¶

Authentication Issues¶

# Verify GitHub token
kubectl get secret github-token -o yaml

# Test token permissions
curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/user

Repository Access¶

# Check repository exists and is accessible
curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/repos/your-username/your-repo

# Verify repository permissions
curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/repos/your-username/your-repo/collaborators/your-username/permission

Branch Conflicts¶

If you see branch conflict errors:

The operator will automatically create a new branch with a different timestamp
Check for existing PRs that might conflict
Consider using different branch prefixes for different types of updates

Common Error Messages¶

Error	Cause	Solution
"401 Unauthorized"	Invalid GitHub token	Update token with correct permissions
"404 Not Found"	Repository doesn't exist	Verify repository URL
"422 Validation Failed"	Invalid PR content	Check title and body formatting
"Branch already exists"	Timing collision	Operator will retry with new timestamp

Best Practices¶

Descriptive Titles: Use clear, descriptive PR titles with context
Detailed Bodies: Include checklists and context for reviewers
Branch Prefixes: Use meaningful prefixes that indicate PR purpose
Security: Never include actual secrets in PR content
Testing: Test PullRequest resources in non-production first

Cleanup¶

# Delete PullRequest resource (doesn't affect created PRs)
kubectl delete pullrequest config-update-pr

# The actual GitHub PR remains and must be closed manually if needed

Next Steps¶

Advanced Scenarios - Multi-cluster and complex workflows
Error Handling Reference - Troubleshooting guide