Publish from CI/CD
Publish a new version of your extension every time you push a version tag like v1.2.3, from GitHub Actions, GitLab CI or any other CI system, with a publish token stored as the INGOT_PUBLISH_TOKEN secret.
@ingotide/cli@0.1.0. If the package isn't on npm yet during the Beta, publish from your machine for now (see the creator guide) and keep the workflow for later.How it works: you bump the version in ingot.json, commit, and push a matching tag. CI checks that the tag matches the manifest, runs ingot package (the same checks as the store), keeps the .ingotx as a build artifact, and runs ingot publish --no-package with the token from the secret. No ingot login is needed in CI.
1. Create a token for CI
- Open Dashboard › Publisher (/dashboard/publisher).
- Under Publish tokens, name it after the CI system and repository, for example
GitHub Actions acme/react-rules. - Pick an expiry. 90 or 180 days is a good balance; you'll replace it before it expires (step 5).
- Click Create token and copy the
ingot_pub_…value. It's shown only once.
Use a separate token for each CI system or repository, never the one on your laptop, so you can revoke one without breaking the others.
2. Store the token as a secret
Never commit the token, print it in logs, or put it in ingot.json.
GitHub: in the repository, open Settings › Secrets and variables › Actions › New repository secret. Name: INGOT_PUBLISH_TOKEN, value: the token. Or with the GitHub CLI:
gh secret set INGOT_PUBLISH_TOKEN --repo acme/react-rules
GitLab: open Settings › CI/CD › Variables › Add variable. Key: INGOT_PUBLISH_TOKEN, value: the token, and check Mask variable and Protect variable. Protected variables are only given to protected branches and tags, so also protect your version tags under Settings › Repository › Protected tags (pattern v*).
Other CI: add a secret environment variable named INGOT_PUBLISH_TOKEN. The CLI reads it automatically.
3. Add the workflow
ingot init already wrote the file for you (--ci github, the default, or --ci gitlab). To add it to an existing extension, copy one of the files below.
GitHub Actions
.github/workflows/ingot-publish.yml:
name: Publish to the Ingot store
on:
push:
tags: ['v*.*.*']
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ingot-publish-${{ github.ref }}
cancel-in-progress: false
jobs:
publish:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Check the tag matches ingot.json
if: startsWith(github.ref, 'refs/tags/')
run: |
manifest_version=$(node -p "require('./ingot.json').version")
if [ "v${manifest_version}" != "${GITHUB_REF_NAME}" ]; then
echo "::error::Tag ${GITHUB_REF_NAME} does not match ingot.json version ${manifest_version}"
exit 1
fi
- name: Validate and package
run: npx --yes @ingotide/cli@0.1.0 package
- name: Publish
run: npx --yes @ingotide/cli@0.1.0 publish --no-package
env:
INGOT_PUBLISH_TOKEN: ${{ secrets.INGOT_PUBLISH_TOKEN }}
- uses: actions/upload-artifact@v4
with:
name: ingotx
path: '*.ingotx'
if-no-files-found: error
The job only reads the repository (contents: read) and passes the token to the publish step alone.
GitLab CI
.gitlab-ci.yml:
stages:
- package
- publish
default:
image: node:22-alpine
package:
stage: package
script:
- npx --yes @ingotide/cli@0.1.0 package
artifacts:
paths:
- '*.ingotx'
expire_in: 1 week
publish:
stage: publish
needs: [package]
rules:
- if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/'
script:
- test "v$(node -p "require('./ingot.json').version")" = "$CI_COMMIT_TAG" || (echo "Tag $CI_COMMIT_TAG does not match ingot.json" && exit 1)
- npx --yes @ingotide/cli@0.1.0 publish --no-package
The package job runs on every push, so a broken manifest fails the pipeline before you tag. publish runs for version tags only.
Any other CI
The same three commands work anywhere with Node.js 22:
npx --yes @ingotide/cli@0.1.0 validate
npx --yes @ingotide/cli@0.1.0 package
INGOT_PUBLISH_TOKEN=*** npx --yes @ingotide/cli@0.1.0 publish --no-package
4. Release by pushing a tag
ingot version patch # or minor / major; updates ingot.json and CHANGELOG.md
git commit -am "v1.2.4"
git tag v1.2.4
git push --follow-tags
The tag must be v plus the exact version in ingot.json. Pre-releases work too: ingot version 2.0.0-beta.1, tag v2.0.0-beta.1. Check the run in your CI; the log ends with the store page of the new version.
5. Rotate the token before it expires
The dashboard shows each token's expiry, and ingot whoami prints it. Before it expires: create a new token, replace the secret's value, re-run the last workflow to check it, then revoke the old token. A revoked or expired token fails right away with invalid_token or token_expired, and nothing is published.
If a token leaks, revoke it in Dashboard › Publisher first, then create a new one.
Troubleshooting
| Error in the log | Cause and fix |
|---|---|
No publish token. | The secret isn't set or isn't passed to the step. Check the name is exactly INGOT_PUBLISH_TOKEN; on GitLab, check the tag is protected. |
401 invalid_token | The token was revoked or mistyped. Create a new one and update the secret. |
401 token_expired | Create a new token and update the secret (step 5). |
403 publisher_mismatch | publisher in ingot.json isn't the handle that owns the token. |
409 version_exists | That version was already published. Bump the version and push a new tag; tags can't republish a version. |
409 version_not_newer | The version is lower than the latest one. Use ingot version patch. |
Tag v1.2.3 does not match ingot.json | You tagged before bumping. Delete the tag (git tag -d v1.2.3 && git push origin :v1.2.3), bump, commit and tag again. |
400 invalid_manifest or invalid_contents | The log lists each problem. Run ingot validate locally and fix them. |
429 rate_limited | More than 30 uploads in an hour. Wait, then re-run the job. |
The registry must use https:// | INGOT_REGISTRY points at an http:// address that isn't localhost. Remove it to use the store. |
npm ERR! 404 @ingotide/cli | The CLI isn't on npm yet (Beta). Publish from your machine for now. |