githubactions

package module
Version: v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2022 License: Apache-2.0 Imports: 13 Imported by: 56

README

GitHub Actions SDK (Go)

GoDoc GitHub Actions

This library provides an SDK for authoring GitHub Actions in Go. It has no external dependencies and provides a Go-like interface for interacting with GitHub Actions' build system.

Installation

Download the library:

$ go get -u github.com/sethvargo/go-githubactions/...

Usage

The easiest way to use the library is by importing it and invoking the functions at the root:

import (
  "github.com/sethvargo/go-githubactions"
)

func main() {
  val := githubactions.GetInput("val")
  if val == "" {
    githubactions.Fatalf("missing 'val'")
  }
}

You can also create an instance with custom fields that will be included in log messages:

import (
  "github.com/sethvargo/go-githubactions"
)

func main() {
  actions := githubactions.WithFieldsMap(map[string]string{
    "file": "myfile.js",
    "line": "100",
  })

  val := actions.GetInput("val")
  if val == "" {
    actions.Fatalf("missing 'val'")
  }
}

For more examples and API documentation, please see the Go docs.

Publishing

There are multiple ways to publish GitHub Actions written in Go:

By default, GitHub Actions expects actions to be written in Node.js. For other languages like Go, you need to provide a Dockerfile and entrypoint instructions in an action.yml file:

# your-repo/Dockerfile
FROM golang:1.18
RUN go build -o /bin/app .
ENTRYPOINT ["/bin/app"]

# your-repo/action.yml
name: My action
author: My name
description: My description

runs:
  using: docker
  image: Dockerfile

And then users can import your action by the repository name:

# their-repo/.github/workflows/thing.yml
steps:
- name: My action
  uses: username/repo@latest

However, this will clone the entire repo and compile the Go code each time the action runs. Worse, it uses the Go base container which is a few hundred MBs and includes a ton of unnecessary things.

Fortunately, GitHub Actions can also source from a Docker container directly from Docker Hub:

steps:
- name: My action
  uses: docker://username/repo:latest

Now we can precompile and publish our Go Action as a Docker container, but we need to make it much, much smaller first. This can be achieved using multi-stage Docker builds:

FROM golang:1.18 AS builder

ENV GO111MODULE=on \
  CGO_ENABLED=0 \
  GOOS=linux \
  GOARCH=amd64

RUN apt-get -qq update && \
  apt-get -yqq install upx

WORKDIR /src
COPY . .

RUN go build \
  -ldflags "-s -w -extldflags '-static'" \
  -o /bin/app \
  . \
  && strip /bin/app \
  && upx -q -9 /bin/app

RUN echo "nobody:x:65534:65534:Nobody:/:" > /etc_passwd



FROM scratch

COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /etc_passwd /etc/passwd
COPY --from=builder --chown=65534:0 /bin/app /app

USER nobody
ENTRYPOINT ["/app"]

The first step, uses a fat container to build, strip, and compress the compiled Go binary. Then, in the second step, the compiled and compressed binary is copied into a scratch (bare) container along with some SSL certificates and a nobody user in which to execute the container.

This will usually produce an image that is less than 10MB in size, making for much faster builds.

Documentation

Overview

Package githubactions provides an SDK for authoring GitHub Actions in Go. It has no external dependencies and provides a Go-like interface for interacting with GitHub Actions' build system.

Index

Examples

Constants

View Source 
const EOF = "\n"

Variables

This section is empty.

Functions

func AddMask 

func AddMask(p string)

AddMask adds a new field mask for the given string "p". After called, future attempts to log "p" will be replaced with "***" in log output.

func AddMatcher 

func AddMatcher(p string)

AddMatcher adds a new matcher with the given file path.

func AddPath 

func AddPath(p string)

AddPath adds the string "p" to the path for the invocation.

func AddStepSummary added in v1.0.0 

func AddStepSummary(markdown string)

AddStepSummary writes the given markdown to the job summary. If a job summary already exists, this value is appended.

