{"id":13644636,"url":"https://github.com/sethvargo/ratchet","last_synced_at":"2025-05-16T07:03:27.456Z","repository":{"id":37975341,"uuid":"475208896","full_name":"sethvargo/ratchet","owner":"sethvargo","description":"A tool for securing CI/CD workflows with version pinning.","archived":false,"fork":false,"pushed_at":"2025-05-08T21:07:33.000Z","size":2478,"stargazers_count":828,"open_issues_count":2,"forks_count":37,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-08T22:20:26.375Z","etag":null,"topics":["cicd","dependency","security"],"latest_commit_sha":null,"homepage":"","language":"Go","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/sethvargo.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-03-28T23:15:09.000Z","updated_at":"2025-05-08T21:07:07.000Z","dependencies_parsed_at":"2023-02-18T17:30:57.696Z","dependency_job_id":"71748500-bcff-401e-b1bb-369d27c766e5","html_url":"https://github.com/sethvargo/ratchet","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethvargo%2Fratchet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethvargo%2Fratchet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethvargo%2Fratchet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethvargo%2Fratchet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sethvargo","download_url":"https://codeload.github.com/sethvargo/ratchet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485029,"owners_count":22078767,"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":["cicd","dependency","security"],"created_at":"2024-08-02T01:02:09.884Z","updated_at":"2025-05-16T07:03:27.366Z","avatar_url":"https://github.com/sethvargo.png","language":"Go","funding_links":[],"categories":["Go","Build techniques"],"sub_categories":["Supply chain beyond libraries"],"readme":"# Ratchet\n\n![ratchet logo](docs/ratchet.png)\n\nRatchet is a tool for improving the security of CI/CD workflows by automating\nthe process of pinning and unpinning upstream versions. It's like Bundler,\nCargo, Go modules, NPM, Pip, or Yarn, but for CI/CD workflows. Ratchet supports:\n\n-   Circle CI\n-   GitHub Actions\n-   GitLab CI\n-   Google Cloud Build\n-   Harness Drone\n-   Tekton\n\n**⚠️ Warning!** The README corresponds to the `main` branch of ratchet's\ndevelopment, and it may contain unreleased features.\n\n\n## Problem statement\n\nMost CI/CD systems are one layer of indirection away from `curl | sudo bash`.\nUnless you are specifically pinning CI workflows, containers, and base images to\nchecksummed versions, _everything_ is mutable: GitHub labels are mutable and\nDocker tags are mutable. This poses a substantial security and reliability risk.\n\nWhat you're probably doing:\n\n```yaml\nuses: 'actions/checkout@v4'\n# or\nimage: 'ubuntu:20.04'\n```\n\nWhat you should really be doing:\n\n```yaml\nuses: 'actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683'\n# or\nimage: 'ubuntu@sha256:47f14534bda344d9fe6ffd6effb95eefe579f4be0d508b7445cf77f61a0e5724'\n```\n\nBut resolving those checksums and managing the update lifecycle is extremely\ntoilsome. That's what ratchet aims to solve! Ratchet resolves and updates\nunpinned references to the latest version that matches their constraint, and\nthen keeps a record of the original constraint.\n\n```yaml\nuses: 'actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683' # ratchet:actions/checkout@v4\n# or\nimage: 'ubuntu@sha256:47f14534bda344d9fe6ffd6effb95eefe579f4be0d508b7445cf77f61a0e5724' # ratchet:ubuntu:20.04\n```\n\n\n## Installation\n\nThere are a few options for installing ratchet:\n\n-   Via homebrew:\n\n    ```sh\n    brew install ratchet\n    ```\n\n    Note this option is community supported and may not be the latest\n    available version.\n\n-   As a single-static binary from the [releases page][releases].\n-   As a container image from the [container registry][containers].\n-   Via nix:\n\n    ```sh\n    nix run 'github:NixOS/nixpkgs/nixpkgs-unstable#ratchet' -- --help\n    ```\n\n    Note this option is community supported and may not be the latest\n    available version.\n\n-   Via golang:\n\n    ```sh\n    go install github.com/sethvargo/ratchet@latest\n    ```\n\n-   Compiled from source yourself. Note this option is not supported.\n\n\n## Usage\n\nFor more information about available commands and options, run a command with\n`-help` to use detailed usage instructions.\n\n#### Pin\n\nThe `pin` command pins to specific versions:\n\n```shell\n# pin the input file\nratchet pin workflow.yml\n\n# pin a circleci file\nratchet pin -parser circleci circleci.yml\n\n# pin a cloudbuild file\nratchet pin -parser cloudbuild cloudbuild.yml\n\n# pin a drone file\nratchet pin -parser drone drone.yml\n\n# pin a gitlab file\nratchet pin -parser gitlabci gitlabci.yml\n\n# output to a tekton file\nratchet pin -out -parser tekton tekton.yml\n\n# output to a different path\nratchet pin -out workflow-compiled.yml workflow.yml\n```\n\n#### Unpin\n\nThe `unpin` command unpins any pinned versions:\n\n```shell\n# unpin the input file\nratchet unpin workflow.yml\n\n# output to a different path\nratchet unpin -out workflow.yml workflow-compiled.yml\n```\n\n#### Update\n\nThe `update` command updates all versions to the latest matching constraint:\n\n```shell\n# update the input file\nratchet update workflow.yml\n\n# update a circleci file\nratchet update -parser circleci circleci.yml\n\n# update a cloudbuild file\nratchet update -parser cloudbuild cloudbuild.yml\n\n# output to a different path\nratchet update -out workflow-compiled.yml workflow.yml\n```\n\n#### Upgrade\n\n\u003e [!NOTE]\n\u003e This command only works with GitHub Actions references. It does not support\n\u003e container or Docker-based references.\n\nThe `upgrade` command upgrades all versions to the latest version, changing the\nratchet comment and also updating the ref.\n\n```shell\n# upgrade the input file\nratchet upgrade workflow.yml\n\n# output to a different path\nratchet upgrade -out workflow-compiled.yml workflow.yml\n```\n\n\u003e [!NOTE]\n\u003e Performs an `update` if the constraint ref is for a branch.\n\n#### Lint\n\nThe `lint` command reports if all versions are pinned, printing any violations,\nand exiting with a non-zero error code when entries are not pinned:\n\n```shell\nratchet lint workflow.yml\n```\n\n## Examples\n\n#### CI/CD workflow\n\nRatchet is distributed as a very small container, so you can use it as a step\ninside CI/CD jobs. Here is a GitHub Actions example:\n\n```yaml\njobs:\n  my_job:\n    runs-on: 'ubuntu-latest'\n    name: 'ratchet'\n    steps:\n      - uses: 'actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683'\n      - uses: 'sethvargo/ratchet@main' # ratchet:exclude\n        with:\n          files: '.github/workflows/*.yml'\n```\n\nThis same pattern can be extended to other CI/CD systems: download the `ratchet`\nbinary from [GitHub Releases][releases].\n\n#### Runnable container CLI\n\nRatchet can run directly from a container on your local system:\n\n```shell\ndocker run -it --rm -v \"${PWD}:${PWD}\" -w \"${PWD}\" ghcr.io/sethvargo/ratchet:latest COMMAND\n```\n\nCreate a shell alias to make this easier:\n\n```shell\nfunction ratchet {\n  docker run -it --rm -v \"${PWD}:${PWD}\" -w \"${PWD}\" ghcr.io/sethvargo/ratchet:latest \"$@\"\n}\n```\n\n\n## Auth\n\n-   The container resolver uses default \"keychain\" auth, which looks for local\n    system auth, similar to the Docker and gcloud CLIs.\n\n-   The GitHub resolver defaults to public github.com. Provide an oauth access\n    token with appropriate permissions via the `GITHUB_TOKEN` environment\n    variable. To use a GitHub Enterprise installation, set the\n    `ACTIONS_BASE_URL` and `ACTIONS_UPLOAD_URL` environment variables to point\n    your instance.\n\n\n## Excluding\n\nThere may be instances in which you want to exclude a particular reference from\nbeing pinned. You can use the `ratchet:exclude` annotation as a line comment and\nratchet will not process that reference:\n\n```yaml\nuses: 'actions/checkout@v4' # ratchet:exclude\n```\n\nThere **cannot** be any spaces in the exclusion string, and the exclusion string\nonly applies to the line on which it appears.\n\n\n## Terminology\n\n-   **Unpinned version** - An unpinned version is a non-absolute reference to a\n    floating tag or label, such as `actions/checkout@v4` or `ubuntu:22.04`.\n\n-   **Pinned version** - A pinned version is an absolute hashed reference, such\n    as `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` or\n    `ubuntu@sha256:82becede498899ec668628e7cb0ad87b6e1c371cb8a1e597d83a47fac21d6af3`.\n\n\n## Known issues\n\n-   Indentation is always set to 2 spaces. The upstream YAML library does not\n    capture pre-parsing indentation. Thus, all files will be saved with 2 spaces\n    for indentation.\n\n-   Does not support resolving values in anchors or aliases. This is technically\n    possible, but most CI systems also don't support these advanced YAML\n    features.\n\n    Similarly, Ratchet does not support expansion or interpolation, since those\n    values cannot be guaranteed to be known at compile time. For example,\n    Ratchet will ignore the following `${{ }}` reference in a GitHub Actions\n    workflow:\n\n    ```yaml\n    jobs:\n      my_job:\n        strategy:\n          matrix:\n            version:\n            - '1'\n            - '2'\n\n        steps:\n          - uses: 'actions/checkout@v${{ matrix.version }}'\n    ```\n\n[containers]: https://github.com/sethvargo/ratchet/pkgs/container/ratchet\n[releases]: https://github.com/sethvargo/ratchet/releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethvargo%2Fratchet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsethvargo%2Fratchet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethvargo%2Fratchet/lists"}