Semaphore를 사용하는 도구에 연결

REST API로 리소스를 관리하고 작업 및 워크플로를 실행하며 결과를 가져옵니다. 웹훅으로 수신 이벤트를 연결하세요.

무료로 설치 REST API 살펴보기

별도 도구에 있는 자동화는 작업 흐름을 끊습니다

포털, 파이프라인, 인프라 도구가 이미 업무를 움직입니다. 자동화가 별도로 있으면 설정 반복, 인터페이스 전환, 수동 결과 수집이 필요합니다.

설정과 실행을 위한 하나의 API

Semaphore 관리프로젝트, 접근, 자동화 설정

자동화 트리거작업, 워크플로, 이벤트 기반 실행

결과 가져오기실행 상태, 로그, 실행 출력

자체 시스템에서 Semaphore 관리

REST API로 프로젝트, 접근, 자동화 리소스를 만들고 업데이트하세요. Semaphore를 서비스 카탈로그, 온보딩 프로세스, 인프라 도구와 동기화합니다.

플랫폼 전체를 위한 문서화된 API

리소스를 설정하고 접근을 관리하며 상태를 살펴보세요. 요청은 인증된 계정의 권한을 사용합니다. OpenAPI 레퍼런스에 매개변수, 요청 본문, 응답이 문서화되어 있습니다.

API 레퍼런스 살펴보기

자동화를 트리거하고 결과 추적

REST 호출에는 서비스에 필요한 프로젝트 접근 권한이 있는 계정으로 API 토큰을 만드세요. 수신 웹훅에는 연동을 만들고 작업 템플릿을 선택한 뒤 요청 인증을 설정하세요.

같은 자동화에 도구 연결

작업을 작업 템플릿에 보관

포털이 엔지니어가 UI에서 실행하는 것과 같은 작업을 시작합니다.

작업 템플릿

일련의 작업 트리거

작업, 데이터, 승인, 결과 기반 분기를 연결하세요.

워크플로

요청이 시작한 작업 추적

반환된 작업 ID를 보관하고 기록된 결과를 확인하세요.

실행 기록 및 로그

REST API 및 웹훅 연동 옵션

수신 이벤트를 올바른 작업에 라우팅

프로젝트 웹훅 별칭으로 연동 매처를 평가하고 이벤트를 수락할 작업을 선택하세요. 연동별 별칭은 매처를 우회해 한 연동을 직접 호출합니다. 여러 시스템이 엔드포인트를 공유할 때 리포지토리, 브랜치, 이벤트 필드를 매칭하고 일치하는 요청과 일치하지 않는 요청을 모두 테스트하세요.

이벤트 페이로드를 실행 입력에 매핑

값 추출기로 요청 헤더나 본문 필드를 읽고 환경 값 또는 지원되는 작업 매개변수로 매핑하세요. 저장된 작업을 다시 만들지 않고 릴리스 버전, 서비스 이름, 요청 참조 같은 값을 전달합니다. 매개변수 매핑은 작업 템플릿이 공개한 프롬프트와 일치해야 합니다.

API 호출 및 수신 웹훅 인증

REST API 호출은 개인 API 토큰과 해당 Semaphore 계정의 권한을 사용합니다. 웹훅 연동은 GitHub 및 Bitbucket 웹훅, Token, HMAC SHA-256 또는 SHA-512, BasicAuth 등 자체 인증 설정을 가집니다. 발신자가 지원하는 방식을 설정하고 요청 자격 증명을 작업에 사용하는 인프라 자격 증명과 구분하세요.

자체 시스템에서 Semaphore 관리

REST API는 프로젝트, 리포지토리, 인벤토리, 자격 증명, 변수 그룹, 작업 템플릿, 예약, 연동과 작업 실행 및 Pro Workflow API를 다룹니다. 서비스에서 자동화 리소스를 프로비저닝하고 설정된 작업을 시작한 다음 상태와 출력을 읽습니다. OpenAPI 레퍼런스에 엔드포인트 매개변수, 요청 본문, 응답 스키마가 문서화되어 있습니다.