func AddStepSummaryTemplate added in v1.0.0 

func AddStepSummaryTemplate(tmpl string, data any) error

AddStepSummaryTemplate adds a summary template by parsing the given Go template using html/template with the given input data. See AddStepSummary for caveats.

This primarily exists as a convenience function that renders a template.

func Debugf 

func Debugf(msg string, args ...any)

Debugf prints a debug-level message. The arguments follow the standard Printf arguments.

func EndGroup 

func EndGroup()

EndGroup ends the current group.

func Errorf 

func Errorf(msg string, args ...any)

Errorf prints a error-level message. The arguments follow the standard Printf arguments.

func Fatalf 

func Fatalf(msg string, args ...any)

Fatalf prints a error-level message and exits. This is equivalent to Errorf followed by os.Exit(1).

func GetIDToken added in v0.5.0 

func GetIDToken(ctx context.Context, audience string) (string, error)

GetIDToken returns the GitHub OIDC token from the GitHub Actions runtime.

func GetInput 

func GetInput(i string) string

GetInput gets the input by the given name.

func Group 

func Group(t string)

Group starts a new collapsable region up to the next ungroup invocation.

func Infof added in v0.4.0 

func Infof(msg string, args ...any)

Infof prints a info-level message. The arguments follow the standard Printf arguments.

func IssueCommand added in v0.3.0 

func IssueCommand(cmd *Command)

IssueCommand issues an arbitrary GitHub actions Command.

func IssueFileCommand added in v0.3.0 

func IssueFileCommand(cmd *Command)

IssueFileCommand issues a new GitHub actions Command using environment files.

func Noticef added in v1.1.0 

func Noticef(msg string, args ...any)

Noticef prints a notice-level message. The arguments follow the standard Printf arguments.

func RemoveMatcher 

func RemoveMatcher(o string)

RemoveMatcher removes a matcher with the given owner name.

func SaveState 

func SaveState(k, v string)

SaveState saves state to be used in the "finally" post job entry point.

func SetEnv 

func SetEnv(k, v string)

SetEnv sets an environment variable.

func SetOutput 

func SetOutput(k, v string)

SetOutput sets an output parameter.

func Warningf 

func Warningf(msg string, args ...any)

Warningf prints a warning-level message. The arguments follow the standard Printf arguments.

Types

type Action 

type Action struct {
	// contains filtered or unexported fields
}

Action is an internal wrapper around GitHub Actions' output and magic strings.

func New 

func New(opts ...Option) *Action

New creates a new wrapper with helpers for outputting information in GitHub actions format.

Example 
a = githubactions.New()

Output:

func WithFieldsMap 

func WithFieldsMap(m map[string]string) *Action

WithFieldsMap includes the provided fields in log output. The fields in "m" are automatically converted to k=v pairs and sorted.

func WithFieldsSlice 

func WithFieldsSlice(f []string) *Action

WithFieldsSlice includes the provided fields in log output. "f" must be a slice of k=v pairs. The given slice will be sorted.

func (*Action) AddMask 

func (c *Action) AddMask(p string)

AddMask adds a new field mask for the given string "p". After called, future attempts to log "p" will be replaced with "***" in log output. It panics if it cannot write to the output stream.

Example 
a := githubactions.New()
a.AddMask("my-password")

Output:

func (*Action) AddMatcher 

func (c *Action) AddMatcher(p string)

AddMatcher adds a new matcher with the given file path. It panics if it cannot write to the output stream.

func (*Action) AddPath 

func (c *Action) AddPath(p string)

AddPath adds the string "p" to the path for the invocation. It panics if it cannot write to the output file.

https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#adding-a-system-path https://github.blog/changelog/2020-10-01-github-actions-deprecating-set-env-and-add-path-commands/

Example 
a := githubactions.New()
a.AddPath("/tmp/myapp")

Output:

func (*Action) AddStepSummary added in v1.0.0 

