외부 서비스에 빌드 결과를 보내는 스크립트가 있다고 가정해 보세요. 스크립트에 토큰을 직접 적거나 값을 출력하면 저장소나 빌드 로그를 통해 의도치 않게 노출될 수 있습니다. 따라서 저장할 값의 성격부터 구분해야 합니다.

Apple은 워크플로 환경 변수와 공유 환경 변수, 비밀값, 미리 정의된 환경 변수를 구분해 설명합니다. Xcode Cloud 환경 변수 참고 자료에서 변수의 용도를 확인한 다음, 실제 사용 위치에 맞춰 선택하세요.

주의: 로그에서 비밀값이 가려지는 동작은 권한 분리를 대신하지 않습니다. 스크립트가 실행되는 맥락과 자격 증명을 전달할 작업도 따로 검토하세요.

Apple의 Xcode Cloud 워크플로 참고 자료는 워크플로 실행 구조와 관련 설정을 설명합니다. 환경 변수만 비밀값으로 바꿨다고 해서 모든 실행 상황에서 안전하다고 단정하지 마세요.

한 워크플로에서만 쓰는 값은 그 워크플로에 설정하고, 실제로 여러 워크플로가 함께 쓰는 값은 공유 환경 변수로 검토하세요. 공유한다는 이유만으로 모든 워크플로에 접근을 열어둘 필요는 없습니다.

Apple의 공유 환경 변수 설정 안내를 따라 공유 대상을 확인하세요. 생성 후에는 목표 워크플로에 변수가 연결되어 있는지, 팀에서 누가 설정을 수정할 수 있는지 확인합니다. Xcode Cloud 워크플로 전략과 편집 권한 안내도 함께 검토하면 역할에 맞지 않는 편집 권한을 줄이는 데 도움이 됩니다.

Apple 문서에는 사용자 설정 빌드 스크립트 단계로 post-clone, pre-xcodebuild, post-xcodebuild가 설명되어 있습니다. 단계마다 목적이 다르므로, 변수가 모든 시점에 같은 조건으로 쓰인다고 가정하지 마세요. 사용자 설정 빌드 스크립트 작성 안내에서 실행 위치와 프로젝트 리소스 경계를 확인하세요.

• post-clone: 저장소를 받은 뒤 의존성이나 빌드 준비를 처리할 때 검토합니다.
• pre-xcodebuild: Xcode 빌드 전에 필요한 점검이나 설정을 수행할 때 사용합니다.
• post-xcodebuild: 빌드 결과를 확인하거나 외부 서비스로 전달하는 후속 작업에 적합한지 검토합니다.

작업 단계별 책임을 명확히 나누세요. 예를 들어 토큰이 빌드 결과 업로드에만 필요하다면, 준비 작업부터 업로드 작업까지 모든 스크립트에 연결하지 않는 편이 낫습니다.

설정 화면에서 값이 보인다는 것만으로 스크립트가 올바르게 읽는다고 판단할 수 없습니다. 다음 순서로 검증하세요.

1. 토큰 대신 식별하기 쉬운 가짜 값으로 테스트 변수를 만듭니다.
2. 변수가 필요한 워크플로에만 연결되어 있는지 확인합니다.
3. 스크립트에서 값을 출력하지 않고, 값이 존재하는지 여부만 검사합니다.
4. 값이 없을 때 업로드나 배포가 중단되도록 실패 처리를 추가합니다.
5. 실행 결과에서 스크립트 출력, 빌드 보고서, 종료 상태를 확인합니다.
6. 검증이 끝나면 테스트 값을 제거하고 실제 비밀값을 지정합니다.

Apple은 비밀값의 로그 처리 방식과 사용자 설정 스크립트 동작을 안내합니다. 비밀값과 스크립트 로그 관련 문서를 확인하되, 로그 마스킹에만 의존하지 말고 출력문과 오류 메시지도 살펴보세요. 변수 이름을 출력하는 것과 값 자체를 출력하는 것은 다른 문제지만, 진단을 위해 전체 환경을 무차별적으로 기록하는 방식은 피해야 합니다.

브랜치 변경, 풀 리퀘스트, 수동 실행, 배포용 워크플로는 코드가 실행되는 맥락이 서로 다를 수 있습니다. 민감한 값이 비밀값으로 표시되어 있다는 사실만으로, 외부 기여 코드나 모든 트리거에서 자격 증명 사용이 적절하다고 볼 수는 없습니다.

각 실행 경로에서 해당 스크립트가 실제로 실행되는지 확인하세요. 외부 서비스에 접근할 필요가 없는 빌드라면 비밀값을 연결하지 마세요. 신뢰할 수 없는 변경을 처리하는 경로와 배포 자격 증명이 필요한 경로를 구분하고, 권한이나 정책이 바뀌면 테스트 워크플로에서 다시 검증합니다.

