common

package module
v0.0.0-...-488b487 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 25, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

README

common

A high-performance Go library for parsing environment variables into structs via struct tags, along with pre-defined CI/CD environment variable bindings.

Install

go get codefloe.com/actions/common

Quick Start

env := common.NewEnvironment()
fmt.Println(env.Repo)           // value of CI_REPO
fmt.Println(env.PipelineNumber) // value of CI_PIPELINE_NUMBER
fmt.Println(env)                // JSON representation

ParseEnv

ParseEnv populates any struct from environment variables using the env struct tag. Reflection is performed only once per struct type; subsequent calls use cached field metadata with direct pointer writes for minimal overhead.

type Config struct {
    Host    string        `env:"APP_HOST"`
    Port    int           `env:"APP_PORT"`
    Debug   bool          `env:"APP_DEBUG"`
    Timeout time.Duration `env:"APP_TIMEOUT"`
    Workers *int          `env:"APP_WORKERS"`
    Tags    []string      `env:"APP_TAGS"`
}

var cfg Config
common.ParseEnv(&cfg)
Supported Types
Type Format Example
string any string hello
bool true/false/1/0 true
int, int8 .. int64 decimal integer -42
uint, uint8 .. uint64 decimal unsigned integer 42
float32, float64 decimal float 3.14
time.Duration Go duration string 5s, 100ms
[]string comma-separated, optional brackets a,b,c or [a,b,c]
Pointer Types

Pointer variants of all basic types above are supported. This allows distinguishing between "not set" and "zero value":

type Config struct {
    Debug   bool   `env:"DEBUG"`   // unset -> false
    Verbose *bool  `env:"VERBOSE"` // unset -> nil

    Port    int    `env:"PORT"`    // unset -> 0
    Workers *int   `env:"WORKERS"` // unset -> nil
}
Field type Env var not set Env var set
T (value) zero value ("", false, 0) parsed value
*T (pointer) nil pointer to parsed value
[]string Formats

All three formats are accepted:

APP_TAGS=single
APP_TAGS=a,b,c
APP_TAGS=[a,b,c]
Embedded Structs

Anonymous (embedded) struct fields are traversed automatically:

type Base struct {
    Name string `env:"APP_NAME"`
}

type Config struct {
    Base
    Port int `env:"APP_PORT"`
}

var cfg Config
common.ParseEnv(&cfg)
// cfg.Name is populated from APP_NAME
Behavior Notes
  • Fields without an env tag or with env:"-" are skipped.
  • If an environment variable is not set (os.LookupEnv returns false), the field is left untouched.
  • If an environment variable is set but cannot be parsed (e.g. "abc" for an int field), the field retains its zero value.

CI Environment

NewEnvironment() returns a fully populated *Environment struct covering standard CI/CD variables:

Group Prefix Examples
General CI_ CI, CI_WORKSPACE, CI_REPO, CI_REPO_PRIVATE
Commit CI_COMMIT_ CI_COMMIT_SHA, CI_COMMIT_BRANCH, CI_COMMIT_TAG
Pipeline CI_PIPELINE_ CI_PIPELINE_NUMBER, CI_PIPELINE_EVENT, CI_PIPELINE_URL
Workflow CI_WORKFLOW_ CI_WORKFLOW_NAME
Previous Commit CI_PREV_COMMIT_ CI_PREV_COMMIT_SHA, CI_PREV_COMMIT_BRANCH
Previous Pipeline CI_PREV_PIPELINE_ CI_PREV_PIPELINE_NUMBER, CI_PREV_PIPELINE_STATUS
System CI_SYSTEM_ CI_SYSTEM_NAME, CI_SYSTEM_URL, CI_SYSTEM_VERSION
Forge CI_FORGE_ CI_FORGE_TYPE, CI_FORGE_URL

Performance

Struct metadata is compiled once via reflection and cached per type. On the hot path, ParseEnv uses pre-computed field offsets with unsafe.Pointer arithmetic -- no reflection calls occur after the first invocation.

BenchmarkParseEnv-20    ~340,000 iter    ~3.3 us/op    1104 B/op    3 allocs/op

The 3 allocations come from []string fields (PipelineEvent, PipelineFiles) split via strings.Split. All scalar field writes are zero-allocation.

License

Apache License 2.0. See LICENSE for details.

Documentation

Index

Constants

View Source 
const (
	DefaultEndpoint = "https://codefloe.com"
)

Variables

This section is empty.

Functions

func Error 

func Error(format string, args ...any)

func Fatal 

func Fatal(format string, args ...any)

func Info 

func Info(format string, args ...any)

func ParseEnv 

func ParseEnv(dst any)

ParseEnv reads environment variables and populates struct fields tagged with `env:"VAR_NAME"`. The argument must be a non-nil pointer to a struct. Slice fields ([]string) are split by comma.

Types

type CommitEnvironment 

