Skip to main content

Release Management

Automated Release System​

Status: FULLY AUTOMATED as of 2025-10-17

How It Works​

  1. Push to main branch → Release workflow triggers
  2. Version auto-bumps (patch) → Creates "Bump version to X.X.X" commit
  3. Builds and publishes to NPM automatically
  4. Creates git tag for the release

What You Need to Do​

Use Smart Push! GitHub Actions creates version bump commits, so use:

# CORRECT - Use smart push to handle automated version bumps
git pushup # Git alias method
npm run smart-push # NPM script method
./scripts/smart-push.sh # Direct script method

# WRONG - Will cause "fetch first" errors
git push origin main

The system handles:

  • Version bumping (patch increments)
  • README updates
  • NPM publishing
  • Git tagging
  • Build validation
  • Auto-rebase with remote changes

Critical Workflow Dependencies​

** DO NOT MODIFY THESE WITHOUT EXTREME CAUTION:**

GitHub Secrets (Required)​

  • PAT_TOKEN: Personal Access Token with repo permissions
  • NPM_TOKEN: NPM Automation token from grok_cli account

Package Configuration (Sacred)​

{
  "name": "@xagent/x-cli", // NEVER change - breaks publishing
  "publishConfig": {
    "access": "public" // Must NOT include registry override
  }
}

Working Release Workflow​

File: .github/workflows/release.yml

# This workflow took multiple attempts to get working!
# DO NOT MODIFY without understanding all dependencies
name: Release
on:
push:
branches: [ main ]
permissions:
contents: write
jobs:
release:
runs-on: ubuntu-latest
steps:
# Critical: Fresh dependency install
- name: Install dependencies
run: |
rm -rf node_modules package-lock.json
npm install

# Critical: Loop prevention
- name: Skip if previous commit was auto-bump
run: |
if git log -1 --pretty=%B | grep -qiE "^Bump version to "; then
echo "Auto-bump detected; skipping."
exit 78
fi

# Critical: Git authentication for push
- name: Create tag and push
env:
GITHUB_TOKEN: ${{ secrets.PAT_TOKEN || secrets.GITHUB_TOKEN }}

# Critical: NPM authentication
- name: Configure npm auth
run: |
echo "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}" > ~/.npmrc
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Manual Release Guidelines (Emergency Only)​

Version Bumping Types​

  • Patch (1.0.41 → 1.0.42): Bug fixes, small updates (DEFAULT)
  • Minor (1.0.41 → 1.1.0): New features, backwards-compatible
  • Major (1.0.41 → 2.0.0): Breaking changes

Manual Process (If Automation Fails)​

# 1. Bump version locally
npm version patch # or minor/major

# 2. Test build
npm run build
npm run local

# 3. Manual publish (emergency only)
npm publish --access public

# 4. Push changes
git push origin main --follow-tags

Best Practices​

  • Conventional commits: feat:, fix:, BREAKING CHANGE:
  • Test locally: npm run local before pushing
  • Monitor automation: Check GitHub Actions for failures
  • Don't force-push: Breaks automation workflow

Timing for Releases​

  • Automatic patch: Every push to main (current behavior)
  • Manual minor: Accumulate features, then manual npm version minor
  • Manual major: Breaking changes, coordinate with team

Troubleshooting Automation​

If Publishing Fails​

  1. Check GitHub Actions logs
  2. Verify secrets are set: PAT_TOKEN, NPM_TOKEN
  3. Confirm NPM token hasn't expired
  4. Check package.json name hasn't changed
  5. See /docs/troubleshooting for detailed troubleshooting

Emergency Manual Publish​

If automation is broken and you need to publish immediately:

npm version patch
npm run build
npm publish --access public
git push origin main --follow-tags

Remember: Fix automation before next release!