JOB_CONTAINER_DEMO_GUIDE.md

GitHub Actions Job Containers Demo Guide

Overview

This demo showcases the various capabilities of job containers in GitHub Actions, demonstrating real-world use cases and best practices. The workflow is designed to be educational and comprehensive while remaining accessible for audiences at different technical levels.

🎯 Learning Objectives

After running this demo, participants will understand:

• How to configure job containers in GitHub Actions
• The difference between job containers and service containers
• Container networking in GitHub Actions
• Best practices for using containers in CI/CD pipelines
• How to troubleshoot container-related issues

🚀 How to Run the Demo

Prerequisites

1. Access to the GitHub repository with admin or write permissions
2. GitHub Actions enabled on the repository
3. Basic understanding of Docker containers (helpful but not required)

Step-by-Step Execution

1. Navigate to Actions Tab

1. Go to your GitHub repository
2. Click on the "Actions" tab
3. Look for "Job Containers Demo" in the workflow list
4. Click "Run workflow" button

2. Configure Demo Parameters

When triggering the workflow manually, you can choose:

• Environment: Select from development, staging, or production
  • This demonstrates how input parameters work with containers
  • Different environments may have different configurations

3. Monitor Execution

• Watch the workflow progress in real-time
• Each job runs in parallel (except where dependencies exist)
• Total execution time: approximately 5-8 minutes

📋 Demo Script & Explanation

Introduction (2 minutes)

"Today we're going to explore GitHub Actions job containers - a powerful feature that allows us to run our CI/CD jobs inside Docker containers. This provides consistency, isolation, and access to specific tools and environments."

Key Points to Mention:

• Containers ensure consistent environments across different runners
• They provide isolation and security
• Allow access to specific tools, languages, and configurations

Job 1: Basic Container Job (3 minutes)

What it demonstrates:

container:
  image: node:18-alpine
  env:
    NODE_ENV: development
  options: --cpus 1

Explanation:

"Our first job shows the simplest container configuration. We're running inside a Node.js 18 Alpine Linux container. Notice how we can set environment variables and Docker options directly in the workflow."

Key Learning Points:

• Basic container syntax
• Environment variable injection
• Container resource limits
• How the runner mounts the workspace

What to Show:

• Point out the container image selection
• Explain environment variables
• Show the output displaying Node.js and system information

Job 2: Container with Services (4 minutes)

What it demonstrates:

container:
  image: python:3.11-slim
services:
  postgres:
    image: postgres:15
    options: --health-cmd pg_isready
  redis:
    image: redis:7-alpine

Explanation:

"This job showcases service containers - additional containers that run alongside your main job container. Here we have PostgreSQL and Redis services that our Python application can connect to."

Key Learning Points:

• Service container configuration
• Health checks for services
• Container networking (automatic DNS resolution)
• Database connectivity patterns

What to Show:

• Explain the services section
• Point out health check configurations
• Show database connection and data insertion
• Demonstrate Redis caching functionality

Job 3: Multi-Container Matrix (3 minutes)

What it demonstrates:

strategy:
  matrix:
    container_config:
      - name: "Alpine Linux"
        image: "alpine:latest"
      - name: "Ubuntu" 
        image: "ubuntu:22.04"

Explanation:

"Using matrix strategies with containers allows us to test across different operating systems and environments. This job runs the same steps in Alpine Linux, Ubuntu, and Amazon Linux containers."

Key Learning Points:

• Matrix strategies with containers
• Cross-platform testing
• Container options and configurations
• Package manager differences across distributions

What to Show:

• Explain matrix strategy syntax
• Point out different package installation commands
• Show OS-specific outputs

Job 4: Custom Container Configuration (3 minutes)

What it demonstrates:

container:
  image: nginx:alpine
  options: >-
    --user root
    --workdir /usr/share/nginx/html
  credentials:
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_PASSWORD }}

Explanation:

"This job shows advanced container configuration including custom working directories, user settings, and how to authenticate with private registries."

Key Learning Points:

• Advanced container options
• Working directory customization
• User and permission management
• Private registry authentication (concept)

What to Show:

• Container customization options
• File system manipulation within containers
• Security considerations

Job 5: Networking Demo (3 minutes)

What it demonstrates:

services:
  web-server:
    image: httpd:2.4-alpine
    ports:
      - 8080:80

Explanation:

"Our final job explores container networking, showing how containers communicate with each other and how port mapping works in GitHub Actions."

Key Learning Points:

• Container-to-container networking
• Port mapping concepts
• DNS resolution between containers
• Network isolation and security

What to Show:

• Service connectivity by name
• Port mapping demonstration
• Network configuration details

🔍 Key Concepts to Emphasize

1. Container vs. Runner Environment

• Without containers: Jobs run directly on the GitHub-hosted runner
• With containers: Jobs run inside a Docker container on the runner
• Benefits: Consistency, isolation, specific tool versions

2. Service Containers

• Run alongside your job container
• Provide databases, caches, or other services
• Automatically networked with job container
• Support health checks for reliability

3. Container Networking

• Containers can communicate by service name
• Port mapping for external access
• Automatic DNS resolution
• Isolated network environments

4. Best Practices Demonstrated

• Use specific image tags (not latest in production)
• Implement health checks for services
• Set appropriate resource limits
• Use official images when possible
• Secure credential management

🎤 Presentation Tips

Audience Engagement

1. Ask Questions: "Who has used Docker before?" "What challenges have you faced with CI/CD environments?"
2. Interactive Elements: Have attendees guess what will happen next
3. Real-world Examples: Relate each concept to practical scenarios

Common Questions & Answers

Q: Why use containers instead of installing tools directly on the runner? A: Containers provide version consistency, faster setup (pre-built images), isolation between jobs, and easier local reproduction.

Q: How do containers affect job performance? A: There's a slight overhead for container startup, but this is usually offset by having pre-configured environments and parallel downloads.

Q: Can I use private Docker registries? A: Yes! Use the credentials section with GitHub secrets for authentication.

Q: What's the difference between job containers and service containers? A: Job containers run your workflow steps, while service containers provide supporting services like databases.

🐛 Troubleshooting Common Issues

Container Pull Failures

• Check image name and tag spelling
• Verify registry accessibility
• Ensure credentials are correct (for private images)

Service Connectivity Issues

• Verify service health checks pass
• Check service container logs
• Ensure correct hostname (use service name)

Permission Problems

• Use --user root option if needed
• Check file system permissions
• Verify container user has necessary access

📊 Expected Output Summary

When the demo completes successfully, you should see:

1. Job 1: Node.js version info and successful package installation
2. Job 2: Database and Redis connectivity confirmation
3. Job 3: Three parallel jobs showing different OS environments
4. Job 4: Custom Nginx configuration and HTML serving
5. Job 5: Network connectivity tests and container isolation info

Total runtime: ~5-8 minutes with all jobs running in parallel where possible.

🎯 Follow-up Activities

For Beginners

1. Modify the Node.js version in Job 1 and observe differences
2. Add a new service container (e.g., MongoDB)
3. Experiment with different base images

For Advanced Users

1. Implement multi-stage container builds
2. Add custom Dockerfile usage
3. Integrate with container registries
4. Add security scanning steps

📚 Additional Resources

• GitHub Actions Container Documentation
• Docker Hub Official Images
• GitHub Actions Best Practices
• Container Security Guidelines

---

Demo Duration: 15-20 minutes
Skill Level: Beginner to Intermediate
Prerequisites: Basic GitHub Actions knowledge helpful but not required