3squaredcircles/custos repository overview

⁠3SC Custos

The Universal API-Driven Gate for Your CI/CD Pipeline.

3SC Custos is a powerful, dynamic pipeline gate that can pause, pass, or fail a CI/CD workflow based on the state of any external system that has an API. It acts as a universal adapter, allowing you to integrate external approval processes, quality checks, or operational states directly into your deployment pipeline without brittle, custom scripts.

Custos transforms manual, human-based approval gates (like waiting for a Slack message or a ServiceNow ticket update) into a fully automated, auditable, and reliable API call. It answers the question: "Can this pipeline proceed, according to the state of our external systems?"

Visit: https://docs.3squaredcircles.com⁠ for complete configuration options.

⁠A Note on the Name

Custos is the Latin word for "guardian," "guard," or "watchman." This name was chosen because the tool acts as a sentry for your pipeline, guarding it and only allowing passage when the correct conditions are met.

---

⁠For the Manager (VP of Eng, Director of DevOps)

As a leader, you need to balance deployment velocity with operational stability and compliance. Manual approval gates are a common bottleneck, slowing down delivery and introducing human error. Custos automates these gates, increasing both speed and reliability.

Custos answers your critical questions:

• "How do we eliminate the deployment delays caused by waiting for manual approvals in ServiceNow, JIRA, or Slack?"
• "How can we automatically check if a feature flag is enabled in LaunchDarkly before deploying a new mobile version?"
• "How can we create a fully auditable record of every external approval that allowed a deployment to proceed?"
• "How do we empower teams to build their own automated quality gates without writing complex, custom integration code?"

⁠Key Business Values:

• Accelerate Delivery: By replacing slow, manual approval steps with high-speed API polls, Custos can shave hours or even days off your deployment cycle times.
• Improve Reliability & Auditability: Automated gates are 100% consistent and repeatable. Every decision is based on a verifiable API response, and the result is logged, creating a perfect audit trail for compliance.
• Increase Developer Autonomy: Empower teams to connect their pipelines to any tool they need—from security scanners to incident management platforms—using a simple, standardized configuration file, without needing a central DevOps team to write custom scripts.
• Reduce Operational Overhead: Eliminate the need for engineers to act as "human API pollers," constantly checking the status of an external ticket or system.

---

⁠For the Engineer & SRE

As an engineer, you want to remove manual toil from your deployment process. Custos is a generic, powerful tool that lets you model any external dependency as a simple API check.

Custos turns any API endpoint into a pipeline gate.

⁠The Workflow:

1. Define a Gate: In your repository, you create a simple .json file (e.g., production.gate.config.json) that defines the gate's logic. There is a robust UI to build this file for you.
2. Basic Mode Example (Check Status):
   • URL: Point to your JIRA API to get a ticket's status.
   • Evaluation: jsonpath($.fields.status.name) == 'Approved for Prod'
3. Advanced Mode Example (Wait for Approval):
   • URL: Poll a ServiceNow endpoint for a Change Request ticket.
   • Success Condition: jsonpath($.result.state) == 3 (State for "Closed Complete")
   • Failure Condition: jsonpath($.result.state) == 4 (State for "Closed Incomplete")
   • Action: If success, PASS. If failure, BREAK. If neither, PAUSE and poll again.
4. Execute in Pipeline: In your CI/CD pipeline, you run the Custos container, telling it which configuration to use. Custos handles the polling, authentication, and evaluation, and returns the correct exit code (0 for Pass, 70 for Pause, 71 for Break) to control the pipeline flow. This allows for multiple Custos runs within one pipeline, with multiple config files.

---

⁠For the Platform Engineer (DevOps)

As an operator, you need tools that are secure, automatable, and consistent. Custos is a containerized, self-hosted application designed for safe and seamless integration into any CI/CD pipeline.

⁠Execution Modes:

• execute The primary CI mode. It reads a specified gate configuration file, executes the defined logic (e.g., polling an API), and returns an exit code to control the pipeline.
• interactive: Starts a local web-based "Configuration Studio" UI for creating, testing, and managing .gate.config.json files.
• serve-docs: Starts a lightweight server to display embedded tool documentation.

⁠Produced Artifacts

Verifying Image Signatures All published images are signed with Cosign. To verify:

Install cosign: https://docs.sigstore.dev/cosign/system_config/installation/⁠ Download our public key: curl -O https://www.3squaredsquaredcircles.com/keys/3squaredcircles.pub⁠ Verify: cosign verify --key 3squaredcircles.pub 3squaredcircles/custos:latest