func (c *Action) AddStepSummary(markdown string)

AddStepSummary writes the given markdown to the job summary. If a job summary already exists, this value is appended.

https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/

Example 
a := githubactions.New()
a.AddStepSummary(`
## Heading

- :rocket:
- :moon:
`)

Output:

func (*Action) AddStepSummaryTemplate added in v1.0.0 

func (c *Action) AddStepSummaryTemplate(tmpl string, data any) error

AddStepSummaryTemplate adds a summary template by parsing the given Go template using html/template with the given input data. See AddStepSummary for caveats.

This primarily exists as a convenience function that renders a template.

Example 
a := githubactions.New()
if err := a.AddStepSummaryTemplate(`
## Heading

- {{.Input}}
- :moon:
`, map[string]string{
	"Input": ":rocket:",
}); err != nil {
	// handle error
}

Output:

func (*Action) Context added in v1.0.0 

func (c *Action) Context() (*GitHubContext, error)

Context returns the context of current action with the payload object that triggered the workflow

func (*Action) Debugf 

func (c *Action) Debugf(msg string, args ...any)

Debugf prints a debug-level message. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.

Example 
a := githubactions.New()
a.Debugf("a debug message")

Output:
Example (FieldsMap) 
a := githubactions.New()
m := map[string]string{
	"file": "app.go",
	"line": "100",
}
a.WithFieldsMap(m).Debugf("a debug message")

Output:
Example (FieldsSlice) 
a := githubactions.New()
s := []string{"file=app.go", "line=100"}
a.WithFieldsSlice(s).Debugf("a debug message")

Output:

func (*Action) EndGroup 

func (c *Action) EndGroup()

EndGroup ends the current group. It panics if it cannot write to the output stream.

Example 
a := githubactions.New()
a.Group("My group")

// work

a.EndGroup()

Output:

func (*Action) Errorf 

func (c *Action) Errorf(msg string, args ...any)

Errorf prints a error-level message. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.

Example 
a := githubactions.New()
a.Errorf("an error message")

Output:
Example (FieldsMap) 
a := githubactions.New()
m := map[string]string{
	"file": "app.go",
	"line": "100",
}
a.WithFieldsMap(m).Errorf("an error message")

Output:
Example (FieldsSlice) 
a := githubactions.New()
s := []string{"file=app.go", "line=100"}
a.WithFieldsSlice(s).Errorf("an error message")

Output:

func (*Action) Fatalf 

func (c *Action) Fatalf(msg string, args ...any)

Fatalf prints a error-level message and exits. This is equivalent to Errorf followed by os.Exit(1).

func (*Action) GetIDToken added in v0.5.0 

func (c *Action) GetIDToken(ctx context.Context, audience string) (string, error)

GetIDToken returns the GitHub OIDC token from the GitHub Actions runtime.

Example 
ctx := context.Background()

a := githubactions.New()
token, err := a.GetIDToken(ctx, "my-aud")
if err != nil {
	// handle error
}
_ = token

Output:

func (*Action) GetInput 

func (c *Action) GetInput(i string) string

GetInput gets the input by the given name. It returns the empty string if the input is not defined.

Example 
a := githubactions.New()
a.GetInput("foo")

Output:

func (*Action) Getenv added in v0.5.3 

func (c *Action) Getenv(key string) string

Getenv retrieves the value of the environment variable named by the key. It uses an internal function that can be set with `WithGetenv`.

func (*Action) Group 

func (c *Action) Group(t string)

Group starts a new collapsable region up to the next ungroup invocation. It panics if it cannot write to the output stream.

Example 
a := githubactions.New()
a.Group("My group")

Output:

func (*Action) Infof added in v0.4.0 

func (c *Action) Infof(msg string, args ...any)

Infof prints message to stdout without any level annotations. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.

func (*Action) IssueCommand added in v0.3.0 

func (c *Action) IssueCommand(cmd *Command)

