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
PORTenvironment 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
- Create an App Config Service instance and wait until it is running.
- Store your secrets and settings in its parameter store.
- Set
ConfigServiceto its URL andOscAccessTokento your OSC token (andConfigApiKeyto decrypt secret parameters) when creating the Golang Runner instance.
The runner fetches the parameters at startup and injects them as environment variables.