forge

README

forge

Have you ever had to swap to using a new CI system? Twice? Three times? Done with searching for a replacement for each Action, CloudBuilder or resource that you were using in your old one? Tired of waiting minutes for feedback on each iteration of figuring out the quirks of your new one?

Forge is here to help.

Forge is a library and CLI for running reusable steps from various proprietary CI systems using a pluggable container runtime. This, for example, makes the functionality provided to GitHub Actions easily consumable (or testable) by users of other CI systems.

Learn more.

Documentation

Index

• Constants
• Variables
• func AzureDevOpsTaskWorkingDir(workingDir string) string
• func CloudBuildWorkingDir(workingDir string) string
• func ConcourseResourceWorkingDir(workingDir string) string
• func GitHubActionPath(workingDir string) string
• func GitHubEnv(workingDir string) string
• func GitHubOutput(workingDir string) string
• func GitHubPath(workingDir string) string
• func GitHubRunnerTmp(workingDir string) string
• func GitHubRunnerToolCache(workingDir string) string
• func GitHubState(workingDir string) string
• func GitHubWorkspace(workingDir string) string
• func InterceptingDockerSock(workingDir string) string
• type Action
  • func (o *Action) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error
• type CloudBuild
  • func (o *CloudBuild) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error
• type Container
• type ContainerConfig
• type ContainerRuntime
• type Hook
  • func (h *Hook[T]) Dispatch(ctx context.Context, t T)
  • func (h *Hook[T]) Listen(f ...func(context.Context, T))
• type Image
• type ImageBuilder
• type Mount
• type Pipe
  • func (o *Pipe) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) (err error)
• type Pure
  • func (o *Pure) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error
• type Resource
  • func (o *Resource) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error
• type RunOpt
  • func WithStdStreams() RunOpt
  • func WithStreams(streams *Streams) RunOpt
• type RunOpts
  • func (o *RunOpts) Apply(opts *RunOpts)
• type Runnable
• type SleepingShimContainer
  • func (c *SleepingShimContainer) Exec(ctx context.Context, cc *ContainerConfig, s *Streams) (int, error)
• type Streams
  • func StdStreams() *Streams
  • func StdTerminalStreams() (*Streams, func() error)
  • func TerminalStreams(stdin io.Reader, stdout, stderr io.Writer) (*Streams, func() error, error)
• type Task
  • func (o *Task) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error

Constants

const (
	DefaultNode10ImageReference = "docker.io/library/node:10"
	DefaultNode12ImageReference = "docker.io/library/node:12"
	DefaultNode16ImageReference = "docker.io/library/node:16"
	DefaultNode20ImageReference = "docker.io/library/node:20"
	DefaultNodeImageReference   = DefaultNode16ImageReference
)

const DefaultDetachKeys = "ctrl-d"

DefaultDetachKeys are the default key combinations to use when detaching from a Container that has been attached to.

Variables

var (
	ShimName   = "shim"
	ScriptName = "script"
)

var (
	// ErrContainerExecutedWithNonzeroExitCode is returned when a container
	// returns an unexpected nonzero exit code. Used with errors.Is to avoid
	// printing this error's text so that os.Exit doesn't double-inform a user
	// of the same nonzero exit code.
	ErrContainerExitedWithNonzeroExitCode = errors.New("container exited with nonzero exit code")
	// ErrCannotBuildDockerfile will be returned when a forge.ContainerRuntime
	// does not implement ImageBuilder.
	ErrCannotBuildDockerfile = errors.New("runtime cannot build Dockerfile")
)

var (
	Node10ImageReference = DefaultNode10ImageReference
	Node12ImageReference = DefaultNode12ImageReference
	Node16ImageReference = DefaultNode16ImageReference
	Node20ImageReference = DefaultNode20ImageReference
	NodeImageReference   = DefaultNodeImageReference
)

var HookContainerStarted = new(Hook[Container])

Functions

func AzureDevOpsTaskWorkingDir

func AzureDevOpsTaskWorkingDir(workingDir string) string

func CloudBuildWorkingDir

func CloudBuildWorkingDir(workingDir string) string

func ConcourseResourceWorkingDir

func ConcourseResourceWorkingDir(workingDir string) string

func GitHubActionPath

func GitHubActionPath(workingDir string) string

func GitHubEnv

func GitHubEnv(workingDir string) string

func GitHubOutput

func GitHubOutput(workingDir string) string

func GitHubPath

func GitHubPath(workingDir string) string

func GitHubRunnerTmp

func GitHubRunnerTmp(workingDir string) string

func GitHubRunnerToolCache

func GitHubRunnerToolCache(workingDir string) string

func GitHubState

func GitHubState(workingDir string) string

func GitHubWorkspace

func GitHubWorkspace(workingDir string) string

func InterceptingDockerSock

func InterceptingDockerSock(workingDir string) string

Types

type Action

type Action struct {
	ID            string
	Uses          string
	With          map[string]string
	Env           map[string]string
	GlobalContext *githubactions.GlobalContext
}

