GitHub Integration Commands

Overview

Manage GitHub integration for CI/CD workflows, cache management, and repository access. The GitHub integration allows you to use Ubicloud resources in GitHub Actions and manage GitHub Actions cache.

Installation Management

List Installations

List all GitHub App installations:

ubi gh installation list

--no-headers

flag

Don’t display column headers in output.

Output columns:

id - Installation identifier
name - Installation name

List Repositories

List repositories for a GitHub installation:

ubi gh installation installation-name list-repositories

installation-name

string

required

Name of the GitHub App installation.

Example

ubi gh installation my-org list-repositories

Cache Management

List Cache Entries

List cache entries for a GitHub repository:

ubi gh installation-name/repository-name list-cache-entries

installation-name/repository-name

string

required

GitHub installation and repository name (e.g., my-org/my-repo).

Output columns:

id - Cache entry ID
size - Cache size (human-readable)
key - Cache key

Example

ubi gh my-org/web-app list-cache-entries

Remove Cache Entry

Delete a specific cache entry:

ubi gh installation-name/repository-name remove-cache-entry cache-id

cache-id

string

required

ID of the cache entry to remove.

Example

ubi gh my-org/web-app remove-cache-entry cache-123

Remove All Cache Entries

Delete all cache entries for a repository:

ubi gh installation-name/repository-name remove-all-cache-entries

Example

ubi gh my-org/web-app remove-all-cache-entries

This will permanently delete all cache entries. Build times may increase until caches are rebuilt.

Common Workflows

View Organization Setup

# List all installations
ubi gh installation list

# View repositories for an installation
ubi gh installation my-org list-repositories

# Check cache for a repository
ubi gh my-org/web-app list-cache-entries

Clean Up Old Caches

# View current cache
ubi gh my-org/web-app list-cache-entries

# Remove specific old entries
ubi gh my-org/web-app remove-cache-entry cache-old-1
ubi gh my-org/web-app remove-cache-entry cache-old-2

# Or remove all and rebuild
ubi gh my-org/web-app remove-all-cache-entries

Debug Cache Issues

# Check cache size
ubi gh my-org/web-app list-cache-entries

# Remove problematic cache
ubi gh my-org/web-app remove-all-cache-entries

# Trigger workflow to rebuild cache
gh workflow run build.yml

GitHub Actions Integration

Using Ubicloud in Workflows

Integrate Ubicloud CLI in GitHub Actions:

name: Deploy to Ubicloud
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Ubicloud CLI
        run: |
          curl -LO https://github.com/ubicloud/cli/releases/latest/download/ubi-linux-amd64
          chmod +x ubi-linux-amd64
          sudo mv ubi-linux-amd64 /usr/local/bin/ubi
      
      - name: Deploy Application
        env:
          UBI_TOKEN: ${{ secrets.UBI_TOKEN }}
        run: |
          # Create or update VM
          ubi vm eu-central-h1/app-server create my-key || true
          
          # Deploy code
          ubi vm eu-central-h1/app-server ssh "cd /app && git pull && ./deploy.sh"

Manage Cache from Workflows

name: Clear Cache
on:
  workflow_dispatch:
    inputs:
      repository:
        description: 'Repository name'
        required: true

jobs:
  clear-cache:
    runs-on: ubuntu-latest
    steps:
      - name: Install CLI
        run: |
          curl -LO https://github.com/ubicloud/cli/releases/latest/download/ubi-linux-amd64
          chmod +x ubi-linux-amd64
          sudo mv ubi-linux-amd64 /usr/local/bin/ubi
      
      - name: Clear Cache
        env:
          UBI_TOKEN: ${{ secrets.UBI_TOKEN }}
        run: |
          ubi gh ${{ github.repository_owner }}/${{ inputs.repository }} remove-all-cache-entries

Best Practices

Monitor Cache Usage

Regularly check cache sizes:

# Check all repositories
for repo in $(ubi gh installation my-org list-repositories | tail -n +2 | awk '{print $1}'); do
  echo "\nCache for $repo:"
  ubi gh my-org/$repo list-cache-entries
done

Large caches can indicate:

