DevOps and infrastructure toolkit with GitHub Actions, Kamal deployment, and Tailscale VPN configuration

version
0.1.4
GitHub stars
12

Install

/plugin install devops@jebs-dev-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add el-feo/ai-context.

Contents

Discovered from source

Skills 3

GitHub Actions

GitHub Actions automates software workflows with event-driven CI/CD pipelines. Workflows are YAML files in .github/workflows/ that define jobs, steps, and actions triggered by repository events.

Action types:

  • Workflow files: CI/CD pipelines using existing actions (.github/workflows/*.yml)
  • Custom JavaScript actions: Fast, cross-platform, use @actions/toolkit
  • Custom Docker actions: Full environment control, Linux only, slower startup
  • Composite actions: Combine multiple steps into reusable units

Quick Start

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test

Ruby/Rails with RSpec:

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: .ruby-version
    bundler-cache: true

- name: Setup database
  env:
    RAILS_ENV: test
  run: bin/rails db:setup

- run: bundle exec rspec

TypeScript/Node.js:

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

- run: npm ci
- run: npm run build --if-present
- run: npm test

Deploy to Fly.io:

- uses: superfly/flyctl-actions/setup-flyctl@1.5
- run: flyctl deploy --remote-only
  env:
    FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

Creating Workflows

  1. Identify triggers: push, pull_request, workflow_dispatch, schedule, etc.
  2. Define jobs: Specify runner OS, steps, and dependencies
  3. Add security: Set GITHUB_TOKEN permissions to read-only, pin actions to SHA
  4. Optimize performance: Enable caching, use matrix builds for parallelization
  5. Test locally: Use act or GitHub CLI to test before pushing

Evaluating Workflows

  1. Security scan: Check permissions, secrets exposure, action pinning, pull_request_target usage
  2. Performance analysis: Identify slow steps, missing caches, parallelization opportunities
  3. Best practices review: Validate naming, structure, error handling, documentation

Critical Security Patterns

  1. Always set GITHUB_TOKEN permissions to read-only:

    permissions:
      contents: read
    
  2. Pin actions to commit SHA (most secure):

    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
    
  3. Use OIDC for cloud deployments (credential-less):

    permissions:
      id-token: write
      contents: read
    
  4. Avoid pull_request_target with untrusted code - runs in base repository context with access to secrets

  5. Never log secrets - use ::add-mask:: for dynamic values

  6. Validate user-controlled inputs via environment variables:

    - env:
        TITLE: ${{ github.event.issue.title }}
      run: echo "Title: $TITLE"
    

For complete security guidelines, see references/security-checklist.md.

Key Anti-Patterns

  • Running as root in Docker actions
  • Hardcoded secrets (always use GitHub Secrets)
  • Overly broad permissions
  • No caching (wastes time on every run)
  • Sequential jobs that could be parallel
  • Using branch references for actions (use tags or SHAs)
  • No timeout-minutes (jobs default to 6 hours)
  • fetch-depth: 0 when full history isn't needed

Concurrency Control

Cancel outdated runs to save resources:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Reference Guides

For detailed information on specific topics:

  • Workflow Syntax: Complete YAML reference - triggers, jobs, steps, expressions, contexts, matrix, reusable workflows
  • Custom Actions: Building JavaScript, Docker, and composite actions with @actions/toolkit
  • Security Checklist: GITHUB_TOKEN permissions, action pinning, OIDC setup, secrets management, input validation, self-hosted runner security
  • Performance Optimization: Dependency caching (Ruby/Node/Python/Docker), parallelization, selective triggers, test splitting, self-hosted runners
  • Common Workflows: Production-ready templates for Rails CI/CD, TypeScript CI, Heroku/Fly.io deployments, monorepos, release automation, full-stack examples
  • Troubleshooting: Permission errors, caching issues, secret problems, database connections, timeout debugging, act for local testing

Validation Checklist

Pre-deployment:

  • YAML syntax valid
  • Required secrets configured
  • GITHUB_TOKEN permissions set to minimum required
  • Actions pinned to SHA or trusted tags
  • Caching configured for dependencies
  • Workflow triggers appropriate for use case

Post-deployment:

  • First run completes successfully
  • Execution time acceptable (<15 min for full CI)
  • No secrets in logs
  • Cache hit rate >80% after first run

Kamal Deployment

Kamal is a zero-downtime deployment tool for containerized applications, built by 37signals. It combines SSH, Docker, and Kamal Proxy to deploy any containerized web app to bare Linux servers.

Key components: SSH/SSHKit (remote execution), Docker (containers), Kamal Proxy (zero-downtime routing), Accessories (supporting services).

Quick Start

gem install kamal
cd your-app && kamal init          # Generate config/deploy.yml and .kamal/secrets
# Edit config/deploy.yml and .kamal/secrets
kamal setup                         # Bootstrap servers, install Docker, deploy

Minimal deploy.yml

service: myapp
image: username/myapp

servers:
  web:
    - 192.168.1.10

registry:
  server: ghcr.io
  username: myuser
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    RAILS_ENV: production

proxy:
  ssl: true
  host: example.com

For complete configuration options (registry variants, builder, proxy, accessories, SSH, volumes, aliases, healthchecks, rollout strategies), see references/configuration.md.

Essential Commands

kamal deploy                    # Build, push, deploy with zero downtime
kamal deploy -d staging         # Deploy to specific environment
kamal rollback VERSION          # Rollback to previous version
kamal app logs -f               # Follow application logs
kamal app exec -i --reuse "bin/rails console"  # Interactive console
kamal app maintenance           # Enable maintenance mode
kamal app live                  # Disable maintenance mode
kamal config                    # Show parsed configuration
kamal lock release              # Release stuck deployment lock

For complete command reference with all options, see references/commands.md.

Common Workflows

Deploy with Database Migration

Create .kamal/hooks/pre-deploy:

#!/bin/bash
kamal app exec -p -q "bin/rails db:migrate"

Then chmod +x .kamal/hooks/pre-deploy && kamal deploy.

Rollback

kamal app containers            # List available versions
kamal rollback abc123def        # Rollback to specific version

Debugging Failed Deployments

  1. kamal app logs -n 500 — check application logs
  2. kamal server exec "docker ps -a" — check container status
  3. kamal app exec "curl localhost:3000/up" — test health endpoint
  4. kamal config — verify configuration
  5. kamal lock release — clear stuck locks

Multiple Environments

Create config/deploy.staging.yml, then:

kamal setup -d staging && kamal deploy -d staging

For detailed workflows (CI/CD, scaling, backups, security, canary deploys, monitoring), see references/workflows.md.

Limitations

  • No state reconciliation — removing servers from config does not decommission containers
  • No dynamic provisioning — cannot auto-scale or provision servers
  • Single-server load balancing — Kamal Proxy balances containers per server; use an external LB across servers

Tailscale Network Management

Quick Start

# Install (Linux)
curl -fsSL https://tailscale.com/install.sh | sh

# Install (macOS)
brew install tailscale

# Connect and authenticate
sudo tailscale up

# Check status
tailscale status

# Get your Tailscale IP
tailscale ip -4

Common Operations

Connection Management

tailscale up                    # Connect
tailscale down                  # Disconnect (daemon stays running)
tailscale status                # View peers
tailscale status --json | jq    # Detailed network map
tailscale ping machine-name     # Test connectivity (ignores ACLs)
tailscale ping --icmp machine-name  # Test with ACLs
tailscale set --exit-node=name  # Use exit node
tailscale set --exit-node=      # Stop using exit node

Use tailscale set to change settings without reconnecting. Use tailscale up for initial setup.

Subnet Router Setup

Run scripts/setup_subnet_router.sh <subnet_cidr> [auth_key] for automated setup.

Manual steps:

  1. Enable IP forwarding on the router device
  2. sudo tailscale up --advertise-routes=192.168.1.0/24
  3. Approve routes in admin console (Machines > device > Edit route settings)
  4. Linux clients: sudo tailscale up --accept-routes

Exit Node Setup

Run scripts/setup_exit_node.sh [auth_key] for automated setup.

Manual steps:

  1. Enable IP forwarding on the exit node
  2. sudo tailscale up --advertise-exit-node
  3. Approve in admin console (Machines > device > Edit route settings > Use as exit node)
  4. Clients: tailscale set --exit-node=node-name --exit-node-allow-lan-access

Tailscale SSH

# Enable on server
sudo tailscale set --ssh

# Connect from client (no special setup needed)
ssh machine-name

Requires both network access grant and SSH ACL rule. See acl-examples.md for SSH ACL patterns.

Serve and Funnel

# Serve locally to tailnet
tailscale serve 3000

# Expose to public internet (ports 443, 8443, or 10000 only)
tailscale funnel 3000

# TCP forwarding with TLS termination
tailscale serve --tls-terminated-tcp=5432 localhost:5432

# Check status / turn off
tailscale serve status
tailscale serve off

Access Control

Use Grants (modern, recommended) over ACLs (legacy). Both work, but Grants support application-layer capabilities.

{
  "groups": {
    "group:engineering": ["alice@example.com"]
  },
  "tagOwners": {
    "tag:server": ["group:engineering"]
  },
  "grants": [
    {
      "src": ["group:engineering"],
      "dst": ["tag:server"],
      "ip": ["22", "443"]
    }
  ]
}

Key patterns: Use groups for people, tags for machines. Always include both network grants and SSH rules for SSH access.

For detailed ACL scenarios, SSH access patterns, posture checks, auto-approvers, GitOps integration, and common mistakes, see acl-examples.md.

Reference Files

  • cli-reference.md - Complete CLI command reference with all flags, target formats, and platform-specific notes
  • acl-examples.md - Detailed ACL/grants configuration: team-based access, dev/staging/prod isolation, SSH patterns, posture checks, auto-approvers, GitOps, migration from ACLs to Grants
  • api-usage.md - REST API, Terraform provider, Python SDK, webhooks, automation examples
  • troubleshooting.md - Connectivity diagnostics, subnet router issues, exit node issues, SSH problems, MagicDNS, performance tuning, common error messages
  • production-setup.md - Architecture patterns, HA setup, security hardening, IaC (Terraform/Ansible/K8s), monitoring, DR, operational procedures

Scripts

  • scripts/setup_subnet_router.sh <subnet_cidr> [auth_key] - Automated subnet router setup (installs Tailscale, enables IP forwarding, configures routes)
  • scripts/setup_exit_node.sh [auth_key] - Automated exit node setup (installs Tailscale, enables IP forwarding, advertises as exit node)

Commands 1

Delegate GitHub Actions tasks to the github-actions skill for: $ARGUMENTS

This routes to specialized skill containing workflows, security patterns, performance optimization, and deployment strategies for Ruby/Rails and TypeScript projects.

1. Use Skill tool to invoke github-actions skill 2. Pass user's request: $ARGUMENTS 3. Let skill handle workflow creation, evaluation, or optimization

<success_criteria>

  • Skill successfully invoked
  • Arguments passed correctly to skill
  • User receives comprehensive GitHub Actions guidance </success_criteria>

Sponsors

Details

Marketplace
el-feo/ai-context
Source
plugins/devops
Author
Jeb Coleman
Category
Community

More from el-feo/ai-context

All 8