🚀 Configuring GitHub Actions Runner: Simple Guide

Let’s set up a GitHub Actions runner on Alpine Linux! 💻 This tutorial shows you how to create your own automation worker that runs tasks for your GitHub projects. It’s like having a helpful robot that does repetitive work for you! 😊

🤔 What is a GitHub Actions Runner?

A GitHub Actions runner is like a dedicated worker for your code projects! 🤖 It automatically runs tests, builds applications, and deploys software whenever you make changes to your GitHub repository.

A GitHub Actions runner is like:

• 🏭 A factory worker who builds products automatically
• 🔄 A washing machine that runs cleaning cycles
• 📋 An assistant who follows your instruction list perfectly

🎯 What You Need

Before we start, you need:

• ✅ Alpine Linux system running
• ✅ GitHub account with repository access
• ✅ Root access to your system
• ✅ Internet connection for downloading runner software

📋 Step 1: Prepare System

Installing Required Dependencies

Let’s start by installing everything needed for the GitHub runner. It’s easy! 😊

What we’re doing: Installing tools and dependencies required by GitHub Actions runner.

# Update package index
apk update

# Install required packages
apk add curl bash git tar gzip

# Install Docker for containerized actions
apk add docker docker-compose

# Install Node.js for JavaScript actions
apk add nodejs npm

# Start Docker service
rc-service docker start
rc-update add docker default

# Create user for running actions
adduser -D -s /bin/bash github-runner

What this does: 📖 Your system now has all tools needed to run GitHub Actions.

Example output:

✅ Dependencies installed successfully
✅ Docker service started
✅ GitHub runner user created

What this means: Your system is ready for GitHub Actions! ✅

💡 Important Tips

Tip: Always use a dedicated user for security! 💡

Warning: Keep your runner token secret and secure! ⚠️

🛠️ Step 2: Download and Configure Runner

Getting the GitHub Actions Runner

Now let’s download and set up the GitHub Actions runner software! 📦

What we’re doing: Downloading the runner and configuring it for your GitHub repository.

# Switch to github-runner user
su - github-runner

# Create directory for runner
mkdir -p /home/github-runner/actions-runner
cd /home/github-runner/actions-runner

# Download latest runner (check GitHub for current version)
curl -o actions-runner-linux-x64-2.311.0.tar.gz \
  -L https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-x64-2.311.0.tar.gz

# Verify download (optional)
echo "29fc8cf2dab4c195bb147384e7e2c94cfd4d4022c793b346a6175435265e8153  actions-runner-linux-x64-2.311.0.tar.gz" | sha256sum -c

# Extract runner files
tar xzf ./actions-runner-linux-x64-2.311.0.tar.gz

Code explanation:

• curl -L: Downloads the runner package from GitHub
• tar xzf: Extracts the compressed runner files
• sha256sum -c: Verifies file integrity for security
• /home/github-runner/actions-runner: Runner installation directory

Expected Output:

✅ Runner downloaded successfully
✅ File integrity verified
✅ Runner files extracted

What this means: Great job! Runner software is ready for configuration! 🎉

🎮 Let’s Try It!

Time for hands-on practice! This is the fun part! 🎯

What we’re doing: Configuring the runner to connect to your GitHub repository.

# Configure the runner (you'll need a token from GitHub)
# Go to your repo → Settings → Actions → Runners → New self-hosted runner

# Run configuration script
./config.sh --url https://github.com/YOUR-USERNAME/YOUR-REPO --token YOUR-TOKEN

# When prompted, provide:
# - Runner name: alpine-runner-01
# - Runner group: Default
# - Labels: alpine,linux,self-hosted
# - Work folder: _work

# Test runner configuration
./run.sh --once

Configuration example:

Enter the name of the runner group: [press Enter for default]
Enter the name of runner: alpine-runner-01
Enter any additional labels: alpine,linux,docker
Enter name of work folder: _work

You should see:

✅ Runner successfully configured
✅ Connected to GitHub repository
✅ Ready to process jobs

Awesome work! 🌟

📊 Quick Summary Table

🎮 Practice Time!

Let’s practice what you learned! Try these simple examples:

Example 1: Create Runner Service 🟢

What we’re doing: Setting up the runner to start automatically as a system service.

# Exit from github-runner user
exit

# Create systemd service file
cat > /etc/systemd/system/github-actions-runner.service << 'EOF'
[Unit]
Description=GitHub Actions Runner
After=network.target

