workflowforge
Advanced tools
A robust and flexible library for creating GitHub Actions workflows, Jenkins pipelines, and AWS CodeBuild BuildSpecs programmatically in Python
A robust and flexible library for creating GitHub Actions workflows, Azure DevOps pipelines, Jenkins pipelines, and AWS CodeBuild BuildSpecs programmatically in Python.
pip install workflowforge
Check out the examples/ directory for complete working examples:
# Run individual examples
python examples/github_actions/basic_ci.py
python examples/jenkins/maven_build.py
python examples/codebuild/node_app.py
python examples/azure_devops/hello_world.py
python examples/azure_devops/python_ci.py
This will generate actual pipeline files and diagrams using the new import structure.
WorkflowForge can automatically generate comprehensive README documentation for your workflows using Ollama (free local AI):
# Install Ollama (one-time setup)
curl -fsSL https://ollama.com/install.sh | sh
ollama serve
ollama pull llama3.2
# Generate workflow with AI documentation and diagram
workflow.save(".github/workflows/ci.yml", generate_readme=True, use_ai=True, generate_diagram=True)
# Creates: ci.yml + ci_README.md + CI_Pipeline_workflow.png
# Or generate README separately
readme = workflow.generate_readme(use_ai=True, ai_model="llama3.2")
print(readme)
Features:
WorkflowForge automatically generates visual diagrams of your pipelines using Graphviz:
# Install Graphviz (one-time setup)
brew install graphviz # macOS
sudo apt-get install graphviz # Ubuntu
choco install graphviz # Windows
# Generate workflow with automatic diagram
workflow.save(".github/workflows/ci.yml", generate_diagram=True)
# Creates: ci.yml + CI_Pipeline_workflow.png
# Generate diagram separately
diagram_path = workflow.generate_diagram("png")
print(f"📊 Diagram saved: {diagram_path}")
# Multiple formats supported
workflow.generate_diagram("svg") # Vector graphics
workflow.generate_diagram("pdf") # PDF document
Features:
from workflowforge import github_actions
# Create workflow using snake_case functions
workflow = github_actions.workflow(
name="My Workflow",
on=github_actions.on_push(branches=["main"])
)
# Create job
job = github_actions.job(runs_on="ubuntu-latest")
job.add_step(github_actions.action("actions/checkout@v4", name="Checkout"))
job.add_step(github_actions.run("echo 'Hello World!'", name="Say Hello"))
# Add job to workflow
workflow.add_job("hello", job)
# Generate YAML
print(workflow.to_yaml())
# Save with documentation and diagram
workflow.save(".github/workflows/hello.yml", generate_readme=True, generate_diagram=True)
# Creates: hello.yml + hello_README.md + My_Workflow.png
from workflowforge import jenkins_platform
# Create Jenkins pipeline using snake_case
pipeline = jenkins_platform.pipeline()
pipeline.set_agent(jenkins_platform.agent_docker("maven:3.9.3-eclipse-temurin-17"))
# Add stages
build_stage = jenkins_platform.stage("Build")
build_stage.add_step("mvn clean compile")
pipeline.add_stage(build_stage)
# Generate Jenkinsfile with diagram
pipeline.save("Jenkinsfile", generate_diagram=True)
# Creates: Jenkinsfile + jenkins_pipeline.png
from workflowforge import aws_codebuild
# Create BuildSpec using snake_case
spec = aws_codebuild.buildspec()
# Add environment
env = aws_codebuild.environment()
env.add_variable("JAVA_HOME", "/usr/lib/jvm/java-17-openjdk")
spec.set_env(env)
# Add build phase
build_phase = aws_codebuild.phase()
build_phase.add_command("mvn clean package")
spec.set_build_phase(build_phase)
# Set artifacts
artifacts_obj = aws_codebuild.artifacts(["target/*.jar"])
spec.set_artifacts(artifacts_obj)
# Generate buildspec.yml with AI documentation and diagram
spec.save("buildspec.yml", generate_readme=True, use_ai=True, generate_diagram=True)
# Creates: buildspec.yml + buildspec_README.md + codebuild_spec.png
Generate a simple “hello” pipeline:
from workflowforge import azure_devops as ado
pipeline = ado.hello_world_template_azure(
name="Hello ADO",
message="Hello Azure DevOps from WorkflowForge!",
)
pipeline.save("azure-pipelines.yml")
Or generate a Python matrix CI with caching across Ubuntu/Windows/macOS:
from workflowforge import azure_devops as ado
pipeline = ado.python_ci_template_azure(
python_versions=["3.11", "3.12", "3.13"],
os_list=["ubuntu-latest", "windows-latest", "macOS-latest"],
use_cache=True,
)
pipeline.save("azure-pipelines.yml")
Optionally, scan the emitted YAML with Checkov (if installed):
from workflowforge import azure_devops as ado
pipeline = ado.python_ci_template_azure()
pipeline.save("azure-pipelines.yml", scan_with_checkov=True)
See also: examples/azure_devops/python_ci_scan.py.
# GitHub Actions with AI README
workflow = Workflow(name="CI Pipeline", on=on_push())
job = Job(runs_on="ubuntu-latest")
job.add_step(action("actions/checkout@v4"))
workflow.add_job("test", job)
# Save with AI documentation and diagram
workflow.save("ci.yml", generate_readme=True, use_ai=True, generate_diagram=True)
# Creates: ci.yml + ci_README.md + Test_Workflow.png
# Jenkins with AI README and diagram
pipeline = pipeline()
stage_build = stage("Build")
stage_build.add_step("mvn clean package")
pipeline.add_stage(stage_build)
# Save with AI documentation and diagram
pipeline.save("Jenkinsfile", generate_readme=True, use_ai=True, generate_diagram=True)
# Creates: Jenkinsfile + Jenkinsfile_README.md + jenkins_pipeline.png
# Check AI availability
from workflowforge import OllamaClient
client = OllamaClient()
if client.is_available():
print("AI documentation available!")
else:
print("Using template documentation (Ollama not running)")
WorkflowForge supports platform-specific imports with snake_case naming following Python conventions:
# Import specific platforms
from workflowforge import github_actions, jenkins_platform, aws_codebuild, azure_devops
# Or use short aliases
from workflowforge import github_actions as gh
from workflowforge import jenkins_platform as jenkins
from workflowforge import aws_codebuild as cb
from workflowforge import azure_devops as ado
✅ Platform separation - Clear namespace for each platform
✅ Snake case naming - Follows Python PEP 8 conventions
✅ IDE autocompletion - Better IntelliSense support
✅ Shorter code - gh.action() vs github_actions.action()
from workflowforge import github_actions as gh
job = gh.job(
runs_on="ubuntu-latest",
strategy=gh.strategy(
matrix=gh.matrix(
python_version=["3.11", "3.12", "3.13"],
os=["ubuntu-latest", "windows-latest"]
)
)
)
from workflowforge import github_actions as gh
workflow = gh.workflow(
name="CI/CD",
on=[
gh.on_push(branches=["main"]),
gh.on_pull_request(branches=["main"]),
gh.on_schedule("0 2 * * *") # Daily at 2 AM
]
)
from workflowforge import github_actions as gh
test_job = gh.job(runs_on="ubuntu-latest")
deploy_job = gh.job(runs_on="ubuntu-latest")
deploy_job.needs = "test"
workflow = gh.workflow(name="CI/CD")
workflow.add_job("test", test_job)
workflow.add_job("deploy", deploy_job)
GitHub Actions:
on_push(), on_pull_request(), on_schedule(), on_workflow_dispatch()action(), run() stepssecret(), variable(), github_context() for credentialsworkflow.save(path, scan_with_checkov=True)Jenkins:
pipeline(), stage(), agent_docker(), agent_any()jenkins_credential(), jenkins_env(), jenkins_param()AWS CodeBuild:
buildspec(), phase(), environment(), artifacts()codebuild_secret(), codebuild_parameter(), codebuild_env()Azure DevOps:
pipeline(), job(), strategy(matrix=...), task(), script()pipeline.save(path, scan_with_checkov=True)Contributions are welcome! Please:
Brainy Nimbus, LLC - We love opensource! 💖
Website: brainynimbus.io Email: info@brainynimbus.io GitHub: @brainynimbus
MIT License - see LICENSE for details.
GitHub Actions:
Jenkins:
AWS CodeBuild:
Azure DevOps Pipelines:
FAQs
A robust and flexible library for creating GitHub Actions workflows, Jenkins pipelines, and AWS CodeBuild BuildSpecs programmatically in Python
We found that workflowforge demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Campaign of 108 extensions harvests identities, steals sessions, and adds backdoors to browsers, all tied to the same C2 infrastructure.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.