CI/CD Repository

Scenario

You maintain CI/CD configuration responsible for:

• testing;
• building;
• container publishing;
• deployments;
• release automation.

Changes to pipeline files can affect every developer or trigger production deployments.

You want coding agents to understand which parts of the pipeline are ordinary validation and which parts can create external side effects.

Repository Structure

application/
├── src/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       ├── deploy-staging.yml
│       └── deploy-production.yml
├── scripts/
│   ├── build.sh
│   └── deploy.sh
├── Dockerfile
└── AGENTS.md

AGENTS.md

# CI/CD Instructions

## CI Workflows

- Preserve existing validation stages unless the task explicitly changes CI policy.
- Reuse repository scripts instead of duplicating complex commands directly in workflow files when practical.
- Keep local validation and CI validation aligned.

## Deployment Workflows

- Treat deployment workflow changes as high-impact.
- Preserve existing environment protections and approval gates.
- Do not remove production approvals merely to simplify automation.
- Do not change production deployment triggers unintentionally.

## Secrets

- Reference CI/CD secrets through the platform's secret mechanism.
- Never hardcode credentials, tokens, private keys, or production secrets in workflow files.
- Do not print secrets in diagnostic output.

## Permissions

- Keep workflow permissions as narrow as practical.
- Do not grant broad repository or cloud permissions solely to resolve a failing step.

## Validation

After workflow changes:

- validate YAML syntax;
- inspect trigger changes;
- inspect permissions;
- verify referenced scripts and commands exist;
- run locally reproducible commands when practical.

For deployment changes, review environment and production impact before completion.

What This Does

This separates two types of pipeline behavior.

For example:

pull request
    ↓
lint
typecheck
test
build

primarily validates code.

But:

merge
   ↓
build image
   ↓
push registry
   ↓
deploy production

creates external side effects.

The second workflow deserves additional caution.

What This Does NOT Do

The instructions do not prevent agents from improving deployment automation.

They also do not require every CI command to live in a shell script.

The important goal is avoiding duplicated complex logic when a repository command already exists.

For example, if:

pnpm validate

already runs the correct checks, the workflow may not need to reconstruct that sequence independently.

Why These Instructions Matter

A one-line CI change can have a large impact.

For example:

on:
  pull_request:

changing to:

on:
  push:

may completely change when a workflow executes.

Likewise:

permissions:
  contents: write

is materially different from:

permissions:
  contents: read

Pipeline code deserves the same review as application code, sometimes more.

Deployment gates are another example.

An agent may remove a manual production approval because:

It prevents the workflow from being fully automatic.

But the approval may be an intentional operational control.

Key Decisions

Treat triggers as behavior

Workflow triggers determine when side effects occur.

They should be reviewed like application control flow.

Keep CI and local workflows aligned

If developers run:

pnpm validate

locally, CI should ideally reuse the same underlying validation rather than implement a different interpretation.

Protect deployment controls

Environment approvals and protected branches may exist for operational or security reasons.

Minimize permissions

CI systems often have powerful repository and cloud credentials.

Grant only what the workflow actually needs.

Never expose secrets for debugging

A failing deployment does not justify printing credentials into CI logs.

When to Use This Pattern

Use this pattern when:

• CI/CD configuration lives in the repository;
• workflows deploy applications;
• pipelines use privileged credentials;
• workflow changes can affect production;
• coding agents modify automation files.

CI/CD code is application infrastructure and should be treated accordingly.