Quickstart Guide

Get your first GitHub Actions workflow running on Builtiful's managed infrastructure in just a few minutes.

Prerequisites

Before you begin, ensure you have:

• A GitHub account with admin access to a repository or organization
• A credit card for billing (you'll get free trial credits to start)
• An existing GitHub Actions workflow (or we'll help you create one)

Step 1: Install the Builtiful GitHub App

1. Visit app.builtiful.com
2. Click "Sign in with GitHub" to authenticate
3. You'll be redirected to GitHub to install the Builtiful app
4. Select the repositories or organization where you want to use Builtiful runners
5. Click "Install & Authorize"

Note: You can start with specific repositories and add more later through GitHub's app settings.

Step 2: Complete Onboarding

After installation, you'll be redirected back to Builtiful to complete setup:

1. Verify your email - We'll send a confirmation link
2. Start your free trial - Get $15 in credits to test Builtiful
3. Add payment method - Required after trial credits are exhausted

Step 3: Configure Your Workflow

Update your GitHub Actions workflow to use Builtiful runners. Replace the runs-on value with a Builtiful runner label:

Basic Example

name: CI Pipeline
on: [push, pull_request]
 
jobs:
  build:
    # Before: runs-on: ubuntu-latest
    runs-on: builtiful(ubuntu)  # After: Use Builtiful runner
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Build project
        run: npm run build

Available Runner Labels

Choose the right size for your workload:

• builtiful(ubuntu, cpus=1) - 1 vCPUs, ~4GB RAM
• builtiful(ubuntu, cpus=2) - 2 vCPUs, ~8GB RAM
• builtiful(ubuntu, cpus=2) - 3 vCPUs, ~12GB RAM
• builtiful(ubuntu, cpus=2) - 4 vCPUs, ~16GB RAM
• ...
• builtiful(ubuntu, cpus=16) - 16 vCPUs, ~64GB RAM

See Runner Configuration for advanced options.

Step 4: Push and Run

1. Commit your updated workflow file:

   git add .github/workflows/ci.yml
   git commit -m "Switch to Builtiful runners"
   git push

2. Navigate to the Actions tab in your GitHub repository

3. You'll see your workflow running on Builtiful infrastructure!

4. Monitor progress in real-time through:

   • GitHub's workflow UI
   • Builtiful dashboard at app.builtiful.com

Step 5: Monitor Usage

Track your runner usage and costs in the Builtiful dashboard:

• Active Jobs - See currently running workflows
• Job History - Review completed jobs and their duration
• Usage Metrics - Monitor compute minutes and costs
• Credits Balance - Track remaining trial credits

Example Workflows

Multi-Job Pipeline

name: Full CI/CD Pipeline
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: builtiful(ubuntu) # Default CPU is 2, equivlent to ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/test.sh
 
  build:
    runs-on: builtiful(ubuntu, cpus=8)  # Larger runner for build
    needs: test
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/build.sh
      
  labeler:
    runs-on: builtiful(ubuntu, cpus=1)  # Smaller runner for labeling tasks that does not require more resource

Matrix Build

name: Matrix Testing
on: [push]
 
jobs:
  test:
    runs-on: builtiful(ubuntu)
    strategy:
      matrix:
        node: [18, 20, 22]
        os: [linux]  # More OS options coming soon
    
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Troubleshooting

Workflow not starting?

• Verify the Builtiful app is installed on your organization and has access to your repository
• Check that your runs-on label is spelled correctly
• Ensure your account payment information is up to date

Job queued for long time?

• Check the Builtiful status page for any ongoing issues
• Verify your runner syntax is correct (typos will cause indefinite queuing)

Authentication errors?

• Re-authenticate at app.builtiful.com
• Verify the Builtiful app has necessary repository permissions

Next Steps

• 📖 Learn about advanced runner configuration
• 💰 Understand our pricing model
• 🔒 Review our security practices
• 🚀 Explore best practices for optimal performance

Need Help?

• Documentation: You're already here!
• Support: Email support@builtiful.io
• Status: Check status.builtiful.com for service updates

Ready to scale your CI/CD without the infrastructure headaches? You're all set with Builtiful!