Publish from GitHub Actions

Publish theme versions and release apps from a GitHub Actions workflow with trusted publishing: no stored secret, a 15-minute token for one theme listing or app.

Publish theme versions and release apps from a GitHub Actions workflow with trusted publishing: push a tag, and the workflow publishes it. No Tringify token, password or secret is stored in GitHub. You tell Tringify once, in the Developer Portal, which GitHub workflow may publish a theme listing or an app. Each run then proves which repository, workflow and tag it is with the OpenID Connect (OIDC) ID token GitHub gives the job, and the Tringify CLI exchanges that ID token for a publishing token.

A publishing token lasts 15 minutes, can publish only the one theme listing or app whose trusted publisher matched, and can run only the publishing commands. The CLI keeps it in memory: never in a keychain or a file, and never printed. There is nothing to rotate and nothing to leak from your repository settings, and removing the trusted publisher stops it at once. It works the same way as trusted publishing on PyPI and npm.

What

Theme listing

App

Commands

theme publish, theme docs (and theme docs status), theme update

app config check, app config push, app release, app publish, app docs push, app docs status

Publisher added under

Themes › your listing › Trusted publishing

Apps › your app › Trusted publishing

Who can add or remove one

Edit Themes (themes:write)

Edit Apps and Release Apps (apps:write and apps:release)

The token may

read and publish that listing (themes:read, themes:write)

read, change and release that app (apps:read, apps:write, apps:release)

1. Add a trusted publisher#

In the Developer Portal, open your organization, then the theme listing (under Themes) or the app (under Apps), and open the Trusted publishing tab. Choose Add publisher and enter:

Field

Enter

Rules

Owner

The GitHub user or organization that owns the repository, for example tringify.

A GitHub login: letters, digits and hyphens, up to 39 characters. Tringify looks it up on GitHub when you add the publisher and stores its permanent account ID.

Repository

The repository name, for example my-theme.

Up to 100 letters, digits, ., _ or -. Compared without regard to case. Use the current name: a public repository that was renamed or moved is refused under its old name.

Workflow file

The workflow file name, for example release.yml. The API takes the full path, .github/workflows/release.yml.

A .yml or .yaml file directly in .github/workflows, compared exactly.

Environment

Optional. The GitHub environment the publishing job runs in, for example release.

Empty matches any job of the workflow, with or without an environment. A name matches only jobs that declare that environment (compared without regard to case). Recommended: see Recommended hardening.

Ref pattern

The tags that may publish. Default refs/tags/v*.

Tags only: it starts with refs/tags/. * is the only wildcard and matches any characters, / included; without * the tag must match exactly, for example refs/tags/v2.0.0.

Tringify records the repository's permanent GitHub ID along with its name. For a public repository it does so when you add the publisher; for a private one, which Tringify cannot see, the first successful run records it. From then on only that repository can publish: a repository created later under the same name, after the original was deleted or transferred, cannot. The owner is matched by its account ID, so renaming the GitHub account does not break the publisher, and another account that takes the old name gets nothing.

A theme listing or app can have up to 10 trusted publishers, for example one per release workflow. Adding the same publisher twice is refused. When several publishers of one listing or app match a run, the most specific one is used: one that names an environment before one that does not.

The member who adds a publisher is its acting member. A publishing token never has more access than that member has now: if they leave the organization or lose the permission needed to add the publisher, the publisher stops working, and the Developer Portal shows it as inactive. Someone who has the permission then removes it and adds it again. Everything a publishing token changes is recorded in the organization's activity log as made by the acting member through Trusted publisher github.com/OWNER/REPO (.github/workflows/release.yml); adding and removing publishers is recorded there too.

2. Add the workflow#

tringify theme init and tringify app init write this workflow into new projects as .github/workflows/release.yml. For an existing repository, add the one for your project. It runs on a tag push only, and the job that runs tringify has permissions: id-token: write, which is what lets it request an ID token. The CLI uses trusted publishing on its own when it runs in such a job; outside one, --oidc asks for it and fails with a clear message.

