Publish from CI without a stored secret

Let a GitHub Actions workflow publish skills with a key that lives for minutes. Write a trust policy, exchange the workflow's OIDC token for a one-repository key, and publish with it.

By The SKaaS team. Last updated . Markdown version

A publish key that sits in a CI secret can be copied, and it works until someone revokes it. Trusted publishing replaces it. The workflow proves who it is with a token that GitHub issues for that one run, and SKaaS trades the token for a key that expires in minutes.

Edition and plan: every edition and every plan.

How does it work?

  1. An administrator writes a trust policy on a SKaaS repository. It says which GitHub repository may publish into it, from which refs, environments and workflows.
  2. The workflow asks GitHub for an OIDC token whose audience is your SKaaS service.
  3. The workflow sends the token to the exchange route.
  4. SKaaS checks the signature of the token against the published keys of GitHub Actions, its issuer, its audience and its expiry. It finds an enabled policy that every claim satisfies, and it refuses a token that it has seen before.
  5. SKaaS returns a key with the skills:write scope, limited to that one repository. It lives for 10 minutes by default and never more than 15. Nothing stores it and nothing shows it again.
  6. The workflow publishes with the key.

How do I write a trust policy?

Create one per GitHub repository and workflow. You need the repos:admin scope.

curl -sS -X POST "https://api.skaas.io/v1/repos/$REPO_ID/trust-policies" \
  -H "authorization: Bearer $SKAAS_TOKEN" -H "content-type: application/json" \
  -d '{
    "github_repository": "acme/skills",
    "github_repository_id": "123456789",
    "ref": "refs/tags/v*",
    "environment": "release",
    "workflow": ".github/workflows/publish.yml",
    "description": "Publish tagged releases"
  }'

Every condition must hold for the policy to match.

How do I write a trust policy?
Field Meaning
github_repository The owner/name of the GitHub repository. Compared exactly.
github_repository_id Optional. The numeric identifier. It survives a rename or a transfer, and it stops someone who registers a name that was released.
ref A pattern for the ref of the run, such as refs/heads/main or refs/tags/v*.
environment Optional. A pattern. A policy that names one refuses a job that runs in no environment.
workflow The path of the workflow file, such as .github/workflows/publish.yml.
workflow_repository Optional. The repository that holds the workflow, when a shared repository of reusable workflows does.

A pattern is exact text with two wildcards. * matches any run of characters inside one path segment, and ? matches one character. Neither crosses a /, so refs/tags/v* accepts refs/tags/v1.2 and refuses refs/tags/v1/x. There is no **. A repository holds at most 50 policies. Set "enabled": false to switch one off without deleting it.

What does the workflow do?

It needs the id-token: write permission. Request a token for your service, exchange it, and publish.

name: publish
on:
  push:
    tags: ["v*"]
permissions:
  id-token: write
  contents: read
jobs:
  publish:
    runs-on: ubuntu-latest
    environment: release
    steps:
      - uses: actions/checkout@v4
      - name: Publish
        env:
          API: https://api.skaas.io
        run: |
          OIDC=$(curl -sS -H "authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$API" | jq -r .value)
          KEY=$(curl -sS -X POST "$API/v1/orgs/acme/repos/platform/publish-credentials" \
            -H "content-type: application/json" \
            -d "$(jq -n --arg token "$OIDC" '{token: $token}')" | jq -r .token)
          echo "::add-mask::$KEY"
          SKAAS_TOKEN="$KEY" npx skaas@<version> publish skills/code-review \
            --repo acme/platform --channel stable --endpoint "$API"

Pin the version of the CLI in the last step, as skaas@<version>, and do not use latest: the step holds a key that can publish, so it should run only code that you chose. The exchange route needs no credential. The audience must match the one that your deployment expects, which names the service, usually its public address. A token for another audience is refused. On a self-hosted deployment the audience is SKAAS_OIDC_AUDIENCE, which defaults to the API address, and the issuer and key set are SKAAS_OIDC_ISSUER and SKAAS_OIDC_JWKS_URI, which default to GitHub Actions on github.com. The Compose file passes all three to the server, so setting them in .env is enough.

Why was my exchange refused?

The answer names the condition that failed, and never the token. The usual causes are a ref or environment that no policy allows, a workflow path that differs from the policy, a repository that was renamed when the policy pinned its numeric identifier, a token that expired or was already used, and a repository with no enabled policy.

What can the key do?

The key holds the one scope skills:write, and it is limited to the repository that the policy belongs to. It can begin a publish, upload files and commit a release there, including a private repository, and nothing else. It cannot read or write another repository of the organization, which answers NOT_FOUND, and it cannot administer anything: no tokens, no policies, no members. The service marks the key as a publish credential when it mints it, and no ordinary key carries that mark, so a key that you create by hand does not gain this reach. The key expires by itself, and it does not appear again after the exchange answers.

A release published this way goes through the same pipeline as any other: the audit, the policy gate, and the signature of the organization's active key when it has one.

Where do I set it up?

In the dashboard, open the repository and choose Integrations. The section Publish from GitHub Actions lists the trust policies, lets an administrator add or remove one, and shows a workflow that you can copy. The workflow follows the policy that you pick: its ref, its environment and its file name. The address in it is the public address of the API, which a self-hosted deployment sets with SKAAS_PUBLIC_API_URL on the web application. The audience that the server expects is the address of the API unless SKAAS_OIDC_AUDIENCE says otherwise. The Compose file of the self-hosted edition does not pass that variable on, so add it to the environment of the skaas service if you need another audience.

A deployment that has not set this up shows the section with the words "Publishing from GitHub Actions is not set up on this deployment". It means that the server has no exchange service, and whoever runs the deployment has to provide it. The rest of the Integrations page still loads, because each section loads and fails alone.

To let people check what your pipeline published, sign your releases. See Signed releases.