☁️ Salesforce DevOps Starter Kit
Validation
Release
<img src="https://raw.githubusercontent.com/svierk/salesforce-devops-starter-kit/HEAD/images/salesforce-devops-starter-kit.png" alt="salesforce-devops-starter-kit" width="900"/>
GitHub Actions를 사용하여 Salesforce 프로젝트에 대한 유연한 CI/CD 파이프라인을 쉽게 구축할 수 있도록 돕는 Trailblazer Community용 오픈 소스 스타터 키트입니다.
이 키트는 작고 집중된 GitHub Actions 세트를 기반으로 하며, 이들이 Salesforce CLI의 복잡성을 추상화합니다. 이것들을 **빌딩 블록(building blocks)**이라고 생각할 수 있습니다: 각각은 하나의 작업을 잘 수행하며, 필요한 파이프라인에 맞게 이를 조합하여 사용합니다. 빌딩 블록 외에도, 이 저장소는 바로 사용할 수 있는 재사용 가능한 워크플로우와 복사/붙여넣기 예제를 제공하므로 몇 분 만에 작동하는 파이프라인을 구축할 수 있습니다.
전체 **문서화 사이트**는 모든 빌딩 블록과 재사용 가능한 워크플로우의 자동 생성 카탈로그입니다. 각 항목은 완전한 입력/Secret 참조와 복사/붙여넣기 예제를 갖추고 있습니다.
<a href="https://svierk.github.io/salesforce-devops-starter-kit/"><img src="https://img.shields.io/badge/Actions_Catalog-Explore_the_docs-0d6efd?style=for-the-badge&logo=readthedocs&logoColor=white" alt="Explore the documentation" /></a>
🧱 철학 (Philosophy)
- GitHub 네이티브(GitHub-native) - 외부 DevOps 플랫폼이 필요하지 않으며, GitHub와 GitHub Actions만 있으면 됩니다.
- 조합 가능(Composable) - 명확한 입력과 출력을 가진 작은 액션들을 자유롭게 연결할 수 있습니다.
- 투명성(Transparent) - 모든 액션은 공식
sf CLI를 감싸는 얇고 읽기 쉬운 Wrapper입니다.
- 유연성(Flexible) - 즉시 사용 가능한 재사용 워크플로우를 사용하거나, 블록들로부터 자신만의 파이프라인을 구축할 수 있습니다.
🧩 빌딩 블록 (Building Blocks)
각 빌딩 블록은 독립적으로 버전 관리되고 소비될 수 있도록 자체 레포지토리에 존재합니다.
🏗️ 아키텍처
빌딩 블록들은 공통의 기반(체크아웃 → 설정 → 로그인)을 공유한 다음, 필요한 흐름으로 분기됩니다:
flowchart TD
A[Checkout] --> B[get-node-version]
B --> C[sfdx-cli-setup]
...
🚀 빠른 시작
필수 조건
- Salesforce Dev Hub (스크래치 org 흐름용) 및/또는 배포하려는 대상 org.
- JWT bearer flow로 인증된 CI 통합 사용자 - 이 키트 전체에서 사용되는 권장되는 프로덕션 준비 옵션입니다.
- GitHub Actions secrets에 저장된 자격 증명:
SFDX_CONSUMER_KEY, SFDX_JWT_SECRET_KEY 및 SFDX_USERNAME.
단계별 JWT 설정(및 로컬 실험을 위한 더 간단한 SFDX Auth URL 대안)은 docs/authentication.md를 참조하세요.
최소 파이프라인
🔁 재사용 가능한 워크플로우
일반적인 시나리오의 경우, 블록들을 직접 연결할 필요 없이 유지 관리되는 재사용 가능한 워크플로우 중 하나를 호출하세요:
| Workflow | 목적 |
|---|
| pr-validation.yml | 풀 리퀘스트(pull request) 검증: 정적 분석 + 테스트를 포함한 체크 전용(delta) 배포 |
| ... | |
| Call one from your own repository like this: | |
📋 예시 (Examples)
examples 폴더에는 각 재사용 가능한 워크플로우(reusable workflow)에 대한 완전하고 복사하여 붙여넣기만 하면 되는 호출자 워크플로우가 포함되어 있습니다. 이 중 하나를 프로젝트의 .github/workflows/ 디렉터리에 넣고 입력값(inputs)을 조정하세요.
📚 문서 (Documentation)
🔐 보안 및 버전 관리 (Security & versioning)
이 저장소의 모든 uses: 참조(재사용 가능한 워크플로우, reusable workflows, examples 및 위 스니펫에서)는 정확한 릴리스 버전으로 고정되어 있습니다. 예: svierk/[email protected]. 여러분의 파이프라인에서도 동일하게 하세요:
@main이나 @v1 같은 변경 가능한 참조(mutable ref)는 절대 사용하지 마세요. 이들은 실행 시 해당 브랜치/태그에 있는 모든 코드를—사용자의 org 자격 증명에 접근하여—실행하기 때문에, 손상되거나 재작성된 참조가 눈에 띄지 않게 실행될 수 있습니다.- 좋음 - 정확한 릴리스 태그에 고정(pin)하세요 (
@v1.2.1). 읽기 쉽고 구체적이며 검토된 풀 리퀘스트를 거쳐 버전이 올라갑니다. 이 키트 자체가 사용하는 방식입니다.
- 가장 엄격함 - 완전한 커밋 SHA(
@a1b2c3d…)에 고정하고, 뒤에 버전을 주석으로 추가하세요. SHA는 발행자에 의해 절대 재지정될 수 없습니다. 단점은 가독성입니다. 통제하지 않는 발행자로부터의 액션에는 그만한 가치가 있습니다.
github-actions용 **Dependabot**을 활성화하여 이러한 고정(pin)이 시간이 지나도 사라지지 않도록 하세요. 여기에서 사용된 설정은 .github/dependabot.yml를 참조하세요 (각 생태계별로 하나의 그룹화된 풀 리퀘스트가 생성되며, 필요한 검사가 통과하면 자동으로 병합됩니다).
이는 워크플로우가 참조하는 모든 액션에 적용됩니다—이 키트의 구성 요소뿐만 아니라 actions/* 및 기타 모든 타사 액션에도 해당합니다.
고정(pinning) 외에도, 이 키트의 워크플로우는 복사할 가치가 있는 몇 가지 규칙을 따릅니다:
- 최소 권한의
GITHUB_TOKEN - 모든 워크플로우는 필요한 것만 부여하는 permissions: 블록을 선언합니다 (contents: read가 대부분의 경우입니다). 재사용 가능한 워크플로우는 호출자가 허용하는 것보다 더 많은 것을 받을 수 없다는 점을 기억하십시오. 따라서 PR 검증은 호출 워크플로우에서도 security-events: write가 필요합니다.
- checkout에서
persist-credentials: false - 토큰이 .git/config에 기록되지 않으므로, 후속 단계(SF CLI, 타사 액션)에서 이를 재사용할 수 없습니다.
- 시크릿은 시크릿으로 전송됨 - 재사용 가능한 워크플로우의
secrets: 블록이나 액션 입력으로 전달하고, 셸 단계에서는 환경 변수("$TARGET_ORG")로 참조하며, 스크립트 자체에 ${{ ... }}를 보간하는 방식으로 절대 참조하지 마십시오. 그렇게 하면 명령어 주입(command injection)이 발생할 수 있고 값이 로그에 유출될 수 있습니다.
pull_request로 풀 리퀘스트 검증 (절대 pull_request_target 사용 금지) - 후자는 기본 저장소의 시크릿으로 실행되므로, 포크가 자체 코드를 귀하의 조직(org)을 대상으로 실행하도록 허용할 수 있습니다.- 생성된 자격 증명 마스킹 - 런타임에 생성되는 값(예: 스크래치 org 비밀번호)은 로그에 도달하기 전에
::add-mask::로 마스킹됩니다.
- GitHub Environment 뒤에서 프로덕션을 보호하십시오 - 배포 워크플로우는 필요한 검토자 및 환경 범위 시크릿을 위해
environment 입력을 받습니다.
🤝 기여하기 (Contributing)
기여를 환영합니다! 변경 사항 제안, 문제 보고 또는 새로운 빌딩 블록 추가 방법은 CONTRIBUTING.md를 참조하십시오.
라이선스 (License)
본 프로젝트의 스크립트와 문서는 MIT License에 따라 공개됩니다.
