gofrolist/molecule

Molecule for GitHub Action 镜像文档

镜像概述和主要用途

该GitHub Action允许在GitHub Actions工作流中运行Molecule以测试Ansible角色。Molecule是Ansible的测试框架，可自动化角色的创建、配置、验证等测试流程。此Action提供了灵活的配置选项，支持自定义测试命令、参数和工作目录，适用于Ansible角色的持续集成和自动化测试。

核心功能和特性

输入参数

molecule_options

描述：Molecule命令的选项参数。
必填：否

选项说明：

• --debug / --no-debug：启用或禁用调试模式，默认禁用。
• -v, --verbose：增加Ansible详细级别，默认0（x≥0）。
• -c, --base-config TEXT：基础配置文件路径（可多次指定）。Molecule会先按指定顺序加载并深度合并配置，再合并每个场景的molecule.yml。默认查找当前版本控制仓库中的.config/molecule/config.yml，若未找到则查找用户主目录（无默认值）。
• -e, --env-file TEXT：渲染molecule.yml时读取变量的文件，默认.env.yml。
• --version：显示版本信息。
• --help：显示帮助信息并退出。

molecule_command

描述：要执行的Molecule命令。
必填：是
默认值：test

命令说明：

• check：使用配置器执行空运行（销毁、依赖、创建、准备、配置）。
• cleanup：使用配置器清理测试阶段对外部系统的更改。
• converge：使用配置器配置实例（依赖、创建、准备、配置）。
• create：使用配置器启动实例。
• dependency：管理角色依赖。
• destroy：使用配置器销毁实例。
• drivers：列出驱动程序。
• idempotence：使用配置器配置实例并解析输出以确定幂等性。
• init：初始化新角色或场景。
• lint：检查角色代码规范（依赖、lint）。
• list：列出实例状态。
• login：登录到一个实例。
• matrix：列出测试实例使用的步骤矩阵。
• prepare：使用配置器将实例准备到特定初始状态。
• reset：重置Molecule临时文件夹。
• side-effect：使用配置器对实例执行副作用操作。
• syntax：使用配置器检查角色语法。
• test：完整测试流程（依赖、lint、清理、销毁、语法检查、创建、准备、配置、幂等性、副作用、验证、清理、销毁）。
• verify：对实例运行自动化测试。

molecule_args

描述：Molecule命令的参数。
必填：否

参数说明：

• -s, --scenario-name TEXT：目标场景名称，默认default。
• -d, --driver-name [delegated|docker]：使用的驱动名称，默认delegated。
• --all / --no-all：测试所有场景，默认False。
• --destroy [always|never]：Molecule运行结束时的销毁策略，默认always。
• --parallel / --no-parallel：启用或禁用并行模式，默认禁用。

molecule_working_dir

描述：仓库中执行Molecule命令的目录路径。适用于Ansible角色不在仓库根目录的情况。
必填：否
默认值：${GITHUB_REPOSITORY}

使用场景和适用范围

• Ansible角色的持续集成测试：在GitHub Actions中自动化执行Molecule测试，验证角色功能。
• 多场景测试：通过--scenario-name指定不同场景（如不同操作系统），确保角色在多种环境中兼容。
• 自定义测试流程：通过molecule_command选择特定测试阶段（如仅检查语法、仅验证幂等性）。
• 复杂项目结构：通过molecule_working_dir指定角色所在目录，支持非根目录的角色测试。

使用方法和配置说明

基本示例

在仓库的.github/workflows/目录下创建main.yml（或自定义名称），配置如下：

yaml
on: push

jobs:
  molecule:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          path: "${{ github.repository }}"
      - uses: gofrolist/molecule-action@v2

注意：默认情况下，Molecule会在molecule/*/molecule.yml查找配置。若未指定molecule-working-dir，checkout操作需将文件放置在${{ github.repository }}目录，以便Molecule找到角色。若角色位于仓库其他位置，需设置molecule-working-dir，确保执行molecule命令前切换到该目录。

高级示例

yaml
name: Molecule

on:
  push:
    branches:
      - master
  pull_request:
    branches:
      - master

jobs:
  molecule:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        scenario:
          - centos-8
          - debian-10
          - fedora-34
          - oraclelinux-8
          - ubuntu-20.04
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          path: "${{ github.repository }}"
      - name: Molecule
        uses: gofrolist/molecule-action@v2
        with:
          molecule_options: --debug --base-config molecule/_shared/base.yml
          molecule_command: test
          molecule_args: --scenario-name ${{ matrix.scenario }}

提示：建议使用gofrolist/molecule-action@v2或其他有效标签、分支、提交SHA代替v2，以固定Action版本。

安装Python依赖

若角色需要特定Python模块（如netaddr），可在Molecule的prepare阶段安装：

yaml
---
- name: Prepare
  hosts: all

  tasks:
    - name: 在控制主机（虚拟环境）上安装netaddr依赖
      pip:
        name: netaddr
      delegate_to: 127.0.0.1

许可证

本项目中的Dockerfile、相关脚本和文档以MIT许可证发布。