Forgejo-runner-darwin-builder

A macOS-compiled version of the Forgejo Runner, providing a pre-built binary for executing Forgejo Actions workflows on macOS systems (10.15+).

What is Forgejo?

Forgejo is a self-hosted, lightweight software forge designed for version control and collaboration. It is a community-driven hard-fork of Gitea, emphasizing ease of installation, low maintenance, and an inclusive governance model. Forgejo supports features such as Git repository hosting, issue tracking, pull requests, wikis, and continuous integration through Actions. It is suitable for individuals, teams, and organizations requiring a reliable, open-source alternative to proprietary platforms like GitHub.

Key characteristics include:

• Lightweight and Efficient: Minimal resource usage, making it ideal for deployment on modest hardware.
• Self-Hosted: Full control over data and infrastructure.
• Community-Focused: Governed by a transparent, democratic process.

For more details, refer to the official Forgejo website and documentation.

What is the Forgejo Runner?

The Forgejo Runner is a daemon application responsible for executing jobs defined in Forgejo Actions workflows. It connects to a Forgejo instance, polls for pending jobs, runs them in isolated environments, and reports results back to the server. This enables continuous integration and deployment (CI/CD) pipelines, automated testing, and other automation tasks directly within your Forgejo repositories.

The official runner supports Linux only and can be configured to use various execution modes such as containerized (e.g., Docker) or host-based environments. It fetches workflows from the Forgejo server, executes steps defined in YAML files, and handles artifacts, logs, and status updates.

This repository provides a pre-compiled macOS binary of the Forgejo Runner, simplifying setup for macOS users. It is a build of the official Forgejo Runner source code repository, with no modifications of the source tree.

Key Features of the Forgejo Runner

• Scalability: Multiple runners can be registered to a single Forgejo instance for distributed execution.
• Security: Runs jobs in isolated contexts to prevent interference with the host system.
• Customization: Supports custom labels for targeting specific runners (e.g., Windows-specific jobs).
• Integration: Seamless compatibility with Forgejo Actions syntax, which is similar to GitHub Actions.

Installation and Usage

1. Download the Binary:

   • Visit the Releases page to download the latest macOS executable (e.g., forgejo-runner-darwin-amd64).

2. Make Executable:

   • Run chmod +x forgejo-runner-darwin-amd64 to make the binary executable.

3. Configure the Runner:

   • Follow the official documentation for runner configuration.

4. Configure as a Service (Optional, for persistent operation):

   • Use launchd or a third-party tool to run the daemon as a background service.

5. Verify Registration:

   • Return to your Forgejo instance's Actions settings to confirm the runner appears online and is available for jobs.

6. Running Workflows:

   • In your repository, create .forgejo/workflows/your-workflow.yml files defining jobs that target macOS (e.g., using runs-on: [self-hosted, macOS] labels).
   • Trigger a workflow (e.g., via push or manual dispatch) and monitor execution in the Actions tab.

For additional configuration, such as enabling Docker support or custom environment variables, consult the official documentation.

Troubleshooting

• Ensure the runner has network access to your Forgejo instance.
• Check logs in the --logdir (if specified) for errors.
• If registration fails, verify the token's validity and instance URL.

Relevant Resources

Here is a curated list of links to official and helpful resources for Forgejo, the Runner, and related tools:

Forgejo Core

• Forgejo Official Website – Introduction, downloads, and community information.
• Forgejo Documentation (Latest) – Comprehensive guides for installation, administration, and usage.
• Forgejo Installation Guide – Step-by-step setup for deploying Forgejo.
• User Guide – Tutorials for repository management, issues, and more.
• Administrator Guide – Advanced configuration, including security and performance.

Forgejo Actions and Runner

• Forgejo Actions Administrator Guide – Detailed setup for enabling and managing Actions on your instance.
• Forgejo Actions User Guide – How to write and run workflows.
• Actions Reference – Syntax and built-in functions for YAML workflows.
• Quick Start for Actions – Beginner tutorial for creating your first workflow.
• Official Forgejo Runner Repository – Source code, issues, and build instructions for the runner.
• Runner Installation Guide – Official instructions for installing and configuring the runner.

Community and Support

• Forgejo Discourse Forum – Community discussions and support threads.
• Forgejo Matrix Channel – Real-time chat for developers and users.
• Codeberg Documentation on Forgejo Actions – Practical guide from a Forgejo hoster.
• Gitea Actions Documentation – Compatible reference, as Forgejo Actions are derived from Gitea (note version differences).

Contributing

Contributions to improve documentation or binaries are welcome via pull requests. For issues specific to this macOS build, open a new issue in this repository.