GitLab CI/CD配置Terraform非保护分支报错：S3后端无有效凭证

问题描述 #

将Terraform与GitLab CI/CD集成后，默认受保护的develop分支运行流水线无异常，但feature/test等非保护分支执行时，出现以下错误：

error configuring S3 Backend: no valid credential sources for S3 Backend found

已在GitLab变量中配置AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY，需排查原因并解决。

相关配置代码 #

.gitlab-ci.yml #

include:
  - template: Terraform/Base.gitlab-ci.yml
  - template: Jobs/SAST-IaC.gitlab-ci.yml

stages:
  - validate
  - test
  - build
  - deploy
  - cleanup

validate:
  extends: .terraform:validate
  needs: []

build:
  extends: .terraform:build
  environment:
    name: $TF_STATE_NAME
    action: prepare

deploy:
  extends: .terraform:deploy
  dependencies:
    - build
  environment:
    name: $TF_STATE_NAME
    action: start

cleanup:
  extends: .terraform:destroy
  environment:
    name: $TF_STATE_NAME
    action: access

variables:
  TF_STATE_NAME: default
  TF_CACHE_KEY: default

Provider配置（terraform块） #

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.54.0"
    }
  }

  backend "s3" {
    bucket = "my-remote-state-bucket"
    key    = "terraform.tfstate"
    region = "eu-west-1"
  }
}

# Configure the AWS Provider
provider "aws" {
  region = "eu-west-1"
}

main.tf资源配置 #

resource "aws_s3_bucket" "test" {
  bucket = "my-bucket-test-2023-00001"
}

问题原因 #

核心原因是GitLab变量默认开启「保护变量」属性：创建变量时默认勾选该选项，导致变量仅对受保护分支（如develop）或受保护标签的流水线可见，非保护分支无法读取这些AWS凭证变量，进而导致Terraform无法配置S3后端。

解决方法 #

根据安全需求选择以下方案：

方案1：取消现有变量的保护属性 #

适用于允许非保护分支使用AWS凭证的场景：

• 进入GitLab项目的「设置」→「CI/CD」→「变量」
• 找到AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY变量，点击编辑
• 取消勾选「保护变量」选项，保存更改
• 重新运行非保护分支的流水线，变量会被自动注入环境

方案2：为非保护分支配置独立非保护变量 #

适用于需要区分环境权限（比如非保护分支使用受限AWS角色）的场景：

1. 在GitLab变量中新增一对AWS凭证变量（如AWS_ACCESS_KEY_ID_UNPROTECTED、AWS_SECRET_ACCESS_KEY_UNPROTECTED），确保不勾选「保护变量」
2. 修改.gitlab-ci.yml，通过分支规则为非保护分支注入对应变量：

variables:
  TF_STATE_NAME: default
  TF_CACHE_KEY: default
  # 定义非保护分支的变量模板
  .non_protected_aws_vars: &non_protected_aws_vars
    AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID_UNPROTECTED
    AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY_UNPROTECTED

validate:
  extends: .terraform:validate
  needs: []
  rules:
    - if: $CI_COMMIT_BRANCH !~ /^develop$/
      <<: *non_protected_aws_vars

build:
  extends: .terraform:build
  environment:
    name: $TF_STATE_NAME
    action: prepare
  rules:
    - if: $CI_COMMIT_BRANCH !~ /^develop$/
      <<: *non_protected_aws_vars

deploy:
  extends: .terraform:deploy
  dependencies:
    - build
  environment:
    name: $TF_STATE_NAME
    action: start
  rules:
    - if: $CI_COMMIT_BRANCH !~ /^develop$/
      <<: *non_protected_aws_vars

cleanup:
  extends: .terraform:destroy
  environment:
    name: $TF_STATE_NAME
    action: access
  rules:
    - if: $CI_COMMIT_BRANCH !~ /^develop$/
      <<: *non_protected_aws_vars

额外说明 #

无需添加额外脚本手动导出变量，GitLab CI会自动将可见变量注入流水线环境。只要变量对当前分支可见，Terraform的S3后端和AWS Provider会自动读取环境中的AWS凭证。

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