fireactions

README

Fireactions is an orchestrator for GitHub runners. BYOM (Bring Your Own Metal) and run self-hosted GitHub runners in ephemeral, fast and secure Firecracker based virtual machines.

Several key features:

• Scalable

  Pool based scaling approach. Fireactions always ensures the minimum amount of GitHub runners in the pool.

• Ephemeral

  Each virtual machine is created from scratch and destroyed after the job is finished, no state is preserved between jobs, just like with GitHub hosted runners.

• Customizable

  Define job labels and customize virtual machine resources to fit Your needs.

Quickstart

Create and install a GitHub App (see Creating a GitHub App) with the following permissions:

• Read access to metadata
• Read and write access to actions and organization self hosted runners

Note down the GitHub App ID and generate a private key, save it to a file on the host machine, e.g. /root/private-key.pem.

Download and run the installation script:

curl -sSL https://raw.githubusercontent.com/hostinger/fireactions/main/install.sh -o install.sh
chmod +x install.sh
./install.sh --help
This script installs Fireactions on a Linux machine.

Usage: ./install.sh [options]

Options:
  --github-app-id                     Sepcify the ID of the GitHub App                          (required)
  --github-app-key-file               Specify the path to the GitHub App private key file       (required)
  --github-organization               Specify the name of the GitHub organization               (required)
  --fireactions-version               Specify the Fireactions version to install                (default: 0.2.5)
  --firecracker-version               Specify the Firecracker version to install                (default: 1.4.1)
  --kernel-version                    Specify the kernel version to install                     (default: 5.10)
  --containerd-snapshotter-device     Specify the device to use for Containerd snapshot storage (required)
  --containerd-version                Specify the Containerd version to install                 (default: 1.7.0)
  --cni-version                       Specify the CNI plugin version to install                 (default: 1.6.0)
  -h, --help                          Show this help message

This creates a default configuration with a single pool named default with a single runner. See Configuration for more information.

Test the installation by creating a new GitHub workflow in your repository:

# .github/workflows/test.yaml
name: test

on:
  workflow_dispatch:
  pull_request:
      branches:
      - '*'
  push:
      branches:
      - main

jobs:
  test:
    name: test
    runs-on: # The label(s) of the Fireactions pool
    - self-hosted
    - fireactions
    steps:
    - name: Example
      run: |
        echo "Hello, Fireactions!"

Contributing

See CONTRIBUTING.md for more information on how to contribute to Fireactions.

License

See LICENSE

Documentation

Index

• Variables
• func String() string
• type Client
  • func NewClient(opts ...ClientOpt) *Client
  • func (c *Client) GetMicroVM(ctx context.Context, vmid string) (*MicroVM, *Response, error)
  • func (c *Client) GetPool(ctx context.Context, id string) (*Pool, *Response, error)
  • func (c *Client) ListMicroVMs(ctx context.Context, pool string) (*MicroVMs, *Response, error)
  • func (c *Client) ListPools(ctx context.Context, opts *ListOptions) (Pools, *Response, error)
  • func (c *Client) PausePool(ctx context.Context, id string) (*Response, error)
  • func (c *Client) Reload(ctx context.Context) (*Response, error)
  • func (c *Client) ResumePool(ctx context.Context, id string) (*Response, error)
  • func (c *Client) ScalePool(ctx context.Context, id string, replicas int) (*Response, error)
• type ClientOpt
  • func WithEndpoint(endpoint string) ClientOpt
  • func WithHTTPClient(client *http.Client) ClientOpt
  • func WithPassword(password string) ClientOpt
  • func WithUserAgent(userAgent string) ClientOpt
  • func WithUsername(username string) ClientOpt
• type Error
  • func (e *Error) Error() string
• type ListOptions
  • func (o *ListOptions) Apply(req *http.Request)
• type MicroVM
• type MicroVMs
  • func (m MicroVMs) Cols() []string
  • func (m MicroVMs) ColsMap() map[string]string
  • func (m MicroVMs) KV() []map[string]interface{}
• type Pool
  • func (p *Pool) Cols() []string
  • func (p *Pool) ColsMap() map[string]string
  • func (p *Pool) KV() []map[string]interface{}
• type PoolState
  • func (p PoolState) String() string
• type PoolStatus
• type Pools
  • func (p Pools) Cols() []string
  • func (p Pools) ColsMap() map[string]string
  • func (p Pools) KV() []map[string]interface{}
• type Response
  • func (r *Response) HasNextPage() bool
  • func (r *Response) NextPage() (string, error)

Variables

var (
	// Version is the version of the Fireactions.
	Version = "0.0.0"

	// Date is the date when the binary was built.
	Date = "1970-01-01T00:00:00Z"

	// Commit is the Git SHA of the commit that was built.
	Commit = ""
)

var (
	// ErrPoolNotFound is returned when a pool is not found
	ErrPoolNotFound = errors.New("pool not found")
)

Functions

func String

func String() string

String returns a string representation of the Fireactions version.

Types

type Client

type Client struct {

	// Endpoint is the Fireactions API endpoint.
	Endpoint string

	// UserAgent is the User-Agent header to send when communicating with the
	// Fireactions API.
	UserAgent string

	// Username is the username to use when authenticating with the Fireactions API
	Username string

	// Password is the password to use when authenticating with the Fireactions API
	Password string
	// contains filtered or unexported fields
}

Client is a client for the Fireactions API.

func NewClient

