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
¶
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 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) 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
Examples ¶
Constants ¶
This section is empty.
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 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 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 ¶
a = githubactions.New()
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 ¶
a := githubactions.New()
a.AddMask("my-password")
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.
Example ¶
a := githubactions.New()
a.AddPath("/tmp/myapp")
Output:
func (*Action) Debugf ¶
Debugf prints a debug-level message. The arguments follow the standard Printf arguments.
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) Errorf ¶
Errorf prints a error-level message. The arguments follow the standard Printf arguments.
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 ¶
Fatalf prints a error-level message and exits. This is equivalent to Errorf followed by os.Exit(1).
func (*Action) RemoveMatcher ¶
RemoveMatcher removes a matcher with the given owner name.
func (*Action) SetEnv ¶
SetEnv sets an environment variable.
Example ¶
a := githubactions.New()
a.SetEnv("MY_THING", "my value")
Output:
func (*Action) SetOutput ¶
SetOutput sets an output parameter.
Example ¶
a := githubactions.New()
a.SetOutput("filepath", "/tmp/file-xyz1234")
Output:
func (*Action) Warningf ¶
Warningf prints a warning-level message. The arguments follow the standard Printf arguments.
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 ¶
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.
Source Files