Connect Your Workload to Git

Version control your infrastructure by connecting CloudAgent workloads to GitHub. Every deployment creates a pull request with your CloudFormation changes — giving you full history, code review, and GitOps workflows.

What You'll Learn

• Connect a GitHub repository to your workload via the dashboard
• How CloudAgent proposes infrastructure changes via pull requests
• Review infrastructure diffs before they're merged

Prerequisites: Complete Deploy AWS from Cursor first.

Why Git Integration?

How Git Integration Works

CloudAgent's git integration follows a PR-only model for security:

• All changes go through pull requests — CloudAgent never commits directly to your main branch
• You control the merge — Review, approve, and merge PRs through your normal GitHub workflow
• CloudAgent has no write access to main — This is intentional for security

This design ensures your infrastructure changes always go through code review before being applied.

Step 1: Connect GitHub to CloudAgent

Link your GitHub account to CloudAgent via the dashboard:

1. Go to Dashboard → Integrations (opens in a new tab)
2. Click Connect GitHub
3. Complete the OAuth authorization flow in GitHub
4. Select which repositories CloudAgent can access

Step 2: Link Repository to Workload

Configure git for your workload through the dashboard:

1. Go to Dashboard → Workloads (opens in a new tab)
2. Select your workload
3. Click Settings and Deployment tab
4. Under Source code, select GitHub repository
5. Choose:
   • GitHub Connection: Your linked account
   • Repository: Target repo
   • Base Branch: main or master (the branch PRs will target)
6. Click Save Changes

Step 3: Deploy with Pull Requests

When you deploy with git integration enabled, CloudAgent creates a pull request:

You: "Add an SQS queue for async processing"

CloudAgent generates the resource and shows:

Adding to workload: file-processor
Repository: myorg/file-processor-infra

Changes:
+ AWS::SQS::Queue (ProcessingQueue)
+ AWS::SQS::QueuePolicy

This will create a pull request for review.

Proceed?

You: "Yes"

Result:

• CloudAgent creates a new branch with your changes
• A pull request is opened against your base branch
• You receive a link to review: https://github.com/myorg/file-processor-infra/pull/42

Step 4: Review Changes in GitHub

After deployment, review the pull request in GitHub:

PR Contents

Your PR includes:

• CloudFormation diff showing exactly what changed
• Resources being added, modified, or deleted
• Security rules that were applied
• Estimated cost impact (if enabled)

Repository Structure

Once merged, your repository contains:

myorg/file-processor-infra/
├── cloudformation/
│   └── file-processor.yaml    ← Full CloudFormation template
├── README.md
└── .cloudagent/
    └── workload.json          ← Workload metadata

Your CloudFormation template contains all resources:

# cloudformation/file-processor.yaml
AWSTemplateFormatVersion: '2010-09-09'
Description: file-processor workload managed by CloudAgent
 
Resources:
  UploadsBucket:
    Type: AWS::S3::Bucket
    # ... full configuration
 
  ProcessorFunction:
    Type: AWS::Lambda::Function
    # ... full configuration
 
  ProcessingQueue:          # ← New resource
    Type: AWS::SQS::Queue
    # ... full configuration

Rollbacks and Reverts

To revert infrastructure changes:

1. Use git revert — Create a revert commit in your repository
2. Merge the revert — Follow your normal PR/merge process
3. Redeploy via CloudAgent — Ask CloudAgent to sync the workload with the reverted template

# In your repository
git revert <commit-hash>
git push origin main

Then in Cursor:

You: "Sync file-processor with the latest template from git"

This design ensures:

• The main branch owner controls what gets merged
• All changes (including reverts) go through code review
• CloudAgent cannot accidentally overwrite your main branch

Git Configuration Options

Configure in Dashboard → Workloads → Settings and Deployment → Git Repository.

Troubleshooting

"Repository not found"

• Ensure CloudAgent has access: Dashboard → Integrations (opens in a new tab)
• Check repository name is correct
• Verify the OAuth connection is still valid

"Permission denied"

• Re-authorize the GitHub connection in the dashboard
• Ensure the repository allows CloudAgent to create branches and PRs

PRs not appearing

• Check the configured base branch exists
• Verify deployment succeeded in CloudFormation console
• Check GitHub for any branch protection rules blocking PR creation

"Can't configure git via chat"

• Git setup requires OAuth authentication
• Use the Dashboard → Integrations (opens in a new tab) page to connect GitHub

Security Design

CloudAgent's git integration is designed with security in mind:

This ensures that CloudAgent enhances your workflow without compromising your repository's security model.

Next Steps

Related

• Managing Workloads — Full workload configuration options
• Integrations — Connect GitHub, GitLab, Bitbucket