요청이 생성한 작업 추적

생성된 작업은 실행 대기 중인 작업이지 완료된 작업이 아닙니다. API가 반환한 식별자를 보관하고 문서화된 작업 엔드포인트를 폴링하여 상태와 출력을 확인하세요. 그러면 서비스가 요청 오류, 대기 중인 실행, 완료된 결과를 구분하고 엔지니어에게 실제 증거로 바로 연결되는 링크를 제공할 수 있습니다. 전달 방식에 대해 단정하지 마세요. 첫 요청이 도착했어도 상위 서비스가 시간 초과 후 재시도할 수 있으므로, 영향을 수반하는 작업은 중복을 처리하고 자동화를 멱등하게 설계하세요. 결과를 채팅이나 이메일로 보내는 것은 별도의 기능입니다.

GitHub, Bitbucket 및 다른 이벤트 소스 연결

연동은 GitHub 및 Bitbucket 웹훅 인증, 토큰, HMAC SHA-256 또는 SHA-512, Basic Auth를 지원합니다. 수신 헤더나 본문 필드를 매칭한 다음 저장된 작업에 필요한 값을 추출하세요. 호출자가 결과 확인이나 리소스 관리도 해야 한다면 REST API를 사용하세요.

문서 및 관련 기능

FAQ

작업 시작에 REST API와 웹훅 연동 중 무엇을 사용해야 하나요?

외부 이벤트로 사전 정의된 작업 템플릿을 선택하고 요청 값을 허용된 입력에 매핑하려면 웹훅 연동을 사용하세요. 애플리케이션이 작업 시작과 상태 읽기 같은 명시적 리소스 및 실행 흐름을 필요로 하면 REST API를 사용합니다. 두 경우 모두 자동화는 Semaphore의 설정된 실행 모델로 실행됩니다. 호출자가 보내고 추적해야 할 내용을 기준으로 선택하세요.

프로젝트 별칭과 연동별 별칭은 어떻게 다른가요?

프로젝트 별칭은 해당 연동에 설정된 매처를 평가하고 요청에 일치하는 연동을 시작할 수 있습니다. 연동별 별칭은 매처를 평가하지 않고 하나의 연동을 직접 지정합니다. 브랜치나 이벤트 유형 규칙으로 실행을 제어하려면 이 차이가 중요합니다. 모든 별칭 경로에 같은 필터가 적용된다고 가정하지 말고, 엔드포인트를 의도적으로 선택하여 일치하는 페이로드와 일치하지 않는 페이로드를 모두 테스트하세요.

웹훅으로 릴리스 버전이나 환경 값을 어떻게 전달하나요?

관련 요청 헤더나 본문 필드를 읽고 문서화된 환경 값 또는 작업 매개변수에 매핑하도록 추출기를 설정하세요. 매개변수 대상은 템플릿이 허용하는 프롬프트와 일치해야 합니다. 매핑은 구체적으로 유지하세요. 릴리스 버전은 제한 없는 명령 조각이 아니라 의도한 입력이 되어야 합니다. 의미상 검증이 필요한 값은 자동화에서 검증하고, 프로덕션 사용 전에 누락되거나 예상치 못한 필드도 테스트하세요.

API 요청은 어떤 ID와 권한을 사용하나요?

API 토큰은 해당 Semaphore 사용자의 권한으로 동작합니다. 연동에서 의도하는 작업에 맞는 프로젝트 접근을 가진 ID를 사용하고 호출자가 저장하는 토큰을 보호하세요. API로 프로젝트 인가를 우회할 수는 없습니다. 웹훅 연동도 문서화된 요청 인증과 엔드포인트 노출 범위를 의도적으로 설정하세요. 호출자 인증과, 생성된 작업이 인프라에 접근할 때 사용하는 자격 증명은 구분하세요.

