fireactions

package module
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Jan 28, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

README

Go Report Card

Banner

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.

Architecture

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

Constants

This section is empty.

Variables

View Source 
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 = ""
)
View Source 
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 added in v0.4.0 

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 added in v0.3.0 

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 added in v0.2.4 

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 added in v0.3.0 

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 added in v0.3.0 

type MicroVMs []MicroVM

MicroVMs represents a slice of MicroVM

func (MicroVMs) Cols added in v0.3.0 

func (m MicroVMs) Cols() []string

func (MicroVMs) ColsMap added in v0.3.0 

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

func (MicroVMs) KV added in v0.3.0 

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
fireactions command
mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
helper
deepcopy
github
logger
printer
stringid
mmds

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.