phobos-api

module
v0.52.0 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2026 License: MPL-2.0

README

Phobos API

Phobos API is the core component of the Phobos platform, a modern, open-source release management and deployment orchestration tool. It provides a comprehensive solution for managing release processes, pipelines, and deployments within an organization. The API is designed as a stateless service, allowing for horizontal scaling and high availability deployments.

Key Features

  • Release Management:

    • Define release processes using HashiCorp Configuration Language (HCL)
    • Version and manage release templates
    • Tailor releases to specific environments
    • Support for approval workflows and scheduling
    • Retry capabilities for failed processes

  • Pipeline Orchestration:

    • Create and manage deployment pipelines with HCL
    • Orchestrate complex release workflows
    • Real-time pipeline execution monitoring
    • Version control for pipeline templates
    • Event-driven pipeline triggers

  • Plugin System:

    • Virtually unlimited extensibility with custom plugins
    • Built-in plugin registry for discovery and sharing
    • Plugin lifecycle management
    • Private plugins for organization-specific use cases
    • Extend functionality without modifying core code

  • Authentication & Authorization:

    • Machine to Machine (M2M) authentication with service accounts
    • Role-based access control (RBAC)
    • Configurable approval rules
    • Fine-grained permission management
    • Secure API access with tokens

  • Agent Architecture:

    • Agent-based job execution model
    • Support for containerized environments
    • Tag-based agent selection for job requirements
    • Agent health monitoring
    • Diagnostic capabilities for troubleshooting

  • API Capabilities:

    • GraphQL API for flexible queries
    • gRPC API for high-performance communication
    • Real-time updates with GraphQL subscriptions
    • Comprehensive query and mutation capabilities
    • WebHook support for external integrations

  • Monitoring and Observability:

    • Real-time monitoring of releases and pipelines
    • Activity event tracking
    • Collaboration features
    • Comprehensive logging
    • Organization and project-level visibility

  • Operational Features:

    • Horizontal scaling for high availability
    • Containerized deployment support
    • Team management and access control
    • Written in Go for performance and reliability

Architecture

Phobos API is built with a layered architecture that separates concerns and promotes maintainability:

  • API Layer: GraphQL and gRPC APIs with comprehensive query, mutation, and subscription support
  • Service Layer: Core business logic and service implementations
  • Data Access Layer: Database abstraction for persistent storage
  • Job Execution Layer: Interfaces with agents for job execution
  • Authentication Layer: Handles various authentication mechanisms including service accounts

As a stateless service, the API can be horizontally scaled to handle increased load, with state maintained in the database and external storage systems.

API Capabilities

The Phobos API provides a comprehensive set of operations:

  • GraphQL: Flexible queries and mutations with subscription support for real-time updates
  • gRPC: High-performance API for programmatic access
  • WebHooks: Integration with external systems for event notifications

Get started

For comprehensive documentation, visit the Phobos Documentation Site.

Instructions on building a binary from source can be found here.

Installing locally (Requires Docker)

In order to use Phobos locally, a docker-compose.yml file is available under the docker-compose directory. The use of this requires the installation of Docker. Learn more here.

1. Clone the repository and change to 'docker-compose' directory.
2. Use 'docker compose up' command to launch Phobos using Docker. We could additionally, pass in a `-d` flag to the command to launch everything in the background like so 'docker compose up -d'.

At this point, Docker should begin pulling down all the images needed to provision Phobos. Once this is complete, the Phobos UI will be available at http://localhost:9001/.

When first going to http://localhost:9001/, the KeyCloak login screen will display, which prompts you to create a profile using the KeyCloak identity provider (IDP). Use martian for both the username and password to complete authentication.

Now the Phobos CLI can be used to interact with Phobos. Use the following commands to create a profile named local, which points to the API endpoint and then logs in to Phobos via local:

phobos configure --profile local --http-endpoint http://localhost:9000
phobos -p local sso login

Congratulations! The Phobos CLI is now ready to issue commands, use the -h flag for more info!

Running Phobos API from local source

In order to run Phobos API from local source:

1. Stop the phobos-api docker container if it is running.
2. Copy the `env.example` file in the root folder and paste it as `.env`.
3. Open the Phobos API folder in Visual Studio Code.
4. Install the recommended extensions.
5. Click the `Run and Debug` menu on the left hand side of Visual Studio Code.
6. Click the Start Debugging button next to Launch API.

