Service: Golang Runner - EyevinnOSC/community GitHub Wiki

Golang Runner

Golang Runner (serviceId eyevinn-golang-runner, OSC dashboard) builds and runs Go applications directly from a Git repository. You provide a source URL to a Go project; OSC clones the repo, compiles the binary and serves it as an HTTP service, with no Docker knowledge required. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. It is the Go counterpart to Web Runner (Node.js) and Python Runner.

What it can do

  • Clone a public or private Git repository (optionally a specific branch or a monorepo subdirectory) and build the Go application it contains.
  • Auto-detect the main package, or use a custom build command and binary path.
  • Produce fully static binaries by default (CGO disabled), or enable CGO when needed.
  • Load environment variables and secrets at startup from an App Config Service instance.

Creating an instance

Find the id with list-available-services, read the options with get-service-schema, then call create-service-instance with serviceId: "eyevinn-golang-runner". The instance name must be alphanumeric and at most 20 characters. No other OSC service is required; an App Config Service instance is only needed if you want to load configuration at startup.

{ "name": "mygoapp", "SourceUrl": "https://github.com/myorg/mygoapp" }

Private repository, with the token stored as a service secret (create-service-secret, serviceId eyevinn-golang-runner):

{ "name": "mygoapp", "SourceUrl": "https://github.com/myorg/mygoapp", "GitHubToken": "{{secrets.ghtoken}}" }

Confirm it runs with wait-for-service-ready or get-instance-status; use describe-service-instance for the URL and get-logs-for-instance to inspect the build and run output.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
SourceUrl Yes string HTTPS URL of the Git repository to clone and build. Append #branchname for a specific branch, for example https://github.com/your-org/your-go-app#feat/new-api. Takes precedence over GITHUB_URL if both are set.
GitHubToken No string, sensitive Personal access token for cloning private repositories; injected into the clone URL. Used as a fallback if GIT_TOKEN is not provided.
OscAccessToken No string, sensitive OSC token used to authenticate with the config service to load environment variables at startup. Needs ConfigService to be set as well.
ConfigService No string URL of the OSC config service (an App Config Service instance) to load environment variables from at startup. Both OscAccessToken and ConfigService must be set for the integration to work.
ConfigApiKey No string, sensitive API key used to decrypt secret parameters from the parameter store before they are injected as environment variables. Set it together with OscAccessToken and ConfigService.
SubPath No string Subdirectory of the cloned repository to use as build root, for monorepos. Example: services/my-service.
OscBuildCmd No string Custom build command that overrides auto-detection. Example: go build -tags netgo -o /app/server ./cmd/api.
OscEntry No string Path of the binary to run after the build. Default /app/server. Use it when your build command outputs the binary elsewhere.
CGoEnabled No string Set to 1 to enable CGO (allows calling C code, needs gcc, increases image size). Default 0, which produces fully static binaries. With 1 you typically also set OscBuildCmd, for example CGO_ENABLED=1 go build -o /app/server ..

Sensitive options should be stored as service secrets and passed as {{secrets.NAME}}, which only works as the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

Application requirements

  • The app must read its listening port from the PORT environment variable (OSC injects it).
  • It must be buildable with go build.

Build detection

Without OscBuildCmd the runner tries, in order: cmd/server/main.go, cmd/*/main.go (first match), main.go, then falls back to go build ./....

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"

Minimal compatible application

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 it to a repository and create an instance pointing to it.

Configuration from a parameter store

  1. Create an App Config Service instance and wait until it is running.
  2. Store your secrets and settings in its parameter store.
  3. Set ConfigService to its URL and OscAccessToken to your OSC token (and ConfigApiKey to decrypt secret parameters) when creating the Golang Runner instance.

The runner fetches the parameters at startup and injects them as environment variables.

Resources