Keep integrations in Git

Weik.io is a GitOps platform. The repository has everything a team owns: integrations, variables, channels, APIs and what runs in which environment. Secret values and the platform’s own records, such as agents, users and API keys, are the only things that never live in Git. This page uses GitHub Actions, and any CI system that can run a binary works the same way, because every step is one CLI command.

Push, not pull#

The pipeline runs the weikio CLI, so the hub needs no Git credentials and no network path to your Git host, even when it runs inside your own network. There is no poller inside the platform that could disagree with a person using the CLI, and the review, the approval and the history of each change stay in your Git host, where your team already has them.

The repository#

One repository for all projects, or one per project, both work. The API key’s grants decide what a pipeline may touch, not the layout.

weikio-integrations/
  .github/workflows/
    plan.yaml                   pull request: what would change, as a comment
    devtest.yaml                merge to main: apply to devtest
    production.yaml             merge to main: apply to production, behind approval
  finance/
    project.yaml                admin key: the project is created once
    variables/erp-url.yaml      admin key: a default is every environment at once
    shared/                     what every environment reads, which the devtest job applies
      erp-invoice-export/       the integration directory
      events/                   channels, sources, subscriptions
      apis/                     APIs and their versions
    devtest/                    the devtest job applies it
      variables/
      apis/                     API deployments and subscriptions of devtest
      deployments/erp-invoice-export.yaml         version: 1.1.0
    production/                 the production job applies it
      variables/erp-url.yaml
      apis/
      deployments/erp-invoice-export.yaml         version: 1.0.0

A deployment document says only what should run where:

apiVersion: weik.io/v1
kind: deployment
metadata: { name: erp-invoice-export, project: finance, environment: production }
spec: { version: 1.1.0, state: started }

The loop#

1. Change: a developer edits the integration, runs it on their machine with weikio dev run, raises the version in integration.yaml, commits and opens a pull request.
2. Plan: the pull request workflow runs weikio diff with the devtest key and posts the output as a comment: the versions it would create, the variables that change, the deployments that move and what it would delete. Files changed without a raised version are a would refuse row, and the check fails before anyone merges.
3. Apply to devtest: on merge, the devtest workflow applies shared/ and devtest/ to devtest in one call. The integrations that changed are built once, here, and the other environments deploy those versions.
4. Promote: promotion is a pull request that changes one line, the version in finance/production/deployments/erp-invoice-export.yaml. On merge, the production workflow plans in a job of its own, and its apply job waits for GitHub’s required reviewers to approve after they read that plan.
5. Roll back: git revert of the promotion, merged through the same gate. A revert goes back to a version that already exists, with no build.

The production workflow#

name: production
on:
  push:
    branches: [main]
    paths: ['finance/**']
env:
  WEIKIO_SERVER: https://weikio.example.com
jobs:
  plan:                                     # the diff the reviewers read before they approve
    runs-on: ubuntu-latest
    environment: production-plan            # has the production key, no reviewers
    env:
      WEIKIO_API_KEY: ${{ secrets.WEIKIO_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: |                              # installs the CLI, pinned version, and gives the commit's subject line as the reason
          curl -fsSL https://weik.io/install.sh | WEIKIO_CLI_VERSION=2026.2.1 sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          echo "WEIKIO_REASON=$(git log -1 --format=%s)" >> "$GITHUB_ENV"
      - run: weikio diff -f ./finance/production --env production --prune finance || [ $? -eq 2 ]
  apply:
    needs: plan
    runs-on: ubuntu-latest
    environment: production                 # GitHub's required reviewers gate this job
    env:
      WEIKIO_API_KEY: ${{ secrets.WEIKIO_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: |
          curl -fsSL https://weik.io/install.sh | WEIKIO_CLI_VERSION=2026.2.1 sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          echo "WEIKIO_REASON=$(git log -1 --format=%s)" >> "$GITHUB_ENV"
      - run: printf '%s' "$ERP_API_KEY" | weikio secret set finance/erp-api-key --env production -y
        env:
          ERP_API_KEY: ${{ secrets.ERP_API_KEY }}
      - run: weikio apply -f ./finance/production --env production --prune finance -y

weikio diff exits 0 when nothing changes, 2 when something does and 7 when a document would be refused, so the plan job fails only on a refusal. The platform needs no approval workflow of its own, because GitHub’s required reviewers are the approval.

The devtest and plan workflows#

The devtest workflow is one job with the devtest key and no reviewers. It applies the shared folder and devtest’s folder together:

name: devtest
on:
  push:
    branches: [main]
    paths: ['finance/**']
env:
  WEIKIO_SERVER: https://weikio.example.com
jobs:
  apply:
    runs-on: ubuntu-latest
    environment: devtest
    env:
      WEIKIO_API_KEY: ${{ secrets.WEIKIO_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: |
          curl -fsSL https://weik.io/install.sh | WEIKIO_CLI_VERSION=2026.2.1 sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          echo "WEIKIO_REASON=$(git log -1 --format=%s)" >> "$GITHUB_ENV"
      - run: weikio apply -f ./finance/shared -f ./finance/devtest --env devtest --prune finance -y

The plan workflow runs the same paths through weikio diff on every pull request and posts the result as a comment:

name: plan
on:
  pull_request:
    paths: ['finance/**']
permissions:
  contents: read
  pull-requests: write
env:
  WEIKIO_SERVER: https://weikio.example.com
jobs:
  plan:
    runs-on: ubuntu-latest
    environment: devtest
    env:
      WEIKIO_API_KEY: ${{ secrets.WEIKIO_API_KEY }}
      GH_TOKEN: ${{ github.token }}
    steps:
      - uses: actions/checkout@v4
      - run: |
          curl -fsSL https://weik.io/install.sh | WEIKIO_CLI_VERSION=2026.2.1 sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: weikio diff -f ./finance/shared -f ./finance/devtest --env devtest --prune finance > plan.txt || [ $? -eq 2 ]
      - if: always()
        run: gh pr comment ${{ github.event.pull_request.number }} --body-file plan.txt

A route step Camel doesn’t know passes the plan, and the build in the devtest apply finds it. Production is planned after the merge, because only a job that main reaches has the production key.

Keys#

Each repository has one API key per environment, kept as a GitHub environment secret. Its grant is the deployer role on the repository’s projects, limited to that one environment, so the devtest key can’t touch production even if someone edits the workflow file. A key administers the platform only when it was minted with --platform-admin. It mints keys only within its own grants, so it can’t give itself more.

Two things such a key can’t write, on purpose. A project belongs to a platform administrator, and a default variable or secret, the one with no environment, changes every environment at once. A project is created once by an administrator, and the defaults are applied by a workflow of their own with an admin key: weikio apply -f ./finance/variables --prune finance -y, with no --env.

Secrets#

Values never sit in Git. The {{name}} placeholders in the files show which secrets an integration needs, and the plan fails with secret_missing when a deployment needs one with no value in its environment. Set an environment’s first value by hand before the first delivery that needs it:

$ printf '%s' "$ERP_PROD_KEY" | weikio secret set finance/erp-api-key --env production

From then on, the apply job sets the value from a GitHub secret before it applies, as the production workflow above does, so a changed value waits for the approval like every other change.

What the platform records#

The CLI records the repository, the branch and the commit of every apply it runs in a pipeline. It gets them from the variables GitHub Actions, GitLab CI and Azure DevOps set, or from --origin. weikio describe integration finance/erp-invoice-export shows applied from weikio-integrations@a1b2c3d, and each audit record links the change to the commit and carries the reason, the commit’s subject line. Who changed what and why is answered by Git, and the platform points at it.

/settings/audit

Several teams work in one installation with a project each. The platform enforces the boundary, not the repository: a key with a grant on finance can’t apply hr/, however the workflow is written.