GitHub Actions中workflow_dispatch工作流不显示问题求助

算力阿峰

2026-8-3

问题：包含workflow_dispatch的GitHub Actions工作流未在Actions标签页显示

我创建了一个带有workflow_dispatch触发条件的工作流文件，代码如下：

name: AZ Deploy Workflow
on:
  workflow_dispatch:  
    inputs:
      deploy-environment:
        description: 'Environment to deploy to'
        required: true
        default: 'dev'
      image-tag:
        description: 'Docker tag to deploy'
        required: true
        default: 'latest'

但该工作流未在GitHub Actions标签页中显示。此前我在.github目录下添加的其他工作流（甚至空文件）都能正常显示，请问可能是什么问题？

可能的排查方向

检查文件存放路径：确保工作流文件放在.github/workflows/目录下，GitHub仅识别这个特定路径下的YAML文件作为工作流，放在.github根目录或其他子目录都不会被加载。
确认文件扩展名：文件后缀必须是.yml或.yaml，如果用了.txt这类非标准后缀，或者没有后缀，GitHub无法识别为工作流文件。
排查YAML语法错误：YAML对缩进要求极严，检查inputs下的字段缩进是否正确——比如deploy-environment需要相对于inputs缩进2个空格（和父级保持一致的缩进规则），哪怕一个空格错误都可能导致工作流不被识别。
刷新或触发仓库扫描：偶尔GitHub Actions的缓存会导致显示延迟，可尝试刷新页面；或者推送一个空提交触发仓库重新扫描：
```
git commit --allow-empty -m "Trigger workflow re-scan"
git push
```
确认分支匹配：如果工作流文件是在非默认分支（比如dev分支）创建的，而你当前查看的是默认分支的Actions标签页，自然看不到该工作流，切换到对应的分支再查看即可。