At this point you can interact with the Phobos UI at http://localhost:9001/ and it will be communicating with your local Phobos API.

Documentation

Security

If you've discovered a security vulnerability in the Phobos API, please let us know by creating a confidential issue in this project.

Statement of support

Please submit any bugs or feature requests for Phobos. Of course, MR's are even better. :)

License

Phobos API is distributed under Mozilla Public License v2.0.

Directories

Path Synopsis
cmd
agent command
Package main contains the top-level code for the Phobos org agent.
 Package main contains the top-level code for the Phobos org agent.
apiserver command
Package main is the entrypoint to the API.
 Package main is the entrypoint to the API.
job command
Package main package
 Package main package
Package frontend allows the compiled UI files to be embedded into the API binary.
 Package frontend allows the compiled UI files to be embedded into the API binary.
internal
agent
Package agent provides the agent that will claim and run the jobs.
 Package agent provides the agent that will claim and run the jobs.
agent/jobdispatcher
Package jobdispatcher package
 Package jobdispatcher package
agent/jobdispatcher/docker
Package docker package
 Package docker package
agent/jobdispatcher/ecs
Package ecs package
 Package ecs package
agent/jobdispatcher/kubernetes
Package kubernetes package
 Package kubernetes package
agent/jobdispatcher/kubernetes/configurer
Package configurer package
 Package configurer package
agent/jobdispatcher/kubernetes/configurer/cert
Package cert provides a Kubernetes configurer that uses TLS certificates for authentication.
 Package cert provides a Kubernetes configurer that uses TLS certificates for authentication.
agent/jobdispatcher/kubernetes/configurer/configfile
Package configfile provides a Configurer implementation that reads Kubernetes configuration from a specified file.
 Package configfile provides a Configurer implementation that reads Kubernetes configuration from a specified file.
agent/jobdispatcher/kubernetes/configurer/eks
Package eks package
 Package eks package
agent/jobdispatcher/kubernetes/configurer/idtoken
Package idtoken provides a Kubernetes configurer that uses the agent's ID token for authentication.
 Package idtoken provides a Kubernetes configurer that uses the agent's ID token for authentication.
agent/jobdispatcher/kubernetes/configurer/incluster
Package incluster provides a Kubernetes configurer that retrieves the configuration from the pod's environment.
 Package incluster provides a Kubernetes configurer that retrieves the configuration from the pod's environment.
agent/jobdispatcher/local
Package local package
 Package local package
agent/types
Package types provides additional types used by different job dispatchers
 Package types provides additional types used by different job dispatchers
api
Package api package
 Package api package
api/controllers
Package controllers adds support for RESTful endpoints.
 Package controllers adds support for RESTful endpoints.
api/graphql
Package graphql package
 Package graphql package
api/graphql/loader
Package loader package
 Package loader package
api/graphql/resolver
Package resolver contains functionality for interacting with the API via GraphQL.
 Package resolver contains functionality for interacting with the API via GraphQL.
api/graphql/schema
Package schema contains all of the Schema Definition Files (abbreviated SDL) which define this API.
 Package schema contains all of the Schema Definition Files (abbreviated SDL) which define this API.
api/grpc
Package grpc implements gRPC functionality.
 Package grpc implements gRPC functionality.
api/grpc/interceptors
Package interceptors contains the GRPC interceptors
 Package interceptors contains the GRPC interceptors
api/grpc/reader
Package reader implements a size-limited reader for uploading templates of multiple kinds.
 Package reader implements a size-limited reader for uploading templates of multiple kinds.
api/grpc/servers
Package servers implements the gRPC servers.
 Package servers implements the gRPC servers.
api/middleware
Package middleware allows adding custom middleware(s) to the RESTful API, such as, JWT based authentication.
 Package middleware allows adding custom middleware(s) to the RESTful API, such as, JWT based authentication.
api/response
Package response providers support for returning http responses
 Package response providers support for returning http responses
apiserver
Package apiserver is used to initialize the api
 Package apiserver is used to initialize the api
apiserver/config
Package config contains the configuration for the API.
 Package config contains the configuration for the API.
asynctask
Package asynctask allows running tasks asynchronously.
 Package asynctask allows running tasks asynchronously.
