ducky/nerd-monitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Update RELEASE.md with Gitea Actions setup and troubleshooting

Browse Source 
- Add detailed Gitea configuration instructions
- Document how to create and configure API tokens as repository secrets
- Explain the automated release workflow step-by-step
- List all artifacts created during release (binaries, checksums, Docker images)
- Add comprehensive troubleshooting section with solutions
- Include workflow monitoring and log inspection guide
- Add information about manual trigger testing
This commit is contained in:
Ducky SSH User
2025-12-20 06:06:04 +00:00
parent 5664105111
commit 3dbd60ac27
1 changed files with 155 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
RELEASE.md
View File

@@ -40,42 +40,58 @@ The Gitea Actions workflow is defined in `.gitea/workflows/release.yml`
- `build`: Compiles all platform binaries and generates checksums - `build`: Compiles all platform binaries and generates checksums
- `docker-build`: Builds Docker images for server and agent - `docker-build`: Builds Docker images for server and agent
## Creating a Release ### Creating a Release
### Option 1: Automatic Release (Recommended) #### Step 1: Create and Push a Tag
1. Create a new tag:
```bash ```bash
# Create an annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0" git tag -a v1.0.0 -m "Release version 1.0.0"
# Push the tag to Gitea
git push origin v1.0.0 git push origin v1.0.0
``` ```
2. Gitea Actions will automatically: #### Step 2: Monitor the Workflow
- Build all binaries
- Create a release in Gitea
- Upload all artifacts
3. View the release in Gitea: `Releases` tab on your repository 1. Go to your repository on Gitea
2. Click the **Actions** tab
3. You'll see the workflow running:
- `build` job: Compiles all binaries (5-10 minutes)
- `docker-build` job: Builds Docker images (5-10 minutes)
### Option 2: Manual Release Upload #### Step 3: Verify the Release
If you need to manually upload binaries to Gitea: Once the workflow completes:
```bash 1. Go to the **Releases** tab
# Set your Gitea token (create one in Gitea Settings → Applications → Generate Token) 2. You'll see a new release with:
export GITEA_TOKEN=your_token_here - All platform binaries (Linux, macOS, Windows)
- SHA256SUMS file with checksums
- Docker image files (.tar)
# Build all binaries ### What Gets Built and Released
make build-all
# Upload to release When you push a tag, the workflow automatically:
./scripts/upload-release.sh v1.0.0
```
Environment variables (optional): **Binaries** (10 files total):
- `GITEA_URL`: Gitea server URL (default: `https://git.nerdnest.dev`) - `nerd-monitor-server-linux-amd64` - Server for Linux x86_64
- `REPO_OWNER`: Repository owner (default: `ducky`) - `nerd-monitor-server-linux-arm64` - Server for Linux ARM64 (Raspberry Pi, etc.)
- `REPO_NAME`: Repository name (default: `nerd-monitor`) - `nerd-monitor-server-darwin-amd64` - Server for macOS Intel
- `nerd-monitor-server-darwin-arm64` - Server for macOS Apple Silicon
- `nerd-monitor-server-windows-amd64.exe` - Server for Windows
- `nerd-monitor-agent-linux-amd64` - Agent for Linux x86_64
- `nerd-monitor-agent-linux-arm64` - Agent for Linux ARM64
- `nerd-monitor-agent-darwin-amd64` - Agent for macOS Intel
- `nerd-monitor-agent-darwin-arm64` - Agent for macOS Apple Silicon
- `nerd-monitor-agent-windows-amd64.exe` - Agent for Windows
**Checksums**:
- `SHA256SUMS` - SHA256 checksums for all binaries (for verification)
**Docker Images**:
- `nerd-monitor-server-v1.0.0.tar` - Server Docker image (can be imported)
- `nerd-monitor-agent-v1.0.0.tar` - Agent Docker image (can be imported)
## Local Building ## Local Building
@@ -112,33 +128,64 @@ docker run nerd-monitor-agent --server your-server:8080
## Gitea Configuration ## Gitea Configuration
### Enable Gitea Actions ### Prerequisites
1. SSH into your Gitea server Before the CI/CD pipeline can create releases automatically, you need to:
2. Edit `app.ini`:
```ini 1. **Ensure Gitea Actions is enabled** on your Gitea server
2. **Create a Gitea API Token** with release permissions
3. **Add the token as an Actions secret** in your repository
### Setup Instructions
#### 1. Enable Gitea Actions (Server Admin)
SSH into your Gitea server and verify Actions is enabled:
```bash
# Edit the Gitea configuration
sudo vi /etc/gitea/app.ini
# Add or verify:
[actions] [actions]
ENABLED = true ENABLED = true
``` ```
3. Restart Gitea:
Then restart Gitea:
```bash ```bash
systemctl restart gitea sudo systemctl restart gitea
``` ```
### Create an API Token (for manual uploads) #### 2. Create an API Token
1. Go to Settings → Applications 1. Log in to Gitea with your user account
2. Click "Generate New Token" 2. Go to **Settings** → **Applications**
3. Name it (e.g., "Release Upload") 3. Click **Generate New Token**
4. Give it `repo` permissions 4. Fill in:
5. Copy the token - **Token Name**: `release-automation` (or any descriptive name)
- **Scopes**: Select `repo` (full repository access)
5. Click **Generate Token**
6. **Copy the token** (you won't be able to see it again)
Use it with the upload script: #### 3. Add Token as Repository Secret
```bash
./scripts/upload-release.sh v1.0.0 <your_token>
```
## Release Files 1. Go to your repository on Gitea
2. Navigate to **Settings** → **Secrets**
3. Click **Add Secret**
4. Fill in:
- **Secret Name**: `GITEA_TOKEN`
- **Secret Value**: Paste the token you copied
5. Click **Save**
Now the workflow will be able to create releases automatically!
### Workflow Configuration
The Gitea Actions workflow is defined in `.gitea/workflows/release.yml`
### Trigger Events
- Push to `master` or `main` branch (builds only, no release)
- Push of git tags (e.g., `v1.0.0`) - triggers full release with uploads
Each release includes: Each release includes:
@@ -173,20 +220,76 @@ If you want to use Coolify for deployment:
## Troubleshooting ## Troubleshooting
### Actions not running ### Workflow Not Triggering
- Ensure Gitea Actions is enabled on your server
- Check that your runner is available (`Settings → Actions`)
- Review action logs in the `Actions` tab
### Release not created **Problem**: I pushed a tag but the workflow didn't start
- Ensure the tag format matches semantic versioning (v1.0.0)
- Check workflow logs for build errors
- Verify Go 1.24.4 is available in the runner environment
### Docker images not building **Solutions**:
- Ensure Docker/Buildx is available in the runner 1. Check that the tag is pushed: `git push origin v1.0.0`
- Check the Dockerfile syntax 2. Verify Gitea Actions is enabled: Settings → Actions → Status should show "Enabled"
- Review build logs in the Actions tab 3. Check Actions tab for any error messages
4. Ensure your runner is online: Settings → Runners
### Token Authentication Failed
**Problem**: `"message":"Unauthorized"` or token-related errors in the logs
**Solutions**:
1. Verify the `GITEA_TOKEN` secret is set correctly: Repository → Settings → Secrets
2. Ensure the token has `repo` scope permissions
3. Token should not be expired - regenerate if needed
4. Double-check there are no extra spaces in the token
### Build Fails with "Go not found"
**Problem**: Workflow fails when trying to build, says Go is not available
**Solutions**:
1. This is usually a temporary issue - runner environment might not have been fully initialized
2. Retry the workflow: Go to Actions tab → Click the failed workflow → Click "Re-run jobs"
3. Check if the runner has enough disk space: `df -h` on the runner machine
### Binaries Not Uploaded to Release
**Problem**: Workflow completes but binaries don't appear in the release
**Solutions**:
1. Check the workflow logs: Actions tab → Click the workflow → View logs
2. Look for "Uploading" messages and any error messages
3. Verify the release was created: Go to Releases tab
4. Check that `GITEA_TOKEN` secret is still valid (tokens can expire)
### Docker Image Build Fails
**Problem**: `docker-build` job fails
**Solutions**:
1. Verify Docker is installed on the runner: SSH to runner and run `docker --version`
2. Check if the Dockerfile has syntax errors: `docker build -f Dockerfile.server .`
3. Ensure runner has enough disk space for building: `docker system df`
4. Check Docker daemon is running: `sudo systemctl status docker`
### How to Check Workflow Logs
1. Go to your Gitea repository
2. Click the **Actions** tab
3. Click on the workflow run (should show the tag name)
4. Click on the job that failed (`build` or `docker-build`)
5. Scroll through the log to find error messages
6. Look for red `❌` marks indicating failures
### Manual Trigger for Testing
If you want to test the workflow without creating a full release:
```bash
# Push to main/master branch (triggers build only, no release)
git push origin main
# Then push a tag when you're ready (triggers full release)
git tag -a v1.0.0 -m "Release"
git push origin v1.0.0
```
## Additional Resources ## Additional Resources
@@ -194,3 +297,4 @@ If you want to use Coolify for deployment:
- [Project README](./README.md) - [Project README](./README.md)
- [Quick Start Guide](./QUICKSTART.md) - [Quick Start Guide](./QUICKSTART.md)
- [Agent Guidelines](./AGENTS.md) - [Agent Guidelines](./AGENTS.md)
- [Docker Compose Guide](./DOCKER_COMPOSE.md)