{"id":22347760,"url":"https://github.com/wearetechnative/race","last_synced_at":"2026-04-28T22:34:34.376Z","repository":{"id":243641257,"uuid":"794153365","full_name":"wearetechnative/race","owner":"wearetechnative","description":"Terraform Tools for TechNative CatStack","archived":false,"fork":false,"pushed_at":"2026-02-11T15:02:24.000Z","size":333,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-11T23:33:04.710Z","etag":null,"topics":["catstack","opentofu","terraform"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wearetechnative.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-04-30T14:56:04.000Z","updated_at":"2026-02-11T15:02:21.000Z","dependencies_parsed_at":"2024-06-10T11:34:33.359Z","dependency_job_id":"78f44af1-e7d8-4088-bfb1-66721c206399","html_url":"https://github.com/wearetechnative/race","commit_stats":null,"previous_names":["wearetechnative/race"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/wearetechnative/race","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearetechnative%2Frace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearetechnative%2Frace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearetechnative%2Frace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearetechnative%2Frace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wearetechnative","download_url":"https://codeload.github.com/wearetechnative/race/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wearetechnative%2Frace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32402670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"ssl_error","status_checked_at":"2026-04-28T19:37:55.688Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["catstack","opentofu","terraform"],"created_at":"2024-12-04T10:10:49.342Z","updated_at":"2026-04-28T22:34:34.370Z","avatar_url":"https://github.com/wearetechnative.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Race - Remote AWS Code Control Executor - Terraform Tools for CatStack\n\n**Tools for CatStack** (https://github.com/wearetechnative/catstack)\n\n\u003cimg src=\"images/image1-3.jpg\" /\u003e\n\n\n\nRACE (Remote AWS Code Control Executor) is a collection of Infrastructure as Code (IaC) utilities that make life easier for Cloud Engineers. RACE is designed to work with [CatStack](https://github.com/wearetechnative/catstack) and provides an integrated CLI for managing backends, variables, and Nix workflows. Currently focused on Terraform, with future support planned for OpenTofu and other IaC tools.\n\n**Version:** 0.1.5\n\n## Features\n\n- **Backend Management**: Easily switch between multiple IaC backends (Terraform/OpenTofu)\n- **Automatic tfvars selection**: Automatically matches the correct `.tfvars` files to your backend\n- **Nix Integration**: Intelligent matching of backends with Nix flake targets\n- **Safety Protection**: Prevents accidental destruction of critical resources (backend, DynamoDB, KMS)\n- **Interactive CLI**: User-friendly menus for backend selection\n- **Multi-environment support**: Work seamlessly with nonprod, prod, and other environments\n- **Extensible**: Designed with future support for OpenTofu and other IaC tools in mind\n- **Git Sync**: Automatically commit, tag, and push after successful applies to keep git in sync with cloud state\n\n## Installation\n\n### Via Nix Flakes\n\n```bash\nnix profile install github:wearetechnative/race\n```\n\n### Manual installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/wearetechnative/race.git\ncd race\n```\n\n2. Make the scripts executable and add to your PATH:\n```bash\nchmod +x race\nsudo ln -s $(pwd)/race /usr/local/bin/race\n```\n\n## Usage\n\nRACE provides a unified command-line interface for all IaC utilities:\n\n```bash\nrace [command]\n```\n\n### Available commands\n\n- `race usage` - Show help information\n- `race version` - Show race version\n- `race init` - Configure backend (currently Terraform, OpenTofu support planned)\n- `race plan` - Run plan command with automatic tfvars selection\n- `race apply` - Run apply command with automatic tfvars selection\n- `race nixrun` - Run nix run for the selected backend\n- `race elastinixkey` - Generate SSH keypair\n\n### Workflow\n\n#### 1. Configure backend\n\n```bash\nrace init\n```\n\nThis script searches for all `*.tfbackend` files in your project and lets you interactively choose a backend. The selection is saved in `.terraform/tfbackend.state`.\n\n#### 2. Plan/Apply\n\n```bash\nrace plan\nrace apply\n```\n\nThese commands:\n- Read the active backend from `.terraform/tfbackend.state`\n- Automatically match the corresponding `.tfvars` file (e.g., `nonprod.tfbackend` → `nonprod.tfvars`)\n- Execute the IaC tool (currently Terraform) with the correct variables\n\n#### 3. Nix integration\n\nFor projects using Nix flakes:\n\n```bash\nrace nixrun\n```\n\nThis script:\n- Reads the active backend from `.terraform/tfbackend.state`\n- Searches for matching targets in `flake.nix`\n- Executes `nix run .#\u003ctarget\u003e` for the correct environment\n\n## Project Structure\n\nRACE expects a specific project structure that works with CatStack:\n\n```\nproject/\n├── *.tfbackend          # Backend configurations (nonprod.tfbackend, prod.tfbackend)\n├── *.tfvars             # Variable files (nonprod.tfvars, prod.tfvars)\n├── flake.nix            # (Optional) Nix flake for declarative workflows\n├── stack/               # IaC stack directories (Terraform/OpenTofu)\n│   └── domain/          # Domain-specific IaC code\n└── .terraform/\n    └── tfbackend.state  # Current active backend (managed by race)\n```\n\n## Examples\n\n### Example 1: Switching between environments\n\n```bash\n# Configure nonprod backend\nrace init\n# Select: 0: nonprod.tfbackend\n\n# Plan changes for nonprod\nrace plan\n\n# Switch to prod\nrace init\n# Select: 1: prod.tfbackend\n\n# Plan changes for prod\nrace plan -out prod.tfplan\n```\n\n### Example 2: Nix workflow\n\n```bash\n# Configure backend\nrace init\n# Select: nonprod\n\n# Run nix run (automatically matches nonprod_apply in flake.nix)\nrace nixrun\n```\n\n## Requirements\n\n- Bash 4.0+\n- Terraform (or OpenTofu - planned support)\n- AWS CLI (with configured `AWS_PROFILE`)\n- (Optional) Nix with flakes support\n- (Optional) gum - for better interactive prompts\n\n## Git Sync (Auto-commit after Apply)\n\nRACE can automatically commit, tag, and push your changes after a successful `terraform apply` or `nix run` apply operation. This ensures your git repository stays in sync with your deployed cloud state.\n\n### How it works\n\n1. **Pre-apply check**: Before running apply, RACE checks for untracked files. If found, the apply is blocked to ensure all changes are committed.\n2. **Post-apply sync**: After a successful apply, RACE automatically:\n   - Commits any staged changes with message: `RACE: apply {environment} {domain}`\n   - Creates a tag: `{environment}_{domain}_{YYYYMMDD-HHhMMm}` (e.g., `nonprod_01_shared_kms_20260211-14h30m`)\n   - Pushes the commit and tag to the remote\n\n### Configuration\n\nGit sync is **enabled by default**. Configure with environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `RACE_GIT_SYNC_ENABLED` | `true` | Set to `false` to disable git sync |\n| `RACE_GIT_REMOTE` | `origin` | Git remote to push to |\n| `RACE_STACK_DOMAIN` | auto-detected | Override the stack domain name in tags |\n\n### Examples\n\n```bash\n# Disable git sync for this apply\nRACE_GIT_SYNC_ENABLED=false race apply\n\n# Use a different git remote\nRACE_GIT_REMOTE=upstream race apply\n\n# Override the domain name in tags\nRACE_STACK_DOMAIN=custom_domain race apply\n```\n\n## Safety Measures\n\nRACE includes built-in safety measures:\n\n1. **Git status check**: Before apply operations, RACE checks for untracked files and blocks the operation if found\n2. **Nix projects**: When `.nix` files are detected, race asks for confirmation before executing IaC commands\n3. **Destroy protection**: The `tfdestroy` script prevents destruction of resources with names:\n   - backend\n   - dynamodb\n   - kms\n\n## Documentation\n\nFor detailed documentation on individual components:\n\n- [Backend Switcher and Tools](./docs/terraform-backend-tools.md)\n- [Setup TF Plugin Cache](./docs/setup_tf_plugin_cache.md)\n\n## Future Roadmap\n\n- **OpenTofu Support**: Native support for OpenTofu as an alternative to Terraform\n- **Additional IaC Tools**: Expand support to other Infrastructure as Code tools\n- **Enhanced Nix Integration**: Extended Nix flake patterns and workflows\n\n## Development\n\nRACE is built with:\n- Bash for the core scripts\n- Python for documentation generation\n- Nix for reproducible builds and distribution\n\n### Testing\n\nRACE uses [ShellSpec](https://github.com/shellspec/shellspec) for unit testing.\n\n```bash\n# Enter the development shell (includes shellspec)\nnix develop\n\n# Run all tests\nshellspec\n\n# Run tests with verbose output\nshellspec --format documentation\n\n# Run specific spec file\nshellspec spec/racelib_spec.sh\n\n# Run tests in parallel\nshellspec --jobs 4\n```\n\nTest files are located in `spec/`:\n- `spec/racelib_spec.sh` - Tests for core library functions\n- `spec/git_sync_spec.sh` - Tests for git sync functionality\n\n### Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for a complete overview of changes.\n\n## License\n\nRACE is available under the MIT license. See [LICENSE](./LICENSE) for more information.\n\n## Authors\n\nDeveloped by Wouter, Pim, et al. at [Technative](https://technative.nl)\n\n© Technative 2024\n\n## Links\n\n- [GitHub Repository](https://github.com/wearetechnative/race)\n- [CatStack](https://github.com/wearetechnative/catstack)\n- [Technative](https://technative.eu)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwearetechnative%2Frace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwearetechnative%2Frace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwearetechnative%2Frace/lists"}