Github Actions部署Google Cloud Function构建失败求助

问题场景 #

配置的GitHub Actions部署文件.github/workflows/deploy.yml如下：

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - id: "auth"
        uses: "google-github-actions/auth@v1"
        with:
          credentials_json: "${{ secrets.GOOGLE_CLOUD_KEY }}"

      - name: "Set up Cloud SDK"
        uses: "google-github-actions/setup-gcloud@v1"

      - name: Deploy Cloud Function
        run: |
          gcloud functions deploy name-of-function \
            --gen2 \
            --region=europe-west1 \
            --runtime=python310 \
            --source=src/directory_of_main_py \
            --entry-point=entry_function_in_main_py \
            --stage-bucket=test-temp \
            --memory=256MB \
            --timeout=180 \
            --trigger-http

在GitHub云环境执行时，前序步骤正常，但部署阶段报通用构建失败错误：

ERROR: (gcloud.functions.deploy) OperationError: code=3, message=Build failed with status: FAILURE and message: An unexpected error occurred. Refer to build logs:

本地执行相同命令可正常部署，怀疑路径问题但尝试多种方案未解决。

解决思路与步骤 #

• 补全代码检出步骤
  GitHub Actions默认不会自动拉取仓库代码，这是最容易忽略的点。本地有代码所以没问题，但CI环境初始是空的，必须添加代码检出步骤，放在auth和Cloud SDK setup之前：

  - name: Checkout repository
    uses: actions/checkout@v4
  

• 验证CI环境的目录结构
  在部署步骤前加命令查看文件结构，确认--source指定的路径是否存在、文件是否完整：

  - name: Inspect directory structure
    run: |
      pwd
      ls -la ${{ github.workspace }}
      ls -la ${{ github.workspace }}/src/directory_of_main_py
  

  对比本地目录，排查是否有文件因为.gitignore未被提交，或者目录名拼写错误。

• 查看Google Cloud端的详细构建日志
  gcloud返回的错误太通用，直接去Google Cloud Console的Cloud Build > 历史记录里找到对应失败的构建，查看完整日志。常见问题包括：

  • requirements.txt缺失或依赖包安装失败
  • main.py里有语法错误或导入问题
  • 入口函数名称（entry-point）拼写错误
  • 构建过程中权限不足

• 确认依赖配置文件的正确性
  Python Cloud Function要求requirements.txt必须在--source指定的目录下（或通过--requirements参数指定路径）。检查该文件是否已提交到仓库，且包含所有必要依赖，避免本地环境已安装但CI打包时缺失的情况。

• 尝试绝对路径或指定工作目录
  直接使用github.workspace变量拼接绝对路径，或者给部署步骤指定工作目录：
  方案1：用绝对路径

  - name: Deploy Cloud Function
    run: |
      gcloud functions deploy name-of-function \
        --gen2 \
        --region=europe-west1 \
        --runtime=python310 \
        --source=${{ github.workspace }}/src/directory_of_main_py \
        --entry-point=entry_function_in_main_py \
        --stage-bucket=test-temp \
        --memory=256MB \
        --timeout=180 \
        --trigger-http
  

  方案2：指定工作目录

  - name: Deploy Cloud Function
    working-directory: ${{ github.workspace }}/src/directory_of_main_py
    run: |
      gcloud functions deploy name-of-function \
        --gen2 \
        --region=europe-west1 \
        --runtime=python310 \
        --source=. \
        --entry-point=entry_function_in_main_py \
        --stage-bucket=test-temp \
        --memory=256MB \
        --timeout=180 \
        --trigger-http
  

• 检查服务账号权限
  确认GOOGLE_CLOUD_KEY对应的服务账号拥有足够权限：

  • Cloud Functions Developer
  • Cloud Build Editor
  • Storage Object Creator（对stage-bucket的权限）
    本地用个人账号可能权限充足，但CI用的服务账号权限不足也会导致构建失败。

内容的提问来源于stack exchange，提问作者fxmb