# Deployment Bot

LLMS index: [llms.txt](https://hummingbird-project.io/llms.txt) | Full content: [llms-full.txt](https://hummingbird-project.io/llms-full.txt)

---

An AWS CloudFormation/SAM stack that provisions IAM resources for automated
AWS deployments from GitLab CI. Creates a service account with permissions
to deploy SAM applications including Lambda functions, API Gateway, SNS
topics, and related resources.

## Features

- **IAM Service Account**: Dedicated user for CI/CD pipelines
- **Scoped Permissions**: Least-privilege access for SAM deployments
- **Resource Naming**: All managed resources use consistent prefix

## Architecture

Single SAM template that creates:

1. **IAM User** - Service account for deployments (`${ResourcePrefix}-deployment-bot`)
2. **IAM Policy** - Permissions for SAM deployment operations

## Prerequisites

- AWS CLI configured with admin credentials
- Podman or Docker (for containerized SAM build/deploy)

## Deployment

Deploy using containerized AWS SAM CLI:

```bash
cd deployment-bot
sam build
sam deploy --guided  # First deployment (interactive)
sam deploy           # Subsequent deployments
```

After deployment, create access keys for the IAM user and store them securely
in HashiCorp Vault.

### SAM Parameters

| Parameter                  | Description                                          | Default      |
|----------------------------|------------------------------------------------------|--------------|
| `ResourcePrefix`           | Prefix for resources                                 | `myapp-prod` |
| `AdditionalResourcePrefix` | Additional prefix this bot can manage (e.g. staging) | `""`         |

**Resource naming:** IAM resources follow `{ResourcePrefix}-deployment-bot`
pattern (e.g., `myapp-prod-deployment-bot`). Use `AdditionalResourcePrefix`
to allow the same bot to manage resources in another environment.

## Permissions

The deployment bot has permissions to manage:

| Service        | Scope                                                      |
|----------------|------------------------------------------------------------|
| CloudFormation | Stacks matching `${ResourcePrefix}-*`, SAM bootstrap stack |
| S3             | SAM CLI managed buckets                                    |
| Lambda         | Functions matching `${ResourcePrefix}-*`                   |
| API Gateway    | All REST APIs and domains                                  |
| SNS            | Topics matching `${ResourcePrefix}-*`                      |
| IAM            | Users/policies/roles matching `${ResourcePrefix}-*`        |
| CloudWatch     | Log groups for managed Lambda functions                    |
| Route53        | Record changes (for custom domains)                        |
| ACM            | Certificate management                                     |

## Usage

### Bootstrap (One-Time)

The deployment bot must be deployed first using admin credentials:

```bash
# With admin AWS credentials
cd deployment-bot
sam build
sam deploy --guided
```

Create access keys for the new IAM user and store in HashiCorp Vault.

### Automated Deployments

Once bootstrapped, the deployment bot credentials are used by `aws_deploy.sh`
in the infrastructure repository for all subsequent SAM deployments:

```bash
export PROJECT_NAME=gitlab-event-forwarder
./aws_deploy.sh
```

GitLab CI runs this automatically via the `aws` matrix job.

## Development

This project contains only a SAM template with no application code.

## Security

- Access keys should be stored in HashiCorp Vault
- Permissions are scoped to resources with the configured prefix
- Route53 and ACM have broader permissions due to API limitations

## License

This project is licensed under the GNU General Public License v3.0 or later -
see the [LICENSE][license] file for details.

[license]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/LICENSE