Skip to content

GITHUB-ACTIONS-README.md

Latest commit

 

History

History
309 lines (232 loc) · 9.17 KB

GITHUB-ACTIONS-README.md

File metadata and controls

309 lines (232 loc) · 9.17 KB

Creating Customized GitHub Actions Templates

This guide covers how to create and customize GitHub Actions workflow templates using DevOps-OS tooling. The GitHub Actions generator helps you create workflows that integrate with your development environment and deployment needs.

Table of Contents

Understanding the GitHub Actions Generator

The GitHub Actions generator (github-actions-generator-improved.py) creates YAML workflow files that orchestrate continuous integration and deployment processes using GitHub's action system. The workflows leverage the DevOps-OS container to provide a consistent environment for building, testing, and deploying your applications.

Basic Usage

To generate a basic GitHub Actions workflow:

python -m cli.scaffold_gha --name "My Workflow" --type complete

This generates a complete CI/CD workflow including build, test, and deploy stages.

Output: .github/workflows/my-workflow-complete.yml

The filename is built as <name-lowercased-and-hyphenated>-<type>.yml inside the output directory.
Change the output directory with --output <dir> (default: .github/workflows/).

Workflow Types

The generator supports several types of workflows:

  1. Build Workflow (--type build): Focuses on building and packaging your application.
  2. Test Workflow (--type test): Focuses on running tests and validating your application.
  3. Deploy Workflow (--type deploy): Focuses on deploying your application to the target environment.
  4. Complete Workflow (--type complete): Combines build, test, and deploy stages.
  5. Reusable Workflow (--type reusable or --reusable): Creates a reusable workflow that can be called from other workflows.

Customization Options

Basic Options

  • --name: The name of the workflow (e.g., "Backend CI/CD")
  • --languages: Comma-separated list of languages to enable (e.g., "python,java,javascript,go")
  • --output: Output directory for the generated workflow file

Example with Basic Options

python -m cli.scaffold_gha --name "Python API" --languages python --output ./.github/workflows

Output: .github/workflows/python-api-complete.yml

Matrix Builds

Matrix builds allow you to run your workflows across multiple configurations, such as different operating systems or language versions:

python -m cli.scaffold_gha --matrix

Output: .github/workflows/devops-os-complete.yml

This creates a workflow with a matrix strategy that runs on multiple platforms.

Custom Matrix Configuration

For more advanced matrix configurations, you can provide a custom values file:

{
  "matrix": {
    "os": ["ubuntu-latest", "windows-latest", "macos-latest"],
    "python-version": ["3.8", "3.9", "3.10", "3.11"],
    "exclude": [
      {
        "os": "windows-latest",
        "python-version": "3.11"
      }
    ]
  }
}
python -m cli.scaffold_gha --custom-values matrix-config.json

Kubernetes Integration

To include Kubernetes deployment steps in your workflow:

python -m cli.scaffold_gha --kubernetes --k8s-method kubectl

Kubernetes Deployment Methods

Four Kubernetes deployment methods are supported:

  1. kubectl (--k8s-method kubectl): Direct deployment using kubectl commands.
  2. kustomize (--k8s-method kustomize): Deployment using Kustomize for environment-specific configurations.
  3. argocd (--k8s-method argocd): GitOps deployment using ArgoCD.
  4. flux (--k8s-method flux): GitOps deployment using Flux CD.

Reusable Workflows

Reusable workflows can be called from other workflows, making them ideal for creating standardized CI/CD templates:

python -m cli.scaffold_gha --type reusable

Output: .github/workflows/devops-os-reusable.yml

Using a Reusable Workflow

The generated reusable workflow can be called from another workflow:

jobs:
  call-devops-os-workflow:
    uses: ./.github/workflows/devops-os-reusable.yml
    with:
      languages: '{"python": true, "java": true}'
      deploy_environment: 'production'

Environment Variables

