Deploy just-optimism

Woodpecker CI

Lightweight self-hosted CI/CD platform — GitHub Actions alternative. Runs pipelines as steps via a local backend (no Docker daemon required). Two services: server + agent.

Deploy and Host

Host your own Woodpecker CI on Railway. This template provisions a server (UI, API, SQLite) and an agent (pipeline executor) with persistent storage for your build data.

Architecture

• Server — UI, API, webhook receiver, pipeline analyzer. Stores everything in SQLite (/var/lib/woodpecker).
• Agent — connects to the server via GRPC and executes pipeline steps locally. No Docker socket required.

Features

• GitHub Actions alternative — familiar YAML pipeline syntax
• OAuth login — GitHub/GitLab/Forgejo/Gitea OAuth2 (configure via env vars)
• Local backend — runs pipeline steps directly on the agent (no Docker daemon needed)
• SQLite by default — zero external database to manage
• Webhook triggers — automatic pipeline runs on push/PR
• Secrets management — built-in secret store for pipeline variables
• Parallel steps — WOODPECKER_MAX_WORKFLOWS controls concurrency
• Persistent — SQLite DB persists across deploys via Railway volume

Dependencies for

This template is self-contained — no external services required. All data persists on the server's volume. The only external dependency is an OAuth app with your forge (GitHub, GitLab, Forgejo, or Gitea) for user authentication.

About Hosting

This template deploys to Railway's managed infrastructure. After deployment, you'll need to configure OAuth credentials for your chosen forge (GitHub, GitLab, Forgejo, or Gitea) via environment variables in the Railway dashboard. The server will not start until a valid forge OAuth app is configured — this is a security requirement.

Configuration

Deployment Dependencies

Before the server can start, you must configure at least one forge OAuth app:

1. Register an OAuth application with your forge (GitHub/GitLab/Forgejo/Gitea)
2. In Railway dashboard, set these env vars on the server service:
   • WOODPECKER_GITHUB=true (or GITLAB, FORGEJO, GITEA)
   • WOODPECKER_GITHUB_CLIENT — your OAuth Client ID
   • WOODPECKER_GITHUB_SECRET — your OAuth Client Secret
3. The server will restart automatically once valid credentials are set

Server

Agent

Usage

1. Deploy the template to Railway
2. Generate a shared agent secret: openssl rand -hex 32
3. Set WOODPECKER_AGENT_SECRET on both server and agent services
4. Set WOODPECKER_HOST to your server's public URL
5. Configure GitHub/GitLab OAuth credentials (required for server to start)
6. Open the server URL — first user becomes admin
7. Activate repositories and add .woodpecker.yml pipeline files

Pipeline Example (.woodpecker.yml)

steps:
  build:
    image: alpine
    commands:
      - echo "Building..."
      - make build
  test:
    image: alpine
    commands:
      - echo "Testing..."
      - make test

Common Use Cases

• CI/CD for open-source projects — free self-hosted alternative to GitHub Actions
• Private repo automation — build/test/deploy without leaving your infrastructure
• Lightweight pipelines — Node.js, Go, Rust, Python projects without heavy CI overhead
• Fork-friendly — anyone can deploy their own copy in one click

Why Deploy

• No Docker-in-Docker — Railway doesn't expose the docker socket; Woodpecker's local backend works around this
• Zero external dependencies — SQLite means no Postgres to manage
• One-click deploy — no manual OAuth setup wizard; configure via env vars after deploy
• Cost-efficient — two small services, shared volume, runs cheap on Railway's free tier

Notes

• The local backend runs steps directly on the agent container. Steps are isolated per workflow but share the agent's filesystem.
• For Docker-based steps, use WOODPECKER_BACKEND=docker — but this requires mounting /var/run/docker.sock, which Railway does not support.
• To update, redeploy the service — Railway pulls the latest image.