Inefficient caching strategies
Too many cache keys
Need for cleanup

Clean Up Stale Caches

Remove old or unused caches:

# After major refactoring
ubi gh my-org/web-app remove-all-cache-entries

# After changing dependencies
ubi gh my-org/api remove-all-cache-entries

Clean caches when:

Changing build dependencies
After major refactoring
Troubleshooting build issues
Cache keys change

Use Specific Cache Keys

In GitHub Actions, use specific cache keys:

- name: Cache Dependencies
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

This creates manageable caches that can be selectively removed.

Automate Cache Management

Set up automated cache cleanup:

name: Weekly Cache Cleanup
on:
  schedule:
    - cron: '0 0 * * 0'  # Every Sunday

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Install CLI
        run: |
          curl -LO https://github.com/ubicloud/cli/releases/latest/download/ubi-linux-amd64
          chmod +x ubi-linux-amd64
          sudo mv ubi-linux-amd64 /usr/local/bin/ubi
      
      - name: Remove Old Caches
        env:
          UBI_TOKEN: ${{ secrets.UBI_TOKEN }}
        run: |
          # List and selectively remove old caches
          ubi gh ${{ github.repository }} list-cache-entries

Document Cache Strategy

Keep track of cache usage:

# Cache Strategy

## npm dependencies
- Key: `${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}`
- Size: ~500MB
- Rebuild: When package-lock.json changes

## Build artifacts
- Key: `${{ runner.os }}-build-${{ github.sha }}`
- Size: ~100MB
- Rebuild: Every commit

## Test results
- Key: `${{ runner.os }}-test-${{ github.sha }}`
- Size: ~50MB
- Rebuild: Every commit

Troubleshooting

Cannot Access Repository

If you cannot list repositories or caches:

Verify installation exists:
```
ubi gh installation list
```

Check repository name format:

# Correct format
ubi gh my-org/my-repo list-cache-entries

# Wrong
ubi gh my-repo list-cache-entries  # Missing org

Ensure GitHub App is installed for the repository

Cache Removal Fails

If cache deletion fails:

Verify cache ID:

ubi gh my-org/my-repo list-cache-entries

Use correct cache ID:

ubi gh my-org/my-repo remove-cache-entry cache-123

Try removing all caches:

ubi gh my-org/my-repo remove-all-cache-entries

Workflows Not Using Ubicloud

If GitHub Actions aren’t working with Ubicloud:

Verify UBI_TOKEN secret is set:
- Go to repository Settings → Secrets
- Check UBI_TOKEN exists

Test CLI in workflow:

- name: Test CLI
  env:
    UBI_TOKEN: ${{ secrets.UBI_TOKEN }}
  run: |
    ubi vm list

Check CLI installation:

- name: Verify CLI
  run: |
    which ubi
    ubi version

Next Steps

Virtual Machines

Deploy from GitHub Actions

Authentication

Configure CI/CD secrets

CLI Overview

Learn more CLI features

Overview

Commands

​Overview

​Installation Management

​List Installations

​List Repositories

​Example

​Cache Management

​List Cache Entries

​Example

​Remove Cache Entry

​Example

​Remove All Cache Entries

​Example

​Common Workflows

​View Organization Setup

​Clean Up Old Caches

​Debug Cache Issues

​GitHub Actions Integration

​Using Ubicloud in Workflows

​Manage Cache from Workflows

​Best Practices

​Troubleshooting

​Cannot Access Repository

​Cache Removal Fails

​Workflows Not Using Ubicloud

​Next Steps

Virtual Machines

Authentication

CLI Overview

Build docs developers (and LLMs) love

Overview

Installation Management

List Installations

List Repositories

Example

Cache Management

List Cache Entries

Example

Remove Cache Entry

Example

Remove All Cache Entries

Example

Common Workflows

View Organization Setup

Clean Up Old Caches

Debug Cache Issues

GitHub Actions Integration

Using Ubicloud in Workflows

Manage Cache from Workflows

Best Practices

Troubleshooting

Cannot Access Repository

Cache Removal Fails

Workflows Not Using Ubicloud

Next Steps