func NewClient(opts ...ClientOpt) *Client

NewClient returns a new Client

func (*Client) GetMicroVM

func (c *Client) GetMicroVM(ctx context.Context, vmid string) (*MicroVM, *Response, error)

GetMicroVM returns a MicroVM by VMID.

func (*Client) GetPool

func (c *Client) GetPool(ctx context.Context, id string) (*Pool, *Response, error)

GetPool returns a pool by ID.

func (*Client) ListMicroVMs

func (c *Client) ListMicroVMs(ctx context.Context, pool string) (*MicroVMs, *Response, error)

ListMicroVMs returns a list of MicroVM(s). If pool is empty, returns all MicroVMs across all pools. If pool is specified, returns only MicroVMs from that pool.

func (*Client) ListPools

func (c *Client) ListPools(ctx context.Context, opts *ListOptions) (Pools, *Response, error)

ListPools returns a list of pools.

func (*Client) PausePool

func (c *Client) PausePool(ctx context.Context, id string) (*Response, error)

PausePool pauses a pool by ID.

func (*Client) Reload

func (c *Client) Reload(ctx context.Context) (*Response, error)

Reload reloads the Fireactions server.

func (*Client) ResumePool

func (c *Client) ResumePool(ctx context.Context, id string) (*Response, error)

ResumePool resumes a pool by ID.

func (*Client) ScalePool

func (c *Client) ScalePool(ctx context.Context, id string, replicas int) (*Response, error)

ScalePool sets the desired number of replicas for a pool.

type ClientOpt

type ClientOpt func(*Client)

ClientOpt is an option for a new Fireactions client.

func WithEndpoint

func WithEndpoint(endpoint string) ClientOpt

WithEndpoint returns a ClientOpt that specifies the Fireactions API endpoint to use when making requests to the Fireactions API.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOpt

WithHTTPClient returns a ClientOpt that specifies the HTTP client to use when making requests to the Fireactions API.

func WithPassword

func WithPassword(password string) ClientOpt

WithPassword returns a ClientOpt that specifies the password to use when authenticating with the Fireactions API.

func WithUserAgent

func WithUserAgent(userAgent string) ClientOpt

WithUserAgent returns a ClientOpt that specifies the User-Agent header to use when making requests to the Fireactions API.

func WithUsername

func WithUsername(username string) ClientOpt

WithUsername returns a ClientOpt that specifies the username to use when authenticating with the Fireactions API.

type Error

type Error struct {
	Message string `json:"error"`
}

Error represents an error returned by the Fireactions API.

func (*Error) Error

func (e *Error) Error() string

Error returns the error message. Implements the error interface.

type ListOptions

type ListOptions struct {
	Page    int
	PerPage int
}

ListOptions specifies the optional parameters to various List methods that support pagination.

func (*ListOptions) Apply

func (o *ListOptions) Apply(req *http.Request)

Apply modifies the request to include the optional pagination parameters.

type MicroVM

type MicroVM struct {
	VMID      string    `json:"VMID"`
	Pool      string    `json:"Pool"`
	IPAddr    string    `json:"IPAddr"`
	CreatedAt time.Time `json:"CreatedAt"`
}

MicroVM represents a Firecracker based virtual machine

type MicroVMs

type MicroVMs []MicroVM

MicroVMs represents a slice of MicroVM

func (MicroVMs) Cols

func (m MicroVMs) Cols() []string

func (MicroVMs) ColsMap

func (m MicroVMs) ColsMap() map[string]string

func (MicroVMs) KV

func (m MicroVMs) KV() []map[string]interface{}

type Pool

type Pool struct {
	Name            string     `json:"name"`
	Replicas        int        `json:"replicas"`
	CurrentReplicas int        `json:"current_replicas"`
	DesiredReplicas int        `json:"desired_replicas"`
	Organization    string     `json:"organization"`
	GroupID         int64      `json:"group_id"`
	Labels          []string   `json:"labels"`
	Image           string     `json:"image"`
	Status          PoolStatus `json:"status"`
}

Pool represents a pool of GitHub runners

func (*Pool) Cols

func (p *Pool) Cols() []string

func (*Pool) ColsMap

func (p *Pool) ColsMap() map[string]string

func (*Pool) KV

func (p *Pool) KV() []map[string]interface{}

type PoolState

type PoolState string

PoolState represents the state of a pool

const (
	// PoolStateActive represents the active state, meaning the pool is running
	PoolStateActive PoolState = "Active"

	// PoolStatePaused represents the paused state, meaning the pool is stopped
	PoolStatePaused PoolState = "Paused"
)

func (PoolState) String

func (p PoolState) String() string

String returns the string representation of the pool state

type PoolStatus

type PoolStatus struct {
	State   PoolState `json:"state"`
	Message string    `json:"message"`
}

PoolStatus represents the status of a pool

type Pools

type Pools []*Pool

Pool represents a slice of Pool

func (Pools) Cols

func (p Pools) Cols() []string

func (Pools) ColsMap

func (p Pools) ColsMap() map[string]string

func (Pools) KV

func (p Pools) KV() []map[string]interface{}

type Response

type Response struct {
	*http.Response
}

Response wraps an HTTP response.

func (*Response) HasNextPage

func (r *Response) HasNextPage() bool

HasNextPage returns true if the response has a next page.

func (*Response) NextPage

func (r *Response) NextPage() (string, error)

NextPage returns the next page URL.