Apple의 Xcode Cloud 피드백 및 스크립트 로그 안내는 로그 내용과 관련된 확인 자료입니다. 임시 빌드 환경과 보조 도구에 관한 기술 참고 자료도 참고해 실행 환경과 도구의 동작을 확인하세요.

알림: 환경 변수 오류가 나면 실제 비밀값을 출력해 원인을 찾지 마세요. 변수 연결, 실행 단계, 변수 이름, 종료 코드 순서로 추적하면 노출 위험을 낮출 수 있습니다.

Xcode Cloud에 사용자 설정 환경 변수를 어디에 추가하나요?

앱의 Xcode Cloud 설정에서 사용할 워크플로에 환경 변수를 추가하고, 빌드 스크립트가 실행되는 작업에서 값이 전달되는지 확인하세요. 여러 워크플로가 같은 값을 써야 한다면 공유 환경 변수를 검토할 수 있습니다. 다만 공유 설정을 만들었다고 모든 워크플로에 무조건 할당하지 말고, 실제로 필요한 대상만 지정하세요. 민감하지 않은 설정은 일반 변수로 두고 토큰이나 비밀번호는 비밀값으로 관리합니다.

Xcode Cloud 비밀값이 빌드 로그에 나오지 않게 하려면 어떻게 해야 하나요?

민감한 값을 일반 환경 변수로 두지 말고 비밀값으로 표시한 뒤, 스크립트에서 값을 출력하지 않도록 작성하세요. Apple은 비밀값을 로그에서 보호하는 동작을 설명하지만, 이는 스크립트가 값을 출력해도 안전하다는 뜻이 아닙니다. 테스트용 가짜 값으로 로그와 빌드 보고서를 확인하고, 실제 자격 증명은 필요한 작업에만 전달하세요. 로그 마스킹과 자격 증명 접근 권한은 서로 다른 통제입니다.

여러 Xcode Cloud 워크플로가 같은 환경 변수를 함께 쓸 수 있나요?

공유 환경 변수를 사용하면 여러 워크플로에서 공통 설정을 참조할 수 있습니다. 하지만 공유 범위가 넓을수록 불필요한 작업에도 값이 연결될 수 있으므로, 각 워크플로에서 실제 사용 여부를 확인한 뒤 할당하세요. 외부 서비스 토큰처럼 영향이 큰 값은 공유가 편리하다는 이유만으로 모든 빌드에 연결하지 않는 편이 안전합니다. 변수 편집 권한도 팀의 역할에 맞게 검토하세요.

사용자 설정 스크립트에서 환경 변수를 읽지 못하면 무엇을 확인해야 하나요?

먼저 변수가 실행 대상 워크플로에 연결되어 있는지 확인하고, 스크립트가 실행되는 단계와 변수 이름이 일치하는지 점검하세요. 사용자 설정 스크립트 단계마다 프로젝트 파일과 실행 조건이 같다고 가정하지 마세요. 값 자체를 로그에 남기지 말고, 가짜 값의 존재 여부만 검사하도록 임시 검증을 작성할 수 있습니다. 변수가 없을 때는 업로드나 배포를 계속하지 말고 명확한 오류와 실패 상태를 반환하게 하세요.

Xcode Cloud에서 제공하는 워크플로와 스크립트로 현재 빌드 요구를 충족한다면, 변수 범위와 검증 절차를 정리해 계속 사용할 수 있습니다. 반대로 빌드 사이에 상태를 계속 보존해야 하거나, 대화형으로 문제를 조사해야 하거나, 직접 관리할 macOS 환경이 필요하다면 별도 환경을 검토할 시점입니다. 다만 필요한 제어 수준과 실제 작업 흐름을 먼저 적어야 합니다. 원격 환경이 모든 빌드 요구를 자동으로 해결한다고 가정하지 마세요.

현재 방식은 관리할 호스트가 적고 워크플로 통합이 편리할 수 있지만, 지속 상태를 직접 다루거나 실행 환경을 세밀하게 조정하는 데 제약이 있을 수 있습니다. 맥을 직접 구매하면 물리 장비와 유지 관리를 맡아야 하고, 원격 환경은 접속 방식과 제공 범위를 먼저 확인해야 합니다. 비용과 조건을 비교할 때는 독립 개발자를 위한 맥 미니 대여 비용 안내를 참고하고, 필요한 환경이 맞는지 KVMNODE의 맥 원격 이용 안내에서 확인하세요.

기존 워크플로가 자주 중단되지 않고 환경 제어도 충분하다면 지금 전환할 필요는 없습니다. 지속 작업 공간이나 대화형 점검이 실제 병목이라면, 원격 맥을 보조 빌드 경로로 검토해 현재 방식과 비교하세요. 어느 쪽을 선택하든 비밀값은 필요한 작업에만 전달하고 로그로 다시 확인하는 원칙을 유지해야 합니다.