func (*Action) Run

func (o *Action) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error

type CloudBuild

type CloudBuild struct {
	cloudbuild.Step
}

func (*CloudBuild) Run

func (o *CloudBuild) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error

type Container

type Container interface {
	GetID() string
	CopyTo(context.Context, string, io.Reader) error
	CopyFrom(context.Context, string) (io.ReadCloser, error)
	Run(context.Context, *Streams) (int, error)
	Start(context.Context) error
	Restart(context.Context) error
	Exec(context.Context, *ContainerConfig, *Streams) (int, error)
	Stop(context.Context) error
	Remove(context.Context) error
	Kill(context.Context) error
}

Container represents a container created by a ContainerRuntime.

type ContainerConfig

type ContainerConfig struct {
	Entrypoint []string
	Cmd        []string
	WorkingDir string
	Env        []string
	User       string
	Privileged bool
	Mounts     []Mount
}

ContainerConfig is the configuration that is used to create a container or an exec in a running container.

type ContainerRuntime

type ContainerRuntime interface {
	GetContainer(context.Context, string) (Container, error)
	CreateContainer(context.Context, Image, *ContainerConfig) (Container, error)
	PullImage(context.Context, string) (Image, error)
	Close() error
}

ContainerRuntime represents the functionality needed by Runnables to pull OCI images and run containers when being processed.

type Hook

type Hook[T any] struct {
	Listeners []func(context.Context, T)
	sync.Mutex
}

func (*Hook[T]) Dispatch

func (h *Hook[T]) Dispatch(ctx context.Context, t T)

func (*Hook[T]) Listen

func (h *Hook[T]) Listen(f ...func(context.Context, T))

type Image

type Image interface {
	Manifest() (*imagespecsv1.Manifest, error)
	Config() (*imagespecsv1.ImageConfig, error)
	Digest() (digest.Digest, error)
	Blob() io.Reader
	Name() string
}

Image represents a image pulled by a ContainerRuntime. Used to create Containers from.

type ImageBuilder

type ImageBuilder interface {
	BuildDockerfile(context.Context, string, string) (Image, error)
}

ImageBuilder is for a ContainerRuntime to implement building a Dockerfile. Because building an OCI image is not ubiquitous, forge.ContainerRuntimes are not required to implement this, but they may. The default runtime (Docker) happens to so as to support GitHub Actions that run using "docker".

type Mount

type Mount struct {
	Source      string `json:"source,omitempty"`
	Destination string `json:"destination,omitempty"`
}

type Pipe

type Pipe struct {
	From Runnable
	To   Runnable
}

func (*Pipe) Run

func (o *Pipe) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) (err error)

type Pure

type Pure struct {
	Image      string
	Entrypoint []string
	Cmd        []string
	Env        []string
}

func (*Pure) Run

func (o *Pure) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error

type Resource

type Resource struct {
	Method       string
	Version      map[string]any
	Params       map[string]any
	Resource     *concourse.Resource
	ResourceType *concourse.ResourceType
}

func (*Resource) Run

func (o *Resource) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error

type RunOpt

type RunOpt interface {
	Apply(*RunOpts)
}

func WithStdStreams

func WithStdStreams() RunOpt

func WithStreams

func WithStreams(streams *Streams) RunOpt

type RunOpts

type RunOpts struct {
	Streams             *Streams
	Mounts              []Mount
	InterceptDockerSock bool
	WorkingDir          string
}

func (*RunOpts) Apply

func (o *RunOpts) Apply(opts *RunOpts)

type Runnable

type Runnable interface {
	Run(context.Context, ContainerRuntime, ...RunOpt) error
}

type SleepingShimContainer

type SleepingShimContainer struct {
	Container
	WorkingDir          string
	InterceptDockerSock bool
}

func (*SleepingShimContainer) Exec

func (c *SleepingShimContainer) Exec(ctx context.Context, cc *ContainerConfig, s *Streams) (int, error)

type Streams

type Streams struct {
	In         io.Reader
	Out        io.Writer
	Err        io.Writer
	Tty        bool
	DetachKeys string
}

Streams represents streams to and from a process inside of a Container.

func StdStreams

func StdStreams() *Streams

StdStreams returns a Streams consisting of os.Stdin, os.Stdout and os.Stderr.

func StdTerminalStreams

func StdTerminalStreams() (*Streams, func() error)

StdTerminalStreams creates a Streams with os.Stdin, os.Stdout and os.Stderr made raw and a restore function to return them to their previous state. For use with attaching to a shell inside of a Container.

func TerminalStreams

func TerminalStreams(stdin io.Reader, stdout, stderr io.Writer) (*Streams, func() error, error)

TerminalStreams creates a Streams with each of the given streams that is a terminal made raw and a restore function to return them to their previous states. For use with attaching to a shell inside of a Container.

type Task

type Task struct {
	Task      string
	Inputs    map[string]string
	Execution string
}

func (*Task) Run

func (o *Task) Run(ctx context.Context, containerRuntime ContainerRuntime, opts ...RunOpt) error