Hopsule CLI in CI/CD Pipelines

The Role of Hopsule CLI in Automated Governance

In modern engineering organizations, the gap between a high-level decision and its technical implementation is often where organizational memory begins to erode. While the Hopsule Dashboard serves as the central authority for defining and managing these decisions, the Hopsule CLI acts as the enforcement arm within the developer's natural workflow. By integrating the CLI into your Continuous Integration and Continuous Deployment (CI/CD) pipelines, you transform your team's collective judgment from passive documentation into active, enforceable constraints. This integration ensures that no code is merged that contradicts the Accepted Decisions your team has committed to uphold.

Automated governance via CI/CD is not about restricting developer creativity; it is about the preservation of context. When a pipeline fails due to a Hopsule conflict, it serves as a moment of remembrance, reminding the contributor of the reasoning, history, and Memories associated with a specific architectural or procedural choice. This prevents the "drift" that occurs when teams scale or when projects transition between different owners. By making enforcement a standard part of the build process, organizations can maintain a high bar for quality and consistency without requiring manual oversight for every pull request.

Furthermore, using the Hopsule CLI in your pipelines provides a verifiable audit trail of compliance. For engineering leaders and CTOs, this offers a real-time view of how well the organization is adhering to its own standards. Whether you are managing a single repository in solo mode or coordinating hundreds of microservices across an enterprise, the CI/CD integration ensures that your Context Packs are respected at the most critical stage of the software development lifecycle.

Authentication and Security Setup

To interact with your team's decisions and memories from a remote environment like a CI runner, the Hopsule CLI requires a secure method of authentication. We utilize a token-based system that ensures your data remains protected while providing the necessary access for automated checks. This token, typically referred to as HOPSULE_TOKEN, should be treated with the same level of security as your cloud provider credentials or private registry keys.

You can generate a CI/CD token directly within the Hopsule Dashboard under the organization or project settings. These tokens are designed for programmatic use and are scoped to the specific Context Packs or projects they need to validate. Unlike personal access tokens, these are optimized for long-running environments and can be revoked or rotated without affecting individual developer access. Once generated, the token must be added to your CI/CD provider's secret management system as an environment variable.

Important: Security is a baseline guarantee at Hopsule. All data transmitted between the Hopsule CLI and our servers is protected by TLS 1.3, and all decisions and memories are encrypted at rest using AES-256. For teams using Hopsule Enterprise (Self-Hosted), the CLI can be configured to point to your internal endpoint, ensuring that your organizational judgment never leaves your controlled infrastructure. This allows for full data sovereignty while still benefiting from the automated enforcement capabilities of the platform.

The Check Command: Automating Enforcement

The primary tool for CI/CD integration is the hopsule check command. This command performs a deep analysis of the current codebase and compares it against the active Accepted Decisions stored in your Context Packs. Unlike traditional linters that look for static patterns, hopsule check is context-aware. it understands the intent behind your decisions and uses the Memories linked to those decisions to identify contradictions that might otherwise go unnoticed.

When executed, the command scans the staged changes or the entire repository (depending on your configuration) and cross-references the code with the enforceable constraints defined in the Hopsule Dashboard. If a contradiction is detected, the CLI provides a detailed output explaining which decision is being violated, the reasoning behind that decision, and a link to the relevant Memory for further context. This immediate feedback loop allows developers to correct issues before they reach production, preserving the integrity of the project's architectural vision.

The hopsule check command supports several flags to customize its behavior in a pipeline environment. These flags allow you to filter by specific categories, include or exclude certain Capsules, and define the severity of the enforcement. For example, you might choose to only enforce "Security" and "Architecture" decisions during the build process while treating "Style" decisions as warnings.

GitHub Actions Integration

Integrating the Hopsule CLI into GitHub Actions is a straightforward process that involves adding a step to your workflow YAML file. By running Hopsule checks on every pull request, you ensure that contributors are alerted to decision conflicts early in the review process. This reduces the burden on senior developers and maintainers, as Hopper and the CLI handle the routine enforcement of established standards.

