cinzel

cinzel

Table of Contents

• About
• Installation and usage
  • Quick start
  • Configuration file
  • AI-assisted generation
  • Version management (GitHub Actions)
• Providers
  • GitHub Actions
  • GitLab CI/CD Pipelines
• Changelog
• Code of Conduct
• Contributing
• License

About

cinzel, pronounced as "sin-ZEL" (IPA: /sĩˈzɛl/), is the Portuguese word for chisel.

It's a bidirectional converter between HCL and CI/CD pipeline YAML, with provider-specific mappings (currently GitHub Actions and GitLab CI/CD).

Made with ❤ by YLD Limited.

Installation and usage

Install cinzel using one of these options:

• Download a prebuilt binary from GitHub Releases (recommended for most users).
• Install with Homebrew:

brew tap yldio/cinzel
brew install --cask cinzel

• Install from source with Go:

go install github.com/yldio/cinzel@latest

Confirm installation:

cinzel --help

Quick start

Use the provider command shape:

cinzel <provider> parse --file <input.hcl> --output-directory <out-dir>
cinzel <provider> unparse --file <input.yaml> --output-directory <out-dir>

Example: GitHub Actions parse/unparse:

cinzel github parse --file ./test.hcl --output-directory .github/workflows
cinzel github unparse --file ./.github/workflows/test.yaml --output-directory ./cinzel

Example: GitLab CI/CD parse/unparse:

cinzel gitlab parse --file ./pipeline.hcl --output-directory .
cinzel gitlab unparse --file ./.gitlab-ci.yml --output-directory ./cinzel

Read a whole directory instead of one file, and walk into its subdirectories:

cinzel github parse --directory ./cinzel --recursive

Flags shared by parse and unparse:

parse also takes --yml, which writes .yml files instead of .yaml. GitLab parse always writes .gitlab-ci.yml, so the flag only affects GitHub.

Configuration file

A .cinzelrc.yaml in the working directory supplies defaults, which any flag on the command line overrides:

github:
  parse:
    directory: ./cinzel
    output-directory: .github/workflows
    yml: false

It applies to parse and unparse only, per provider. assist, pin, upgrade and init ignore it. The keys under a command are file, directory, output-directory and, for parse, yml; anything else is reported as warning: ...: unknown key and skipped, recursive included.

Paths in it must be relative and written with forward slashes. The file is meant to be committed, so it is read on every machine that checks the repo out: an absolute path names one machine's disk and a leading ~ names one user, and both are refused with an error naming the key. Forward slashes are converted to the separator the running system uses, so one spelling works on Linux, macOS and Windows alike.

AI-assisted generation

Generate HCL workflow definitions from a natural language prompt:

cinzel github assist --prompt "golang PR with tests and linting"

This calls an LLM (Anthropic by default), generates valid YAML, converts it to HCL via the unparse pipeline, and writes to a timestamped session folder under ./cinzel/assist/. For GitHub, action versions are automatically pinned to SHAs. Blocks that match your existing HCL are replaced with // reuses: comments.

Each prompt creates its own session:

cinzel/assist/
  20260317-150405/     # first prompt
    assist.hcl
  20260317-151200/     # second prompt
    assist.hcl

Requires an API key, read from the environment:

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...
cinzel github assist --ai openai --prompt "..."

cinzel init writes a config file holding the default provider and the model to use for each. It does not store a key: the config is written to disk and swept up by a backup of your home directory, so the environment is the place for one.

cinzel init

Refine previous output (targets the latest session by default):

cinzel github assist --refine "add slack notification on failure" --prompt "add to PR workflow"

Refine a specific session:

cinzel github assist --refine "add caching" --from 20260317-150405

Other assist flags:

assist is available for both providers.

Version management (GitHub Actions)

pin and upgrade are GitHub-only; there is no GitLab equivalent.

Pin action tags to commit SHAs:

cinzel github pin                     # pin all actions in ./cinzel/
cinzel github pin --dry-run           # preview without writing

Upgrade actions to their latest versions:

cinzel github upgrade                 # bump to latest + pin SHAs
cinzel github upgrade --dry-run       # preview changes
cinzel github upgrade --parse         # bump + regenerate YAML

Both take --file/-f for a single file and --directory/-d for a directory (default cinzel). upgrade --parse writes the regenerated YAML to --output-directory (default .github/workflows).

No GitHub token is required for public actions. Set GITHUB_TOKEN for higher rate limits (5000/hr vs 60/hr).

For release operator details about Homebrew automation, see docs/release/homebrew.md.

Providers

Providers are the CI/CD platforms that cinzel can convert between HCL and YAML.

GitHub Actions

See provider/github/README.md for the full HCL schema reference and feature coverage.

GitLab CI/CD Pipelines

See provider/gitlab/README.md for the GitLab HCL schema and conversion coverage.

Changelog

Please visit the Changelog for more details.

Code of Conduct

Please check our Code of Conduct.

Contributing

Contributions are welcome, as well as suggestions for cinzel. Please go over to the Discussions first to understand the current state, features and issues before creating any issue or pull request. ❤

Please make sure to update tests as appropriate.

License

This project is licensed under the Apache-2.0 license. See LICENSE for details.