IssueCommand issues a new GitHub actions Command. It panics if it cannot write to the output stream.

func (*Action) IssueFileCommand added in v0.3.0 

func (c *Action) IssueFileCommand(cmd *Command)

IssueFileCommand issues a new GitHub actions Command using environment files. It panics if writing to the file fails.

https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#environment-files

The TypeScript equivalent function:

https://github.com/actions/toolkit/blob/4f7fb6513a355689f69f0849edeb369a4dc81729/packages/core/src/file-command.ts#L10-L23

IssueFileCommand currently ignores the 'CommandProperties' field provided with the 'Command' argument as it's scope is unclear in the current TypeScript implementation.

func (*Action) Noticef added in v0.5.1 

func (c *Action) Noticef(msg string, args ...any)

Noticef prints a notice-level message. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.

func (*Action) RemoveMatcher 

func (c *Action) RemoveMatcher(o string)

RemoveMatcher removes a matcher with the given owner name. It panics if it cannot write to the output stream.

func (*Action) SaveState 

func (c *Action) SaveState(k, v string)

SaveState saves state to be used in the "finally" post job entry point. It panics if it cannot write to the output stream.

On 2022-10-11, GitHub deprecated "::save-state name=<k>::<v>" in favor of environment files.

func (*Action) SetEnv 

func (c *Action) SetEnv(k, v string)

SetEnv sets an environment variable. It panics if it cannot write to the output file.

https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable https://github.blog/changelog/2020-10-01-github-actions-deprecating-set-env-and-add-path-commands/

Example 
a := githubactions.New()
a.SetEnv("MY_THING", "my value")

Output:

func (*Action) SetOutput 

func (c *Action) SetOutput(k, v string)

SetOutput sets an output parameter. It panics if it cannot write to the output stream.

On 2022-10-11, GitHub deprecated "::set-output name=<k>::<v>" in favor of environment files.

Example 
a := githubactions.New()
a.SetOutput("filepath", "/tmp/file-xyz1234")

Output:

func (*Action) Warningf 

func (c *Action) Warningf(msg string, args ...any)

Warningf prints a warning-level message. It follows the standard fmt.Printf arguments, appending an OS-specific line break to the end of the message. It panics if it cannot write to the output stream.

Example 
a := githubactions.New()
a.Warningf("a warning message")

Output:
Example (FieldsMap) 
a := githubactions.New()
m := map[string]string{
	"file": "app.go",
	"line": "100",
}
a.WithFieldsMap(m).Warningf("a warning message")

Output:
Example (FieldsSlice) 
a := githubactions.New()
s := []string{"file=app.go", "line=100"}
a.WithFieldsSlice(s).Warningf("a warning message")

Output:

func (*Action) WithFieldsMap 

func (c *Action) WithFieldsMap(m map[string]string) *Action

WithFieldsMap includes the provided fields in log output. The fields in "m" are automatically converted to k=v pairs and sorted.

func (*Action) WithFieldsSlice 

func (c *Action) WithFieldsSlice(f []string) *Action

WithFieldsSlice includes the provided fields in log output. "f" must be a slice of k=v pairs. The given slice will be sorted. It panics if any of the string in the given slice does not construct a valid 'key=value' pair.

type Command added in v0.3.0 

type Command struct {
	Name       string
	Message    string
	Properties CommandProperties
}

Command can be issued by a GitHub action by writing to `stdout` with following format.

::name key=value,key=value::message 

Examples:
  ::warning::This is the message
  ::set-env name=MY_VAR::some value

func (*Command) String added in v0.3.0 

func (cmd *Command) String() string

String encodes the Command to a string in the following format:

::name key=value,key=value::message

type CommandProperties added in v0.3.0 

type CommandProperties map[string]string

CommandProperties is a named "map[string]string" type to hold key-value pairs passed to an actions command.

func (*CommandProperties) String added in v0.3.0 

func (props *CommandProperties) String() string

