Golang Runner

Golang Runner is an OSC service that builds and runs Go applications directly from a Git repository. You provide a source URL pointing to a Go project, and OSC clones the repo, compiles the binary, and serves it as a live HTTP service — no Docker knowledge required.

It is the Go counterpart to Web Runner (Node.js) and Python Runner.

Getting Started

Launch a Golang Runner instance from the OSC dashboard.

Prerequisites

  • An OSC account. Sign up here.
  • A Go application in a Git repository. The app must listen on the port provided via the PORT environment variable (OSC injects this automatically).
  • For private repositories: a personal access token (PAT) with read access.

Application Requirements

  • The app must read its listening port from the PORT environment variable.
  • The binary must be built with go build — the runner auto-detects the project layout (see Build Detection below).
  • CGO is disabled by default (CGO_ENABLED=0), producing fully static binaries.

Build Detection

The runner tries the following in order until it finds a main package:

  1. cmd/server/main.go
  2. cmd/*/main.go (first match)
  3. main.go
  4. go build ./... (fallback)

Override with OscBuildCmd if your project uses a non-standard layout.

Create a Golang Runner Instance

Using the OSC dashboard

  1. Go to Golang Runner on OSC.
  2. Click Create instance.
  3. Fill in the required fields:
  4. Name — alphanumeric identifier
  5. SourceUrl — HTTPS URL of the Git repository (append #branchname for a specific branch)
  6. Optional fields:
  7. GitHubToken — PAT for private repositories
  8. SubPath — subdirectory in the repo to use as build root (for monorepos)
  9. OscBuildCmd — override the auto-detected build command
  10. OscEntry — override the binary path (default: /app/server)
  11. CGoEnabled — set to 1 to enable CGO
  12. ConfigService + OscAccessToken — load env vars from an App Config Service instance at startup
  13. Click Create.

Using the CLI

# Public repository
osc create eyevinn-golang-runner mygoapp \
  -o SourceUrl="https://github.com/myorg/mygoapp"

# Private repository
osc create eyevinn-golang-runner mygoapp \
  -o SourceUrl="https://github.com/myorg/mygoapp" \
  -o GitHubToken="ghp_..."

# Monorepo with a service in a subdirectory
osc create eyevinn-golang-runner myservice \
  -o SourceUrl="https://github.com/myorg/monorepo" \
  -o SubPath="services/myservice"

Usage Example

A minimal Go application compatible with Golang Runner:

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello from Golang Runner on OSC!")
    })
    http.ListenAndServe(":"+port, nil)
}

Push this to a GitHub repository, then create an instance pointing to that repo. Once running, the instance URL is accessible publicly.

Using a Parameter Store for Configuration

To inject environment variables (secrets, config) at startup without hardcoding them in the repo:

  1. Create an App Config Service instance.
  2. Store your secrets using the OSC parameter store.
  3. Set ConfigService to the App Config Service URL and OscAccessToken to your OSC PAT when creating the Golang Runner instance.

The runner fetches all parameters from the config service on startup and injects them as environment variables.

Resources