AGENT.md

Overview

This repository leverages GitHub Copilot as an embedded agent to assist with large-scale infrastructure management using Terraform and GitHub Actions. Copilot automates, reviews, and enhances workflows, improving reliability and developer experience.

Agent Role

Automation Assistant: Generate, review, and validate Terraform and CI/CD code.
Workflow Orchestrator: Trigger and manage GitHub Actions pipelines for infrastructure changes.
Advisor: Detect anti-patterns, recommend best practices, and surface documentation.
Monitor & Notifier: Track pipeline status, errors, and changes, notifying teams as needed.

How Copilot Operates

Offers context-aware completions for Terraform modules, variables, and workflows.
Suggests improvements, refactoring, or best practices during PRs and code reviews.
Reviews PRs for formatting, validation, and security.
Posts comments or statuses based on validation results.
Initiates infrastructure plans and applies via GitHub Actions, ensuring state files are stored securely.
Surfaces workflow errors, deployment status, and change logs.

Guardrails for Environment Safety

Copilot and automation agents should only have direct apply permissions in the Copilot/Dev environment.
For staging and production, all changes must be proposed via pull requests and require human approval before apply actions can be performed.
Production and stage environments are protected:
- No direct changes from Copilot or automation.
- All changes must be merged via Pull Requests with human review.
- GitHub Actions for production require manual approval and restricted secrets access.
Environment-specific workflows isolate deployment and validation actions.
Terraform workspaces and state files are separated by environment to prevent accidental cross-environment changes.

Summary:
Copilot can automate, validate, and propose changes in non-production environments, but cannot apply changes to staging or production directly. All production changes require PRs, review, and explicit approval.

Best Practices

Always review Copilot’s recommendations before merging or applying changes.
Store sensitive information in GitHub Secrets and remote state backends.
Document custom workflows and modules for future reference.
Use PR approvals and branch protections to enforce safe changes.

Limitations

Copilot does not apply infrastructure changes automatically; human approval is always required.
Cannot access secrets or sensitive data directly.
Operates only within the context of the repository and its workflows.

Sample GitHub Actions Workflows (with tfplan Artifact Handling)

1. Terraform Plan & Artifact Upload (Copilot/Dev)

on:
  push:
    branches:
      - copilot
      - dev
jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform fmt -check
      - run: terraform validate
      - run: terraform plan -out=tfplan
      - uses: actions/upload-artifact@v4
        with:
          name: tfplan-dev
          path: tfplan

2. Terraform Apply (Copilot/Dev) – Downloads Artifact

on:
  workflow_dispatch:
jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - uses: actions/download-artifact@v4
        with:
          name: tfplan-dev
          path: .
      - run: terraform apply -auto-approve tfplan
        env:
          TF_VAR_environment: "dev"

3. Terraform Plan & Artifact Upload (Production/Staging) – No Direct Apply

on:
  pull_request:
    branches:
      - main
      - prod
      - stage
jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform fmt -check
      - run: terraform validate
      - run: terraform plan -out=tfplan
      - uses: aquasecurity/[email protected]
      - uses: actions/upload-artifact@v4
        with:
          name: tfplan-prod
          path: tfplan

4. Terraform Apply (Production/Staging) – Manual Approval & Artifact Download

on:
  workflow_dispatch:
    inputs:
      approved:
        description: 'Has the change been approved by a maintainer?'
        required: true
        type: boolean
jobs:
  terraform:
    runs-on: ubuntu-latest
    environment:
      name: production
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - uses: actions/download-artifact@v4
        with:
          name: tfplan-prod
          path: .
      - run: terraform apply -auto-approve tfplan
        env:
          TF_VAR_environment: "prod"

How It Works:

The plan workflow creates a tfplan file and uploads it as an artifact.
The apply workflow is manually triggered, downloads the artifact, and applies it.
Artifacts are not stored by GitHub automatically for use between workflows—you must upload and download them as shown.

References

For questions or suggestions, open an issue or PR in this repository.

gdumitrescu/AGENT.md