To get started, you will need to ensure that the HOPSULE_TOKEN is available in your repository secrets. The following example demonstrates a standard workflow that installs the CLI and runs a compliance check against the main branch. This setup ensures that any code that contradicts an Accepted Decision will trigger a failure in the GitHub Actions status check, effectively blocking the merge until the conflict is resolved or the decision is intentionally overridden.

name: Hopsule Governance Check
on: [pull_request]

jobs:
  enforce-decisions:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Install Hopsule CLI
        run: curl -sL https://get.hopsule.com/install.sh | sh

      - name: Run Hopsule Check
        env:
          HOPSULE_TOKEN: ${{ secrets.HOPSULE_TOKEN }}
        run: hopsule check --severity error

name: Hopsule Governance Check
on: [pull_request]

jobs:
  enforce-decisions:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Install Hopsule CLI
        run: curl -sL https://get.hopsule.com/install.sh | sh

      - name: Run Hopsule Check
        env:
          HOPSULE_TOKEN: ${{ secrets.HOPSULE_TOKEN }}
        run: hopsule check --severity error

name: Hopsule Governance Check
on: [pull_request]

jobs:
  enforce-decisions:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Install Hopsule CLI
        run: curl -sL https://get.hopsule.com/install.sh | sh

      - name: Run Hopsule Check
        env:
          HOPSULE_TOKEN: ${{ secrets.HOPSULE_TOKEN }}
        run: hopsule check --severity error

name: Hopsule Governance Check
on: [pull_request]

jobs:
  enforce-decisions:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Install Hopsule CLI
        run: curl -sL https://get.hopsule.com/install.sh | sh

      - name: Run Hopsule Check
        env:
          HOPSULE_TOKEN: ${{ secrets.HOPSULE_TOKEN }}
        run: hopsule check --severity error

Tip: You can use the --json flag in conjunction with GitHub's job summaries to provide a rich, formatted report of decision compliance directly within the pull request interface. This makes it easier for reviewers to see exactly which decisions were evaluated and why certain blocks of code were flagged as contradictions.

GitLab CI Integration

For organizations using GitLab, the Hopsule CLI can be integrated into the .gitlab-ci.yml pipeline configuration. Similar to other CI environments, the goal is to create a governance gate that validates the repository state against the team's Context Packs. GitLab's powerful pipeline stages allow you to run Hopsule checks in parallel with tests or as a prerequisite for deployment, ensuring that your organizational memory is always respected.

In GitLab, you should define the HOPSULE_TOKEN as a CI/CD Variable within the project or group settings. By marking the variable as "Masked," you ensure that the token does not appear in the pipeline logs. The following configuration snippet illustrates how to define a dedicated governance stage that utilizes the Hopsule CLI to enforce decisions across the entire project.

stages:
  - test
  - governance
  - deploy

hopsule-check:
  stage: governance
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
    - curl -sL https://get.hopsule.com/install.sh | sh
  script:
    - hopsule check
  only:
    - merge_requests
    - main

stages:
  - test
  - governance
  - deploy

hopsule-check:
  stage: governance
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
    - curl -sL https://get.hopsule.com/install.sh | sh
  script:
    - hopsule check
  only:
    - merge_requests
    - main

stages:
  - test
  - governance
  - deploy

hopsule-check:
  stage: governance
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
    - curl -sL https://get.hopsule.com/install.sh | sh
  script:
    - hopsule check
  only:
    - merge_requests
    - main

stages:
  - test
  - governance
  - deploy

hopsule-check:
  stage: governance
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
    - curl -sL https://get.hopsule.com/install.sh | sh
  script:
    - hopsule check
  only:
    - merge_requests
    - main

By including the check in the merge_requests pipeline, you provide immediate feedback to developers. If a conflict is found, the pipeline will fail, and the developer can use Hopsule for VS Code or the Hopsule Dashboard to investigate the Memories associated with the conflicting decision. This encourages a culture of accountability and ensures that decisions are not just made, but followed.