Theme#

yaml
# Publishes the theme when you push a tag such as v1.2.0:
#   git tag -a v1.2.0 -m "What changed"   # the tag message becomes the release notes
#   git push origin v1.2.0
# Uses trusted publishing: no secret is stored. Before the first release, add a
# trusted publisher on the theme listing in the Developer Portal (Themes > your
# listing > Trusted publishing) with this repository, workflow file release.yml
# and environment "release".
name: Release
on:
  push:
    tags: ["v*"]
permissions:
  contents: read
jobs:
  release:
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with: {fetch-depth: 0}
      - run: curl -fsSL https://raw.githubusercontent.com/tringify/cli/main/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: tringify theme check --mode sealed
      - name: Release notes from the tag message
        run: |
          git fetch --force origin "refs/tags/$GITHUB_REF_NAME:refs/tags/$GITHUB_REF_NAME"
          git tag -l --format='%(contents)' "$GITHUB_REF_NAME" > "$RUNNER_TEMP/notes.md"
      - run: tringify theme publish --version "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md" --yes
      - if: hashFiles('docs/*.md') != ''
        run: tringify theme docs

The job checks the theme with theme check --mode sealed, the same rules a published version must pass, then publishes it as the tag's version (v1.2.0 publishes 1.2.0) with the tag's message as the release notes, and adds Source commit: <sha> to the notes as on your computer. The listing comes from the publishing token, so --listing is not needed. If the repository has docs/*.md, theme docs saves them as the theme documentation's draft and submits it for review. To also change the listing's text or images from CI, add tringify theme update with the flags you need.

Marketplace app#

yaml
# Releases the app when you push a tag such as v1.2.0:
#   git tag -a v1.2.0 -m "What changed"   # the tag message becomes the release notes
#   git push origin v1.2.0
# Uses trusted publishing: no secret is stored. Before the first release, add a
# trusted publisher on the app in the Developer Portal (Apps > your app >
# Trusted publishing) with this repository, workflow file release.yml and
# environment "release".
name: Release
on:
  push:
    tags: ["v*"]
permissions:
  contents: read
jobs:
  release:
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with: {fetch-depth: 0}
      - run: curl -fsSL https://raw.githubusercontent.com/tringify/cli/main/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Release notes from the tag message
        run: |
          git fetch --force origin "refs/tags/$GITHUB_REF_NAME:refs/tags/$GITHUB_REF_NAME"
          git tag -l --format='%(contents)' "$GITHUB_REF_NAME" > "$RUNNER_TEMP/notes.md"
      - run: tringify app config push --yes
      - run: tringify app release --version "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md" --yes
      - if: hashFiles('docs/*.md') != ''
        run: tringify app docs push --submit
  # Fails while the version is in review: once Tringify approves it, re-run
  # this job from the workflow run's page (it gets a fresh ID token).
  publish:
    needs: release
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://raw.githubusercontent.com/tringify/cli/main/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: tringify app publish "$GITHUB_REF_NAME"

The release job pushes tringify.app.json and its block sources as the draft, then submits the draft for review as exactly the tag's version. The version must be the next patch, minor or major version after the newest one (after 1.4.2: 1.4.3, 1.5.0 or 2.0.0), and an app's first version is always 1.0.0. If the repository has docs/*.md, app docs push --submit saves and submits the app's documentation. The app comes from app_id in tringify.app.json.

Tringify reviews every marketplace version, so the publish job fails while the version is in review, with a message that says so. Once the version is approved, open the workflow run on GitHub and select Re-run jobs › Re-run failed jobs: the re-run gets a fresh ID token for the same tag and publishes the version. Re-running needs nobody's token, and with a required reviewer on the environment it waits for their approval again. You can also publish from your own computer with tringify app publish 1.2.0.

Private app#

yaml
# Releases the app when you push a tag such as v1.2.0:
#   git tag -a v1.2.0 -m "What changed"   # the tag message becomes the release notes
#   git push origin v1.2.0
# Uses trusted publishing: no secret is stored. Before the first release, add a
# trusted publisher on the app in the Developer Portal (Apps > your app >
# Trusted publishing) with this repository, workflow file release.yml and
# environment "release".
name: Release
on:
  push:
    tags: ["v*"]
permissions:
  contents: read
jobs:
  release:
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with: {fetch-depth: 0}
      - run: curl -fsSL https://raw.githubusercontent.com/tringify/cli/main/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Release notes from the tag message
        run: |
          git fetch --force origin "refs/tags/$GITHUB_REF_NAME:refs/tags/$GITHUB_REF_NAME"
          git tag -l --format='%(contents)' "$GITHUB_REF_NAME" > "$RUNNER_TEMP/notes.md"
      - run: tringify app config push --yes
      - run: tringify app release --notes-file "$RUNNER_TEMP/notes.md" --yes
      - if: hashFiles('docs/*.md') != ''
        run: tringify app docs push --submit

A private app has no review: app release --yes sends the draft as an update to every installed store that does not have it yet, and each store's owner accepts it in Store Admin. Tringify numbers private updates itself, so app release takes no --version here (it is refused for a private app) and the tag only starts the release; there is no publish job.

What every workflow relies on#

  • permissions: id-token: write on the job that runs tringify. Without it GitHub gives the job no ID token and the CLI stops with GitHub Actions did not give this job an ID token. Add permissions: id-token: write to the job that runs tringify. Keep the workflow's default at contents: read, as above, so other jobs get no ID token.

  • The tringify steps run in the workflow file named on the publisher. Steps in a reusable workflow it calls with uses: are refused.

  • --yes on theme publish, app config push and app release. Trusted publishing never asks a question; without --yes the command stops before doing anything.

  • --notes-file reads the release notes from a file (- reads standard input). The step before it writes the annotated tag's message there; it fetches the tag again because the checkout can leave it without its message. The file is in $RUNNER_TEMP, outside the checkout, because theme publish refuses a work tree with uncommitted or untracked files, so every version matches a commit.

  • --version accepts a tag name: v1.2.0 means 1.2.0, so "$GITHUB_REF_NAME" works as it is.

  • The jobs run on ubuntu-latest and install the CLI with the install script; any Linux or macOS runner works.

3. Tag and push#

Commit, then create an annotated tag on the commit to release. Its message becomes the release notes:

bash
git tag -a v1.2.0 -m "Faster product pages and a new header layout"
git push origin v1.2.0

The push starts the workflow. Its log shows which listing or app it may publish, for example Trusted publishing: this workflow run may publish theme listing Aurora (2b0c…) in Acme Themes. A theme version is published, and a marketplace app version is submitted for review, as soon as the job finishes. A version number is used once: to retry after a failure that happened before publishing, re-run the job; to fix something in the code, commit and push a new tag such as v1.2.1.

Anyone who can push a matching tag to the repository can publish. These GitHub settings narrow that down; use all of them for a listing or app that merchants rely on.

  • Use a GitHub environment and name it on the publisher. In the repository's Settings › Environments, create release (GitHub also creates it on the first run of a job that names it, without rules) and add Required reviewers, so every release waits for one of them to approve it, and under Deployment branches and tags allow only Selected branches and tags with the tag rule v*. Then put release in the publisher's Environment field: a job that does not run in that environment, and so skipped its rules, cannot publish.

  • Protect release tags with a repository ruleset. In Settings › Rules › Rulesets, add a tag ruleset targeting v* that restricts creations, updates and deletions to maintainers (the bypass list). Nobody else can then push a release tag, and a published tag cannot be moved to another commit.

  • Tag only commits on main. Protect main with a branch ruleset (pull requests and reviews before merging) and create release tags only on its commits. To enforce it in the workflow, add a step before publishing that fails for any other commit: git merge-base --is-ancestor "$GITHUB_SHA" origin/main (the scaffold's fetch-depth: 0 already fetches main).

  • Keep the ref pattern narrow. The default refs/tags/v* suits tags like v1.2.0. If the repository uses v tags for other things, use a separate prefix such as refs/tags/release-* (* is the only wildcard).

  • Keep publishing in its own workflow file that runs only on tag pushes, so changes to other workflows cannot publish, and review changes to it like code. Consider pinning third-party actions to a commit SHA.

What trusted publishing refuses#

Run or request

Why it cannot publish

Pull requests (pull_request, pull_request_target)

Only runs started by pushing a tag (event_name push) are accepted, so code from a pull request never gets a token, whoever opened it.

Forks

A fork is another repository with another ID. It matches no publisher, even when it pushes a tag that matches the pattern; and GitHub gives a fork's pull request runs no ID token at all.

Branch pushes

The ref must be a tag (ref_type tag, refs/tags/…) that matches the publisher's ref pattern.

workflow_dispatch, schedule, workflow_run, release and other events

Only tag pushes are accepted. Start a release by pushing a tag.

A reusable workflow from another file

The job must run in the workflow file named on the publisher: GitHub's job_workflow_ref must equal workflow_ref, both naming that file in this repository at this tag.

Another workflow file or environment

The workflow path is compared exactly, and a publisher that names an environment matches only jobs in that environment.

Another theme listing or app

A publishing token is bound to the listing or app whose publisher matched; every other listing or app answers TRUSTED_PUBLISHING_ROUTE_REFUSED.

Other commands

Only the publishing commands in the table above run. Other commands that need the Developer API, such as theme submit, app secret rotate, app install-link or app privacy push, stop with an error, as does theme publish --install-store. Commands that need no sign-in, such as theme check, work as usual.

Managing trusted publishers

Adding, listing and removing publishers needs a browser session in the Developer Portal; a publishing token cannot change who may publish.

A reused ID token

Each GitHub ID token can be exchanged once. The CLI requests a fresh one for every exchange, including when a long job outlives its 15-minute publishing token.

Troubleshooting#

The CLI prints the reason a run was refused, with the error code. When no publisher matches, it prints what GitHub reported about the run (repository and repository ID, workflow, ref and environment) so you can compare it with the publisher field by field. Refused exchanges also appear under Recent publish attempts in the Developer Portal.

Error

Cause

Fix

GitHub Actions did not give this job an ID token

The job has no permissions: id-token: write, --oidc was used outside a GitHub Actions job, or the run is a fork's pull request.

Add permissions: id-token: write to the job that runs tringify.

GitHub Actions refused to issue an ID token (HTTP …)

GitHub would not issue an ID token to this job.

Add permissions: id-token: write to the job; check that an organization policy does not restrict it.

TRUSTED_PUBLISHING_NO_MATCH (403)

No publisher matches the repository, workflow file, environment and tag GitHub reported. Common causes: the publisher names an environment the job does not use (or the other way round), the workflow file has another name, the tag does not match the ref pattern, or the repository was deleted and created again.

Compare the printed values with the publisher and add one with exactly those values.

TRUSTED_PUBLISHING_EVENT_REFUSED (403)

The run was not started by a push (for example a pull request, workflow_dispatch or a schedule).

Trigger the workflow with on: push: tags: ["v*"] and push a tag.

TRUSTED_PUBLISHING_REF_REFUSED (403)

The run was started by a branch push, not a tag.

Trigger on tags only and push a tag such as v1.2.3.

TRUSTED_PUBLISHING_WORKFLOW_REFUSED (403)

The tringify steps run in a reusable workflow called with uses:, or GitHub named a workflow outside .github/workflows or another repository.

Move the tringify steps into the workflow file named on the publisher.

TRUSTED_PUBLISHING_AMBIGUOUS (409)

The run matches publishers of several listings or apps; the error lists them.

Name the one to publish: --listing ID on the theme commands, --app ID or app_id in tringify.app.json on the app commands.

TRUSTED_PUBLISHING_MEMBER_INACTIVE (403)

The member who added the publisher left the organization or lost the permission it needs.

Someone with the permission removes the publisher and adds it again.

TRUSTED_PUBLISHING_INVALID_TOKEN (401)

The ID token failed a check; the message names it (signature, issuer, audience tringify, expiry, a missing claim).

Re-run the job. If it keeps failing, check the runner's clock and that nothing changes the ID token request.

TRUSTED_PUBLISHING_REPLAYED (409)

This ID token was already exchanged.

Re-run the job; every exchange needs a fresh ID token, which the CLI requests.

TRUSTED_PUBLISHING_INVALID_REQUEST (400)

The request was malformed: no token, only one of resource_kind and resource_id, an unknown kind, an ID that is not a UUID, a body over 16 KiB, or a request that also carried a session cookie or an Authorization header.

Check --listing or --app, or update the Tringify CLI. Calling the API yourself: see the API reference.

RATE_LIMITED (429)

Too many exchanges from this repository (more than 30 in 10 minutes) or from this runner's IP address.

Wait a few minutes, then re-run the job.

TRUSTED_PUBLISHING_UNAVAILABLE (503)

Tringify could not fetch GitHub's signing keys to check the ID token.

Re-run the job in a few minutes.

TRUSTED_PUBLISHING_ROUTE_REFUSED (403)

A publishing token was used for a request it may not make: another listing or app, or an action outside the publishing commands.

Run that command on your own computer after tringify login.

Tringify refused the publishing token (401)

The token expired, or was revoked during the run because the publisher was removed, the acting member lost the permission, or the listing or app was deleted.

Check the publisher in the Developer Portal, then re-run the job.

trusted publishing publishes without asking: pass --yes

A command that asks for confirmation ran without --yes.

Add --yes to theme publish, app config push and app release.

tringify … cannot run with trusted publishing

The command is not a publishing command.

Run it on your own computer after tringify login.

--install-store does not work with trusted publishing

A publishing token can only publish.

Install the version from your own computer or with Install in dev store in the Developer Portal.

the trusted publisher that matched this workflow run is on …, but this command publishes …

The workflow is a publisher of an app and runs a theme command, or the other way round.

Add a publisher on the listing or app the command publishes, or use another workflow for it.

this workflow run may publish …, not …

--listing, --app or app_id names another listing or app than the one whose publisher matched.

Pass the ID the message names, or leave --listing out.

the git work tree has uncommitted or untracked changes

A step wrote a file into the checkout before theme publish.

Write files to $RUNNER_TEMP instead, as the release notes step does.

version … is submitted; only an approved version can be published

The publish job ran while the version is in review.

Re-run the job once the version is approved.

version … skips versions · is not greater than the newest version · its first version is always 1.0.0

The tag is not the next version of the app.

Push a tag for the next patch, minor or major version the message names.

When adding a publisher in the Developer Portal fails:

Error

Cause

Fix

TRUSTED_PUBLISHER_INVALID (400)

A field does not follow the rules above; details.field names it (repository_owner, repository_name, workflow_path, environment, ref_pattern or provider). Also returned for a repository that was renamed or moved on GitHub.

Correct that field; for a moved repository, enter its current owner and name.

TRUSTED_PUBLISHER_GITHUB_OWNER_NOT_FOUND (400)

GitHub has no user or organization with that name.

Check the owner's spelling on GitHub.

TRUSTED_PUBLISHER_GITHUB_UNAVAILABLE (503)

GitHub could not be reached, or gave inconsistent answers.

Try again.

TRUSTED_PUBLISHER_DUPLICATE (409)

The same publisher is already on this listing or app.

Nothing to add; edit by removing it and adding a new one.

TRUSTED_PUBLISHER_LIMIT_REACHED (409)

The listing or app already has 10 publishers.

Remove one you no longer use.

TRUSTED_PUBLISHER_NOT_FOUND (404)

Removing a publisher that was already removed.

Reload the page.

PERMISSION_DENIED (403)

You lack the permission: Edit Themes for a listing; Edit Apps and Release Apps for an app.

Ask the organization's owner for it on the Team page.

Remove a publisher#

In Trusted publishing, select Remove next to the publisher. It stops working at once: publishing tokens it issued are revoked immediately, so a run that is publishing at that moment fails at its next request. Workflows still in the repository are refused with TRUSTED_PUBLISHING_NO_MATCH from then on. Remove a publisher when you rename or move the repository, rename the workflow file, or no longer publish from it; to change one, remove it and add the new one. Removing a publisher changes nothing already published.

Last use and history#

Trusted publishing shows, for each publisher, when it was last used, with the tag and a link to the workflow run, and whether its acting member is still active. Below the list:

  • History: the 20 most recent changes, newest first: who added or removed which publisher and when, and when a private repository's ID was recorded by its first run.

  • Recent publish attempts: the 10 most recent token requests for this listing or app, accepted or refused, with the reason, repository, tag and a link to the run. A refused request appears here when a publisher of this listing or app was considered for it.

What each run then changed is in the organization's activity log, attributed to the trusted publisher and its acting member.

API reference#

The CLI does all of this for you. These are the Developer API requests behind it, for tools other than the CLI.

Exchange an ID token#

http
POST https://api-dev.tringify.com/api/v1/trusted-publishing/token
Content-Type: application/json

Public: it takes no session and no other credential. A request that carries a session cookie or an Authorization header is refused. The body is JSON, at most 16 KiB. Request the ID token with the audience tringify, for example curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=tringify", and use it once.

json
{
  "token": "<GitHub Actions ID token>",
  "resource_kind": "theme_listing",
  "resource_id": "2b0c5f4e-8a61-4d2f-9c3e-6f1a7b9d0e12"
}

Field

Type

Description

token

string, required

The GitHub Actions OIDC ID token, audience tringify.

resource_kind

string, optional

theme_listing or app. Send it together with resource_id, or neither.

resource_id

UUID, optional

The listing or app to publish. Needed only when publishers of several listings or apps match the run (TRUSTED_PUBLISHING_AMBIGUOUS); when given, only that listing's or app's publishers are considered.

A successful exchange answers 200:

json
{
  "success": true,
  "data": {
    "access_token": "ttpa_…",
    "token_type": "Bearer",
    "expires_in": 900,
    "organization_id": "7d1e0c52-3b4a-4f6e-9a28-1c5d8e7f6a90",
    "organization_name": "Acme Themes",
    "resource": {
      "kind": "theme_listing",
      "id": "2b0c5f4e-8a61-4d2f-9c3e-6f1a7b9d0e12",
      "name": "Aurora"
    },
    "scopes": [
      "themes:read",
      "themes:write"
    ],
    "publisher_id": "5c8e2a71-0f4b-4d39-b6e2-9a1f3c7d8e45"
  }
}

Field

Description

access_token

The publishing token: ttpa_ and 43 characters. Keep it in memory and never log it.

token_type, expires_in

Bearer; it expires after 900 seconds (15 minutes). Exchange a fresh ID token for a new one.

organization_id, organization_name

The organization that owns the listing or app.

resource

The listing or app the token may publish: kind, id and name.

scopes

For a listing themes:read and themes:write; for an app apps:read, apps:write and apps:release; each only while the acting member still holds it.

publisher_id

The trusted publisher that matched.

Tringify checks, in this order: the token is a JWT signed with RS256 by a key in GitHub's key set (https://token.actions.githubusercontent.com/.well-known/jwks); the issuer is exactly https://token.actions.githubusercontent.com; the audience includes tringify; it has not expired and is not from the future (60 seconds' leeway) and lives at most one hour; it has the claims used below; event_name is push; ref_type is tag and ref starts with refs/tags/; job_workflow_ref equals workflow_ref and both name OWNER/REPO/.github/workflows/FILE@REF of this run; the repository is within its rate limit; the ID token's jti has not been exchanged before; a publisher matches the owner ID, the repository name and ID, the workflow path, the environment (when the publisher names one) and the ref pattern; and its acting member is still an active member with the permission. Every attempt, accepted or refused with its reason, is recorded.

Errors use the flat error body:

json
{
  "code": "TRUSTED_PUBLISHING_NO_MATCH",
  "message": "No trusted publisher matches this workflow run (repository, workflow, environment and tag).",
  "status_code": 403,
  "details": {
    "repository": "acme/aurora-theme",
    "repository_id": 123456789,
    "workflow_path": ".github/workflows/release.yml",
    "ref": "refs/tags/v1.2.0",
    "environment": ""
  }
}

Code

Status

Meaning

TRUSTED_PUBLISHING_INVALID_REQUEST

400

Malformed request: no token, one of resource_kind and resource_id without the other, an unknown kind or invalid ID, a body over 16 KiB, or a session cookie or Authorization header sent along.

TRUSTED_PUBLISHING_INVALID_TOKEN

401

The ID token failed a check; message names it.

TRUSTED_PUBLISHING_EVENT_REFUSED

403

The run was not started by a push.

TRUSTED_PUBLISHING_REF_REFUSED

403

The ref is not a tag.

TRUSTED_PUBLISHING_WORKFLOW_REFUSED

403

The job runs in a reusable workflow from another file, or workflow_ref does not name a workflow of this repository at this ref.

TRUSTED_PUBLISHING_NO_MATCH

403

No publisher matches. details has repository, repository_id, workflow_path, ref and environment as GitHub reported them.

TRUSTED_PUBLISHING_MEMBER_INACTIVE

403

The publisher's acting member is no longer an active member with the permission.

TRUSTED_PUBLISHING_AMBIGUOUS

409

Publishers of several listings or apps match; details.resources lists them as {kind, id}. Send resource_kind and resource_id.

TRUSTED_PUBLISHING_REPLAYED

409

The ID token was already exchanged.

RATE_LIMITED

429

Too many exchanges; see below.

TRUSTED_PUBLISHING_UNAVAILABLE

503

GitHub's signing keys could not be fetched.

Rate limits: each client IP address has the same budget as sign-in attempts, answered with RATE_LIMITED, the X-RateLimit-* headers and Retry-After; and each repository may make 30 exchanges in 10 minutes, counting accepted and refused ones but not those refused for the rate limit itself.

Use the publishing token#

Send it as Authorization: Bearer ttpa_… to https://api-dev.tringify.com/api/v1, without a session cookie. X-Organization-ID is optional; another organization than the token's is refused. It works on these requests only, and only for its own listing or app (:listingId or :id); anything else answers 403 TRUSTED_PUBLISHING_ROUTE_REFUSED, and an expired or revoked token 401. Requests share a per-token rate limit.

Request

Used by

GET /org/themes/:listingId, GET /org/themes/:listingId/versions, GET /org/themes/:listingId/versions/:versionId/package

theme publish

POST /org/themes/upload, POST /org/themes/upload/finalize, POST /org/themes/upload/status, POST /org/themes/:listingId/versions

theme publish

PUT /org/themes/:listingId, GET /org/theme-categories, POST /org/themes/media/upload-intents (and /finalize, /status)

theme update

GET /org/themes/:listingId/docs, PUT /org/themes/:listingId/docs/draft, POST /org/themes/:listingId/docs/submit

theme docs, theme docs status

GET /apps/:id, GET /apps/:id/config, PUT /apps/:id/config, POST /apps/:id/config/check

app config check, app config push

POST /apps/:id/submit, GET /apps/:id/versions, POST /apps/:id/versions/:versionId/publish

app release (marketplace), app publish

GET /apps/:id/private-updates, GET /apps/:id/private-updates/versions, POST /apps/:id/private-updates

app release (private)

GET /apps/:id/site, PUT /apps/:id/site/docs/draft, POST /apps/:id/site/docs/submit

app docs push, app docs status

Manage trusted publishers#

These requests take a Developer Portal browser session only, with X-Organization-ID like every Developer Portal request; the CLI's and other connected tools' tokens and publishing tokens are refused. Responses use the {"success": true, "data": …} envelope and errors the flat error body.

Request

Permission

Does

GET /org/themes/:listingId/trusted-publishers

View Themes (themes:read)

Lists the listing's publishers, history and recent exchanges.

POST /org/themes/:listingId/trusted-publishers

Edit Themes (themes:write)

Adds a publisher; answers 201 with it.

DELETE /org/themes/:listingId/trusted-publishers/:publisherId

Edit Themes (themes:write)

Removes it and revokes its tokens; answers {"removed": true}.

GET /apps/:id/trusted-publishers

View Apps (apps:read)

The same for an app.

POST /apps/:id/trusted-publishers

Edit Apps and Release Apps (apps:write, apps:release)

Adds a publisher.

DELETE /apps/:id/trusted-publishers/:publisherId

Edit Apps and Release Apps (apps:write, apps:release)

Removes it and revokes its tokens.

Add a publisher. provider (only github), environment (default empty: any) and ref_pattern (default refs/tags/v*) are optional; the field rules are in step 1. Tringify looks the owner up on GitHub, and for a public repository the repository too, which can take a few seconds.

json
{
  "provider": "github",
  "repository_owner": "acme",
  "repository_name": "aurora-theme",
  "workflow_path": ".github/workflows/release.yml",
  "environment": "release",
  "ref_pattern": "refs/tags/v*"
}

The list answers:

json
{
  "success": true,
  "data": {
    "resource": {
      "kind": "theme_listing",
      "id": "2b0c5f4e-8a61-4d2f-9c3e-6f1a7b9d0e12",
      "name": "Aurora"
    },
    "audience": "tringify",
    "exchange_url": "https://api-dev.tringify.com/api/v1/trusted-publishing/token",
    "limit": 10,
    "items": [
      {
        "id": "5c8e2a71-0f4b-4d39-b6e2-9a1f3c7d8e45",
        "provider": "github",
        "repository_owner": "acme",
        "repository_owner_id": 320761138,
        "repository_name": "aurora-theme",
        "repository_id": 123456789,
        "workflow_path": ".github/workflows/release.yml",
        "environment": "release",
        "ref_pattern": "refs/tags/v*",
        "created_at": "2026-11-17T10:00:00Z",
        "created_by": {
          "id": "0e9b6c3d-2a17-4f58-8d41-b7c2e5f9a306",
          "email": "dev@example.com"
        },
        "acting_member_active": true,
        "last_used_at": "2026-11-17T11:00:00Z",
        "last_used_ref": "refs/tags/v1.2.0",
        "last_used_run_url": "https://github.com/acme/aurora-theme/actions/runs/1/attempts/1"
      }
    ],
    "history": [
      {
        "action": "added",
        "at": "2026-11-17T10:00:00Z",
        "actor_email": "dev@example.com",
        "summary": "acme/aurora-theme · .github/workflows/release.yml · release"
      }
    ],
    "recent_exchanges": [
      {
        "at": "2026-11-17T11:00:00Z",
        "outcome": "accepted",
        "reason": "",
        "repository": "acme/aurora-theme",
        "ref": "refs/tags/v1.2.0",
        "run_url": "https://github.com/acme/aurora-theme/actions/runs/1/attempts/1"
      }
    ]
  }
}

repository_id is null for a private repository until its first run, and last_used_at, last_used_ref and last_used_run_url are empty until the first use. history holds at most 20 entries (added, removed, repository_pinned) and recent_exchanges at most 10, newest first; a refused exchange has its error code in reason. The errors are listed under Troubleshooting; a listing or app that is not in the organization answers 404 NOT_FOUND.