From 3c6cbda5b410659d3a731c7653ecc5c053ea4a30 Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Mon, 14 Sep 2026 12:14:24 -0500 Subject: [PATCH 1/9] docs: add kongctl GitHub Actions quickstart --- .../kongctl-ci-cd-github-actions.md | 296 ++++++++++++++++++ app/_indices/kongctl.yaml | 3 + app/_landing_pages/kongctl.yaml | 17 +- app/kongctl/skills.md | 7 + 4 files changed, 316 insertions(+), 7 deletions(-) create mode 100644 app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md new file mode 100644 index 00000000000..e12836b25dd --- /dev/null +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -0,0 +1,296 @@ +--- +title: Set up CI/CD with kongctl and GitHub Actions +description: >- + Review AI Gateway configuration diffs in pull requests and apply changes + from main with kongctl and GitHub Actions. +content_type: how_to +permalink: /kongctl/ci-cd/github-actions/ +breadcrumbs: + - /kongctl/ +products: + - konnect + - ai-gateway +works_on: + - konnect +tools: + - kongctl +min_version: + kongctl: '1.15.1' +tags: + - declarative-config + - ai +automated_tests: false +tldr: + q: How do I use kongctl in GitHub Actions? + a: | + Store declarative configuration in Git. Run `kongctl diff --mode apply` + in pull requests, then `kongctl apply --auto-approve` on pushes to main. +prereqs: + skip_product: false + show_works_on: false + inline: + - title: Konnect access + content: | + You need a {{site.konnect_short_name}} account with access to + {{site.ai_gateway}} and a personal or system account access token + with permission to read and manage AI Gateway resources. See + [kongctl authentication](/kongctl/authentication/). + icon_url: /assets/icons/gateway.svg + - title: GitHub repository and OpenAI key + content: | + Use a GitHub repository with Actions enabled and a `main` branch. + You need permission to add repository secrets and variables, and an + [OpenAI API key](https://platform.openai.com/api-keys). + icon_url: /assets/icons/ai.svg +related_resources: + - text: Declarative configuration with kongctl + url: /kongctl/declarative/ + - text: AI Gateway resource reference + url: /kongctl/supported-resources/#ai-gateway + - text: Use kongctl with AI agent skills + url: /kongctl/skills/ +next_steps: + - text: Learn about kongctl sync + url: /kongctl/sync/ + - text: Manage write-only secrets + url: /kongctl/declarative/#write-only-secret-fields +--- + +This quickstart manages one {{site.ai_gateway}}, an OpenAI Model Provider, +and a Model in {{site.konnect_short_name}}. The repository contains three +files: + +```text +konnect/ai-gateway.yaml +.github/workflows/kongctl-diff.yaml +.github/workflows/kongctl-apply.yaml +``` + +Pull requests display a diff without changing Konnect. Merging into `main` +runs `apply`, which calculates changes against current Konnect state and +executes them. There are no plan artifacts to transfer between workflows. + +## Configure repository secrets and variables + +In your GitHub repository, open **Settings > Secrets and variables > Actions**. +Add these repository secrets: + +| Secret | Value | +| --- | --- | +| `KONNECT_TOKEN` | Your Konnect personal or system account access token | +| `OPENAI_API_KEY` | Your OpenAI API key, without the `Bearer ` prefix | + +On the **Variables** tab, add `KONNECT_REGION` with your Konnect region, such +as `us` or `eu`. Both workflows must use the same region and account. + +The workflows map `KONNECT_TOKEN` to `KONGCTL_DEFAULT_KONNECT_PAT`, so no +interactive `kongctl login` is needed. Only the apply step receives +`OPENAI_API_KEY`. + +Use this example with trusted contributors opening branches in the same +repository. Fork and dependency-bot PRs are skipped because their workflow runs +do not receive repository secrets. See +[Using secrets in GitHub Actions][github-secrets]. + +[github-secrets]: https://docs.github.com/actions/security-guides/encrypted-secrets + +## Declare the gateway, provider, and model + +Create a branch in your repository and add `konnect/ai-gateway.yaml`: + +```yaml +_defaults: + kongctl: + namespace: ai-gateway-cicd + +ai_gateways: + - ref: cicd-ai-gateway + name: cicd-ai-gateway + display_name: CI/CD AI Gateway + description: AI Gateway managed with GitHub Actions + model_providers: + - ref: openai + name: openai + display_name: OpenAI + type: openai + config: + auth: + type: basic + headers: + - name: Authorization + value: !secret + parts: + - "Bearer " + - !env OPENAI_API_KEY + models: + - ref: example-model + name: example-model + display_name: Example Model + type: model + formats: + - type: openai + config: + route: + paths: + - /v1 + model: + body_param: model + values: + - example-model + targets: + - name: gpt-4o + provider: openai + config: + type: openai + capabilities: + - generate +``` + +Choose a namespace and gateway name unique to this repository before the +first deployment. Keep `name` and `ref` stable in later changes. + +`!secret` defers reading the OpenAI key until execution. PR diffs do not need +that key and do not display its value. The model targets `gpt-4o` in OpenAI. + +## Show diffs on pull requests + +Create `.github/workflows/kongctl-diff.yaml`: + +{% raw %} +```yaml +name: kongctl diff + +on: + pull_request: + branches: [main] + paths: + - konnect/** + - .github/workflows/kongctl-*.yaml + +permissions: + contents: read + +jobs: + diff: + if: >- + github.event.pull_request.head.repo.full_name == github.repository && + github.actor != 'dependabot[bot]' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: kong/setup-kongctl@v1 + with: + kongctl-version: '1.15.1' + - name: Show configuration diff + shell: bash + env: + KONGCTL_DEFAULT_KONNECT_PAT: ${{ secrets.KONNECT_TOKEN }} + KONGCTL_DEFAULT_KONNECT_REGION: ${{ vars.KONNECT_REGION }} + NO_COLOR: '1' + run: | + : "${KONGCTL_DEFAULT_KONNECT_PAT:?Set the KONNECT_TOKEN secret}" + : "${KONGCTL_DEFAULT_KONNECT_REGION:?Set KONNECT_REGION}" + kongctl diff --mode apply -f konnect/ai-gateway.yaml -o text \ + --region "$KONGCTL_DEFAULT_KONNECT_REGION" | tee diff.txt + echo '## Konnect configuration diff' >> "$GITHUB_STEP_SUMMARY" + echo '```text' >> "$GITHUB_STEP_SUMMARY" + cat diff.txt >> "$GITHUB_STEP_SUMMARY" + echo '```' >> "$GITHUB_STEP_SUMMARY" +``` +{% endraw %} + +`diff` queries live Konnect state, so it requires the Konnect token even +though it does not change any resources. Its output appears in the workflow +logs and summary. A successful run with proposed changes is expected. + +The workflow uses Bash with pipeline failure handling, so a failed `diff` +command fails the check even though its output is piped through `tee`. + +## Apply changes on main + +Create `.github/workflows/kongctl-apply.yaml`: + +{% raw %} +```yaml +name: kongctl apply + +on: + push: + branches: [main] + paths: + - konnect/** + - .github/workflows/kongctl-*.yaml + +permissions: + contents: read + +concurrency: + group: kongctl-apply-main + cancel-in-progress: false + +jobs: + apply: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: kong/setup-kongctl@v1 + with: + kongctl-version: '1.15.1' + - name: Apply configuration + shell: bash + env: + KONGCTL_DEFAULT_KONNECT_PAT: ${{ secrets.KONNECT_TOKEN }} + KONGCTL_DEFAULT_KONNECT_REGION: ${{ vars.KONNECT_REGION }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + run: | + : "${KONGCTL_DEFAULT_KONNECT_PAT:?Set the KONNECT_TOKEN secret}" + : "${KONGCTL_DEFAULT_KONNECT_REGION:?Set KONNECT_REGION}" + : "${OPENAI_API_KEY:?Set the OPENAI_API_KEY secret}" + kongctl apply -f konnect/ai-gateway.yaml --auto-approve -o text \ + --region "$KONGCTL_DEFAULT_KONNECT_REGION" +``` +{% endraw %} + +Both workflows pin kongctl to the same version. When upgrading, update both +pins together. The deployment concurrency group prevents overlapping apply +runs and allows an active apply to finish. + +`--auto-approve` runs without an interactive confirmation. `apply` generates +its own plan from the merged configuration and current Konnect state; the +result can differ from the earlier PR diff if state has changed. + +## Open a PR and deploy + +1. Commit the manifest and both workflow files, then open a PR targeting + `main`. +1. Open the **kongctl diff** check. Follow its **Details** link to the workflow + run and review the diff in the summary. For a new namespace, expect the + gateway, provider, and model to be created, with no plaintext OpenAI key. +1. Merge the PR. Open **Actions > kongctl apply** and check that the run + succeeds. Verify the gateway, provider, and model in your Konnect region. +1. In another branch, change only the gateway's `description`. Open a PR and + confirm the diff shows an update rather than a new gateway. Merge it and + verify the updated description in Konnect. +1. Re-run the successful apply job without changing the configuration. + Expect no further configuration changes. + +Every matching push to `main` deploys, including direct pushes. Use your +repository's branch rules if all changes must go through PR review. + +## Understand the update behavior + +`apply` creates and updates resources. Removing an entry from the manifest +does not delete it from Konnect. See [kongctl sync](/kongctl/sync/) when you +need deletion-based reconciliation. + +The provider key is written when the provider is created. Changing the +GitHub secret does not trigger a workflow and an ordinary apply does not +rotate an existing write-only credential. Use explicit secret-write +selection when rotating credentials; see +[Write-only secret fields](/kongctl/declarative/#write-only-secret-fields). + +If a check fails, verify the repository secret names, region variable, token +permissions, and {{site.ai_gateway}} access. For an existing gateway managed +outside this repository, follow +[adoption guidance](/kongctl/adopt/ai-gateway/) before using it in this +configuration. diff --git a/app/_indices/kongctl.yaml b/app/_indices/kongctl.yaml index 25771ca6cdb..4d6c4486776 100644 --- a/app/_indices/kongctl.yaml +++ b/app/_indices/kongctl.yaml @@ -30,6 +30,9 @@ groups: - path: /kongctl/declarative/ - path: /kongctl/supported-resources/ - path: /kongctl/kongctl-and-deck/ + - title: CI/CD + items: + - path: /kongctl/ci-cd/github-actions/ - title: Other References items: - path: /kongctl/skills/ diff --git a/app/_landing_pages/kongctl.yaml b/app/_landing_pages/kongctl.yaml index 0eab1a6ff21..0824141edb3 100644 --- a/app/_landing_pages/kongctl.yaml +++ b/app/_landing_pages/kongctl.yaml @@ -33,6 +33,10 @@ rows: The declarative configuration feature lets you define API platform infrastructure as code using YAML and a stateless reconciliation system. kongctl manages APIs, Dev Portals, control planes, {{site.ai_gateway}}, {{site.event_gateway_short}}, organization, and {{site.konnect_catalog}} resources. kongctl also ships installable AI agent skills that help coding agents generate, review, and operate kongctl configuration from a repository. + + **[CI/CD with GitHub Actions](/kongctl/ci-cd/github-actions/)**: + Follow the quickstart to review {{site.ai_gateway}} diffs in + pull requests and apply changes on main. kongctl is one of multiple tools you can use to manage {{site.konnect_short_name}} and {{site.base_gateway}}. To learn about other tools, see the [tools page](/tools/). @@ -347,13 +351,12 @@ rows: Configuration and device flow authentication credentials are stored in `$XDG_CONFIG_HOME/kongctl/` (typically `~/.config/kongctl/`). - q: Can I use kongctl in CI/CD pipelines? a: | - Yes. kongctl is designed for CI/CD integration: - - * Use personal access tokens for non-interactive authentication - * Generate plan artifacts in pull requests for review before applying changes - * Store plan JSON files in version control for audit trails - * Use namespace isolation to separate environments - * Implement approval gates for production deployments + Yes. Start with the + [GitHub Actions quickstart](/kongctl/ci-cd/github-actions/) + to show configuration diffs in pull requests and apply + changes on pushes to main. The example manages an + {{site.ai_gateway}}, provider, and model using repository + secrets for non-interactive authentication. - q: How is kongctl different from the {{site.konnect_short_name}} APIs? a: | diff --git a/app/kongctl/skills.md b/app/kongctl/skills.md index 28cf212fd98..57e2aede28f 100644 --- a/app/kongctl/skills.md +++ b/app/kongctl/skills.md @@ -18,6 +18,8 @@ breadcrumbs: - /kongctl/ related_resources: + - text: Set up CI/CD with kongctl and GitHub Actions + url: /kongctl/ci-cd/github-actions/ - text: Declarative configuration with kongctl url: /kongctl/declarative/ - text: kongctl install skills @@ -83,6 +85,11 @@ agent: - Work through plan, diff, apply, sync, delete, and adopt workflows. - Scaffold CI/CD workflows for declarative configuration. +For a complete starting point, use the +[GitHub Actions quickstart](/kongctl/ci-cd/github-actions/). It shows diffs in +pull requests and applies changes on main for an {{site.ai_gateway}}, +provider, and model, including GitHub secret configuration. + ### kongctl-extension-builder From 228c136214fe82766348295609dc776054f6fac6 Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Mon, 14 Sep 2026 12:18:00 -0500 Subject: [PATCH 2/9] docs: use AI Gateway substitution in quickstart metadata --- .../konnect-platform/kongctl-ci-cd-github-actions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md index e12836b25dd..d78b2fbbe90 100644 --- a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -1,8 +1,8 @@ --- title: Set up CI/CD with kongctl and GitHub Actions description: >- - Review AI Gateway configuration diffs in pull requests and apply changes - from main with kongctl and GitHub Actions. + Review {{site.ai_gateway}} configuration diffs in pull requests and apply + changes from main with kongctl and GitHub Actions. content_type: how_to permalink: /kongctl/ci-cd/github-actions/ breadcrumbs: @@ -33,7 +33,7 @@ prereqs: content: | You need a {{site.konnect_short_name}} account with access to {{site.ai_gateway}} and a personal or system account access token - with permission to read and manage AI Gateway resources. See + with permission to read and manage {{site.ai_gateway}} resources. See [kongctl authentication](/kongctl/authentication/). icon_url: /assets/icons/gateway.svg - title: GitHub repository and OpenAI key @@ -45,7 +45,7 @@ prereqs: related_resources: - text: Declarative configuration with kongctl url: /kongctl/declarative/ - - text: AI Gateway resource reference + - text: "{{site.ai_gateway}} resource reference" url: /kongctl/supported-resources/#ai-gateway - text: Use kongctl with AI agent skills url: /kongctl/skills/ From 0af0305566360a80bb2a261e79f63c42a2e8e528 Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Mon, 14 Sep 2026 17:32:23 -0500 Subject: [PATCH 3/9] docs: simplify APIOps quickstart around a portal and API --- .../kongctl-ci-cd-github-actions.md | 319 +++++++----------- app/_landing_pages/kongctl.yaml | 8 +- app/kongctl/skills.md | 6 +- 3 files changed, 125 insertions(+), 208 deletions(-) diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md index d78b2fbbe90..9dbdaea296d 100644 --- a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -1,15 +1,15 @@ --- -title: Set up CI/CD with kongctl and GitHub Actions +title: APIOps for Konnect with kongctl and GitHub Actions description: >- - Review {{site.ai_gateway}} configuration diffs in pull requests and apply - changes from main with kongctl and GitHub Actions. + Store Konnect declarative configuration in GitHub, show diffs on pull + requests, and apply changes on pushes to main. content_type: how_to permalink: /kongctl/ci-cd/github-actions/ breadcrumbs: - /kongctl/ products: - konnect - - ai-gateway + - dev-portal works_on: - konnect tools: @@ -18,279 +18,196 @@ min_version: kongctl: '1.15.1' tags: - declarative-config - - ai automated_tests: false tldr: - q: How do I use kongctl in GitHub Actions? + q: How do I set up APIOps for Konnect with kongctl? a: | - Store declarative configuration in Git. Run `kongctl diff --mode apply` - in pull requests, then `kongctl apply --auto-approve` on pushes to main. + Store Konnect declarative configuration in GitHub and deploy a simple + GitHub Actions workflow that shows diffs on pull requests and applies + changes on pushes to main. prereqs: skip_product: false show_works_on: false inline: - title: Konnect access content: | - You need a {{site.konnect_short_name}} account with access to - {{site.ai_gateway}} and a personal or system account access token - with permission to read and manage {{site.ai_gateway}} resources. See - [kongctl authentication](/kongctl/authentication/). + You need a {{site.konnect_short_name}} account and a personal or + system account access token with permission to manage Dev Portals + and APIs. See [kongctl authentication](/kongctl/authentication/). icon_url: /assets/icons/gateway.svg - - title: GitHub repository and OpenAI key + - title: GitHub repository content: | Use a GitHub repository with Actions enabled and a `main` branch. - You need permission to add repository secrets and variables, and an - [OpenAI API key](https://platform.openai.com/api-keys). - icon_url: /assets/icons/ai.svg + You need permission to add repository secrets and variables. + icon_url: /assets/icons/code.svg related_resources: - text: Declarative configuration with kongctl url: /kongctl/declarative/ - - text: "{{site.ai_gateway}} resource reference" - url: /kongctl/supported-resources/#ai-gateway - text: Use kongctl with AI agent skills url: /kongctl/skills/ next_steps: - text: Learn about kongctl sync url: /kongctl/sync/ - - text: Manage write-only secrets - url: /kongctl/declarative/#write-only-secret-fields + - text: Explore Dev Portal + url: /dev-portal/ --- -This quickstart manages one {{site.ai_gateway}}, an OpenAI Model Provider, -and a Model in {{site.konnect_short_name}}. The repository contains three -files: +This quickstart publishes a simple API and its OpenAPI specification to a +Dev Portal. It uses two files: ```text -konnect/ai-gateway.yaml -.github/workflows/kongctl-diff.yaml -.github/workflows/kongctl-apply.yaml +konnect/portal.yaml +.github/workflows/kongctl.yaml ``` -Pull requests display a diff without changing Konnect. Merging into `main` -runs `apply`, which calculates changes against current Konnect state and -executes them. There are no plan artifacts to transfer between workflows. +## Configure GitHub authentication -## Configure repository secrets and variables +In **Settings > Secrets and variables > Actions**, add: -In your GitHub repository, open **Settings > Secrets and variables > Actions**. -Add these repository secrets: +| Type | Name | Value | +| --- | --- | --- | +| Secret | `KONNECT_TOKEN` | Your Konnect access token | +| Variable | `KONNECT_REGION` | Your Konnect region, such as `us` or `eu` | -| Secret | Value | -| --- | --- | -| `KONNECT_TOKEN` | Your Konnect personal or system account access token | -| `OPENAI_API_KEY` | Your OpenAI API key, without the `Bearer ` prefix | +The workflow maps the token to `KONGCTL_DEFAULT_KONNECT_PAT`, so no +interactive login or additional credentials are needed. -On the **Variables** tab, add `KONNECT_REGION` with your Konnect region, such -as `us` or `eu`. Both workflows must use the same region and account. +## Declare the portal and API -The workflows map `KONNECT_TOKEN` to `KONGCTL_DEFAULT_KONNECT_PAT`, so no -interactive `kongctl login` is needed. Only the apply step receives -`OPENAI_API_KEY`. - -Use this example with trusted contributors opening branches in the same -repository. Fork and dependency-bot PRs are skipped because their workflow runs -do not receive repository secrets. See -[Using secrets in GitHub Actions][github-secrets]. - -[github-secrets]: https://docs.github.com/actions/security-guides/encrypted-secrets - -## Declare the gateway, provider, and model - -Create a branch in your repository and add `konnect/ai-gateway.yaml`: +Create a branch and add `konnect/portal.yaml`: ```yaml _defaults: kongctl: - namespace: ai-gateway-cicd - -ai_gateways: - - ref: cicd-ai-gateway - name: cicd-ai-gateway - display_name: CI/CD AI Gateway - description: AI Gateway managed with GitHub Actions - model_providers: - - ref: openai - name: openai - display_name: OpenAI - type: openai - config: - auth: - type: basic - headers: - - name: Authorization - value: !secret - parts: - - "Bearer " - - !env OPENAI_API_KEY - models: - - ref: example-model - name: example-model - display_name: Example Model - type: model - formats: - - type: openai - config: - route: - paths: - - /v1 - model: - body_param: model - values: - - example-model - targets: - - name: gpt-4o - provider: openai - config: - type: openai - capabilities: - - generate + namespace: portal-cicd + +portals: + - ref: example-portal + name: Example Portal + display_name: Example Portal + authentication_enabled: false + default_api_visibility: public + default_page_visibility: public + +apis: + - ref: example-api + name: Example API + description: A simple API managed with GitHub Actions + versions: + - ref: example-api-v1 + version: "1.0.0" + spec: | + openapi: 3.0.3 + info: + title: Example API + version: 1.0.0 + paths: + /hello: + get: + operationId: getHello + responses: + '200': + description: A greeting + publications: + - ref: example-api-publication + portal_id: !ref example-portal#id + visibility: public ``` -Choose a namespace and gateway name unique to this repository before the -first deployment. Keep `name` and `ref` stable in later changes. +Choose names and a namespace unique to this repository before deploying. +The publication's `!ref` links the API to the portal. Portal authentication +is disabled so the published API documentation is publicly accessible. + +The specification is inline to keep the example self-contained. See the +[portal example][ex] for a larger configuration with separate +specification files, pages, and customization. -`!secret` defers reading the OpenAI key until execution. PR diffs do not need -that key and do not display its value. The model targets `gpt-4o` in OpenAI. +[ex]: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/portal -## Show diffs on pull requests +## Add the GitHub Actions workflow -Create `.github/workflows/kongctl-diff.yaml`: +Create `.github/workflows/kongctl.yaml`: {% raw %} ```yaml -name: kongctl diff +name: Konnect APIOps on: pull_request: branches: [main] paths: - konnect/** - - .github/workflows/kongctl-*.yaml + - .github/workflows/kongctl.yaml + push: + branches: [main] + paths: + - konnect/** + - .github/workflows/kongctl.yaml permissions: contents: read +concurrency: + group: kongctl-${{ github.ref }} + cancel-in-progress: false + jobs: - diff: + configure: if: >- - github.event.pull_request.head.repo.full_name == github.repository && - github.actor != 'dependabot[bot]' + github.event_name == 'push' || + (github.event.pull_request.head.repo.full_name == github.repository && + github.actor != 'dependabot[bot]') runs-on: ubuntu-latest + env: + KONGCTL_DEFAULT_KONNECT_PAT: ${{ secrets.KONNECT_TOKEN }} + KONGCTL_DEFAULT_KONNECT_REGION: ${{ vars.KONNECT_REGION }} + NO_COLOR: '1' steps: - uses: actions/checkout@v7 - uses: kong/setup-kongctl@v1 with: kongctl-version: '1.15.1' - - name: Show configuration diff - shell: bash - env: - KONGCTL_DEFAULT_KONNECT_PAT: ${{ secrets.KONNECT_TOKEN }} - KONGCTL_DEFAULT_KONNECT_REGION: ${{ vars.KONNECT_REGION }} - NO_COLOR: '1' + - name: Check configuration run: | : "${KONGCTL_DEFAULT_KONNECT_PAT:?Set the KONNECT_TOKEN secret}" : "${KONGCTL_DEFAULT_KONNECT_REGION:?Set KONNECT_REGION}" - kongctl diff --mode apply -f konnect/ai-gateway.yaml -o text \ + - name: Show diff + if: github.event_name == 'pull_request' + shell: bash + run: | + kongctl diff --mode apply -f konnect/portal.yaml -o text \ --region "$KONGCTL_DEFAULT_KONNECT_REGION" | tee diff.txt echo '## Konnect configuration diff' >> "$GITHUB_STEP_SUMMARY" echo '```text' >> "$GITHUB_STEP_SUMMARY" cat diff.txt >> "$GITHUB_STEP_SUMMARY" echo '```' >> "$GITHUB_STEP_SUMMARY" -``` -{% endraw %} - -`diff` queries live Konnect state, so it requires the Konnect token even -though it does not change any resources. Its output appears in the workflow -logs and summary. A successful run with proposed changes is expected. - -The workflow uses Bash with pipeline failure handling, so a failed `diff` -command fails the check even though its output is piped through `tee`. - -## Apply changes on main - -Create `.github/workflows/kongctl-apply.yaml`: - -{% raw %} -```yaml -name: kongctl apply - -on: - push: - branches: [main] - paths: - - konnect/** - - .github/workflows/kongctl-*.yaml - -permissions: - contents: read - -concurrency: - group: kongctl-apply-main - cancel-in-progress: false - -jobs: - apply: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v7 - - uses: kong/setup-kongctl@v1 - with: - kongctl-version: '1.15.1' - name: Apply configuration - shell: bash - env: - KONGCTL_DEFAULT_KONNECT_PAT: ${{ secrets.KONNECT_TOKEN }} - KONGCTL_DEFAULT_KONNECT_REGION: ${{ vars.KONNECT_REGION }} - OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + if: github.event_name == 'push' run: | - : "${KONGCTL_DEFAULT_KONNECT_PAT:?Set the KONNECT_TOKEN secret}" - : "${KONGCTL_DEFAULT_KONNECT_REGION:?Set KONNECT_REGION}" - : "${OPENAI_API_KEY:?Set the OPENAI_API_KEY secret}" - kongctl apply -f konnect/ai-gateway.yaml --auto-approve -o text \ + kongctl apply -f konnect/portal.yaml --auto-approve -o text \ --region "$KONGCTL_DEFAULT_KONNECT_REGION" ``` {% endraw %} -Both workflows pin kongctl to the same version. When upgrading, update both -pins together. The deployment concurrency group prevents overlapping apply -runs and allows an active apply to finish. - -`--auto-approve` runs without an interactive confirmation. `apply` generates -its own plan from the merged configuration and current Konnect state; the -result can differ from the earlier PR diff if state has changed. - -## Open a PR and deploy - -1. Commit the manifest and both workflow files, then open a PR targeting - `main`. -1. Open the **kongctl diff** check. Follow its **Details** link to the workflow - run and review the diff in the summary. For a new namespace, expect the - gateway, provider, and model to be created, with no plaintext OpenAI key. -1. Merge the PR. Open **Actions > kongctl apply** and check that the run - succeeds. Verify the gateway, provider, and model in your Konnect region. -1. In another branch, change only the gateway's `description`. Open a PR and - confirm the diff shows an update rather than a new gateway. Merge it and - verify the updated description in Konnect. -1. Re-run the successful apply job without changing the configuration. - Expect no further configuration changes. - -Every matching push to `main` deploys, including direct pushes. Use your -repository's branch rules if all changes must go through PR review. +Use trusted branches in the same repository. The workflow skips fork and +dependency-bot PRs because they lack repository secrets. The concurrency +group prevents overlapping deployments to `main`. -## Understand the update behavior +`diff` reads live Konnect state and displays proposed changes without +applying them. On a push to `main`, `apply` calculates a fresh plan and +executes it without prompting. -`apply` creates and updates resources. Removing an entry from the manifest -does not delete it from Konnect. See [kongctl sync](/kongctl/sync/) when you -need deletion-based reconciliation. +## Review and deploy -The provider key is written when the provider is created. Changing the -GitHub secret does not trigger a workflow and an ordinary apply does not -rotate an existing write-only credential. Use explicit secret-write -selection when rotating credentials; see -[Write-only secret fields](/kongctl/declarative/#write-only-secret-fields). +1. Commit both files and open a PR targeting `main`. Open the **Konnect + APIOps** workflow run and review the diff in its summary. +1. Merge the PR. Check that the **Apply configuration** step succeeds, then + open your Dev Portal in Konnect and verify the published API and spec. +1. In a new PR, change the API's `description`. Review the update in the + diff, merge, and verify the change. Re-running the apply job without + changing configuration should produce no further changes. -If a check fails, verify the repository secret names, region variable, token -permissions, and {{site.ai_gateway}} access. For an existing gateway managed -outside this repository, follow -[adoption guidance](/kongctl/adopt/ai-gateway/) before using it in this -configuration. +Every matching push to `main` deploys, including direct pushes. Use branch +rules if all changes must go through PR review. `apply` creates and updates +resources; use [sync](/kongctl/sync/) when you want removed declarations to +delete resources. diff --git a/app/_landing_pages/kongctl.yaml b/app/_landing_pages/kongctl.yaml index 0824141edb3..2d44ccdadf3 100644 --- a/app/_landing_pages/kongctl.yaml +++ b/app/_landing_pages/kongctl.yaml @@ -35,8 +35,8 @@ rows: kongctl also ships installable AI agent skills that help coding agents generate, review, and operate kongctl configuration from a repository. **[CI/CD with GitHub Actions](/kongctl/ci-cd/github-actions/)**: - Follow the quickstart to review {{site.ai_gateway}} diffs in - pull requests and apply changes on main. + Follow the quickstart to publish an API to a Dev Portal, review + diffs in pull requests, and apply changes on main. kongctl is one of multiple tools you can use to manage {{site.konnect_short_name}} and {{site.base_gateway}}. To learn about other tools, see the [tools page](/tools/). @@ -355,8 +355,8 @@ rows: [GitHub Actions quickstart](/kongctl/ci-cd/github-actions/) to show configuration diffs in pull requests and apply changes on pushes to main. The example manages an - {{site.ai_gateway}}, provider, and model using repository - secrets for non-interactive authentication. + Dev Portal and API using a Konnect token stored in a + repository secret for non-interactive authentication. - q: How is kongctl different from the {{site.konnect_short_name}} APIs? a: | diff --git a/app/kongctl/skills.md b/app/kongctl/skills.md index 57e2aede28f..638ec834ae4 100644 --- a/app/kongctl/skills.md +++ b/app/kongctl/skills.md @@ -18,7 +18,7 @@ breadcrumbs: - /kongctl/ related_resources: - - text: Set up CI/CD with kongctl and GitHub Actions + - text: APIOps for Konnect with kongctl and GitHub Actions url: /kongctl/ci-cd/github-actions/ - text: Declarative configuration with kongctl url: /kongctl/declarative/ @@ -87,8 +87,8 @@ agent: For a complete starting point, use the [GitHub Actions quickstart](/kongctl/ci-cd/github-actions/). It shows diffs in -pull requests and applies changes on main for an {{site.ai_gateway}}, -provider, and model, including GitHub secret configuration. +pull requests and applies changes on main for a Dev Portal and an API with +an inline OpenAPI specification. ### kongctl-extension-builder From a36c475336f7bfc666a3aca4111c3d4915cbe6b2 Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Tue, 15 Sep 2026 12:02:35 -0500 Subject: [PATCH 4/9] docs: streamline APIOps setup instructions --- .../kongctl-ci-cd-github-actions.md | 23 ++++++++----------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md index 9dbdaea296d..66f817db132 100644 --- a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -53,12 +53,7 @@ next_steps: --- This quickstart publishes a simple API and its OpenAPI specification to a -Dev Portal. It uses two files: - -```text -konnect/portal.yaml -.github/workflows/kongctl.yaml -``` +Dev Portal. ## Configure GitHub authentication @@ -69,18 +64,19 @@ In **Settings > Secrets and variables > Actions**, add: | Secret | `KONNECT_TOKEN` | Your Konnect access token | | Variable | `KONNECT_REGION` | Your Konnect region, such as `us` or `eu` | -The workflow maps the token to `KONGCTL_DEFAULT_KONNECT_PAT`, so no -interactive login or additional credentials are needed. +## Create a branch + +In your local repository, create a branch for all the files in this guide: + +```sh +git switch -c konnect-apiops +``` ## Declare the portal and API -Create a branch and add `konnect/portal.yaml`: +On this branch, create `konnect/portal.yaml`: ```yaml -_defaults: - kongctl: - namespace: portal-cicd - portals: - ref: example-portal name: Example Portal @@ -114,7 +110,6 @@ apis: visibility: public ``` -Choose names and a namespace unique to this repository before deploying. The publication's `!ref` links the API to the portal. Portal authentication is disabled so the published API documentation is publicly accessible. From ddb0eede63b3ff6aa486200ce25e368b7b70f510 Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Thu, 17 Sep 2026 10:41:54 -0500 Subject: [PATCH 5/9] docs: clarify APIOps setup and update walkthrough --- .../kongctl-ci-cd-github-actions.md | 87 ++++++++++++++----- 1 file changed, 67 insertions(+), 20 deletions(-) diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md index 66f817db132..75b1b8dd6e6 100644 --- a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -33,7 +33,11 @@ prereqs: content: | You need a {{site.konnect_short_name}} account and a personal or system account access token with permission to manage Dev Portals - and APIs. See [kongctl authentication](/kongctl/authentication/). + and APIs. To get started easily, use a token for an account in the + **Organization Admin** team. See + [Konnect teams and roles](/konnect-platform/teams-and-roles/) + for permissions and + [kongctl authentication](/kongctl/authentication/) for token setup. icon_url: /assets/icons/gateway.svg - title: GitHub repository content: | @@ -52,12 +56,13 @@ next_steps: url: /dev-portal/ --- -This quickstart publishes a simple API and its OpenAPI specification to a -Dev Portal. +This quickstart builds a CI/CD pipeline to deliver a simple API and its +OpenAPI specification to a Dev Portal using GitOps and GitHub Actions. ## Configure GitHub authentication -In **Settings > Secrets and variables > Actions**, add: +In your GitHub repository's web interface, go to +**Settings > Secrets and variables > Actions** and add: | Type | Name | Value | | --- | --- | --- | @@ -66,7 +71,8 @@ In **Settings > Secrets and variables > Actions**, add: ## Create a branch -In your local repository, create a branch for all the files in this guide: +On your development machine, clone your GitHub repository if necessary +and change into its directory. Create a new branch to build this example: ```sh git switch -c konnect-apiops @@ -74,7 +80,14 @@ git switch -c konnect-apiops ## Declare the portal and API -On this branch, create `konnect/portal.yaml`: +Create the configuration directory if it doesn't already exist: + +```sh +mkdir -p konnect +``` + +On your new branch, create a file `konnect/portal.yaml` with the following +kongctl resource definitions: ```yaml portals: @@ -113,7 +126,8 @@ apis: The publication's `!ref` links the API to the portal. Portal authentication is disabled so the published API documentation is publicly accessible. -The specification is inline to keep the example self-contained. See the +The API specification is inline to keep the example simple and +self-contained. See the [portal example][ex] for a larger configuration with separate specification files, pages, and customization. @@ -121,7 +135,14 @@ specification files, pages, and customization. ## Add the GitHub Actions workflow -Create `.github/workflows/kongctl.yaml`: +Create the workflows directory if it doesn't already exist: + +```sh +mkdir -p .github/workflows +``` + +Create a file `.github/workflows/konnect.yaml` with the following GitHub +Actions workflow definition: {% raw %} ```yaml @@ -132,18 +153,18 @@ on: branches: [main] paths: - konnect/** - - .github/workflows/kongctl.yaml + - .github/workflows/konnect.yaml push: branches: [main] paths: - konnect/** - - .github/workflows/kongctl.yaml + - .github/workflows/konnect.yaml permissions: contents: read concurrency: - group: kongctl-${{ github.ref }} + group: konnect-${{ github.ref }} cancel-in-progress: false jobs: @@ -184,13 +205,21 @@ jobs: ``` {% endraw %} -Use trusted branches in the same repository. The workflow skips fork and -dependency-bot PRs because they lack repository secrets. The concurrency -group prevents overlapping deployments to `main`. +This workflow runs PR checks for branches in the same GitHub repository. +Contributors who can push to these branches can modify workflows that use +your Konnect token, so give that access only to people you trust. The +workflow skips PRs from forks and `dependabot[bot]`, which don't receive the +repository's Actions secrets. -`diff` reads live Konnect state and displays proposed changes without -applying them. On a push to `main`, `apply` calculates a fresh plan and -executes it without prompting. +The workflow has two behaviors: + +- **Pull requests targeting `main`:** `kongctl diff` compares the proposed + configuration with live Konnect state. It shows the changes in the + workflow summary for review without applying them. +- **Pushes to `main`:** `kongctl apply` calculates a fresh plan from live + Konnect state and executes it without prompting. This plan reflects the + state at deployment time, which may have changed since the PR diff. + The concurrency group prevents overlapping deployments to `main`. ## Review and deploy @@ -198,11 +227,29 @@ executes it without prompting. APIOps** workflow run and review the diff in its summary. 1. Merge the PR. Check that the **Apply configuration** step succeeds, then open your Dev Portal in Konnect and verify the published API and spec. -1. In a new PR, change the API's `description`. Review the update in the - diff, merge, and verify the change. Re-running the apply job without - changing configuration should produce no further changes. Every matching push to `main` deploys, including direct pushes. Use branch rules if all changes must go through PR review. `apply` creates and updates resources; use [sync](/kongctl/sync/) when you want removed declarations to delete resources. + +## Update the API + +1. On your development machine, switch to `main`, pull the merged changes, + and create a new branch: + + ```sh + git switch main + git pull --ff-only + git switch -c update-example-api + ``` + +1. In `konnect/portal.yaml`, change the API's `description` to + `An example API deployed with GitOps`. +1. Commit the change, push your branch, and open a PR targeting `main`. + Open the **Konnect APIOps** workflow run and check that the summary + shows an update to the API description. +1. Merge the PR and check that the **Apply configuration** step succeeds. + Open your Dev Portal and verify that the API description has changed. +1. Re-run the apply job without changing the configuration. It should + report no further changes. From 2c2f6ab497598cbbfdc6053a7185def344adc12f Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Thu, 17 Sep 2026 11:17:04 -0500 Subject: [PATCH 6/9] docs: use shared kongctl version and post PR diffs --- .../kongctl-ci-cd-github-actions.md | 49 +++++++++++++------ 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md index 75b1b8dd6e6..4a80c10c4b3 100644 --- a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -14,8 +14,6 @@ works_on: - konnect tools: - kongctl -min_version: - kongctl: '1.15.1' tags: - declarative-config automated_tests: false @@ -27,6 +25,7 @@ tldr: changes on pushes to main. prereqs: skip_product: false + skip_tool: true show_works_on: false inline: - title: Konnect access @@ -144,6 +143,11 @@ mkdir -p .github/workflows Create a file `.github/workflows/konnect.yaml` with the following GitHub Actions workflow definition: +The workflow installs kongctl on the runner. The version below comes from +the docs site's shared release data and is an explicit version when you +copy it. Update `kongctl-version` in your repository when you're ready to +upgrade; existing workflows keep using the version you copied. + {% raw %} ```yaml name: Konnect APIOps @@ -162,6 +166,7 @@ on: permissions: contents: read + pull-requests: write concurrency: group: konnect-${{ github.ref }} @@ -182,7 +187,8 @@ jobs: - uses: actions/checkout@v7 - uses: kong/setup-kongctl@v1 with: - kongctl-version: '1.15.1' + kongctl-version: >- + {% endraw %}{{site.data.kongctl_latest.version}}{% raw %} - name: Check configuration run: | : "${KONGCTL_DEFAULT_KONNECT_PAT:?Set the KONNECT_TOKEN secret}" @@ -193,10 +199,19 @@ jobs: run: | kongctl diff --mode apply -f konnect/portal.yaml -o text \ --region "$KONGCTL_DEFAULT_KONNECT_REGION" | tee diff.txt - echo '## Konnect configuration diff' >> "$GITHUB_STEP_SUMMARY" - echo '```text' >> "$GITHUB_STEP_SUMMARY" - cat diff.txt >> "$GITHUB_STEP_SUMMARY" - echo '```' >> "$GITHUB_STEP_SUMMARY" + { + echo '## Konnect configuration diff' + echo '```text' + cat diff.txt + echo '```' + } > comment.md + cat comment.md >> "$GITHUB_STEP_SUMMARY" + - name: Post diff comment + if: github.event_name == 'pull_request' + uses: marocchino/sticky-pull-request-comment@v2 + with: + header: konnect-diff + path: comment.md - name: Apply configuration if: github.event_name == 'push' run: | @@ -215,7 +230,9 @@ The workflow has two behaviors: - **Pull requests targeting `main`:** `kongctl diff` compares the proposed configuration with live Konnect state. It shows the changes in the - workflow summary for review without applying them. + workflow summary and a PR comment for review without applying them. + Each successful diff run updates the same comment. The + `pull-requests: write` permission lets the workflow post this comment. - **Pushes to `main`:** `kongctl apply` calculates a fresh plan from live Konnect state and executes it without prompting. This plan reflects the state at deployment time, which may have changed since the PR diff. @@ -223,8 +240,8 @@ The workflow has two behaviors: ## Review and deploy -1. Commit both files and open a PR targeting `main`. Open the **Konnect - APIOps** workflow run and review the diff in its summary. +1. Commit both files, push your branch, and open a PR targeting `main`. + Review the diff comment posted by the **Konnect APIOps** workflow. 1. Merge the PR. Check that the **Apply configuration** step succeeds, then open your Dev Portal in Konnect and verify the published API and spec. @@ -247,9 +264,13 @@ delete resources. 1. In `konnect/portal.yaml`, change the API's `description` to `An example API deployed with GitOps`. 1. Commit the change, push your branch, and open a PR targeting `main`. - Open the **Konnect APIOps** workflow run and check that the summary - shows an update to the API description. + Check that the **Konnect APIOps** diff comment shows an update to the + API description. 1. Merge the PR and check that the **Apply configuration** step succeeds. Open your Dev Portal and verify that the API description has changed. -1. Re-run the apply job without changing the configuration. It should - report no further changes. +1. In your GitHub repository's **Actions** tab, open the **Konnect APIOps** + run triggered by the merge's push to `main`. Select **Re-run all jobs** + and confirm the re-run. The **Apply configuration** step should report + no further changes if the configuration and live state are unchanged. + This repeats the existing push run; it doesn't require a + `workflow_dispatch` trigger. From e9b72ecb9176f1b024eb80a2eaf8e9775c9b66ff Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Thu, 17 Sep 2026 11:24:15 -0500 Subject: [PATCH 7/9] docs: spell out pull requests for Vale --- app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md index 4a80c10c4b3..c1d8659eeb5 100644 --- a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -223,8 +223,8 @@ jobs: This workflow runs PR checks for branches in the same GitHub repository. Contributors who can push to these branches can modify workflows that use your Konnect token, so give that access only to people you trust. The -workflow skips PRs from forks and `dependabot[bot]`, which don't receive the -repository's Actions secrets. +workflow skips pull requests from forks and `dependabot[bot]`, which don't +receive the repository's Actions secrets. The workflow has two behaviors: From 79901eed8bafbcd23e8466f4b405787010dc46f4 Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Thu, 17 Sep 2026 11:51:38 -0500 Subject: [PATCH 8/9] docs: streamline APIOps guide and add manual apply --- .../kongctl-ci-cd-github-actions.md | 90 ++++++++++--------- 1 file changed, 48 insertions(+), 42 deletions(-) diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md index c1d8659eeb5..8f615dda484 100644 --- a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -40,7 +40,8 @@ prereqs: icon_url: /assets/icons/gateway.svg - title: GitHub repository content: | - Use a GitHub repository with Actions enabled and a `main` branch. + Use a GitHub repository with Actions enabled and `main` as its + default branch. You need permission to add repository secrets and variables. icon_url: /assets/icons/code.svg related_resources: @@ -58,6 +59,9 @@ next_steps: This quickstart builds a CI/CD pipeline to deliver a simple API and its OpenAPI specification to a Dev Portal using GitOps and GitHub Actions. +Use a test Konnect organization: this example creates a Dev Portal and API +with publicly accessible API documentation. + ## Configure GitHub authentication In your GitHub repository's web interface, go to @@ -122,13 +126,11 @@ apis: visibility: public ``` -The publication's `!ref` links the API to the portal. Portal authentication -is disabled so the published API documentation is publicly accessible. - -The API specification is inline to keep the example simple and -self-contained. See the -[portal example][ex] for a larger configuration with separate -specification files, pages, and customization. +This configuration defines a Dev Portal, an API with an inline OpenAPI +specification, and a publication that makes the API available in the +portal. The publication's `!ref` links it to the portal. Authentication is +disabled so anyone can read the API documentation. See the +[portal example][ex] for separate specification files and customization. [ex]: https://github.com/Kong/kongctl/tree/main/docs/examples/declarative/portal @@ -143,16 +145,12 @@ mkdir -p .github/workflows Create a file `.github/workflows/konnect.yaml` with the following GitHub Actions workflow definition: -The workflow installs kongctl on the runner. The version below comes from -the docs site's shared release data and is an explicit version when you -copy it. Update `kongctl-version` in your repository when you're ready to -upgrade; existing workflows keep using the version you copied. - {% raw %} ```yaml name: Konnect APIOps on: + workflow_dispatch: pull_request: branches: [main] paths: @@ -175,8 +173,11 @@ concurrency: jobs: configure: if: >- - github.event_name == 'push' || - (github.event.pull_request.head.repo.full_name == github.repository && + ((github.event_name == 'push' || + github.event_name == 'workflow_dispatch') && + github.ref == 'refs/heads/main') || + (github.event_name == 'pull_request' && + github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') runs-on: ubuntu-latest env: @@ -213,37 +214,43 @@ jobs: header: konnect-diff path: comment.md - name: Apply configuration - if: github.event_name == 'push' + if: >- + github.ref == 'refs/heads/main' && + (github.event_name == 'push' || + github.event_name == 'workflow_dispatch') run: | kongctl apply -f konnect/portal.yaml --auto-approve -o text \ --region "$KONGCTL_DEFAULT_KONNECT_REGION" ``` {% endraw %} -This workflow runs PR checks for branches in the same GitHub repository. -Contributors who can push to these branches can modify workflows that use -your Konnect token, so give that access only to people you trust. The -workflow skips pull requests from forks and `dependabot[bot]`, which don't -receive the repository's Actions secrets. +The workflow installs the pinned kongctl version and: + +- **On pull requests targeting `main`:** compares configuration with live + Konnect state and posts a diff in the summary and an updating PR comment. + It doesn't apply changes. `pull-requests: write` allows the comment. +- **On pushes or manual runs on `main`:** calculates a fresh plan and + applies it without prompting. Concurrency prevents overlapping applies. + Manual runs on other branches are skipped. -The workflow has two behaviors: +Only give trusted contributors branch access: they can edit workflows +that use your Konnect token. Fork and dependency-bot pull requests are +skipped because they don't receive repository secrets. -- **Pull requests targeting `main`:** `kongctl diff` compares the proposed - configuration with live Konnect state. It shows the changes in the - workflow summary and a PR comment for review without applying them. - Each successful diff run updates the same comment. The - `pull-requests: write` permission lets the workflow post this comment. -- **Pushes to `main`:** `kongctl apply` calculates a fresh plan from live - Konnect state and executes it without prompting. This plan reflects the - state at deployment time, which may have changed since the PR diff. - The concurrency group prevents overlapping deployments to `main`. +The version comes from the docs site's shared release data when the page +is built. Your copied workflow stays pinned; update `kongctl-version` +when you're ready to upgrade. ## Review and deploy 1. Commit both files, push your branch, and open a PR targeting `main`. - Review the diff comment posted by the **Konnect APIOps** workflow. -1. Merge the PR. Check that the **Apply configuration** step succeeds, then - open your Dev Portal in Konnect and verify the published API and spec. + Wait for the **Konnect APIOps** workflow to finish, then review its diff + comment. +1. Merge the PR. In **Actions**, open the **Konnect APIOps** run for the + push to `main`, then open **configure > Apply configuration**. Expect + four creates in the `default` namespace: `portal`, `api`, `api_version`, + and `api_publication`, followed by successful creation messages. Open + your Dev Portal in Konnect and verify the published API and spec. Every matching push to `main` deploys, including direct pushes. Use branch rules if all changes must go through PR review. `apply` creates and updates @@ -264,13 +271,12 @@ delete resources. 1. In `konnect/portal.yaml`, change the API's `description` to `An example API deployed with GitOps`. 1. Commit the change, push your branch, and open a PR targeting `main`. - Check that the **Konnect APIOps** diff comment shows an update to the - API description. + Wait for the **Konnect APIOps** workflow to finish, then check that its + diff comment shows an update to the API description. 1. Merge the PR and check that the **Apply configuration** step succeeds. Open your Dev Portal and verify that the API description has changed. -1. In your GitHub repository's **Actions** tab, open the **Konnect APIOps** - run triggered by the merge's push to `main`. Select **Re-run all jobs** - and confirm the re-run. The **Apply configuration** step should report - no further changes if the configuration and live state are unchanged. - This repeats the existing push run; it doesn't require a - `workflow_dispatch` trigger. +1. In your GitHub repository's **Actions** tab, select **Konnect APIOps**, + click **Run workflow**, select the `main` branch, and confirm with + **Run workflow**. When the run completes, open + **configure > Apply configuration**. It should report no further + changes if the configuration and live state are unchanged. From e7b9108f79942b04d0b6d7f01d6b264bfc62fa80 Mon Sep 17 00:00:00 2001 From: Rick Spurgeon <10521262+rspurgeon@users.noreply.github.com> Date: Thu, 17 Sep 2026 23:04:16 -0500 Subject: [PATCH 9/9] docs: clarify quickstart access requirements --- .../kongctl-ci-cd-github-actions.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md index 8f615dda484..59d66c7fa96 100644 --- a/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md +++ b/app/_how-tos/konnect-platform/kongctl-ci-cd-github-actions.md @@ -32,17 +32,20 @@ prereqs: content: | You need a {{site.konnect_short_name}} account and a personal or system account access token with permission to manage Dev Portals - and APIs. To get started easily, use a token for an account in the - **Organization Admin** team. See - [Konnect teams and roles](/konnect-platform/teams-and-roles/) - for permissions and + and APIs. For this quickstart in a test organization, an account + in the **Organization Admin** team is an easy way to get started. + For production, follow least privilege: assign only the + [API roles](/konnect-platform/teams-and-roles/#apis) and + [Dev Portal roles](/konnect-platform/teams-and-roles/#portals) + your workflow needs. See [kongctl authentication](/kongctl/authentication/) for token setup. icon_url: /assets/icons/gateway.svg - title: GitHub repository content: | Use a GitHub repository with Actions enabled and `main` as its default branch. - You need permission to add repository secrets and variables. + You need permission to add repository secrets and variables, + create branches and pull requests, and merge them into `main`. icon_url: /assets/icons/code.svg related_resources: - text: Declarative configuration with kongctl