Managing Exit Codes and Pipeline Gates

The Hopsule CLI uses standard POSIX exit codes to communicate the result of a check to the CI/CD orchestrator. Understanding these codes is essential for configuring how your pipeline should respond to different types of decision conflicts. A successful check, where no contradictions are found or all found contradictions are below the specified severity threshold, will return an exit code of 0. This allows the pipeline to proceed to the next stage.

If the CLI detects a contradiction that meets the "Error" severity level, it will return an exit code of 1. Most CI/CD systems interpret any non-zero exit code as a failure, which will stop the pipeline and alert the team. This is the primary mechanism for creating a "Governance Gate." However, there are scenarios where you might want to perform a check without failing the build—for example, during a transition period when a new Context Pack is being introduced. In these cases, you can use the --severity warn flag or configure your CI tool to allow failure for the Hopsule step.

Important: We recommend a "fail-fast" approach for critical architectural and security decisions. By setting these decisions to an "Error" severity in the Hopsule Dashboard, you ensure that the Hopsule CLI will strictly enforce them in the CI/CD pipeline. For less critical guidelines, a "Warning" level allows the pipeline to pass while still providing the developer with a notification about the potential inconsistency.

Best Practices for Governance at Scale

Implementing automated governance across a large engineering organization requires a strategic approach to decision management. One of the most effective best practices is the use of Capsules (Context Packs) to modularize decisions. Instead of having one massive list of decisions for the entire company, create specialized Context Packs for different domains, such as "Cloud Infrastructure," "Frontend Standards," or "Data Privacy." These packs can then be selectively applied to different repositories using the hopsule check --capsule [ID] command.

Another key practice is handling false positives with intentionality. Occasionally, a developer may have a valid reason to deviate from an Accepted Decision. Rather than ignoring the CLI failure or lowering the enforcement bar, Hopsule encourages the use of "Overrides." An override is a documented exception to a decision, which must be justified and recorded. This process ensures that deviations are conscious choices rather than accidental oversights, and the reasoning for the deviation becomes a new Memory in the system.

• Start with Visibility: Initially, set your CI/CD checks to "Warn" only. This allows the team to see where contradictions exist without disrupting their workflow, providing an opportunity to refine decisions or update the codebase.

• Link Decisions to Memories: Ensure every decision has at least one Memory entry explaining the "Why." When a build fails, the developer needs to understand the reasoning to make an informed correction.

• Review Deprecated Decisions: Periodically use the Hopsule Dashboard to review and deprecate old decisions. The CLI will stop enforcing Deprecated decisions, keeping your pipeline checks relevant and fast.

• Use Solo Mode for Local Validation: Encourage developers to run hopsule check locally before pushing their code. This prevents "CI friction" by catching conflicts before they ever reach the remote pipeline.

Self-Hosted and Enterprise Runners

For enterprise organizations with strict compliance requirements, running CI/CD tasks on self-hosted runners is a common necessity. The Hopsule CLI is fully compatible with self-hosted environments, including those that operate behind corporate firewalls or in air-gapped configurations. When using Hopsule Enterprise (Self-Hosted), the CLI communicates directly with your internal Hopsule instance, ensuring that your organizational memory and decision history remain entirely within your sovereign network.

When configuring self-hosted runners, it is important to ensure that the Hopsule CLI binary is either pre-installed on the runner image or accessible via an internal package mirror. This reduces the latency of the check step and eliminates dependencies on external networks during the build process. Additionally, because Hopsule emphasizes that "Enforcement is remembrance, not control," the CLI is designed to be lightweight and non-intrusive, consuming minimal resources on your build infrastructure.

Finally, consider the role of the Hopsule API in your self-hosted setup. You can use webhooks to trigger custom notifications or update internal dashboards whenever a governance check fails in your CI/CD pipeline. This deep integration allows you to build a comprehensive view of organizational health, where every build failure is an opportunity to strengthen the team's shared understanding and preserve the context that makes your engineering organization unique.