ci-integration

# CI Integration Skill

## When to Use

Use this skill to add automatic deployment logging to your CI/CD pipelines so that every production (or staging) deploy is recorded in deployment-tracker without manual steps.

## GitHub Actions Integration

### Full workflow example

```yaml
# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build and deploy
        run: |
          # Your existing build and deploy commands here
          echo "Deploying ${{ github.sha }}"

      - name: Log deployment
        if: success()
        run: |
          npm install -g deploy-tracker
          deploy-tracker deploy \
            --service ${{ vars.SERVICE_NAME }} \
            --version ${{ github.sha }} \
            --env production \
            --deployer ${{ github.actor }} \
            --token ${{ secrets.DEPLOY_TOKEN }} \
            --server ${{ vars.DEPLOY_TRACKER_URL }} \
            --changelog-url "https://github.com/${{ github.repository }}/commit/${{ github.sha }}"

      - name: Log failed deployment
        if: failure()
        run: |
          npm install -g deploy-tracker
          deploy-tracker deploy \
            --service ${{ vars.SERVICE_NAME }} \
            --version ${{ github.sha }} \
            --env production \
            --deployer ${{ github.actor }} \
            --token ${{ secrets.DEPLOY_TOKEN }} \
            --server ${{ vars.DEPLOY_TRACKER_URL }} \
            --status failed
```

### Required secrets and variables

| Name | Type | Value |
|------|------|-------|
| `DEPLOY_TOKEN` | Secret | Deploy token from deployment-tracker settings |
| `DEPLOY_TRACKER_URL` | Variable | `https://your-tracker.example.com` |
| `SERVICE_NAME` | Variable | e.g. `api-gateway` |

### Using semantic versions instead of commit SHAs

```yaml
- name: Log deployment with version tag
  run: |
    deploy-tracker deploy \
      --service my-app \
      --version ${{ github.ref_name }} \
      --env production \
      --deployer ${{ github.actor }} \
      --token ${{ secrets.DEPLOY_TOKEN }}
```

## GitLab CI Integration

```yaml
# .gitlab-ci.yml
stages:
  - build
  - deploy
  - notify

deploy-production:
  stage: deploy
  script:
    - echo "Deploying $CI_COMMIT_SHA"
    # Your deploy commands here

log-deployment:
  stage: notify
  when: always
  script:
    - npm install -g deploy-tracker
    - |
      STATUS="success"
      if [ "$CI_JOB_STATUS" = "failed" ]; then STATUS="failed"; fi
      deploy-tracker deploy \
        --service "$SERVICE_NAME" \
        --version "$CI_COMMIT_SHA" \
        --env production \
        --deployer "$GITLAB_USER_LOGIN" \
        --token "$DEPLOY_TOKEN" \
        --server "$DEPLOY_TRACKER_URL" \
        --status "$STATUS" \
        --changelog-url "$CI_PROJECT_URL/-/commit/$CI_COMMIT_SHA"
  variables:
    SERVICE_NAME: my-api
```

## Using curl Instead of the CLI

For environments where installing Node.js packages is undesirable, use curl directly:

```bash
# In your CI script
curl -s -X POST "$DEPLOY_TRACKER_URL/api/deploy" \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"service\": \"$SERVICE_NAME\",
    \"version\": \"$GIT_SHA\",
    \"environment\": \"production\",
    \"deployer\": \"$CI_USER\",
    \"status\": \"success\"
  }"
```

## Rollback Logging in CI

```yaml
# GitHub Actions rollback job
rollback:
  runs-on: ubuntu-latest
  steps:
    - name: Rollback via Helm
      run: helm rollback my-app 1

    - name: Log rollback
      run: |
        deploy-tracker rollback \
          --deployment ${{ inputs.deployment_id }} \
          --reason "${{ inputs.reason }}" \
          --token ${{ secrets.DEPLOY_TOKEN }} \
          --server ${{ vars.DEPLOY_TRACKER_URL }}
```

## Security Notes

- Store `DEPLOY_TOKEN` as an encrypted secret, never as a plain variable.
- Each service should have its own `DEPLOY_TOKEN`; tokens are scoped per service.
- `DEPLOY_TRACKER_URL` should be on an internal network or protected with network-level auth.
- The `ADMIN_TOKEN` should never be used in CI pipelines; only `DEPLOY_TOKEN` is needed for logging.