Oct 20, 2020
README
GitHub Actions SDK (Go)
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
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:
# Dockerfile
FROM golang:1.13
RUN go build -o /bin/app .
ENTRYPOINT ["/bin/app"]
# 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:
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.13 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 \
-a \
-ldflags "-s -w -extldflags '-static'" \
-installsuffix cgo \
-tags netgo \
-mod vendor \
-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 < 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 ¶
- func AddMask(p string)
- func AddMatcher(p string)
- func AddPath(p string)
- func Debugf(msg string, args ...interface{})
- func EndGroup()
- func Errorf(msg string, args ...interface{})
- func Fatalf(msg string, args ...interface{})
- func GetInput(i string) string
- func Group(t string)
- func IssueCommand(cmd *Command)
- func IssueFileCommand(cmd *Command) error
- func RemoveMatcher(o string)
- func SaveState(k, v string)
- func SetEnv(k, v string)
- func SetOutput(k, v string)
- func Warningf(msg string, args ...interface{})
- type Action
- func (c *Action) AddMask(p string)
- func (c *Action) AddMatcher(p string)
- func (c *Action) AddPath(p string)
- func (c *Action) Debugf(msg string, args ...interface{})
- func (c *Action) EndGroup()
- func (c *Action) Errorf(msg string, args ...interface{})
- func (c *Action) Fatalf(msg string, args ...interface{})
- func (c *Action) GetInput(i string) string
- func (c *Action) Group(t string)
- func (c *Action) IssueCommand(cmd *Command)
- func (c *Action) IssueFileCommand(cmd *Command) error
- func (c *Action) RemoveMatcher(o string)
- func (c *Action) SaveState(k, v string)
- func (c *Action) SetEnv(k, v string)
- func (c *Action) SetOutput(k, v string)
- func (c *Action) Warningf(msg string, args ...interface{})
- func (c *Action) WithFieldsMap(m map[string]string) *Action
- func (c *Action) WithFieldsSlice(f []string) *Action
- type Command
- type CommandProperties
Examples ¶
Constants ¶
Variables ¶
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 Debugf ¶
func Debugf(msg string, args ...interface{})
Debugf prints a debug-level message. The arguments follow the standard Printf arguments.
func Errorf ¶
func Errorf(msg string, args ...interface{})
Errorf prints a error-level message. The arguments follow the standard Printf arguments.
func Fatalf ¶
func Fatalf(msg string, args ...interface{})
Fatalf prints a error-level message and exits. This is equivalent to Errorf followed by os.Exit(1).
func Group ¶
func Group(t string)
Group starts a new collapsable region up to the next ungroup invocation.
func IssueCommand ¶
func IssueCommand(cmd *Command)
IssueCommand issues an arbitrary GitHub actions Command.
func IssueFileCommand ¶
IssueFileCommand issues a new GitHub actions Command using environment files.
func RemoveMatcher ¶
func RemoveMatcher(o string)
RemoveMatcher removes a matcher with the given owner name.
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() *Action
New creates a new wrapper with helpers for outputting information in GitHub actions format.
Example ¶
Output:
func NewWithWriter ¶
NewWithWriter creates a wrapper using the given writer. This is useful for tests. The given writer cannot add any prefixes to the string, since GitHub requires these special strings to match a very particular format.
func WithFieldsMap ¶
WithFieldsMap includes the provided fields in log output. The fields in "m" are automatically converted to k=v pairs and sorted.
func WithFieldsSlice ¶
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 ¶
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.
Example ¶
Output:
func (*Action) AddMatcher ¶
AddMatcher adds a new matcher with the given file path.
func (*Action) AddPath ¶
AddPath adds the string "p" to the path for the invocation. It attempts to issue a file command at first. If that fails, it falls back to the regular (now deprecated) 'add-path' command, which may stop working in the future. The deprecated fallback may be useful for users running an older version of GitHub runner.
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 ¶
Output:
func (*Action) Debugf ¶
Debugf prints a debug-level message. The arguments follow the standard Printf arguments.
Example ¶
Output:
Example (FieldsMap) ¶
Output:
Example (FieldsSlice) ¶
Output:
func (*Action) Errorf ¶
Errorf prints a error-level message. The arguments follow the standard Printf arguments.
Example ¶
Output:
Example (FieldsMap) ¶
Output:
Example (FieldsSlice) ¶
Output:
func (*Action) Fatalf ¶
Fatalf prints a error-level message and exits. This is equivalent to Errorf followed by os.Exit(1).
func (*Action) IssueCommand ¶
IssueCommand issues a new GitHub actions Command.
func (*Action) IssueFileCommand ¶
IssueFileCommand issues a new GitHub actions Command using environment files.
The TypeScript equivalent function:
IssueFileCommand currently ignores the 'CommandProperties' field provided with the 'Command' argument as it's scope is unclear in the current TypeScript implementation.
func (*Action) RemoveMatcher ¶
RemoveMatcher removes a matcher with the given owner name.
func (*Action) SetEnv ¶
SetEnv sets an environment variable. It attempts to issue a file command at first. If that fails, it falls back to the regular (now deprecated) 'set-env' command, which may stop working in the future. The deprecated fallback may be useful for users running an older version of GitHub runner.
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 ¶
Output:
func (*Action) Warningf ¶
Warningf prints a warning-level message. The arguments follow the standard Printf arguments.
Example ¶
Output:
Example (FieldsMap) ¶
Output:
Example (FieldsSlice) ¶
Output:
func (*Action) WithFieldsMap ¶
WithFieldsMap includes the provided fields in log output. The fields in "m" are automatically converted to k=v pairs and sorted.
func (*Action) WithFieldsSlice ¶
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 ¶
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
type CommandProperties ¶
CommandProperties is a named "map[string]string" type to hold key-value pairs passed to an actions command.
func (*CommandProperties) String ¶
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.
Source Files
Valid 
Stable version