type CommitEnvironment struct {
	CommitSHA               string `env:"CI_COMMIT_SHA" json:"CI_COMMIT_SHA"`
	CommitRef               string `env:"CI_COMMIT_REF" json:"CI_COMMIT_REF"`
	CommitRefSpec           string `env:"CI_COMMIT_REF_SPEC" json:"CI_COMMIT_REF_SPEC"`
	CommitBranch            string `env:"CI_COMMIT_BRANCH" json:"CI_COMMIT_BRANCH"`
	CommitSourceBranch      string `env:"CI_COMMIT_SOURCE_BRANCH" json:"CI_COMMIT_SOURCE_BRANCH"`
	CommitTargetBranch      string `env:"CI_COMMIT_TARGET_BRANCH" json:"CI_COMMIT_TARGET_BRANCH"`
	CommitTag               string `env:"CI_COMMIT_TAG" json:"CI_COMMIT_TAG"`
	CommitPullRequest       int64  `env:"CI_COMMIT_PULL_REQUEST" json:"CI_COMMIT_PULL_REQUEST"`
	CommitPullRequestLabels string `env:"CI_COMMIT_PULL_REQUEST_LABELS" json:"CI_COMMIT_PULL_REQUEST_LABELS"`
	CommitMessage           string `env:"CI_COMMIT_MESSAGE" json:"CI_COMMIT_MESSAGE"`
	CommitAuthor            string `env:"CI_COMMIT_AUTHOR" json:"CI_COMMIT_AUTHOR"`
	CommitAuthorEmail       string `env:"CI_COMMIT_AUTHOR_EMAIL" json:"CI_COMMIT_AUTHOR_EMAIL"`
	CommitPrerelease        bool   `env:"CI_COMMIT_PRERELEASE" json:"CI_COMMIT_PRERELEASE"`
}

type Environment 

type Environment struct {
	GeneralEnvironment
	CommitEnvironment
	PipelineEnvironment
	WorkflowEnvironment
	PreviousCommitEnvironment
	PreviousPipelineEnvironment
	SystemEnvironment
	ForgeEnvironment
}

func NewEnvironment 

func NewEnvironment() *Environment

func (Environment) String 

func (c Environment) String() string

type ForgeEnvironment 

type ForgeEnvironment struct {
	ForgeType string `env:"CI_FORGE_TYPE" json:"CI_FORGE_TYPE"`
	ForgeURL  string `env:"CI_FORGE_URL" json:"CI_FORGE_URL"`
}

type GeneralEnvironment 

type GeneralEnvironment struct {
	CI                  string `env:"CI" json:"CI"`
	Workspace           string `env:"CI_WORKSPACE" json:"CI_WORKSPACE"`
	Repo                string `env:"CI_REPO" json:"CI_REPO"`
	RepoOwner           string `env:"CI_REPO_OWNER" json:"CI_REPO_OWNER"`
	RepoName            string `env:"CI_REPO_NAME" json:"CI_REPO_NAME"`
	RepoRemoteID        string `env:"CI_REPO_REMOTE_ID" json:"CI_REPO_REMOTE_ID"`
	RepoURL             string `env:"CI_REPO_URL" json:"CI_REPO_URL"`
	RepoCloneURL        string `env:"CI_REPO_CLONE_URL" json:"CI_REPO_CLONE_URL"`
	RepoCloneSSHURL     string `env:"CI_REPO_CLONE_SSH_URL" json:"CI_REPO_CLONE_SSH_URL"`
	RepoDefaultBranch   string `env:"CI_REPO_DEFAULT_BRANCH" json:"CI_REPO_DEFAULT_BRANCH"`
	RepoPrivate         bool   `env:"CI_REPO_PRIVATE" json:"CI_REPO_PRIVATE"`
	RepoTrustedNetwork  bool   `env:"CI_REPO_TRUSTED_NETWORK" json:"CI_REPO_TRUSTED_NETWORK"`
	RepoTrustedVolumes  bool   `env:"CI_REPO_TRUSTED_VOLUMES" json:"CI_REPO_TRUSTED_VOLUMES"`
	RepoTrustedSecurity bool   `env:"CI_REPO_TRUSTED_SECURITY" json:"CI_REPO_TRUSTED_SECURITY"`
}

type PipelineEnvironment 

type PipelineEnvironment struct {
	PipelineNumber       int64    `env:"CI_PIPELINE_NUMBER" json:"CI_PIPELINE_NUMBER"`
	PipelineParent       int64    `env:"CI_PIPELINE_PARENT" json:"CI_PIPELINE_PARENT"`
	PipelineEvent        []string `env:"CI_PIPELINE_EVENT" json:"CI_PIPELINE_EVENT"`
	PipelineURL          string   `env:"CI_PIPELINE_URL" json:"CI_PIPELINE_URL"`
	PipelineForgeURL     string   `env:"CI_PIPELINE_FORGE_URL" json:"CI_PIPELINE_FORGE_URL"`
	PipelineDeployTarget string   `env:"CI_PIPELINE_DEPLOY_TARGET" json:"CI_PIPELINE_DEPLOY_TARGET"`
	PipelineDeployTask   string   `env:"CI_PIPELINE_DEPLOY_TASK" json:"CI_PIPELINE_DEPLOY_TASK"`
	PipelineCreated      int64    `env:"CI_PIPELINE_CREATED" json:"CI_PIPELINE_CREATED"`
	PipelineStarted      int64    `env:"CI_PIPELINE_STARTED" json:"CI_PIPELINE_STARTED"`
	PipelineFiles        []string `env:"CI_PIPELINE_FILES" json:"CI_PIPELINE_FILES"`
	PipelineAuthor       string   `env:"CI_PIPELINE_AUTHOR" json:"CI_PIPELINE_AUTHOR"`
	PipelineAvatar       string   `env:"CI_PIPELINE_AVATAR" json:"CI_PIPELINE_AVATAR"`
}

