{"id":31073669,"url":"https://github.com/sgaunet/ansible-role-forgejo","last_synced_at":"2026-05-09T05:33:58.305Z","repository":{"id":314444647,"uuid":"1055081102","full_name":"sgaunet/ansible-role-forgejo","owner":"sgaunet","description":"Ansible role to install Forgejo binary on Linux systems. Automated deployment of the self-hosted lightweight software forge with version management and idempotent installation.","archived":false,"fork":false,"pushed_at":"2025-09-12T14:38:54.000Z","size":34,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-12T14:55:51.431Z","etag":null,"topics":["ansible","ansible-role","automation","configuration-management","devops","forgejo","git","gitea","infrastructure-as-code","self-hosted"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgaunet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["sgaunet"]}},"created_at":"2025-09-11T18:32:22.000Z","updated_at":"2025-09-12T14:24:41.000Z","dependencies_parsed_at":"2025-09-12T14:55:54.839Z","dependency_job_id":"1b1df6b4-c422-467d-994c-4537b2772441","html_url":"https://github.com/sgaunet/ansible-role-forgejo","commit_stats":null,"previous_names":["sgaunet/ansible-role-forgejo"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/sgaunet/ansible-role-forgejo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fansible-role-forgejo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fansible-role-forgejo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fansible-role-forgejo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fansible-role-forgejo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgaunet","download_url":"https://codeload.github.com/sgaunet/ansible-role-forgejo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgaunet%2Fansible-role-forgejo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275348501,"owners_count":25448626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-role","automation","configuration-management","devops","forgejo","git","gitea","infrastructure-as-code","self-hosted"],"created_at":"2025-09-16T01:57:41.438Z","updated_at":"2025-09-16T01:57:43.969Z","avatar_url":"https://github.com/sgaunet.png","language":null,"funding_links":["https://github.com/sponsors/sgaunet"],"categories":[],"sub_categories":[],"readme":"[![GitHub release](https://img.shields.io/github/release/sgaunet/ansible-role-forgejo.svg)](https://github.com/sgaunet/ansible-role-forgejo/releases/latest)\n[![CI](https://github.com/sgaunet/ansible-role-forgejo/workflows/CI/badge.svg)](https://github.com/sgaunet/ansible-role-forgejo/actions?query=workflow%3ACI)\n[![License](https://img.shields.io/github/license/sgaunet/ansible-role-forgejo.svg)](LICENSE)\n\n# Ansible Role: Forgejo\n\nAn Ansible Role that installs [Forgejo](https://forgejo.org/) binary on Linux systems.\n\nForgejo is a self-hosted lightweight software forge. Easy to install and low maintenance, it just does the job. Forgejo is a community-driven fork of Gitea.\n\nThis role implements the [binary installation method](https://forgejo.org/docs/latest/admin/installation/binary/) as described in the official Forgejo documentation, providing an automated and idempotent way to manage Forgejo binary installations across your infrastructure.\n\n## Features\n\n- Creates dedicated git user for Forgejo service\n- Creates required data and configuration directories with proper permissions\n- Downloads and installs Forgejo binary from official releases\n- Generates complete `app.ini` configuration with security tokens\n- Sets up systemd service with proper configuration and dependencies\n- Version management with automatic upgrades/downgrades\n- Idempotent installation (only downloads when version differs)\n- Support for multiple Linux distributions\n- Comprehensive molecule tests\n\n## Requirements\n\n- Ansible \u003e= 2.15\n- Linux system (required - Forgejo only provides Linux binaries)\n- Internet connectivity to download Forgejo releases from Codeberg\n\n## Role Variables\n\nAvailable variables are listed below, along with default values (see `defaults/main.yml`):\n\n```yaml\n# Target version of Forgejo to install\nforgejo_target_version: \"12.0.3\"\n\n# Installation directory for the forgejo binary\nforgejo_install_path: \"/usr/local/bin\"\n```\n\n### Git User Configuration\n\nThe role creates a dedicated system user for Forgejo. You can customize these settings:\n\n```yaml\n# Git user configuration for Forgejo service\nforgejo_user: \"git\"              # Username for Forgejo service\nforgejo_group: \"git\"             # Group name for Forgejo service  \nforgejo_home: \"/home/git\"        # Home directory for git user\nforgejo_shell: \"/bin/bash\"       # Shell for git user\n```\n\n### Directory Configuration\n\nThe role creates the required directories for Forgejo data and configuration:\n\n```yaml\n# Forgejo directory configuration\nforgejo_data_path: \"/var/lib/forgejo\"    # Data directory for repositories and application data\nforgejo_config_path: \"/etc/forgejo\"      # Configuration directory for app.ini and other config files\n```\n\n### Systemd Service Configuration\n\nThe role automatically sets up a systemd service for Forgejo:\n\n```yaml\n# Systemd service configuration\nforgejo_service_enabled: true                                    # Enable and start systemd service\nforgejo_service_description: \"Forgejo (Beyond coding. We forge.)\"  # Service description\nforgejo_service_restart_sec: \"2s\"                               # Restart delay after failure\nforgejo_service_enable_capabilities: false                      # Enable CAP_NET_BIND_SERVICE for low ports\n```\n\n### Application Configuration\n\nThe role generates a complete `app.ini` configuration file with sensible defaults:\n\n#### Database Configuration\n```yaml\n# Database configuration (SQLite is default)\nforgejo_database_type: \"sqlite3\"                # Options: sqlite3, mysql, postgres\nforgejo_database_host: \"localhost\"              # Database server host\nforgejo_database_port: 3306                     # Database server port\nforgejo_database_name: \"forgejo\"                # Database name\nforgejo_database_user: \"forgejo\"                # Database user\nforgejo_database_password: \"\"                   # Database password (use Ansible Vault)\n```\n\n#### Server Configuration\n```yaml\n# Server configuration\nforgejo_server_protocol: \"http\"                 # Protocol: http or https\nforgejo_server_domain: \"localhost\"              # Server domain\nforgejo_server_http_port: 3000                  # HTTP port\nforgejo_server_root_url: \"http://localhost:3000/\" # Full URL to Forgejo\nforgejo_server_disable_ssh: false               # Disable SSH access\nforgejo_server_ssh_port: 22                     # SSH port for Git operations\nforgejo_server_ssh_listen_port: 2222            # Internal SSH listen port\n```\n\n#### Security \u0026 Service Configuration\n```yaml\n# Security (secrets auto-generated if empty)\nforgejo_security_secret_key: \"\"                 # Secret key for encryption\nforgejo_security_internal_token: \"\"             # Internal API token\n\n# Service settings\nforgejo_service_disable_registration: false      # Allow new user registration\nforgejo_service_require_signin_view: false      # Require login to view content\nforgejo_service_register_email_confirm: false   # Require email confirmation\n```\n\n#### Email Configuration\n```yaml\n# Mailer configuration\nforgejo_mailer_enabled: false                   # Enable email notifications\nforgejo_mailer_protocol: \"sendmail\"             # Protocol: sendmail or smtp\nforgejo_mailer_smtp_addr: \"\"                    # SMTP server address\nforgejo_mailer_smtp_port: 587                   # SMTP server port\nforgejo_mailer_from: \"Forgejo \u003cnoreply@localhost\u003e\" # From address\n```\n\n### Advanced Configuration\n\nYou can override the following variables for specific use cases:\n\n```yaml\n# Operating system (default: linux)\n# Note: Currently only Linux binaries are provided by Forgejo\nforgejo_os: \"linux\"\n\n# Architecture (default: amd64, options: amd64, arm64)\nforgejo_arch: \"amd64\"\n```\n\n## Dependencies\n\nNone.\n\n## Example Playbook\n\n### Basic Installation\n\n```yaml\n---\n- hosts: servers\n  become: yes\n  roles:\n    - sgaunet.forgejo\n```\n\n### Specific Version Installation\n\n```yaml\n---\n- hosts: servers\n  become: yes\n  vars:\n    forgejo_target_version: \"12.0.3\"\n  roles:\n    - sgaunet.forgejo\n```\n\n### Custom Installation Path\n\n```yaml\n---\n- hosts: servers\n  become: yes\n  vars:\n    forgejo_install_path: \"/opt/forgejo/bin\"\n  roles:\n    - sgaunet.forgejo\n```\n\n### Multiple Servers with Different Versions\n\n```yaml\n---\n- hosts: production\n  become: yes\n  vars:\n    forgejo_target_version: \"12.0.3\"\n  roles:\n    - sgaunet.forgejo\n\n- hosts: staging\n  become: yes\n  vars:\n    forgejo_target_version: \"12.0.2\"\n  roles:\n    - sgaunet.forgejo\n```\n\n\n## Installation\n\n### Via Ansible Galaxy\n\n```bash\nansible-galaxy install sgaunet.forgejo\n```\n\n### Via requirements.yml\n\nAdd this to your `requirements.yml`:\n\n```yaml\n---\nroles:\n  - name: sgaunet.forgejo\n    version: \"1.0.0\"  # Check for latest version\n```\n\nThen install:\n\n```bash\nansible-galaxy install -r requirements.yml\n```\n\n## Development\n\n### Prerequisites\n\n- [Devbox](https://www.jetify.com/devbox) for development environment\n- [Docker](https://www.docker.com/) for molecule tests\n- [Task](https://taskfile.dev/) for task automation\n\n### Setup Development Environment\n\n```bash\n# Install devbox if not already installed\ncurl -fsSL https://get.jetify.com/devbox | bash\n\n# Enter the development shell\ndevbox shell\n\n# Or run commands directly\ndevbox run \u003ccommand\u003e\n```\n\n### Testing\n\nThis role is tested with [Molecule](https://molecule.readthedocs.io/) using Docker containers.\n\n```bash\n# Run all tests\ntask tests\n\n# Or using devbox directly\ndevbox run -- molecule test\n\n# Run specific test sequence\ndevbox run -- molecule create\ndevbox run -- molecule converge\ndevbox run -- molecule verify\ndevbox run -- molecule destroy\n\n# Test idempotence\ndevbox run -- molecule converge\ndevbox run -- molecule idempotence\n```\n\n### Linting\n\n```bash\n# Run ansible-lint\ntask lint\n\n# Or\ndevbox run -- ansible-lint\n```\n\n### Directory Structure\n\n```\nansible-role-forgejo/\n├── defaults/\n│   └── main.yml           # Default variables\n├── meta/\n│   └── main.yml           # Role metadata for Ansible Galaxy\n├── molecule/\n│   └── default/\n│       ├── converge.yml   # Playbook for molecule tests\n│       ├── molecule.yml   # Molecule configuration\n│       └── verify.yml     # Verification tests\n├── tasks/\n│   └── main.yml           # Main task file\n├── .gitignore\n├── devbox.json            # Devbox configuration\n├── devbox.lock            # Devbox lock file\n├── LICENSE                # MIT License\n├── README.md              # This file\n└── Taskfile.yml           # Task automation\n```\n\n## How It Works\n\n1. **User Setup**: Creates a dedicated `git` system user and group for Forgejo service\n2. **Directory Creation**: Creates required directories with proper ownership and permissions:\n   - Data directory: `/var/lib/forgejo` (git:git, 750)\n   - Config directory: `/etc/forgejo` (root:git, 770)\n3. **Version Check**: The role checks if Forgejo is already installed and gets its version\n4. **Conditional Download**: Only downloads if the installed version differs from the target version\n5. **Binary Installation**: Downloads the binary from Codeberg and installs it with proper ownership to the configured path (default: `/usr/local/bin`)\n6. **Configuration**: Generates secure `app.ini` configuration file with auto-generated security tokens\n7. **Systemd Service**: Creates and enables systemd service for automatic startup and management\n8. **Verification**: Verifies the installation by running `forgejo -v`\n\n## Supported Platforms\n\n- **Enterprise Linux**: RHEL/CentOS/Rocky/AlmaLinux 8, 9\n- **Ubuntu**: 20.04 (Focal), 22.04 (Jammy), 24.04 (Noble)\n- **Debian**: 11 (Bullseye), 12 (Bookworm)\n- **Fedora**: 38, 39, 40\n\n**Note**: Forgejo currently only provides Linux binaries. The `forgejo_os` variable is available for future compatibility when other operating systems are supported.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Follow Ansible best practices\n- Add molecule tests for new features\n- Update documentation as needed\n- Ensure all tests pass before submitting PR\n- Use conventional commits format\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Permission Denied**: Ensure you're running the playbook with `become: yes` for system-wide installation\n\n2. **Download Failures**: Check your internet connectivity and firewall rules for accessing Codeberg\n\n3. **Version Not Changing**: The role compares exact version strings. Ensure `forgejo_target_version` matches the release version format (e.g., \"12.0.3\" not \"v12.0.3\")\n\n## License\n\nMIT\n\n## Author Information\n\nThis role was created by [Sylvain Gaunet](https://github.com/sgaunet).\n\n## Links\n\n- [Forgejo Official Website](https://forgejo.org/)\n- [Forgejo Documentation](https://forgejo.org/docs/latest/)\n- [Forgejo Binary Installation Guide](https://forgejo.org/docs/latest/admin/installation/binary/)\n- [Forgejo Releases](https://codeberg.org/forgejo/forgejo/releases)\n- [Ansible Galaxy Page](https://galaxy.ansible.com/sgaunet/forgejo)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgaunet%2Fansible-role-forgejo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgaunet%2Fansible-role-forgejo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgaunet%2Fansible-role-forgejo/lists"}