bootc/AUTOMATION-SETUP.md

# bootc CentOS Stream Automation - Setup Guide

This guide covers the steps needed to activate the automated release process.

## ✅ What's Been Created

The following automation infrastructure is ready:

- `.gitlab-ci.yml` - GitLab CI pipeline configuration
- `scripts/check-upstream-release.sh` - GitHub API poller
- `scripts/create-release-mr.sh` - Main automation orchestrator
- `scripts/update-spec.py` - Spec file updater
- `scripts/create-jira.sh` - JIRA API client
- `scripts/README.md` - Complete documentation

## 🧪 Testing the Workflow

Before setting up production automation, you can test locally:

```bash
# Test release detection and spec update (safe, no changes)
./scripts/test-workflow.sh

# Test in GitLab CI with TEST_MODE (stops before git push)
# 1. Push this branch to GitLab
# 2. Go to CI/CD → Pipelines → Run Pipeline
# 3. Add variable: TEST_MODE=true
# 4. Watch the pipeline execute and stop before making changes
```

**Note:** This automation is currently configured for **c10s only**. To enable for c9s:
1. Create a separate branch from c9s: `git checkout c9s && git checkout -b c9s-add-release-automation`
2. Merge or cherry-pick these changes
3. Update `.gitlab-ci.yml` to set `BASE_BRANCH: c9s`
4. Set up a separate scheduled pipeline for c9s

## 🔧 Required Setup Steps

### 1. Bot Account Creation

Create `bootc-release-bot` account (similar to imagebuilder-bot):

**GitLab Account:**
- Email: `bootc-release-bot@redhat.com`
- Add as Developer to: `gitlab.com/redhat/centos-stream/rpms/bootc`

**JIRA Account:**
- Same email: `bootc-release-bot@redhat.com`
- Request permissions to create issues in RHEL project

### 2. Generate Credentials

**GitLab API Token:**
1. Log in as bootc-release-bot
2. Go to User Settings → Access Tokens
3. Create token with scopes:
   - `api`
   - `write_repository`
4. Save the token securely

**GitLab SSH Key (for centpkg):**
```bash
ssh-keygen -t ed25519 -C "bootc-release-bot@redhat.com" -f ~/.ssh/bootc-bot
# Add public key to GitLab: Settings → SSH Keys
# Save private key for GitLab CI variable
```

**JIRA API Token:**
1. Log in to https://issues.redhat.com as bootc-release-bot
2. Go to Account Settings → Security → API Tokens
3. Create new token
4. Save the token securely

### 3. Configure GitLab CI/CD Variables

In the bootc GitLab project, go to **Settings → CI/CD → Variables** and add:

| Variable Name | Value | Type | Masked | Protected |
|---------------|-------|------|--------|-----------|
| `JIRA_API_TOKEN` | (JIRA token from step 2) | Variable | ✅ | ❌ |
| `GITLAB_API_TOKEN` | (GitLab token from step 2) | Variable | ✅ | ❌ |
| `CENTOS_SSH_PRIVATE_KEY` | (SSH private key from step 2) | File | ✅ | ❌ |
| `BOT_EMAIL` | `bootc-release-bot@redhat.com` | Variable | ❌ | ❌ |
| `ASSIGNEE_USER_ID` | (Your GitLab user ID) | Variable | ❌ | ❌ |

**To find your GitLab user ID:**
```bash
# Using GitLab API
curl "https://gitlab.com/api/v4/users?username=YOUR_USERNAME" | jq '.[0].id'

# Or check your profile URL: gitlab.com/YOUR_USERNAME
# The numeric ID is shown in the API response
```

### 4. Set Up Scheduled Pipeline

1. Go to **Settings → CI/CD → Schedules**
2. Click **New schedule**
3. Fill in:
   - **Description:** `Check for new bootc releases`
   - **Interval Pattern:** Custom
   - **Cron:** `0 */6 * * *` (every 6 hours)
   - **Cron timezone:** UTC
   - **Target branch:** `c10s`
   - **Active:** ✅
4. Save schedule

### 5. Commit Automation to Repository

```bash
git add .gitlab-ci.yml scripts/
git commit -m "Add automated release pipeline

Implements weekly upstream rebase cadence automation:
- Polls GitHub every 6 hours for new releases
- Creates JIRA tickets automatically
- Updates spec file and creates MRs
- Leverages OSCI Bot for auto-merge

Resolves: #RHEL-XXXXX"

git push origin c9s
```

### 6. Test the Automation

**Dry Run Test:**
1. Go to **CI/CD → Pipelines**
2. Click **Run pipeline**
3. Select branch: `c10s`
4. Click **Run pipeline**
5. Watch the pipeline execute
6. Verify it detects the current version correctly

**Live Test (when next release happens):**
1. Wait for next upstream bootc release
2. Within 6 hours, check for automated MR
3. Verify MR has:
   - Correct version in title and spec
   - JIRA ticket created and referenced
   - Assignee set for notifications
4. Monitor OSCI Bot checks
5. Confirm auto-merge if tests pass

## 📋 Checklist

Before going live, ensure:

- [ ] `bootc-release-bot` account created
- [ ] Bot added as Developer to GitLab project
- [ ] Bot has JIRA issue creation permissions
- [ ] GitLab API token generated
- [ ] SSH key generated and added
- [ ] JIRA API token generated
- [ ] All 5 CI/CD variables configured
- [ ] Scheduled pipeline created
- [ ] Automation code committed to `c9s`
- [ ] Dry run pipeline executed successfully
- [ ] Team notified about new automation

## 🎯 Expected Behavior

Once active:

1. **Every 6 hours:** Pipeline checks for new releases
2. **When new release found:**
   - JIRA ticket created automatically
   - Tarballs downloaded from GitHub
   - Spec file updated with changelog
   - MR created and assigned
3. **OSCI Bot workflow:**
   - Runs all required tests
   - Auto-approves if tests pass
   - Auto-merges with Red Hat approval
4. **If tests fail:**
   - Assignee gets email notification
   - Manual intervention required

## 🆘 Rollback Plan

If automation causes issues:

1. **Disable schedule:**
   - Go to Settings → CI/CD → Schedules
   - Toggle schedule to inactive

2. **Revert code:**
   ```bash
   git revert <commit-hash>
   git push origin c9s
   ```

3. **Return to manual process** (documented in scripts/README.md)

## 📞 Support Contacts

- GitLab permissions: (Your GitLab admin contact)
- JIRA permissions: (Your JIRA admin contact)
- Bot account setup: (Your IT/identity management contact)

## 🔍 Monitoring

Track automation health:

- **Pipeline success rate:** Settings → CI/CD → Pipelines
- **MR auto-merge rate:** Check recent MRs for OSCI Bot approvals
- **Missed releases:** Compare GitHub releases vs CentOS Stream versions weekly

Target metrics:
- Pipeline success rate: >95%
- Auto-merge rate: >90%
- Release detection latency: <6 hours

---

**Questions or issues?** See `scripts/README.md` for troubleshooting guide.