gh-actions-lock README

README проекта с github.com/github/gh-actions-lock. Одним файлом markdown: README.md.

gh-actions-lock

A GitHub CLI extension that pins every direct and transitive action your workflows use to a verified commit, recorded in .github/workflows/actions.lock.

Install

Requires an authenticated gh. github.com and GitHub Enterprise Cloud with data residency (*.ghe.com) are supported; GitHub Enterprise Server is not.

gh extension install github/gh-actions-lock

To teach your AI coding agent the CLI:

gh skill install github/gh-actions-lock

Quickstart

From the repository checkout:

gh actions-lock            # onboard or fix: pin every resolvable action and write actions.lock
git add .github/workflows/ # check into source

Rerun gh actions-lock after adding a workflow or changing any uses:.

Make sure you don't check in a corrupt lockfile. Copy .github/workflows/verify-lockfile.yml into your repository, modify it for your needs, then run gh actions-lock once so that workflow is locked too.

GitHub Enterprise Cloud with data residency

Run gh auth login --hostname TENANT.ghe.com, then run gh actions-lock from the tenant repository checkout. The host comes from the repository remote; you don't need --hostname or an exported token.

Actions that aren't on the tenant, such as actions/checkout, are read from public github.com repositories. Those lookups never use the tenant token, GH_TOKEN or GITHUB_TOKEN. They use, in order:

  1. GH_ACTIONS_LOCK_GITHUB_COM_TOKEN, a github.com token used only for these lookups.
  2. Your gh auth login --hostname github.com login.
  3. Otherwise they're anonymous and share GitHub's limit of 60 requests an hour per IP address, which a shared proxy or runner pool can exhaust quickly.

In GitHub Actions on GHE.com, the job's GITHUB_TOKEN is issued by your tenant, so github.com doesn't accept it. Create a fine-grained personal access token on github.com with public repository access only and no permissions, save it as a secret on the tenant, and pass it in:

- run: gh actions-lock --verify
  env:
    GH_TOKEN: ${{ github.token }}
    GH_ACTIONS_LOCK_GITHUB_COM_TOKEN: ${{ secrets.ACTIONS_LOCK_GITHUB_COM_TOKEN }}

Modes

Command Writes Network Use for
gh actions-lock yes yes Onboarding and fixing the lockfile
gh actions-lock --relock yes yes Advancing moved refs (main, v4) to current upstream commits
gh actions-lock --verify no yes CI: the same checks as a fix run
gh actions-lock --verify-local no no Pre-commit: every uses: has a lockfile entry (coverage only, not provenance)
gh actions-lock --no-fix no yes Read-only report

Other flags:

gh actions-lock --help is authoritative.

Limitations

Learn more

Contributing

See CONTRIBUTING.md

Support

See SUPPORT.md.

License

Licensed under MIT.

gh-actions-lock (github/gh-actions-lock)

Ищем в базе…

Что это такое?Расширение для GitHub CLI, которое создаёт и проверяет файл блокировки зависимостей GitHub Actions. Оно закрепляет каждое действие, которое используют ваши workflow, как прямые, так и транзитивные, на точном коммите.
Это отдельное приложение или то, что подключается к gh?Оно подключается к gh CLI как расширение и запускается командой gh actions-lock. Результат записывается в один файл — .github/workflows/actions.lock — в вашем репозитории.
Как это запустить?Войдите командой gh auth login, установите расширение, следуя разделу Install в README, затем запустите gh actions-lock из рабочей копии репозитория. Запускайте снова после добавления workflow или изменения любого uses:.
Что нужно сделать заранее?Нужен авторизованный gh. Работает с github.com и GitHub Enterprise Cloud с хранением данных в регионе, но не работает с GitHub Enterprise Server.
Есть ли подводные камни?Да. Образы контейнеров не блокируются, и reusable workflow, которые вызываются из других репозиториев, тоже не блокируются. Локальное действие ./, которое использует удалённые действия, останавливает запуск, пока вы не передадите флаг. Изменение файла блокировки, которое возвращает плавающую ссылку на более старый коммит, не обнаруживается, поэтому проверяйте различия в файле блокировки.
Может ли работать без интернета?Без интернета работает только --verify-local, и это лишь проверка покрытия: она подтверждает, что у каждого uses: есть запись в файле блокировки, но не проверяет происхождение.
Можно ли использовать бесплатно?Да, лицензия MIT, так что можете свободно использовать его в своих проектах.
Зачем закреплять workflow на коммите?Тег вроде v4 или ветка main может быть перемещена на новый код без каких-либо изменений с вашей стороны. Закрепление на точном коммите означает, что запускается тот код, который вы проверили, однако перемещение обратно на более старый коммит всё равно останется незамеченным.
Что делает --relock?Он переводит плавающие ссылки, такие как main или v4, на текущие коммиты в исходном репозитории. Используйте его осознанно и перед принятием проверяйте, почему закреплённый коммит сдвинулся.
Блокируются ли также действия, которые используют другие действия?Да. Закрепляются все прямые и транзитивные действия, поэтому зависимости используемых вами действий тоже охвачены.
Можно ли заблокировать только один workflow?Да, передайте имена файлов workflow, чтобы ограничить запуск. Записи в файле блокировки для удалённых workflow удаляются только при запуске по всей директории.
Какие есть похожие проекты?gh-aw, gh-secure, gitleaks, gitea, grype, farol, semgrep, bashka
Автор
github
Размер
3.8 MB
Звёзды
385
Возраст
6 мес
Коммиты · 90 дней