podcastrr/README_ACTIONS.md

Podcastrr - Forgejo Actions Guide

This document provides detailed information about the Forgejo Actions implementation in this project.

Overview

Forgejo Actions is a CI/CD feature provided by Forgejo that allows you to automate your software development workflows. This project uses Forgejo Actions to automate testing, building, and publishing Docker images.

Workflow Files

All workflow files are located in the .forgejo/workflows/ directory:

1. Demo Workflow (demo.yaml)

A simple example workflow that demonstrates basic Forgejo Actions functionality:

on: [push]
jobs:
  test:
    runs-on: docker
    steps:
      - run: echo All Good

This workflow:

• Runs on every push to any branch
• Uses a Docker container as the execution environment
• Simply outputs "All Good" to demonstrate successful execution

2. Build and Publish Workflow (build.yml)

A comprehensive CI/CD pipeline that handles testing, building, and publishing:

name: Build and Publish

on:
  push:
    branches:
      - main
    tags:
      - 'v*'
  pull_request:
    branches:
      - main

jobs:
  test:
    # Test job configuration
    # ...

  build:
    # Build job configuration
    # ...

  notify:
    # Notification job configuration
    # ...

This workflow:

• Runs on pushes to the main branch, any tag starting with 'v', and pull requests to the main branch
• Contains three jobs: test, build, and notify
• Uses Docker containers for all jobs
• Builds and publishes Docker images to the Forgejo container registry

How to Use

Prerequisites

1. Ensure your Forgejo instance has Actions enabled
2. Configure the required secrets in your repository settings:
   • FORGEJO_REGISTRY: Your Forgejo container registry URL
   • FORGEJO_USERNAME: Your Forgejo username
   • FORGEJO_PASSWORD: Your Forgejo password

Enabling Actions

1. Go to your repository settings
2. Navigate to the Repository tab
3. Ensure "Enable Repository Actions" is checked
4. Save your settings

Viewing Workflow Results

1. Go to your repository
2. Click on the "Actions" tab
3. You'll see a list of workflow runs
4. Click on a run to see details and logs

Triggering Workflows Manually

Some workflows can be triggered manually:

1. Go to your repository
2. Click on the "Actions" tab
3. Select the workflow you want to run
4. Click "Run workflow"
5. Select the branch and provide any inputs if required
6. Click "Run workflow"

Customizing Workflows

You can customize the existing workflows or create new ones:

1. Edit the files in the .forgejo/workflows/ directory
2. Commit and push your changes
3. The updated workflows will be used for future runs

Troubleshooting

Common Issues

1. Workflow not running:

   • Check if Actions is enabled in your repository settings
   • Verify that the workflow file syntax is correct

2. Build failures:

   • Check the workflow run logs for error messages
   • Ensure all required secrets are configured correctly

3. Docker image not publishing:

   • Verify your container registry credentials
   • Check if your Forgejo instance has the container registry enabled

Getting Help

If you encounter issues with Forgejo Actions, consult the Forgejo documentation or open an issue in this repository.

References

• Forgejo Actions User Guide
• Forgejo Documentation
• Docker Documentation