All options can be set using environment variables prefixed with DEVOPS_OS_GHA_:

export DEVOPS_OS_GHA_NAME="API Service"
export DEVOPS_OS_GHA_TYPE="complete"
export DEVOPS_OS_GHA_LANGUAGES="python,go"
export DEVOPS_OS_GHA_KUBERNETES="true"
export DEVOPS_OS_GHA_K8S_METHOD="kustomize"
export DEVOPS_OS_GHA_MATRIX="true"

python -m cli.scaffold_gha
# Output: .github/workflows/api-service-complete.yml

Advanced Customization

Custom Values File

For advanced customization, create a custom values JSON file:

{
  "build": {
    "cache": true,
    "timeout_minutes": 30,
    "artifact_paths": ["dist/**", "build/**"]
  },
  "test": {
    "coverage": true,
    "junit_reports": true,
    "parallel": 4,
    "timeout_minutes": 20
  },
  "deploy": {
    "environments": ["dev", "staging", "prod"],
    "approval_required": true,
    "rollback_enabled": true
  },
  "notifications": {
    "slack": {
      "channel": "deployments",
      "success": true,
      "failure": true
    },
    "email": {
      "recipients": ["team@example.com"],
      "on_failure_only": true
    }
  }
}
python -m cli.scaffold_gha --custom-values advanced-config.json

Integration with DevOps-OS Configuration

The generator integrates with the DevOps-OS devcontainer.env.json file to ensure consistency between your development environment and CI/CD workflows:

python -m cli.scaffold_gha --env-file ./devcontainer.env.json

Examples

Basic Python Application Workflow

python -m cli.scaffold_gha --name "Python App" --languages python --type complete
# Output: .github/workflows/python-app-complete.yml

Java Application with Maven

python -m cli.scaffold_gha --name "Java Service" --languages java --custom-values maven-config.json
# Output: .github/workflows/java-service-complete.yml

Multi-language Microservices

python -m cli.scaffold_gha --name "Microservices" --languages python,javascript,go --kubernetes --k8s-method kustomize
# Output: .github/workflows/microservices-complete.yml

Cross-platform Node.js Application

python -m cli.scaffold_gha --name "Node.js App" --languages javascript --matrix --custom-values node-matrix.json
# Output: .github/workflows/node-js-app-complete.yml

Complete Docker and Kubernetes Workflow

python -m cli.scaffold_gha --name "Container Deploy" --languages go --kubernetes --k8s-method argocd --registry ghcr.io
# Output: .github/workflows/container-deploy-complete.yml

Understanding the Generated Workflow

The generated GitHub Actions workflow includes:

  1. Triggers: Configures when the workflow runs (push, pull request, workflow dispatch).
  2. Jobs: Defines the jobs to run (build, test, deploy).
  3. Steps: Details the steps within each job.
  4. Environment: Sets up the execution environment using the DevOps-OS container.
  5. Artifacts: Configures artifact handling for sharing between jobs.
  6. Deployments: Includes deployment steps if Kubernetes is enabled.

Example Structure

name: My CI/CD
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        description: Environment to deploy to
        required: true
        default: dev
        type: choice
        options: [dev, test, staging, prod]

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/yourorg/devops-os:latest
    steps:
      # Build steps here
      
  test:
    needs: build
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/yourorg/devops-os:latest
    steps:
      # Test steps here
      
  deploy:
    needs: test
    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/yourorg/devops-os:latest
    steps:
      # Deploy steps here

Best Practices

  1. Start Simple: Begin with a basic workflow and add complexity as needed.
  2. Use Environment Variables: Use environment variables for secrets and configuration.
  3. Leverage Matrix Builds: Use matrix builds for testing across multiple configurations.
  4. Use Reusable Workflows: Create reusable workflows for common patterns.
  5. Custom Values: Use custom values files for advanced configuration.
  6. Integration with DevOps-OS: Integrate with your DevOps-OS configuration for consistency.

Next Steps