# actionlint — Lint GitHub Actions Locally

> actionlint catches syntax mistakes and expression/type errors in GitHub Actions workflows before CI runs, so broken YAML never blocks your team.

## Install

Copy the content below into your project:

## Quick Use

1. Install:
   ```bash
   brew install actionlint
   # or
   go install github.com/rhysd/actionlint/cmd/actionlint@latest
   ```
2. Run in a repo:
   ```bash
   actionlint
   ```
3. Check a specific workflow:
   ```bash
   actionlint .github/workflows/ci.yml
   ```

## Intro

actionlint catches syntax mistakes and expression/type errors in GitHub Actions workflows before CI runs, so broken YAML never blocks your team.

- **Best for:** teams that rely on GitHub Actions heavily and want fast feedback before pushing
- **Works with:** GitHub Actions YAML, `${{ }}` expressions, optional shellcheck/pyflakes integrations
- **Setup time:** 5–10 minutes

## Practical Notes

- Add it as a pre-push hook to prevent broken workflows from reaching CI.
- Run time is usually seconds for typical repos (no CI spin-up).

## What to validate first

1) YAML correctness (missing keys, wrong nesting)
2) Expression issues in `${{ }}` (type mismatch, missing fields)
3) Runner labels and reusable workflow inputs

## Suggested workflow

### Step 1: run locally before you push

```bash
actionlint
```

### Step 2: make it part of your repo hygiene

If you have many workflows, run actionlint as part of your standard checks (for example, the same command your devcontainer or agent runs before opening a PR).

### Step 3: keep false positives low

When you hit a noisy edge case:
- isolate the workflow file and reproduce with `actionlint path/to.yml`,
- then adjust configuration/ignores only for that path.

## Why this matters for AI coding agents

Agents generate YAML quickly, but YAML failures are expensive: you only notice after a CI round-trip.
actionlint gives you a cheap “compiler” step for workflows.

### FAQ

**Q: Is actionlint only for Actions YAML?**
A: Yes—it's specialized for GitHub Actions workflows and their expression system.

**Q: Do I need CI to use it?**
A: No. Run it locally in seconds; CI integration is optional.

**Q: What’s the biggest win?**
A: Catching expression mistakes early—those are common and painful to debug via CI logs.

## Source & Thanks

> Source: https://github.com/rhysd/actionlint
> License: MIT
> GitHub stars: 3,860 · forks: 217

---

<!-- ZH -->

## 快速使用

1. 安装：
   ```bash
   brew install actionlint
   # 或
   go install github.com/rhysd/actionlint/cmd/actionlint@latest
   ```
2. 在仓库里运行：
   ```bash
   actionlint
   ```
3. 只检查某个工作流：
   ```bash
   actionlint .github/workflows/ci.yml
   ```

## 简介

actionlint 能在本地检查 GitHub Actions 工作流的语法、表达式与类型错误，提前抓住 `${{ }}` 的坑；让“YAML 写错导致 CI 挂掉”不再拖慢团队节奏与发布节拍。

- **适合谁：** 强依赖 GitHub Actions、希望在 push 前就拿到快速反馈的团队
- **可搭配：** GitHub Actions 的 YAML 与 `${{ }}` 表达式；可选 shellcheck/pyflakes 集成
- **准备时间：** 5–10 分钟

## 实战建议

- 把它加到 pre-push hook，避免坏工作流进入 CI 队列。
- 典型仓库通常“秒级”完成（不需要等 CI 启动）。

## 优先检查哪些问题

1）YAML 结构/键名错误（缺字段、层级错）  
2）`${{ }}` 表达式错误（类型不匹配、字段不存在）  
3）runner label、复用工作流 inputs 等“看起来对、实际跑不起来”的问题

## 推荐用法

### 第一步：push 前本地跑一次

```bash
actionlint
```

### 第二步：把它变成仓库 hygiene 的一部分

工作流很多时，把 actionlint 加进你们的标准检查流程（例如 devcontainer / agent 的 pre-PR checklist）。

### 第三步：控制误报

遇到噪音：
- 先用 `actionlint path/to.yml` 单文件复现，
- 再只针对该路径做 ignore/config 收敛。

## 对 AI Coding Agent 的价值

Agent 生成 YAML 很快，但 YAML 出错代价高：往往要等 CI 跑一轮才发现。
actionlint 相当于给工作流加了一道“编译器”步骤。

### FAQ

**actionlint 只管 Actions YAML 吗？**
答：是的，它专门面向 GitHub Actions 工作流与表达式系统。

**一定要接 CI 才有用吗？**
答：不需要。本地即可秒级检查，CI 集成是可选项。

**最大的收益是什么？**
答：提前抓住 `${{ }}` 表达式错误——这类问题用 CI 日志排查很痛苦。

## 来源与感谢

> Source: https://github.com/rhysd/actionlint
> License: MIT
> GitHub stars: 3,860 · forks: 217


---
Source: https://tokrepo.com/en/workflows/actionlint-lint-github-actions-locally
Author: Script Depot