|
| 1 | +# GitHub Copilot CI/CD Exercise - Local GitHub Actions with Act |
| 2 | + |
| 3 | +**⚠️ PREREQUISITES REQUIRED ⚠️** |
| 4 | + |
| 5 | +This exercise requires the following to be installed and available on your system: |
| 6 | + |
| 7 | +## 🔧 Required Software |
| 8 | + |
| 9 | +### Essential Requirements |
| 10 | +- **Docker Desktop** - Must be installed and running |
| 11 | + - Download: https://www.docker.com/products/docker-desktop/ |
| 12 | + - Verify: `docker --version` should work |
| 13 | +- **Git** - For repository operations |
| 14 | + - Verify: `git --version` should work |
| 15 | +- **VS Code** with GitHub Copilot extension enabled |
| 16 | + |
| 17 | +### Installation During Exercise |
| 18 | +- **Act** - We'll install this together using Copilot's guidance |
| 19 | + - GitHub: https://github.com/nektos/act |
| 20 | + - Common methods: Homebrew (macOS), Chocolatey (Windows), or manual download |
| 21 | + |
| 22 | +## 🚨 System Requirements |
| 23 | + |
| 24 | +- **Operating System**: macOS, Linux, or Windows with WSL2 |
| 25 | +- **Memory**: At least 4GB RAM available for Docker containers |
| 26 | +- **Storage**: ~2GB free space for Docker images |
| 27 | +- **Internet**: Required for downloading Docker images and Act installation |
| 28 | + |
| 29 | +--- |
| 30 | + |
| 31 | +## Exercise Overview |
| 32 | + |
| 33 | +**Goal**: Set up Act to run GitHub Actions locally and optimize CI workflows with Copilot assistance. |
| 34 | + |
| 35 | +**Time**: 45-60 minutes |
| 36 | +**Difficulty**: Beginner to Intermediate |
| 37 | +**Focus**: DevOps tooling, local development workflows, CI/CD optimization |
| 38 | + |
| 39 | +--- |
| 40 | + |
| 41 | +## Phase 1: Installation and Setup (15-20 minutes) |
| 42 | + |
| 43 | +### Step 1: Verify Prerequisites |
| 44 | + |
| 45 | +First, let's confirm your system is ready: |
| 46 | + |
| 47 | +```bash |
| 48 | +# Verify Docker is running |
| 49 | +docker --version |
| 50 | +docker ps |
| 51 | + |
| 52 | +# Verify Git is available |
| 53 | +git --version |
| 54 | + |
| 55 | +# Check if you're in the project directory |
| 56 | +pwd |
| 57 | +ls -la .github/workflows/ |
| 58 | +``` |
| 59 | + |
| 60 | +### Step 2: Act Installation with Copilot |
| 61 | + |
| 62 | +Use Copilot to guide the installation process: |
| 63 | + |
| 64 | +``` |
| 65 | +@terminal How do I install Act on my operating system to run GitHub Actions locally? |
| 66 | +
|
| 67 | +I need to understand: |
| 68 | +1. The best installation method for my OS |
| 69 | +2. Any additional configuration required |
| 70 | +3. How to verify the installation works |
| 71 | +``` |
| 72 | + |
| 73 | +**Common installation commands** (Copilot will help you choose): |
| 74 | +```bash |
| 75 | +# macOS with Homebrew |
| 76 | +brew install act |
| 77 | + |
| 78 | +# Windows with Chocolatey |
| 79 | +choco install act-cli |
| 80 | + |
| 81 | +# Linux (manual download) |
| 82 | +curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash |
| 83 | +``` |
| 84 | + |
| 85 | +### Step 3: Verify Act Installation |
| 86 | + |
| 87 | +```bash |
| 88 | +# Check Act version |
| 89 | +act --version |
| 90 | + |
| 91 | +# See available workflows |
| 92 | +act -l |
| 93 | +``` |
| 94 | + |
| 95 | +If you encounter issues, use Copilot: |
| 96 | +``` |
| 97 | +Act installation failed with this error: #terminalLastCommand |
| 98 | +
|
| 99 | +Help me troubleshoot: |
| 100 | +1. What caused this error? |
| 101 | +2. What are alternative installation methods? |
| 102 | +3. Are there any missing dependencies? |
| 103 | +``` |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## Phase 2: Running Local CI Pipeline (15-20 minutes) |
| 108 | + |
| 109 | +### Step 1: Analyze Our Workflow |
| 110 | + |
| 111 | +Let's understand what we're about to run: |
| 112 | + |
| 113 | +``` |
| 114 | +#file:.github/workflows/ci.yml /explain |
| 115 | +
|
| 116 | +Analyze our CI workflow. What will happen when I run this locally with Act? |
| 117 | +- What Docker images will it use? |
| 118 | +- Are there any potential issues? |
| 119 | +- What should I expect to see? |
| 120 | +``` |
| 121 | + |
| 122 | +### Step 2: First Act Run (Dry Run) |
| 123 | + |
| 124 | +Always start with a dry run to see what would happen: |
| 125 | + |
| 126 | +```bash |
| 127 | +# Dry run - shows what would execute without running it |
| 128 | +act -n |
| 129 | + |
| 130 | +# If you want to see more details |
| 131 | +act -n -v |
| 132 | +``` |
| 133 | + |
| 134 | +Use Copilot to understand the output: |
| 135 | +``` |
| 136 | +Act dry run shows this output: #terminalLastCommand |
| 137 | +
|
| 138 | +Explain: |
| 139 | +1. What Docker images will be downloaded? |
| 140 | +2. What steps will be executed? |
| 141 | +3. Are there any warnings I should address? |
| 142 | +``` |
| 143 | + |
| 144 | +### Step 3: Full CI Run |
| 145 | + |
| 146 | +Now let's run the actual CI pipeline: |
| 147 | + |
| 148 | +```bash |
| 149 | +# Run the full CI pipeline |
| 150 | +act |
| 151 | + |
| 152 | +# If you want to see detailed logs |
| 153 | +act -v |
| 154 | +``` |
| 155 | + |
| 156 | +**Expected behavior:** |
| 157 | +- Docker images will be downloaded (this may take a few minutes the first time) |
| 158 | +- Python environments will be set up for multiple versions |
| 159 | +- Tests, linting, and formatting checks will run |
| 160 | + |
| 161 | +### Step 4: Troubleshooting Common Issues |
| 162 | + |
| 163 | +If the run fails, use Copilot for diagnosis: |
| 164 | + |
| 165 | +``` |
| 166 | +The Act run failed with this error: #terminalLastCommand |
| 167 | +
|
| 168 | +Help me understand and fix: |
| 169 | +1. Is this a Docker issue, Python issue, or Act configuration issue? |
| 170 | +2. What's the specific cause of this error? |
| 171 | +3. How can I resolve this? |
| 172 | +4. Are there any Act-specific configurations I need? |
| 173 | +``` |
| 174 | + |
| 175 | +**Common issues and Copilot queries:** |
| 176 | +- Docker image problems: `@terminal explain this Docker pull error #terminalLastCommand` |
| 177 | +- Python version issues: `How do I configure Act to use the correct Python versions? #problems` |
| 178 | +- Permission issues: `@terminal how to fix Docker permission denied errors #terminalLastCommand` |
| 179 | + |
| 180 | +--- |
| 181 | + |
| 182 | +## Phase 3: Optimization and Integration (10-15 minutes) |
| 183 | + |
| 184 | +### Step 1: Create Local Development Commands |
| 185 | + |
| 186 | +Use Copilot to create convenient commands: |
| 187 | + |
| 188 | +``` |
| 189 | +/new Create a Makefile that uses Act to run different CI jobs locally |
| 190 | +
|
| 191 | +I want these commands: |
| 192 | +- make test-local: run only the test steps |
| 193 | +- make lint-local: run only linting and formatting |
| 194 | +- make ci-full: run the complete CI pipeline |
| 195 | +- make ci-quick: run a fast subset for development |
| 196 | +
|
| 197 | +Use our existing .github/workflows/ci.yml as the base. |
| 198 | +``` |
| 199 | + |
| 200 | +### Step 2: Act Configuration |
| 201 | + |
| 202 | +Let's optimize Act for our project: |
| 203 | + |
| 204 | +``` |
| 205 | +How can I create a .actrc file to optimize Act for our Python project? #file:.github/workflows/ci.yml |
| 206 | +
|
| 207 | +I want to: |
| 208 | +1. Use appropriate Docker images for Python |
| 209 | +2. Set up proper environment variables |
| 210 | +3. Optimize for faster local development |
| 211 | +4. Handle secrets and environment configuration |
| 212 | +``` |
| 213 | + |
| 214 | +### Step 3: VS Code Integration (Optional) |
| 215 | + |
| 216 | +``` |
| 217 | +/new Create VS Code tasks.json entries for running Act commands |
| 218 | +
|
| 219 | +I want tasks for: |
| 220 | +- Running full CI locally |
| 221 | +- Running just tests |
| 222 | +- Running just linting |
| 223 | +- Debugging CI issues |
| 224 | +
|
| 225 | +Make them easy to run from VS Code's command palette. |
| 226 | +``` |
| 227 | + |
| 228 | +--- |
| 229 | + |
| 230 | +## Success Criteria |
| 231 | + |
| 232 | +By the end of this exercise, you should have: |
| 233 | + |
| 234 | +- [ ] Act installed and working on your system |
| 235 | +- [ ] Successfully run the GitHub Actions workflow locally |
| 236 | +- [ ] Docker images downloaded and cached for future runs |
| 237 | +- [ ] Understanding of Act output and common issues |
| 238 | +- [ ] Local development commands (Makefile or scripts) |
| 239 | +- [ ] Optional: VS Code integration for easy access |
| 240 | + |
| 241 | +--- |
| 242 | + |
| 243 | +## Bonus Challenges 🏴☠️ |
| 244 | + |
| 245 | +If you finish early and want to explore more: |
| 246 | + |
| 247 | +### Challenge 1: Multi-Workflow Support |
| 248 | +``` |
| 249 | +Our project might have multiple workflows in the future. How can I configure Act to handle different types of workflows (CI, deployment, security scans)? |
| 250 | +``` |
| 251 | + |
| 252 | +### Challenge 2: Custom Docker Images |
| 253 | +``` |
| 254 | +How can I create or configure custom Docker images for Act that include all our project dependencies pre-installed for faster local runs? |
| 255 | +``` |
| 256 | + |
| 257 | +### Challenge 3: Integration with Git Hooks |
| 258 | +``` |
| 259 | +/new Create a pre-commit hook that runs a subset of our CI checks locally using Act before allowing commits. |
| 260 | +``` |
| 261 | + |
| 262 | +--- |
| 263 | + |
| 264 | +## Troubleshooting Guide |
| 265 | + |
| 266 | +### Common Issues and Solutions |
| 267 | + |
| 268 | +**"Docker daemon not running"** |
| 269 | +``` |
| 270 | +@terminal How do I start Docker Desktop and verify it's running properly? |
| 271 | +``` |
| 272 | + |
| 273 | +**"Permission denied" errors** |
| 274 | +``` |
| 275 | +@terminal How to fix Docker permission issues on my operating system #terminalLastCommand |
| 276 | +``` |
| 277 | + |
| 278 | +**"Act command not found"** |
| 279 | +``` |
| 280 | +Act installation seems incomplete. How can I verify and fix the installation? #terminalLastCommand |
| 281 | +``` |
| 282 | + |
| 283 | +**Slow Docker image downloads** |
| 284 | +``` |
| 285 | +How can I configure Docker to use faster mirrors or cache images for Act? #problems |
| 286 | +``` |
| 287 | + |
| 288 | +**Python version conflicts** |
| 289 | +``` |
| 290 | +Act is using the wrong Python version. How do I configure it to match our CI requirements? #file:.github/workflows/ci.yml |
| 291 | +``` |
| 292 | + |
| 293 | +--- |
| 294 | + |
| 295 | +## What You've Learned |
| 296 | + |
| 297 | +- How to run GitHub Actions locally for faster feedback |
| 298 | +- Docker-based CI/CD workflows and troubleshooting |
| 299 | +- Act configuration and optimization |
| 300 | +- Integration of local CI tools with development workflow |
| 301 | +- Using Copilot for DevOps tooling and troubleshooting |
| 302 | + |
| 303 | +This exercise bridges the gap between development and deployment, giving you practical DevOps skills that you can immediately apply to any project with GitHub Actions! |
| 304 | + |
| 305 | +*🏴☠️ Congratulations, matey! You've mastered the art of local CI/CD like a true DevOps pirate! ⚓* |
0 commit comments