String encodes the CommandProperties to a string as comma separated 'key=value' pairs. The pairs are joined in a chronological order.

type GetenvFunc added in v0.4.0 

type GetenvFunc func(key string) string

GetenvFunc is an abstraction to make tests feasible for commands that interact with environment variables.

type GitHubContext added in v1.0.0 

type GitHubContext struct {
	Action           string `env:"GITHUB_ACTION"`
	ActionPath       string `env:"GITHUB_ACTION_PATH"`
	ActionRepository string `env:"GITHUB_ACTION_REPOSITORY"`
	Actions          bool   `env:"GITHUB_ACTIONS"`
	Actor            string `env:"GITHUB_ACTOR"`
	APIURL           string `env:"GITHUB_API_URL,default=https://api.github.com"`
	BaseRef          string `env:"GITHUB_BASE_REF"`
	Env              string `env:"GITHUB_ENV"`
	EventName        string `env:"GITHUB_EVENT_NAME"`
	EventPath        string `env:"GITHUB_EVENT_PATH"`
	GraphqlURL       string `env:"GITHUB_GRAPHQL_URL,default=https://api.github.com/graphql"`
	HeadRef          string `env:"GITHUB_HEAD_REF"`
	Job              string `env:"GITHUB_JOB"`
	Path             string `env:"GITHUB_PATH"`
	Ref              string `env:"GITHUB_REF"`
	RefName          string `env:"GITHUB_REF_NAME"`
	RefProtected     bool   `env:"GITHUB_REF_PROTECTED"`
	RefType          string `env:"GITHUB_REF_TYPE"`

	// Repository is the owner and repository name. For example, octocat/Hello-World
	// It is not recommended to use this field to acquire the repository name
	// but to use the Repo method instead.
	Repository string `env:"GITHUB_REPOSITORY"`

	// RepositoryOwner is the repository owner. For example, octocat
	// It is not recommended to use this field to acquire the repository owner
	// but to use the Repo method instead.
	RepositoryOwner string `env:"GITHUB_REPOSITORY_OWNER"`

	RetentionDays int64  `env:"GITHUB_RETENTION_DAYS"`
	RunAttempt    int64  `env:"GITHUB_RUN_ATTEMPT"`
	RunID         int64  `env:"GITHUB_RUN_ID"`
	RunNumber     int64  `env:"GITHUB_RUN_NUMBER"`
	ServerURL     string `env:"GITHUB_SERVER_URL,default=https://github.com"`
	SHA           string `env:"GITHUB_SHA"`
	StepSummary   string `env:"GITHUB_STEP_SUMMARY"`
	Workflow      string `env:"GITHUB_WORKFLOW"`
	Workspace     string `env:"GITHUB_WORKSPACE"`

	// Event is populated by parsing the file at EventPath, if it exists.
	Event map[string]any
}

GitHubContext of current workflow.

See: https://docs.github.com/en/actions/learn-github-actions/environment-variables

func Context added in v1.0.0 

func Context() (*GitHubContext, error)

func (*GitHubContext) Repo added in v1.1.0 

func (c *GitHubContext) Repo() (string, string)

Repo returns the username of the repository owner and repository name.

type Option added in v0.4.0 

type Option func(*Action) *Action

Option is a modifier for an Action.

func WithFields added in v0.4.0 

func WithFields(fields CommandProperties) Option

WithFields sets the extra command field on an Action.

func WithGetenv added in v0.4.0 

func WithGetenv(getenv GetenvFunc) Option

WithGetenv sets the `Getenv` function on an Action. By default, this will be `os.Getenv` from the standard library.

func WithHTTPClient added in v0.5.0 

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets a custom HTTP client on the action. This is only used when the action makes output HTTP requests (such as generating an OIDC token).

func WithWriter added in v0.4.0 

func WithWriter(w io.Writer) Option

WithWriter sets the writer function on an Action. By default, this will be `os.Stdout` from the standard library.

Source Files

View all

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL