GitHub Workflows

Shared GitHub workflows and actions for ConductorOne connector repositories.

CA Trust Guard

Use the CA Trust Guard action as a job's first step for offline incident-chain checks, fingerprint-checked OS denial and a committed clean-bundle environment. No caller checkout is needed.

PR Review Workflow

Runs Claude-powered PR review for same-repository pull requests. Fork PRs are skipped because they do not receive automatic Claude review. The action builds its prompt from a shared base prompt plus optional built-in mixins, and CI — not the model — publishes the report, submits the formal review, and clears the reviewer's own previous blocks once they are resolved. See detailed documentation for the prompt layers, block clearing, publication guarantees, and custom review criteria.

The default profile is connector. Repos that need non-connector review can use the general-pr-review.yaml required workflow, or reusable workflow callers can pass review_prompt: general.

Reusable Workflow Calls

Callers of pr-review.yaml must pass ANTHROPIC_API_KEY as a named secret; do not inherit unrelated secrets. The called workflow uses the caller's existing GITHUB_TOKEN and declared review permissions.

These are pr-review.yaml's inputs. general-pr-review.yaml declares none — it takes the ANTHROPIC_API_KEY secret and nothing else.

Input	Default	Purpose
review_prompt	connector	Which built-in mixin to add: connector or general.
summary_marker	"" (the profile's heading)	Override the review summary heading. Must be a single-line ### ...: Markdown heading and may not embed a reserved one — the action validates this and fails the job otherwise. See Reusable workflow calls.

Release Workflow

Handles building, signing, and publishing connector releases. See detailed documentation for security properties and internals.

Usage

1. Create a .github/workflows/release.yaml file with the following content:

name: Release

on:
  push:
    tags:
      - "*"

jobs:
  release:
    uses: ConductorOne/github-workflows/.github/workflows/release.yaml@v4
    with:
      tag: ${{ github.ref_name }}
    secrets:
      RELENG_GITHUB_TOKEN: ${{ secrets.RELENG_GITHUB_TOKEN }}
      APPLE_SIGNING_KEY_P12: ${{ secrets.APPLE_SIGNING_KEY_P12 }}
      APPLE_SIGNING_KEY_P12_PASSWORD: ${{ secrets.APPLE_SIGNING_KEY_P12_PASSWORD }}
      AC_PASSWORD: ${{ secrets.AC_PASSWORD }}
      AC_PROVIDER: ${{ secrets.AC_PROVIDER }}
      DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY }}
      GORELEASER_PRO_KEY: ${{ secrets.GORELEASER_PRO_KEY }}

The release workflow accepts the following input parameters:

Parameter	Required	Default	Description
tag	Yes	-	The release tag (must be valid semver with v prefix, e.g., v1.0.0)
release_storage_name	No	""	Optional S3 release path segment matching ^[a-z][a-z0-9-]{0,99}$; defaults to the repository name
go_main_package	No	""	Relative Go main package. Defaults to ./cmd/<repository-name>; use ./ for a root command package.
brew_tap	No	homebrew-baton	ConductorOne Homebrew tap repository name. Must not contain a path separator.
go_source_hygiene	No	false	Run go generate ./... and go mod tidy; fail if either changes the tagged source tree.
go_vulnerability_scan	No	false	Run govulncheck for Linux, macOS, and Windows before release.
verify_module_version	No	false	Require a generated binary to embed the release tag as its Go module version.
lambda	No	true	Whether to release with Lambda image support
docker	No	true	Whether to release with Docker image support
dockerfile_template	No	""	Path to a custom Dockerfile in your repo (only valid when lambda: false)
docker_extra_files	No	""	Comma-separated list of extra files/dirs to include in Docker build context
msi	No	true	Whether to build MSI Windows installers
msi_wxs_path	No	""	Path to custom WXS template for MSI installer (uses default if not set)
windows_pre_build_script	No	""	Optional safe repo-relative Bash script, run in the caller checkout by GoReleaser before Windows compilation with RELEASE_TAG set to the requested tag.
brew	No	true	Whether to publish a Homebrew formula to the selected public conductorone tap

2. Ensure your repository has the following secrets configured:

   • RELENG_GITHUB_TOKEN: A GitHub token with permissions to create releases
   • APPLE_SIGNING_KEY_P12: Base64-encoded Apple signing key
   • APPLE_SIGNING_KEY_P12_PASSWORD: Password for the Apple signing key
   • AC_PASSWORD: Apple Connect password
   • AC_PROVIDER: Apple Connect provider
   • DATADOG_API_KEY: Datadog API key for monitoring releases
   • GORELEASER_PRO_KEY: GoReleaser Pro license key (required when msi: true, the default)

3. Remove all GoReleaser, gon files, Dockerfile, and Dockerfile.lambda files from your connector repository, if they were previously created there.

Custom Dockerfiles

For connectors that require a non-standard base image (e.g., Java runtime), you can provide a custom Dockerfile:

jobs:
  release:
    uses: ConductorOne/github-workflows/.github/workflows/release.yaml@v4
    with:
      tag: ${{ github.ref_name }}
      lambda: false
      dockerfile_template: Dockerfile
      docker_extra_files: java # Include the java/ directory in the build context
    secrets:
      # ... secrets ...

Your custom Dockerfile must:

1. Use ARG TARGETPLATFORM for multi-arch build support and pin every base image to a reviewed multi-arch index digest
2. Copy the binary from ${TARGETPLATFORM}/<connector-name>

Example for a Java-based connector:

FROM gcr.io/distroless/java17-debian13:nonroot@sha256:3b74f9967f1674f49c3b7bd0fc3355e4d8591f8f98b9eed020ff9ca8f5bdb38d
ARG TARGETPLATFORM
ENTRYPOINT ["/baton-example"]

COPY ${TARGETPLATFORM}/baton-example /baton-example
COPY java /java

The workflow substitutes ${REPO_NAME} in your Dockerfile if present, so you can also use:

COPY ${TARGETPLATFORM}/${REPO_NAME} /${REPO_NAME}

Note: Use docker_extra_files to include additional files or directories (comma-separated) in the Docker build context. These are paths relative to your connector repository root.

Custom MSI Installers

By default, the workflow builds a simple MSI installer that:

• Installs the binary to C:\Program Files\ConductorOne\<connector-name>
• Adds the installation directory to the system PATH

For connectors that require custom MSI behavior (Windows Service, registry keys, etc.), provide a custom WXS template:

jobs:
  release:
    uses: ConductorOne/github-workflows/.github/workflows/release.yaml@v4
    with:
      tag: ${{ github.ref_name }}
      msi_wxs_path: ci/app.wxs
    secrets:
      # ... secrets ...

Your custom WXS template can use GoReleaser template variables:

• {{ .ProjectName }} - Connector name (e.g., "baton-okta")
• {{ .Binary }} - Binary name without extension
• {{ .Version }} - Full version string
• {{ .Major }}, {{ .Minor }}, {{ .Patch }} - Version components

The ${UPGRADE_CODE} placeholder is automatically replaced with a deterministic UUID v5 generated from the repository name, ensuring consistent upgrade behavior across versions.

See baton-runner/ci/app.wxs for an example Windows Service installer.

To disable MSI builds entirely (e.g., for connectors that don't need Windows installers):

    with:
      tag: ${{ github.ref_name }}
      msi: false

When msi: false, the GORELEASER_PRO_KEY secret is not required.

Windows Pre-build Script

Connectors that generate Windows-specific resources from the release tag can opt in:

    with:
      tag: ${{ github.ref_name }}
      windows_pre_build_script: scripts/release-windows-resources.sh

The script must exist as a file in the tagged caller repository. Paths must use only letters, digits, ., _, /, and -, and must not be absolute or contain .. or whitespace. GoReleaser runs bash ./<path> in _caller as a before.hooks command, after its normal clean-tree/tag validation and before Windows compilation. The hook receives the validated workflow tag as RELEASE_TAG; a failing hook fails the Windows release.

This is Windows-only and opt-in: an empty input leaves the rendered Windows config unchanged and does not run any generation. macOS, Linux, and Docker builds do not run this hook. Keep connector-specific generation in the caller's script; do not skip release validation, use snapshots, retag, or commit generated resources during release.

Verify Workflow

Runs linting, tests, and optional regression verification. See detailed documentation for jobs, regression testing, and all options.

Usage

name: Verify

on:
  pull_request:
    types: [opened, reopened, synchronize]
  push:
    branches:
      - main

jobs:
  verify:
    uses: ConductorOne/github-workflows/.github/workflows/verify.yaml@v4
    with:
      ref: ${{ github.event.pull_request.head.sha || github.sha }}
      connector: baton-okta  # optional: enables regression testing
    secrets:
      RELENG_GITHUB_TOKEN: ${{ secrets.RELENG_GITHUB_TOKEN }}

Parameter	Required	Default	Description
ref	Yes	-	Git ref to check out and verify
run_tests	No	true	Run go test
connector	No	""	Connector name — triggers regression testing when set

Connector Docs Verify Workflow

Runs a standalone docs/connector.mdx validation check for connector repositories. See detailed documentation for behavior and rollout notes.

The workflow is safe to require on every connector pull request because it always reports a status. It skips validation when docs/connector.mdx is unchanged, fails if that file was changed and removed, and validates MDX safety when the file changed.

The reusable workflow checks out its own validator at the exact workflow commit, installs locked dependencies with npm lifecycle scripts disabled, and checks out caller code without persisted credentials.

Usage

name: Connector Docs

on:
  pull_request:
    types: [opened, reopened, synchronize]
  push:
    branches:
      - main

jobs:
  connector-docs:
    uses: ConductorOne/github-workflows/.github/workflows/connector-docs-verify.yaml@v4
    with:
      ref: ${{ github.event.pull_request.head.sha || github.sha }}

When used with the job id connector-docs, the required status check context is connector-docs / validate.

Roll out the caller workflow before marking the check required. The shared workflow ref, such as v4, must include connector-docs-verify.yaml before connector repos call it.

Available Actions

Get Baton

The get-baton action downloads the latest version of Baton and installs it to /usr/local/bin/baton.

- name: Install baton
  uses: ConductorOne/github-workflows/actions/get-baton@v4

You can then use the baton command in your workflow.

Sync Test

The sync-test action tests syncing, granting, and revoking for a baton connector.

Before the grant/revoke cycle it also syncs once with deliberately invalid credentials and asserts the connector exits with gRPC Unauthenticated (16) or PermissionDenied (7). That mapping requires exit.LogExit from baton-sdk v0.25.0+; connectors that still os.Exit(1) skip this check. Dummy values default to invalid for credential-like BATON_* env vars (tokens, passwords, secrets, keys). Override with bad-credentials when the value must parse as JWT, PEM, JSON, or similar before the connector will attempt authentication.

- name: Test Connector Sync
  uses: ConductorOne/github-workflows/actions/sync-test@v4
  with:
    connector: "./my-connector"
    baton-entitlement: "admin-role"
    baton-principal: "user123"
    baton-principal-type: "user"
    sleep: 2 # optional, wait 2 seconds after each write operation
    # optional, only needed when dummy credentials must be well-formed:
    # bad-credentials: |
    #   BATON_PRIVATE_KEY=-----BEGIN PRIVATE KEY----- invalid -----END PRIVATE KEY-----

Account Provisioning Test

The account-provisioning action tests account provisioning and deprovisioning for a baton connector that supports these capabilities.

- name: Test Account Provisioning
  uses: ConductorOne/github-workflows/actions/account-provisioning@v4
  with:
    connector: "./my-connector"
    account-email: "test@example.com"
    account-login: "testuser" # optional
    account-display-name: "Test User" # optional
    account-profile: '{"first_name": "Test", "last_name": "User", "username": "testuser", "email": "test@example.com"}' # optional
    account-type: "user" # optional, defaults to 'user'
    search-method: "email" # optional, defaults to 'email'
    sleep: 2 # optional, wait 2 seconds after each write operation

Account Status Lifecycle Test

The account-status-lifecycle-test action tests disabling and enabling account status changes for a baton connector.

Usage

- name: Test Account Status Changes
  uses: ConductorOne/github-workflows/actions/account-status-lifecycle-test@v3
  with:
    connector: "./my-connector"
    account-id: "user-12345"
    enable-action-name: "enable_user" # optional, defaults to 'enable_user'
    disable-action-name: "disable_user" # optional, defaults to 'disable_user'
    id-parameter-name: "user_id" # optional, defaults to 'user_id'
    test-flow: "disable-enable" # optional, defaults to 'disable-enable'
    sleep: 2 # optional, wait 2 seconds after each write operation

The test-flow parameter can be:

• disable-enable: Disable the account, then enable it (default)
• enable-disable: Enable the account, then disable it
• enable-only: Only test enabling the account
• disable-only: Only test disabling the account

Development

make test runs this repository's own Go tests and script tests, including the pr-review Python suite under .github/actions/pr-review/scripts. ci.yaml ("Repository CI") covers the same ground on pull requests and pushes to main, though not through make: its go-tests job runs go vet ./... and go test ./... directly, and its shell-tests job runs make test-scripts.

Running them locally needs kislyuk's Python/jq yq — apt install yq or pip install yq — not the more common Go yq from mikefarah. Several script tests pipe yq output into json.loads, which only works with the Python one; with the Go build they fail with a JSONDecodeError. ci.yaml installs the right one explicitly for the same reason. pwsh is optional and its test is skipped when absent.

Note that verify.yaml is not this: it is a reusable workflow that tests whichever repo calls it, not this one.

See release-workflow.md for testing and modification guidance.

Versioning

Workflows are versioned using Git tags. The major version tag (e.g., v4) must float:

git tag v4.0.1 && git push origin v4.0.1
git tag -f v4 v4.0.1 && git push origin v4 --force

To test changes, point a connector at your branch:

uses: ConductorOne/github-workflows/.github/workflows/release.yaml@my-branch