{"id":25970599,"url":"https://github.com/devops-infra/velez","last_synced_at":"2025-10-23T23:40:22.639Z","repository":{"id":278788314,"uuid":"935680249","full_name":"devops-infra/velez","owner":"devops-infra","description":"DevOps/CloudOps CLI framework for making work with Terragrunt and performing various cloud operations much easier.","archived":false,"fork":false,"pushed_at":"2025-03-02T00:00:33.000Z","size":282,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-02T01:18:52.898Z","etag":null,"topics":["cloud-engineering","devops-tools","terraform","terragrunt"],"latest_commit_sha":null,"homepage":"https://shyper.pro","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devops-infra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-19T20:55:15.000Z","updated_at":"2025-03-02T00:00:36.000Z","dependencies_parsed_at":"2025-02-21T18:23:15.578Z","dependency_job_id":"79748c42-2748-40eb-a610-41d48285218b","html_url":"https://github.com/devops-infra/velez","commit_stats":null,"previous_names":["devops-infra/velez"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-infra%2Fvelez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-infra%2Fvelez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-infra%2Fvelez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-infra%2Fvelez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devops-infra","download_url":"https://codeload.github.com/devops-infra/velez/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241935264,"owners_count":20044827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cloud-engineering","devops-tools","terraform","terragrunt"],"created_at":"2025-03-04T23:18:12.657Z","updated_at":"2025-10-23T23:40:22.633Z","avatar_url":"https://github.com/devops-infra.png","language":"Python","readme":"# Velez\n\nDevOps/CloudOps CLI framework for making work with Terragrunt and performing various cloud operations much easier and faster.\n\nDo you want to automate your daily tasks with Terragrunt, Terraform, GitHub, and other tools? Velez is here to help you!\n\nDo you sometimes forget to add changed files before pushing to GitHub? Velez will do that for you and even format HCL\nfiles before committing!\n\n\u003ca href=\"https://gitmoji.dev\"\u003e\n  \u003cimg\n    src=\"https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg?style=flat-square\"\n    alt=\"Gitmoji\"\n  /\u003e\n\u003c/a\u003e\n\n## Disclaimer\n\n**This project is in the early development stage and is not ready for production use. It is a work in progress and may\ncontain bugs, incomplete features, incorrect documentation, backward incompatible changes or other issues.\n\nUse it at your own risk before it reaches 1.x.x version. Read the documentation carefully and test it in a \nsafe environment before using it.**\n\nSince it operates on the infrastructure, user is responsible for the consequences of the actions taken by the tool and\nshould review the code before using it.\n\n![Velez](img/velez.jpg)\n\n\n## Advantages\n\n- Terragrunt **backend configuration** is read by invoking `terragrunt` command, so it is **always up to date** and resembles the\n  **real state of the infrastructure**, not just hardcoded values in the code.\n- All operations are performed in the **context of the current directory**, so you don't have to worry about running\n  commands in the wrong environment.\n\n\n## Features\n\nSupporting following services/tools and operations on them:\n\n- Terragrunt operations `-tg` or `--terragrunt`:\n    - Walk directory structure containing Terragrunt modules.\n    - Run Plan, Apply, Destroy and Output on a selected module or a specific target.\n    - Taint and Untaint a resource.\n    - Unlock module and show lock information.\n    - Run Validate and Refresh on a selected module.\n    - Import a resource to the state.\n    - Run State operations, like list, move, remove, show, pull and push.\n    - Run Module operations on source modules:\n        - Move a module to a new directory, including moving remote state.\n        - Destroy resources and backend of the module.\n        - Destroy backend of the module.\n- File operations `-f` or `--file`:\n    - Formatting all HCL files in the project.\n    - Cleaning up temporary files in the project or a selected module.\n- GitHub operations `-gh` or `--github`:\n    - Source operations, like commit, amend, push, pull or rebase.\n    - Branch operations, like create, change local or remote, delete local or remote.\n    - Manage pull requests, like create, list in the repository or the whole organization.\n    - Manage issues, like create, list in the repository or the whole organization.\n    - Easily remove stale branches.\n- Docker operations `-d` or `--docker`:\n    - List images in the registry or save them to a file for later use.\n    - Manage organization members, like invites or removes.\n    - Manage organization groups.\n\n## Installation\n\nFramework is written in Python and can be installed as a package.\n\n1. Clone the repository:\n    ```sh\n    git clone https://github.com/devops-infra/velez.git\n    ```\n2. Navigate to the project directory:\n    ```sh\n    cd velez\n    ```\n3. Install other dependencies:\n    * Install Python if not installed yet - required.\n    * Install Terragrunt, and Terraform or OpenTofu - required for IaaC operations.\n    * Install `hcledit` - required for updating `.hcl` files.\n    * Install `direnv` or similar solution - highly suggested for managing environments.\n\n   It can be installed, e.g. by running:\n    ```sh\n    brew install python\n    brew install terraform\n    brew install terragrunt\n    brew install direnv\n    brew install minamijoyo/hcledit/hcledit\n    ```\n4. Install the package:\n    ```sh\n    pip install .\n    ```\n\n## Usage\n\nTool is designed to speed up the work, so it expects some conditions:\n* It should be run in the project directory.\n* It should be run with the `direnv` or similar solution to load environment variables automatically.\n* It expects the project directory to be a Git repository.\n* It expects the project directory to be a Terragrunt project with a `root.hcl` (or other defined by `VELEZ_TG_ROOT_HCL`) file.\n* It expects the project directory to be a Docker project, with a project directory to be repository name and parent directory to be\n  organization name or personal account name (excluding `-` characters from the folder name).\n\n### Help\n\nRun the CLI with the `--help` argument to see the available commands:\n\n```sh\nvelez --help\n```\n\nTo use the Velez CLI, you have three options:\n\n### Interactive Menu\n\nRun the CLI without additional arguments to use the interactive menu:\n\n```sh\nvelez\n```\n\n### Interactive Menu for specific operation\n\n#### Terragrunt operations (`-tg` or `--terragrunt`)\n\n```sh\nvelez --terragrunt\n```\n\n#### File operations (`-f` or `--file`)\n\nShow menu for file operations:\n\n```sh\nvelez --file\n```\n\n#### GitHub operations (`-gh` or `--github`)\n\nShow menu for GitHub operations:\n\n```sh\nvelez --github\n```\n\n### Automation / CLI\n\nRun the CLI with additional arguments for automation/scripting:\n\n#### Terragrunt operations (`-tg` or `--terragrunt`)\n\n```sh\nvelez --terragrunt \u003coperation\u003e \u003cmodule\u003e \u003cother-arguments\u003e\n```\n\nWhere:\n\n* `\u003coperation\u003e` is a Terraform/Terragrunt operation to perform, e.g. `plan`.\n* `\u003cmodule\u003e` is a relative path to a Terragrunt module to operate on, e.g. `aws/dev-account`.\n* `\u003cother-arguments\u003e` are additional arguments for the Terraform and Terragrunt operations, e.g.\n  `--target=module.resource`.\n\nFor example for the following directory structure:\n\n```plaintext\n. \n├── aws\n│   ├── dev-account\n│   │   └── terragrunt.hcl\n│   ├── prod-account\n│   │   └── terragrunt.hcl\n│   └── aws.hcl\n├── .env\n└── root.hcl\n```\n\nRun the following command to plan the `aws/dev-account` module:\n\n```sh\nvelez -tg plan aws/dev-account\n``` \n\n## Configuration\n\nVelez expects following environment variables to be set:\n\n| Variable                        | Description                                                                                                                           | Required for operations | Default               |\n|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|-------------------------|-----------------------|\n| `VELEZ_TG_ROOT_HCL`             | Relative path to the Terragrunt configuration file.                                                                                   | Terragrunt              | `root.hcl`            |\n| `VELEZ_TG_TEMP_CONFIG`          | Absolute path to a temporary file created to render Terragrunt configuration.                                                         | Terragrunt              | `/tmp/terragrunt.hcl` |\n| `GITHUB_TOKEN`                  | GitHub token for accessing the GitHub API.                                                                                            | GitHub                  | `N/A`                 |\n| `GITHUB_STALE_BRANCHES_DAYS`    | Number of days after which branches are considered stale.                                                                             | GitHub                  | `45`                  |\n| `GITHUB_STALE_BRANCHES_COMMITS` | Number of commits after which branches are considered stale.                                                                          | GitHub                  | `30`                  |\n| `DOCKER_USERNAME`               | Docker username for logging in to the Docker registry.                                                                                | Docker                  | `N/A`                 |\n| `DOCKER_TOKEN`                  | Docker personal access token or organization access token for logging in to the Docker registry.                                      | Docker                  | `N/A`                 |\n| `DOCKER_REPOSITORY`             | Default Docker repository for operations.                                                                                             | Docker                  | current directory     |\n| `DOCKER_OWNER`                  | Default Docker owner of repositories.\u003cbr\u003eCan be not set or set to Docker username for personal repositories, or to organization name. | Docker                  | parent directory      |\n| `DOCKER_STALE_IMAGES_DAYS`      | Number of days after which images are considered stale.                                                                               | Docker                  | `30`                  |\n\nFor the convenience, these variables can be set in a `.envrc` or similar file in the project directory and use with the `direnv` (\nmentioned above; or other similar software) to load them automatically for every project separately and use inheritance for the convenience.\n\nVelez will read Terragrunt configuration to expand any dynamic load available config remotely.\nFor example for each selected Terragrunt module backed configuration will be read to determine exact values of the S3\nbucket and DynamoDB table and key used for locking the state.\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Velez\n\nName of the project is a misspelled name of the slavic god of the\nunderworld - [Veles](https://en.wikipedia.org/wiki/Veles_(god)).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevops-infra%2Fvelez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevops-infra%2Fvelez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevops-infra%2Fvelez/lists"}