Git Integration

The primitive git command group provides integration with Git repositories, enabling version control workflows and collaborative development on the Primitive platform.

Overview

Git integration allows you to:

• Connect repositories to Primitive projects
• Trigger jobs based on Git events (commits, pushes, releases)
• Manage code deployment and testing workflows
• Synchronize development between local and remote environments
• Track project changes and version history

primitive git <subcommand>

Access Git integration features for repository management and workflow automation.

# Basic Git integration commands
primitive git status
primitive git sync
primitive git webhook
primitive git deploy

Repository Integration

Repository Connection

Connect Git repositories to Primitive projects:

• GitHub Integration: Connect GitHub repositories with webhook support
• GitLab Integration: Link GitLab projects for CI/CD workflows
• Bitbucket Integration: Integrate Bitbucket repositories
• Generic Git: Support for any Git hosting service

Authentication

Git integration supports various authentication methods:

• SSH Keys: Secure key-based authentication
• Access Tokens: Personal access tokens for API integration
• OAuth: Streamlined authentication with Git providers
• Deploy Keys: Read-only access for specific repositories

Workflow Automation

Trigger Events

Git integration can trigger Primitive jobs on:

• Push Events: New commits pushed to branches
• Pull Request Events: PR creation, updates, merges
• Release Events: Tagged releases and version updates
• Branch Events: Branch creation, deletion, protection changes
• Webhook Events: Custom webhook configurations

Automated Workflows

Common automated workflows include:

• Continuous Integration: Run tests on every commit
• Deployment Pipelines: Deploy code to different environments
• Build Automation: Compile and package applications
• Quality Assurance: Run linting, security scans, performance tests
• Documentation: Generate and deploy documentation

Development Workflows

Code Synchronization

Keep development environments synchronized:

# Sync latest changes from repository
primitive git sync

# Deploy specific branch or tag
primitive git deploy --branch feature/new-feature

# Deploy tagged release
primitive git deploy --tag v1.2.3

Remote Development

Use Git integration for remote development:

• Code Checkout: Automatically checkout code on remote hardware
• Dependency Installation: Install project dependencies
• Environment Setup: Configure development environments
• Live Sync: Keep remote code synchronized with local changes

Collaborative Development

Support team development workflows:

• Shared Repositories: Multiple developers working on same codebase
• Branch Management: Coordinate feature branches and merges
• Code Review: Integrate with pull request workflows
• Release Management: Automate release processes

Project Integration

Project Configuration

Configure Git integration for projects:

• Repository URL: Connect project to Git repository
• Branch Strategy: Define main, development, and feature branches
• Webhook Configuration: Set up automated triggers
• Environment Variables: Configure secrets and environment settings
• Build Scripts: Define build and deployment commands

File Management

Git integration affects file management:

• Code Files: Automatically sync source code
• Configuration Files: Manage environment configurations
• Build Artifacts: Handle compiled and generated files
• Documentation: Keep documentation synchronized

CI/CD Integration

Continuous Integration

Implement CI workflows with Git integration:

1. Code Push: Developer pushes code to repository
2. Webhook Trigger: Git provider notifies Primitive platform
3. Job Creation: Platform creates CI job for new changes
4. Hardware Allocation: Job scheduled on available hardware
5. Environment Setup: Code checkout and dependency installation
6. Test Execution: Run test suites and quality checks
7. Result Reporting: Report results back to Git provider

Continuous Deployment

Implement CD workflows:

1. Release Creation: Tagged release created in repository
2. Deployment Trigger: Release event triggers deployment job
3. Build Process: Compile and package application
4. Environment Deployment: Deploy to staging or production
5. Health Checks: Verify deployment success
6. Rollback Capability: Automatic rollback on failure

Configuration and Setup

Repository Setup

# Connect repository to project
primitive git connect --repo https://github.com/user/project.git

# Configure webhook endpoints
primitive git webhook --setup

# Test connection
primitive git status

Webhook Configuration

Set up webhooks for automated workflows:

• Endpoint URL: Primitive platform webhook receiver
• Secret Token: Secure webhook authentication
• Event Selection: Choose which events trigger workflows
• Branch Filters: Limit triggers to specific branches

Environment Configuration

Configure Git integration environment:

• SSH Keys: Set up secure repository access
• Environment Variables: Configure secrets and settings
• Build Tools: Install necessary development tools
• Dependency Caches: Optimize build performance

Monitoring and Debugging

Workflow Monitoring

Monitor Git-triggered workflows:

# Check Git integration status
primitive git status

# View recent webhook events
primitive git events

# Monitor automated jobs
primitive jobs list --filter git-triggered

Debugging Workflows

Debug Git integration issues:

• Webhook Logs: Review webhook delivery and processing
• Job Logs: Examine automated job execution
• Authentication Issues: Verify repository access
• Configuration Problems: Check setup and settings

Security Considerations

Access Control

Git integration maintains security through:

• Repository Permissions: Respect Git provider permissions
• Secure Authentication: Use encrypted credential storage
• Webhook Security: Verify webhook authenticity
• Environment Isolation: Isolate build environments
• Secret Management: Secure handling of sensitive data

Best Practices

Security best practices for Git integration:

• Limited Permissions: Use minimal required permissions
• Regular Key Rotation: Rotate access keys and tokens
• Webhook Validation: Always validate webhook signatures
• Environment Separation: Separate development and production environments
• Audit Logging: Monitor all Git integration activities

Troubleshooting

Connection Issues

Repository Access Problems:

# Check repository connection
primitive git status

# Verify authentication
primitive git test-connection

# Update credentials if needed
primitive git configure --update-auth

Webhook Delivery Failures:

# Check webhook configuration
primitive git webhook --status

# Test webhook endpoint
primitive git webhook --test

# Review webhook logs
primitive git events --filter webhook-failures

Workflow Issues

Jobs Not Triggering:

# Verify webhook configuration
primitive git webhook --status

# Check recent events
primitive git events

# Test manual trigger
primitive git trigger --branch main

Build Failures:

# Check job logs
primitive jobs details git-job-123

# Review build environment
primitive git config --show

# Test build manually
primitive exec build-server "cd /project && ./build.sh"

Example Workflows

Basic CI Setup

# 1. Connect repository
primitive git connect --repo https://github.com/myteam/project.git

# 2. Configure webhook
primitive git webhook --setup --events push,pull_request

# 3. Test integration
primitive git status

# 4. Trigger test build
primitive git trigger --branch main

# 5. Monitor results
primitive jobs list

Deployment Pipeline

# 1. Configure deployment webhook
primitive git webhook --setup --events release

# 2. Set up deployment environment
primitive git configure --set deploy_target=production

# 3. Test deployment process
primitive git deploy --tag v1.0.0

# 4. Monitor deployment
primitive jobs details deployment-job-456

Development Workflow

# 1. Sync development environment
primitive git sync

# 2. Deploy feature branch for testing
primitive git deploy --branch feature/new-api

# 3. Run tests on remote hardware
primitive exec test-server "cd /project && npm test"

# 4. Monitor test results
primitive jobs list --project my-project

Integration Examples

GitHub Integration

# .github/workflows/primitive.yml
name: Primitive CI
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  primitive-ci:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Primitive Build
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.PRIMITIVE_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"branch": "${{ github.ref_name }}", "commit": "${{ github.sha }}"}' \
            https://api.primitive.tech/webhooks/github

GitLab Integration

# .gitlab-ci.yml
stages:
  - primitive-build

primitive-job:
  stage: primitive-build
  script:
    - primitive git trigger --commit $CI_COMMIT_SHA
    - primitive jobs wait --tag gitlab-ci
  only:
    - main
    - develop

Automated Testing

# Configure test automation
primitive git webhook --setup --events push
primitive git configure --set test_command="npm test"
primitive git configure --set test_timeout=1800

# Test configuration
primitive git trigger --branch main
primitive jobs details --filter test-jobs