Configure GitHub Actions workflows to use Builtiful runners with the correct runs-on syntax

Runner Configuration

Learn how to configure your GitHub Actions workflows to use Builtiful's managed runners with the correct runs-on syntax.

Basic Configuration

Builtiful Runner Syntax

Builtiful uses a specific syntax format for the runs-on directive:

runs-on: builtiful(distribution, parameter=value, ...)

Simple Examples

jobs:
  build:
    # Basic Ubuntu runner with default settings of 2vCPU and 8GB RAM (same as ubuntu-latest)
    runs-on: builtiful(ubuntu)
    
    # Ubuntu runner with specific CPU count
    runs-on: builtiful(ubuntu, cpus=4)

Available Parameters

Required Parameters

Parameter	Description	Example
`distribution`	Operating system distribution	`ubuntu`

Optional Parameters

Parameter	Description	Default	Example
`cpus`	Number of CPU cores	`2`	`cpus=8`
`arch`	CPU architecture	`x86_64`	`arch=arm64`

Configuration Examples

CPU Scaling

Choose the right CPU count for your workload:

CPU Count	Memory	Syntax
1	4GB	`builtiful(ubuntu, cpus=1)`
2	8GB	`builtiful(ubuntu, cpus=2)`
3	12GB	`builtiful(ubuntu, cpus=3)`
4	16GB	`builtiful(ubuntu, cpus=4)`
5	20GB	`builtiful(ubuntu, cpus=5)`
6	24GB	`builtiful(ubuntu, cpus=6)`
7	28GB	`builtiful(ubuntu, cpus=7)`
8	32GB	`builtiful(ubuntu, cpus=8)`
9	36GB	`builtiful(ubuntu, cpus=9)`
10	40GB	`builtiful(ubuntu, cpus=10)`
11	44GB	`builtiful(ubuntu, cpus=11)`
12	48GB	`builtiful(ubuntu, cpus=12)`
13	52GB	`builtiful(ubuntu, cpus=13)`
14	56GB	`builtiful(ubuntu, cpus=14)`
15	60GB	`builtiful(ubuntu, cpus=15)`
16	64GB	`builtiful(ubuntu, cpus=16)`

Example usage:

jobs:
  # Very small tasks - labeler, bots
  labeler:
    runs-on: builtiful(ubuntu, cpus=1)
 
  # Light tasks - linting, simple builds (2 vCPU is the default)
  lint:
    runs-on: builtiful(ubuntu, cpus=2)
  
  # Medium builds - most application builds
  build:
    runs-on: builtiful(ubuntu, cpus=4)
  
  # Heavy compilation - C++, Rust, large projects
  compile:
    runs-on: builtiful(ubuntu, cpus=16)

Architecture Options

Specify CPU architecture when needed:

jobs:
  # Default x86_64 architecture
  build-x86:
    runs-on: builtiful(ubuntu, cpus=4)
  
  # ARM64 architecture (coming soon)
  build-arm:
    runs-on: builtiful(ubuntu, cpus=4, arch=arm64)

Complete Examples

Multi-Job Workflow

name: Full CI/CD Pipeline
on: [push, pull_request]
 
jobs:
  lint:
    runs-on: builtiful(ubuntu, cpus=2)
    steps:
      - uses: actions/checkout@v4
      - name: Run linter
        run: npm run lint
 
  test:
    runs-on: builtiful(ubuntu, cpus=8)
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test
 
  build:
    needs: [lint, test]
    runs-on: builtiful(ubuntu, cpus=16)
    steps:
      - uses: actions/checkout@v4
      - name: Build application
        run: npm run build
 
  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: builtiful(ubuntu, cpus=4)
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh

Matrix Builds

jobs:
  test:
    strategy:
      matrix:
        node: [18, 20, 22]
        cpus: [4, 8]
    
    runs-on: builtiful(ubuntu, cpus=${{ matrix.cpus }})
    
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Dynamic Configuration

jobs:
  build:
    runs-on: ${{
      github.event_name == 'push' && github.ref == 'refs/heads/main'
        && 'builtiful(ubuntu, cpus=16)'  # Production builds
        || 'builtiful(ubuntu, cpus=4)'   # Development builds
    }}

Pre-installed Software

All Builtiful runners include the same software as GitHub-hosted runners:

You can see the pre-installed software, as well as their versions at the GitHub Runners image release page.

Docker Support

Docker is pre-installed and running on all runners:

jobs:
  docker-build:
    runs-on: builtiful(ubuntu, cpus=8)
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .
      
      - name: Run tests in container
        run: docker run myapp:${{ github.sha }} npm test

Service Containers

Service containers work exactly like GitHub-hosted runners:

jobs:
  integration-test:
    runs-on: builtiful(ubuntu, cpus=4)
    
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
    
    steps:
      - uses: actions/checkout@v4
      - name: Run integration tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test

Migration Guide

From GitHub-Hosted Runners

Before:

runs-on: ubuntu-latest
runs-on: ubuntu-24.04

After:

runs-on: builtiful(ubuntu)

From Self-Hosted Runners

Before:

runs-on: [self-hosted, linux, x64]

After:

runs-on: builtiful(ubuntu)

Performance Optimization

Right-Size Your Runners

CPU Count	RAM	Use Case	Cost/Min
2	~4GB	Linting, deployments, simple scripts	Lowest
4	~8GB	Standard builds, unit tests	Low
8	~16GB	Large projects, integration tests	Medium
16	~32GB	Heavy compilation, parallel testing	Medium-High

Caching Best Practices

Use GitHub's cache action for faster builds:

jobs:
  build:
    runs-on: builtiful(ubuntu, cpus=4)
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/cache@v3
        with:
          path: |
            ~/.npm
            node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
      
      - run: npm ci
      - run: npm run build

Troubleshooting

Common Issues

Job Stuck in Queue

Possible causes:

Typo in runner syntax
Invalid parameter values
Builtiful app not installed

Check syntax:

# ✅ Correct
runs-on: builtiful(ubuntu, cpus=4)
 
# ❌ Wrong - missing parentheses
runs-on: builtiful-ubuntu-4cpu
 
# ❌ Wrong - invalid parameter
runs-on: builtiful(ubuntu, cpu=4)  # Should be 'cpus'

Invalid Configuration

Common syntax errors:

# ❌ Wrong - quotes around values  
runs-on: builtiful(ubuntu, cpus="4")
 
# ❌ Wrong - invalid distribution
runs-on: builtiful(centos, cpus=4)
 
# ✅ Correct
runs-on: builtiful(ubuntu, cpus=4)

Next Steps

Review Pricing to understand costs
Check Best Practices for optimization tips
Read Security for compliance information
Contact support@builtiful.io for help with configuration

Runner Configuration

On this page