script

script.go

Write the rest of your deployment pipeline in Go instead of bash.

This GitHub Action compiles your Go code as a Go plugin and executes it inside the workflow. Your script gets a small, batteries-included API for running local commands, running commands on a remote server over SSH, uploading files, and writing env files — no sshpass, scp flags, or heredoc quoting.

Usage

name: Deploy
on:
  push:
    branches:
      - "main"

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: "stable" # needs Go 1.22+

      - name: Run deployment scripts
        uses: alinz/script.go@main
        with:
          workspace: ${{ github.workspace }} # <- this is important
          paths: .github/scripts/deploy # comma-separated if you have more than one
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

Each script lives in its own folder with its own go.mod, and must export a Runner symbol with the signature func(workspace string) error (either func Runner(workspace string) error or var Runner = func(workspace string) error works):

// .github/scripts/deploy/main.go
package main

import (
	"github.com/alinz/script.go"
)

var Runner = func(workspace string) error {
	runner, err := script.NewRunner(&script.Config{
		User: "deploy",
		Host: "example.com",
		// Port: 22,                        // default
		// PrivateKeyEnv: "SSH_PRIVATE_KEY", // default
	})
	if err != nil {
		return err
	}
	defer runner.Close()

	// build locally — full shell semantics, pipes and quoting included
	err = runner.RunLocal(workspace,
		"go build -o ${workspace}/bin/api ./cmd/api",
	)
	if err != nil {
		return err
	}

	// upload artifacts
	err = runner.CopyFiles("0755", "/opt/api", workspace, "bin/api")
	if err != nil {
		return err
	}

	// write an env file on the server (values may reference local env vars)
	err = runner.CreateEnvFile("/opt/api/.env", map[string]string{
		"DATABASE_URL": "${DATABASE_URL}",
		"PORT":         "8080",
	})
	if err != nil {
		return err
	}

	// restart the service
	return runner.RunRemote(
		"sudo systemctl restart api",
	)
}

Because scripts are compiled with -buildmode=plugin, the action requires a Linux (or macOS) runner. Windows runners are not supported.

For a full example repository, see alinz/examples-script.go.

API

Add the library to your script's module:

go get github.com/alinz/script.go

script.NewRunner(config *script.Config) (script.Runner, error)

Validates the config, connects to the remote host, and returns a Runner. Call Close() when done.

type Config struct {
	User             string        // required
	Host             string        // required
	Port             int           // default: 22
	PrivateKeyEnv    string        // default: "SSH_PRIVATE_KEY"
	DefaultLocalPath string        // default: "~/.ssh/id_rsa" (fallback when the env var is unset)
	HostPublicKey    string        // optional: pin the host key (one line of `ssh-keyscan host` output)
	Timeout          time.Duration // default: 30s connection timeout
}

The private key is read from the environment variable named by PrivateKeyEnv; if that is unset, the file at DefaultLocalPath is used. When HostPublicKey is empty, host key verification is disabled — set it in production so a DNS or network hijack can't intercept your deployment.

Runner

type Runner interface {
	RunLocal(workspace string, cmds ...string) error
	RunRemote(cmds ...string) error
	CopyFiles(permissions, remotePath, workspace string, filepaths ...string) error
	CreateEnvFile(path string, env map[string]string) error
	Close() error
}

• RunLocal runs each command through sh -c, so quoting, pipes, and redirection all work. ${workspace} and any ${ENV_VAR} references are expanded first; unknown references are left for the shell.
• RunRemote runs commands in a single SSH session, streaming stdout/stderr into the workflow log.
• CopyFiles uploads files (paths relative to workspace) into remotePath, creating the directory if needed. permissions is an octal mode like "0644" ("" defaults to 0644).
• CreateEnvFile renders the map as sorted KEY=value lines and uploads it with 0600 permissions. Values may reference local env vars with ${NAME}. The file is transferred over SCP, so values containing quotes, $, or backticks arrive intact.
• Close releases the SSH connection.

The lower-level SSH client is also available as github.com/alinz/script.go/pkg/ssh with a functional-options constructor (ssh.Client(ssh.WithAddr(...), ssh.WithUser(...), ssh.WithPrivateKey(...), ssh.WithHostKey(...), ssh.WithTimeout(...))).

Upgrading

To use the latest version from main, update your workflow to use @main:

uses: alinz/script.go@main

For stable releases, use the latest version tag (e.g., @v1).

Development

# Install dependencies
go mod download

# Run tests
go test ./...

# Build the action (compiles the script-go CLI)
go build ./cmd/script-go/...

# Test the action locally with a sample script
go run ./cmd/script-go ./path/to/test/script

License

MIT