auth
Package auth authenticates and authorizes a subject attempting to access API resources.
 Package auth authenticates and authorizes a subject attempting to access API resources.
db
Package db encapsulates all the logic needed to access information from the DB.
 Package db encapsulates all the logic needed to access information from the DB.
email
Package email supports sending emails.
 Package email supports sending emails.
email/builder
Package builder handles building email templates
 Package builder handles building email templates
email/plunk
Package plunk defines the plunk email plugin
 Package plunk defines the plunk email plugin
email/preview command
Package main is used to preview emails during development
 Package main is used to preview emails during development
email/ses
Package ses defines the ses email plugin
 Package ses defines the ses email plugin
email/smtp
Package smtp defines the smtp email plugin
 Package smtp defines the smtp email plugin
events
Package events supports subscribing to database events.
 Package events supports subscribing to database events.
gid
Package gid package
 Package gid package
http
Package http package
 Package http package
jobexecutor
Package jobexecutor provides the functionality to execute a job
 Package jobexecutor provides the functionality to execute a job
jobexecutor/client
Package client is the gateway for the job executor to interface with the Phobos API.
 Package client is the gateway for the job executor to interface with the Phobos API.
jobexecutor/volume
Package volume is used to mount volumes inside the job executor.
 Package volume is used to mount volumes inside the job executor.
jobexecutor/volume/vcs
Package vcs handles the mounting of VCS volumes (repositories).
 Package vcs handles the mounting of VCS volumes (repositories).
limits
Package limits package
 Package limits package
logstream
Package logstream provides functionality for saving and retrieving logs
 Package logstream provides functionality for saving and retrieving logs
maintenance
Package maintenance provides the maintenance mode monitor
 Package maintenance provides the maintenance mode monitor
metric
Package metric contains functionality about Prometheus metrics including support for a histogram and a simple counter.
 Package metric contains functionality about Prometheus metrics including support for a histogram and a simple counter.
models
Package models defines Phobos resources and their properties as structs.
 Package models defines Phobos resources and their properties as structs.
models/types
Package types provides all Phobos model types
 Package types provides all Phobos model types
notification
Package notification provides notification management functionality for Phobos.
 Package notification provides notification management functionality for Phobos.
plugin
Package plugin defines a plugin store the API uses including, an object store, rate limiting, etc.
 Package plugin defines a plugin store the API uses including, an object store, rate limiting, etc.
plugin/email
Package email supports sending emails.
 Package email supports sending emails.
semver
Package semver package
 Package semver package
services
Package services contains the core business logic for the operations supported by phobos
 Package services contains the core business logic for the operations supported by phobos
services/activityevent
Package activityevent provides functionality for the activity events which are used to track changes to Phobos resources.
 Package activityevent provides functionality for the activity events which are used to track changes to Phobos resources.
services/agent
Package agent contains all functionalities related to Phobos agents, which are responsible for claiming and running jobs.
 Package agent contains all functionalities related to Phobos agents, which are responsible for claiming and running jobs.
services/announcement
Package announcement contains the service for managing announcements
 Package announcement contains the service for managing announcements
services/approvalrule
Package approvalrule implements functionality related to Phobos approval rules.
 Package approvalrule implements functionality related to Phobos approval rules.
services/comment
Package comment implements functionality related to Phobos comments.
 Package comment implements functionality related to Phobos comments.
services/environment
Package environment contains all functionalities related to Phobos environments.
 Package environment contains all functionalities related to Phobos environments.
services/job
Package job implements functionality releated to Phobos jobs
 Package job implements functionality releated to Phobos jobs
services/lifecycletemplate
Package lifecycletemplate implements functionality related to Phobos lifecycle templates.
 Package lifecycletemplate implements functionality related to Phobos lifecycle templates.
services/maintenance
Package maintenance contains the service for enabling/disabling maintenance mode
 Package maintenance contains the service for enabling/disabling maintenance mode
services/membership
Package membership contains all logic for memberships.
 Package membership contains all logic for memberships.
services/metric
Package metric provides functionality for collecting / computing metrics on different Phobos resources.
 Package metric provides functionality for collecting / computing metrics on different Phobos resources.
services/organization
Package organization implements functionality related to Phobos orgs.
 Package organization implements functionality related to Phobos orgs.
services/pipeline
Package pipeline implements functionality related to Phobos pipelines.
 Package pipeline implements functionality related to Phobos pipelines.