[Service]
Type=simple
User=github-runner
WorkingDirectory=/home/github-runner/actions-runner
ExecStart=/home/github-runner/actions-runner/run.sh
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# Install OpenRC service instead (Alpine uses OpenRC)
cat > /etc/init.d/github-actions-runner << 'EOF'
#!/sbin/openrc-run

name="GitHub Actions Runner"
description="GitHub Actions self-hosted runner"

user="github-runner"
directory="/home/github-runner/actions-runner"
command="${directory}/run.sh"
pidfile="/var/run/${RC_SVCNAME}.pid"

depend() {
    need net
    after docker
}

start_pre() {
    checkpath --directory --owner ${user}:${user} --mode 0755 \
        /var/run/${RC_SVCNAME} /var/log/${RC_SVCNAME}
}
EOF

chmod +x /etc/init.d/github-actions-runner

# Start and enable service
rc-service github-actions-runner start
rc-update add github-actions-runner default

What this does: Makes the runner start automatically when system boots! 🌟

Example 2: Create Test Workflow 🟡

What we’re doing: Creating a simple workflow to test your new runner.

# Create example workflow file (do this in your GitHub repo)
mkdir -p .github/workflows

cat > .github/workflows/test-alpine-runner.yml << 'EOF'
name: Test Alpine Runner

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test-on-alpine:
    runs-on: self-hosted
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
    
    - name: Show system info
      run: |
        echo "🏔️ Running on Alpine Linux!"
        uname -a
        cat /etc/alpine-release
        whoami
        pwd
    
    - name: Test Docker
      run: |
        docker --version
        docker run --rm hello-world
    
    - name: Test Node.js
      run: |
        node --version
        npm --version
        echo "console.log('Hello from Alpine runner!');" | node
    
    - name: Success message
      run: |
        echo "✅ Alpine Linux runner working perfectly!"
        echo "🎉 Your CI/CD pipeline is ready!"
EOF

echo "📝 Upload this workflow to your GitHub repository!"
echo "📁 Location: .github/workflows/test-alpine-runner.yml"

What this does: Tests all runner capabilities with a real workflow! 📚

🚨 Fix Common Problems

Problem 1: Runner fails to start ❌

What happened: The runner service won’t start properly. How to fix it: Check logs and permissions!

# Check runner status
rc-service github-actions-runner status

# View runner logs
tail -f /var/log/github-actions-runner/current

# Check file permissions
ls -la /home/github-runner/actions-runner/

# Fix permissions if needed
chown -R github-runner:github-runner /home/github-runner/

Problem 2: Actions fail with permission errors ❌

What happened: GitHub Actions can’t access Docker or other services. How to fix it: Add user to necessary groups!

# Add github-runner to docker group
adduser github-runner docker

# Add to other necessary groups
adduser github-runner wheel

# Restart runner service
rc-service github-actions-runner restart

# Test Docker access
su - github-runner -c "docker ps"

Don’t worry! These problems happen to everyone. You’re doing great! 💪

💡 Simple Tips

1. Monitor regularly 📅 - Check runner status and logs
2. Keep updated 🌱 - Update runner software regularly
3. Secure tokens 🤝 - Rotate runner tokens periodically
4. Scale wisely 💪 - Add more runners when needed

✅ Check Everything Works

Let’s make sure everything is working:

# Check runner service status
rc-service github-actions-runner status

# Verify runner is connected to GitHub
su - github-runner -c "cd actions-runner && ./run.sh --once"

# Test Docker functionality
docker run --rm hello-world

# Check available disk space for builds
df -h /home/github-runner/

Good output:

✅ Runner service is running
✅ Connected to GitHub successfully  
✅ Docker working properly
✅ Sufficient disk space available

🏆 What You Learned

Great job! Now you can:

• ✅ Install and configure GitHub Actions runner
• ✅ Set up automatic service startup
• ✅ Create and test CI/CD workflows
• ✅ Troubleshoot common runner issues

🎯 What’s Next?

Now you can try:

• 📚 Learning about advanced workflow strategies
• 🛠️ Setting up multiple runners for parallel jobs
• 🤝 Helping others automate their development processes
• 🌟 Building complex CI/CD pipelines with testing and deployment!

Remember: Every expert was once a beginner. You’re doing amazing! 🎉

Keep automating and you’ll save tons of time on repetitive tasks! 💫