FORGE - 로컬 CI/CD 러너
<div align="center">
<img src="https://i.imgur.com/O8Xx5NV.png" alt="FORGE Logo">
<p><strong>빠르고, 오프라인이며, 신뢰할 수 있고, 어디서든 실행 가능</strong></p>
<p>
<a href="https://github.com/0xReLogic/Forge/actions/workflows/ci.yml">
<img src="https://github.com/0xReLogic/Forge/actions/workflows/ci.yml/badge.svg" alt="FORGE CI">
</a>
<a href="https://github.com/0xReLogic/Forge/releases/latest">
<img src="https://img.shields.io/github/v/release/0xReLogic/Forge?display_name=tag" alt="Release">
</a>
<a href="https://opensource.org/licenses/MIT">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
</a>
<a href="https://github.com/0xReLogic/Forge/issues?q=is%3Aissue+is%3Aopen+label%3Ahacktoberfest">
<img src="https://img.shields.io/badge/Hacktoberfest-Friendly-orange" alt="Hacktoberfest">
</a>
<a href="https://deepwiki.com/0xReLogic/Forge">
<img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
</a>
</p>
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/0xReLogic/Forge/HEAD/docs/images/forge-demo.gif" alt="FORGE Demo">
</p>
FORGE 소개
FORGE는 Rust로 구축된 경량 로컬 CI/CD 도구로, 사용자가 자신의 로컬 머신에서 자동화 파이프라인을 실행할 수 있게 해줍니다. 이는 대규모 CI/CD 시스템에 푸시하기 전에 파이프라인을 개발하고 테스트하는 데 매우 유용합니다.
FORGE를 사용하는 이유?
- 로컬 및 빠름: CI/CD 서버를 기다릴 필요 없이 로컬 머신에서 파이프라인 실행
- 오프라인 우선(Offline-First): 인터넷 연결 없이 작동함 (Docker 이미지가 로컬에 있는 한)
- 호환성: GitHub Actions 및 GitLab CI와 유사한 구문 사용
- 경량: 최소한의 리소스 소비
- 이식성: Windows, macOS, Linux에서 실행 가능
기능
- 간단한 YAML 파일에서 CI/CD 파이프라인 실행
- Docker 컨테이너를 사용한 격리(Isolation)
- 다양한 Docker 이미지 지원
- 색상이 적용된 실시간 로그 스트리밍 (병렬 스테이지는 로그를 버퍼링하고 정의 순서대로 출력)
- 환경 변수 관리
- 직관적인 명령줄 인터페이스 및 대화형 TUI 대시보드
- 병렬 실행을 지원하는 다단계 파이프라인
- 빌드 속도 향상을 위한 캐싱 (로컬 리포지토리 캐시는
./.forge/cache/에 저장)
- 보안 시크릿 관리 (상세 환경 변수 출력에서는 시크릿이 마스킹되며, 명령어는 여전히 시크릿을 에코할 수 있음)
- 스테이지 간 의존성 및 순환 참조 감지
- 실행 제어: 단계 타임아웃 (
timeout: 30s) 및 자동 컨테이너 취소
- 재시도 복원력: 지연 시간을 포함한 자동 단계 재시도 (
retries: 3, retry_delay: 2s)
- 유연한 실패 정책: 오류 발생 시 계속 진행(
continue_on_error) (단계/스테이지) 및 파이프라인 레벨의 fail_fast: false
- 아티팩트 관리: SHA-256 검증을 통해 스테이지 간 파일/디렉토리 업로드 및 다운로드
- 인간 가독성 요약, JSON, JUnit 출력을 포함하는 구조화된 실행 결과 (
--format)
- 스크립팅 및 자동화를 위한 일관된 종료 코드
- 감사(auditing) 및 재실행을 위해
.forge/runs/<run-id>/에 저장되는 실행 기록 및 아티팩트 매니페스트
빠른 시작
설치
cargo install forge-runner
...
Windows (PowerShell):
Invoke-WebRequest -Uri https://github.com/0xReLogic/Forge/releases/latest/download/forge-windows-amd64.exe -OutFile forge.exe
. orge.exe --version
# 선택 사항: forge.exe를 PATH에 있는 디렉토리로 이동 (또는 해당 디렉토리를 PATH에 추가)
git clone https://github.com/0xReLogic/Forge.git
cd Forge
...
사전 요구 사항: Rust (1.91 이상) 및 Docker (20.10 이상; 28.2.2에서 테스트됨)
자세한 설치 지침은 [docs/installation.md]를 참조하세요.
사용법
표준 CLI 모드 출력:
<p align="center">
<img src="https://raw.githubusercontent.com/0xReLogic/Forge/HEAD/docs/images/forge-cli-demo.gif" alt="FORGE CLI Demo">
</p>
기계가 읽을 수 있는 JSON 출력:
<p align="center">
<img src="https://raw.githubusercontent.com/0xReLogic/Forge/HEAD/docs/images/forge-json-demo.gif" alt="FORGE JSON Output Demo">
</p>
.env를 통한 비밀값 관리 (권장)
FORGE는 환경 변수(environment variables)에서 비밀값(secret values)을 읽습니다. 매번 수동으로 비밀값을 내보내기(exporting) 하는 것을 방지하려면, 로컬 .env 파일에 저장할 수 있습니다.
FORGE는 다음 위치의 .env 파일을 자동으로 로드합니다:
- 현재 작업 디렉토리 (Current working directory)
- 설정 파일 디렉토리 (--file path/to/forge.yaml 사용 시)
더 많은 명령어와 옵션은 docs/usage.md를 참조하세요.
대화형 TUI 대시보드 (신규!)
FORGE는 이제 파이프라인 실행을 모니터링할 수 있는 풍부하고 반응성이 뛰어난 터미널 사용자 인터페이스(TUI, Terminal User Interface) 대시보드를 포함합니다.
TUI 모드로 파이프라인을 실행하려면:
컨트롤:
q 또는 Q: TUI 종료 (활성 docker 컨테이너를 자동으로 중지하고 정리합니다).Tab: Stages & Steps 패널과 Logs 패널 간의 포커스를 전환합니다.Up/Down 화살표:
- 단계 목록 스크롤 (Stages & Steps 패널에서).
- 로그 라인 스크롤 (Logs 패널에서).
PageUp/PageDown: 로그를 페이지 단위로 스크롤합니다.a 또는 A: 자동 스크롤(Auto-Scroll) 토글 (로그 패널이 들어오는 로그를 따라가도록 강제합니다).
문서화 (Documentation)
- 설치 가이드 - 모든 플랫폼에 대한 상세 설치 지침
- 사용법 가이드 - 전체 명령어 참조 및 워크플로우
- 구성 참조 - YAML 형식 및 모든 구성 옵션
- 예제 - 다양한 기술 스택을 위한 실제 사례
- 아키텍처 - 시스템 설계 및 컴포넌트 상세 정보
빠른 예제
version: "1.0"
stages:
- name: build
...
실행할 내용을 검증하고 미리보기(preview)하는 방법:
forge validate --file forge.yaml
forge run --file forge.yaml --dry-run --verbose
캐시 저장소 (Cache storage):
- 캐시 데이터는 프로젝트 내
./.forge/cache/에 저장됩니다.
- FORGE는 공통 잠금 파일(예:
Cargo.lock, package-lock.json, pnpm-lock.yaml, yarn.lock, go.sum)에서 캐시 키를 파생하므로, 서로 다른 의존성 상태는 서로 다른 캐시 폴더를 사용합니다.
- 프로젝트의 캐시를 초기화하려면
.forge/ 디렉토리를 삭제하십시오.
병렬 실행 (Parallel Execution)
더 빠른 파이프라인을 위해 독립적인 작업을 동시에(simultaneously) 실행할 수 있습니다:
version: "1.0"
stages:
- name: test
...
세 단계 모두 순차적으로가 아닌 동시(concurrently)에 실행됩니다 (3배 더 빠름).
스테이지 의존성 (Stage Dependencies)
스테이지 의존성을 사용하여 복잡한 파이프라인을 정의합니다:
stages:
- name: setup
steps: [...]
...
FORGE는 실행 순서를 자동으로 해결하고 순환 참조(circular dependencies)를 감지합니다.
실행 제어 및 아티팩트 (Execution Control & Artifacts)
단계별 실행 제한, 재시도(retries), 실패 처리 방식 등을 제어하고 스테이지 간에 빌드 아티팩트를 공유할 수 있습니다:
version: "1.0"
fail_fast: false
...
자세한 내용은 docs/configuration.md와 examples/execution-control.yaml를 참조하십시오.
더 많은 예시는 docs/examples.md 및 examples/ 디렉토리에서 확인할 수 있습니다.
기여하기 (Contributing)
훌륭한 기여에 감사드립니다!
<div align="center">
<img src="https://contrib.rocks/image?repo=0xReLogic/Forge" alt="Contributors" />
</div>
기여 방법:
- 저장소를 포크(Fork)합니다.
- 기능 브랜치를 생성합니다 (
git checkout -b feature/amazing-feature).
- 변경 사항을 커밋합니다 (
git commit -m 'Add some amazing feature').
- 브랜치로 푸시합니다 (
git push origin feature/amazing-feature).
- 풀 리퀘스트(Pull Request)를 엽니다.
자세한 지침은 CONTRIBUTING.md를 읽어보십시오.
라이선스 (License)
본 프로젝트는 MIT License에 따라 라이선스가 부여됩니다.
크레딧 (Credits)
GitHub Actions, GitLab CI, 그리고 Jenkins에서 영감을 받았습니다.