services/pipeline/commands
Package commands provides pipeline command implementations.
 Package commands provides pipeline command implementations.
services/pipeline/eventhandlers
Package eventhandlers provides pipeline event handling functionality.
 Package eventhandlers provides pipeline event handling functionality.
services/pipeline/eventhandlers/email
Package email implements functionality that assists with the handling of pipeline email notifications.
 Package email implements functionality that assists with the handling of pipeline email notifications.
services/pipeline/graph
Package graph provides pipeline graph management functionality.
 Package graph provides pipeline graph management functionality.
services/pipeline/pipelinebuilder
Package pipelinebuilder provides functionality for constructing pipelines
 Package pipelinebuilder provides functionality for constructing pipelines
services/pipeline/transformers
Package transformers provides pipeline transformation functionality.
 Package transformers provides pipeline transformation functionality.
services/pipeline/types
Package types provides type definitions for pipeline services.
 Package types provides type definitions for pipeline services.
services/pipelinetemplate
Package pipelinetemplate implements functionality related to Phobos pipeline templates.
 Package pipelinetemplate implements functionality related to Phobos pipeline templates.
services/pluginregistry
Package pluginregistry implements a service for interacting with the plugin registry.
 Package pluginregistry implements a service for interacting with the plugin registry.
services/project
Package project implements functionality related to Phobos projects.
 Package project implements functionality related to Phobos projects.
services/projectvariable
Package projectvariable set implements functionality related to project variables
 Package projectvariable set implements functionality related to project variables
services/release
Package release provides the release service.
 Package release provides the release service.
services/releaselifecycle
Package releaselifecycle implements functionality related to Phobos release lifecycles.
 Package releaselifecycle implements functionality related to Phobos release lifecycles.
services/resourcelimit
Package resourcelimit package
 Package resourcelimit package
services/role
Package role implements the service layer functionality related to Phobos roles.
 Package role implements the service layer functionality related to Phobos roles.
services/scim
Package scim package
 Package scim package
services/serviceaccount
Package serviceaccount package
 Package serviceaccount package
services/team
Package team package
 Package team package
services/todoitem
Package todoitem contains the core business logic for the todoitem service.
 Package todoitem contains the core business logic for the todoitem service.
services/user
Package user implements functionality relating to users CRUD.
 Package user implements functionality relating to users CRUD.
services/vcs
Package vcs package
 Package vcs package
services/vcs/github
Package github package
 Package github package
services/vcs/gitlab
Package gitlab package
 Package gitlab package
services/vcs/types
Package types package
 Package types package
services/version
Package version provides functionality to get the current version of the API and its components.
 Package version provides functionality to get the current version of the API and its components.
tracing
Package tracing package
 Package tracing package
ui
Package ui provides handlers for serving the web UI
 Package ui provides handlers for serving the web UI
universalsearch
Package universalsearch provides functionality for searching across multiple resource types
 Package universalsearch provides functionality for searching across multiple resource types
pkg
client
Package client contains a client implementation for interfacing with the Phobos server
 Package client contains a client implementation for interfacing with the Phobos server
hcl/config
Package config contains the HCL config structs
 Package config contains the HCL config structs
hcl/eval
Package eval provides evaluation context building for HCL templates.
 Package eval provides evaluation context building for HCL templates.
hcl/expression
Package expression contains logic for parsing and evaluating hcl expressions
 Package expression contains logic for parsing and evaluating hcl expressions
hcl/funcs
Package funcs provides HCL built-in functions for template evaluation.
 Package funcs provides HCL built-in functions for template evaluation.
hcl/validate
Package validate contains functionality for validating that a pipeline template HCL file is valid
 Package validate contains functionality for validating that a pipeline template HCL file is valid
hcl/variable
Package variable provides a way to parse and validate variables in a HCL file.
 Package variable provides a way to parse and validate variables in a HCL file.
logstream
Package logstream is used to buffer and write logs to a log stream server
 Package logstream is used to buffer and write logs to a log stream server
plugin
Package plugin is used to manage the execution of Phobos plugins
 Package plugin is used to manage the execution of Phobos plugins
protos/gen
statemachine
Package statemachine contains the state machine logic for a pipeline in the form of an acyclic graph
 Package statemachine contains the state machine logic for a pipeline in the form of an acyclic graph

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.