type PreviousCommitEnvironment 

type PreviousCommitEnvironment struct {
	PreviousCommitSHA          string `env:"CI_PREV_COMMIT_SHA" json:"CI_PREV_COMMIT_SHA"`
	PreviousCommitRef          string `env:"CI_PREV_COMMIT_REF" json:"CI_PREV_COMMIT_REF"`
	PreviousCommitRefSpec      string `env:"CI_PREV_COMMIT_REFSPEC" json:"CI_PREV_COMMIT_REFSPEC"`
	PreviousCommitBranch       string `env:"CI_PREV_COMMIT_BRANCH" json:"CI_PREV_COMMIT_BRANCH"`
	PreviousCommitSourceBranch string `env:"CI_PREV_COMMIT_SOURCE_BRANCH" json:"CI_PREV_COMMIT_SOURCE_BRANCH"`
	PreviousCommitTargetBranch string `env:"CI_PREV_COMMIT_TARGET_BRANCH" json:"CI_PREV_COMMIT_TARGET_BRANCH"`
	PreviousCommitURL          string `env:"CI_PREV_COMMIT_URL" json:"CI_PREV_COMMIT_URL"`
	PreviousCommitMessage      string `env:"CI_PREV_COMMIT_MESSAGE" json:"CI_PREV_COMMIT_MESSAGE"`
	PreviousCommitAuthor       string `env:"CI_PREV_COMMIT_AUTHOR" json:"CI_PREV_COMMIT_AUTHOR"`
	PreviousCommitAuthorEmail  string `env:"CI_PREV_COMMIT_AUTHOR_EMAIL" json:"CI_PREV_COMMIT_AUTHOR_EMAIL"`
}

type PreviousPipelineEnvironment 

type PreviousPipelineEnvironment struct {
	PreviousPipelineNumber       int64    `env:"CI_PREV_PIPELINE_NUMBER" json:"CI_PREV_PIPELINE_NUMBER"`
	PreviousPipelineParent       int64    `env:"CI_PREV_PIPELINE_PARENT" json:"CI_PREV_PIPELINE_PARENT"`
	PreviousPipelineEvent        []string `env:"CI_PREV_PIPELINE_EVENT" json:"CI_PREV_PIPELINE_EVENT"`
	PreviousPipelineURL          string   `env:"CI_PREV_PIPELINE_URL" json:"CI_PREV_PIPELINE_URL"`
	PreviousPipelineForgeURL     string   `env:"CI_PREV_PIPELINE_FORGE_URL" json:"CI_PREV_PIPELINE_FORGE_URL"`
	PreviousPipelineDeployTarget string   `env:"CI_PREV_PIPELINE_DEPLOY_TARGET" json:"CI_PREV_PIPELINE_DEPLOY_TARGET"`
	PreviousPipelineDeployTask   string   `env:"CI_PREV_PIPELINE_DEPLOY_TASK" json:"CI_PREV_PIPELINE_DEPLOY_TASK"`
	PreviousPipelineStatus       string   `env:"CI_PREV_PIPELINE_STATUS" json:"CI_PREV_PIPELINE_STATUS"`
	PreviousPipelineCreated      int64    `env:"CI_PREV_PIPELINE_CREATED" json:"CI_PREV_PIPELINE_CREATED"`
	PreviousPipelineStarted      int64    `env:"CI_PREV_PIPELINE_STARTED" json:"CI_PREV_PIPELINE_STARTED"`
	PreviousPipelineFinished     int64    `env:"CI_PREV_PIPELINE_FINISHED" json:"CI_PREV_PIPELINE_FINISHED"`
	PreviousPipelineAuthor       string   `env:"CI_PREV_PIPELINE_AUTHOR" json:"CI_PREV_PIPELINE_AUTHOR"`
	PreviousPipelineAvatar       string   `env:"CI_PREV_PIPELINE_AVATAR" json:"CI_PREV_PIPELINE_AVATAR"`
}

type SystemEnvironment 

type SystemEnvironment struct {
	SystemName    string `env:"CI_SYSTEM_NAME" json:"CI_SYSTEM_NAME"`
	SystemURL     string `env:"CI_SYSTEM_URL" json:"CI_SYSTEM_URL"`
	SystemHost    string `env:"CI_SYSTEM_HOST" json:"CI_SYSTEM_HOST"`
	SystemVersion string `env:"CI_SYSTEM_VERSION" json:"CI_SYSTEM_VERSION"`
}

type WorkflowEnvironment 

type WorkflowEnvironment struct {
	WorkflowName string `env:"CI_WORKFLOW_NAME" json:"CI_WORKFLOW_NAME"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.