서비스에서 시작한 작업을 어떻게 추적해야 하나요?

REST API 흐름에서는 문서화된 동작이 반환한 작업 식별자를 보관하고 해당 API 메서드로 상태와 출력을 확인하세요. 요청 성공은 실행이 요청되었다는 뜻이지 인프라 작업이 성공적으로 완료되었다는 뜻이 아닙니다. 서비스는 요청 오류, 대기 중 또는 실행 중 작업, 완료 결과를 구별해야 합니다. 실제 실행 증거를 조사할 엔지니어에게 해당 작업 링크를 제공하세요.

웹훅이 재시도되어도 작업은 반드시 한 번만 실행되나요?

정확히 한 번만 실행되거나 영속적인 전달이 보장된다고 가정하지 마세요. 첫 요청이 Semaphore에 도달했어도 외부 서비스는 시간 초과 후 요청을 재시도할 수 있습니다. 작업의 영향에 맞춰 중복 처리와 재시도 결정을 설계하고 필요한 경우 기반 자동화를 멱등하게 만드세요. 엔지니어가 반복되거나 불확실한 전달을 이해할 수 있도록 원본 이벤트와 서비스가 추적하는 실행의 연관 관계를 유지하세요.

Semaphore API 명세는 어디서 찾나요?

이 사이트의 레퍼런스는 Semaphore 릴리스와 함께 게시된 Swagger/OpenAPI 문서를 표시하므로 보이는 동작, 경로, 스키마는 수동 요약이 아닌 특정 버전에 대응합니다. /api-docs/에서 리소스별로 보거나 클라이언트 생성에 사용한다면 원문을 읽으세요. 릴리스마다 엔드포인트와 요청 스키마가 바뀔 수 있으므로 실제 사용하는 버전의 명세를 항상 확인하세요.

웹훅 연동에 인터넷 공개 엔드포인트가 필요한가요?

호출 시스템은 Semaphore 인스턴스에 도달해야 하지만 공개 인터넷일 필요는 없습니다. 호출자가 내부에서 실행된다면 프라이빗 네트워크, VPN, 내부 로드 밸런서로 충분합니다. 자체 매처 및 추출기 검증은 인증을 끈 루프백 전용 리스너를 사용했으며 공개 엔드포인트의 모델이 아닙니다. 신뢰 네트워크 밖에서 별칭에 접근할 수 있다면 지원되는 인증 방식을 설정하고 네트워크 계층에서도 노출을 제한하세요.

실제 시스템을 연결하기 전에 연동을 어떻게 테스트하나요?

먼저 영향이 없는 작업 템플릿에 연동을 연결한 뒤 curl이나 HTTP 클라이언트로 직접 페이로드를 보내세요. 일치하지 않는 본문을 보내 작업이 생성되지 않는지 확인하고, 일치하는 본문을 보내 정확히 한 작업이 시작되는지 확인하세요. 해당 작업의 상세 화면을 열면 소스가 연동으로 기록되고 추출된 값이 실행에 표시됩니다. 이는 로컬에서 검증한 것과 같은 순서이며 외부 서비스가 의존하기 전에 잘못된 매처 키를 잡아냅니다.

API로 Semaphore 리소스를 관리하고 워크플로를 실행할 수 있나요?

네. REST API는 프로젝트, 리포지토리, 인벤토리, 자격 증명, 변수 그룹, 작업 템플릿 및 기타 자동화 리소스를 다룹니다. 포털이나 인프라 서비스가 설정하고 작업을 시작하며 실행 상태와 출력을 읽을 수 있습니다. Pro는 API로 워크플로 실행과 승인도 노출하므로 CI/CD 파이프라인이 전체 다단계 작업을 시작할 수 있습니다. 엔드포인트 매개변수와 응답 스키마는 OpenAPI 레퍼런스를 사용하세요.