ngrok 이용 local환경 jenkins github webhooks

1. Jenkins 환경

• 실행환경 : windows Docker Desktop Jenkins (ip: 192.168.56.1:8081)
• jenkins plugin 설치: Github Integration Plugin
  (Jenkins 대시보드에서 Manage Jenkins > Manage Plugins로 이동해 GitHub 플러그인을 검색하고 설치)
• jenkins 작업 설정: (새로운 작업을 생성하거나, 기존 작업 편집)
  . Source Code Management 섹션에서 GitHub 저장소 URL을 입력합니다 (예: https://github.com/username/repository.git).
  . Build Triggers 섹션에서 GitHub hook trigger for GITScm polling 옵션을 체크

2. 로컬 Jenkins를 외부에서 접근 가능하게 만들기

• GitHub Webhooks는 공개적으로 접근 가능한 URL로 요청을 보내야 하므로, 로컬 IP(192.168.56.1:8080)를 외부에 노출해야 합니다. 이를 위해 ngrok를 사용
  1) ngrok 설치 ngrok 공식 사이트에서 계정을 만들고, ngrok 실행 파일을 다운로드합니다. 다운로드한 파일을 압축 해제하고, PC에서 실행 가능한 경로로 이동합니다.
  2) ngrok 실행 터미널(Windows의 경우 명령 프롬프트 또는 PowerShell)을 열고 다음 명령어를 입력해 Jenkins 포트(8080)를 외부로 노출합니다: ngrok http 8080
• 실행 후, ngrok는 다음과 같은 정보 제공
  . Forwarding URL: 예를 들어, https://abcd1234.ngrok.io와 같은 공개 URL이 생성
  . 이 URL은 로컬 Jenkins(http://192.168.56.1:8080)로 요청

ngrok http 8080 실행 화면

 

3. GitHub Webhook 설정 GitHub 저장소에서 Webhook을 설정해 Jenkins로 이벤트를 보낸다.

• (1) GitHub 저장소 이동 GitHub에서 Webhook을 추가할 저장소로 이동
  . Settings > Webhooks > Add webhook을 클릭.
• (2) Webhook 구성 Payload URL: ngrok에서 제공한 공개 URL 뒤에 /github-webhook/을 추가합니다.
  (예: https://abcd1234.ngrok.io/github-webhook/)
  . Content type: application/json을 선택
  . Secret: 보안을 위해 임의의 비밀 키를 설정할 수 있다(선택 사항. Jenkins에서도 동일한 비밀 키를 입력)
  . Which events would you like to trigger this webhook?: 기본적으로 Push events를 선택
  . Active: 체크박스를 활성화
  . Add webhook 버튼을 클릭해 저장
• (3) Webhook 테스트 Webhook 추가 후, GitHub의 Webhook 페이지에서 Recent Deliveries 확인
  . 방금 추가한 Webhook 옆에 있는 ... 버튼을 클릭하고 Redeliver를 선택해 테스트 요청 보낸다
  . 성공적으로 연결되었다면 상태 코드 200 OK가 표시
  . 실패 시, Jenkins 로그나 ngrok 인터페이스(http://127.0.0.1:4040)에서 오류 확인

http://127.0.0.1:4040 접속 화면

 

 

 

ngrok http 8081 명령어를 실행했을 때 발생 오류

• ngrok의 설정 파일(C:\Users\esc0\.ngrok2\ngrok.yml)이 잘못된 형식(YAML 파싱 오류) 때문에 제대로 읽히지 않는 문제
  . 오류 메시지: ngrok authtoken ...

---

ngrok 설정 파일(ngrok.yml)은 ngrok의 동작을 정의하는 YAML 형식의 파일. 일반적으로 ngrok authtoken <토큰> 명령어를 실행하면 이 파일에 authtoken이 저장됩니다. 하지만 다음과 같은 이유로 오류가 발생했을 가능성이 있습니다:

1. ngrok authtoken 명령어를 잘못 입력해 파일에 잘못된 내용이 기록됨.
2. ngrok.yml 파일을 수동으로 편집했거나 손상됨.
3. 파일 형식이 YAML 규칙을 따르지 않음(예: 잘못된 들여쓰기, 잘못된 키-값 쌍).

---

1. ngrok.yml 파일 확인

• 파일 위치: 오류 메시지에 따르면 설정 파일은 C:\Users\esc0\.ngrok2\ngrok.yml
• 형식 예시: 정상적인 ngrok.yml 파일은 다음과 같이 간단한 구조
   

  authtoken: 2aBcDeFgHiJkLmNoPqRsTuVwXyZ123_4567890abcdef1234567890

  또는 더 복잡한 경우:
   

  version: "2"
  authtoken: 2aBcDeFgHiJkLmNoPqRsTuVwXyZ123_4567890abcdef1234567890
  tunnels:
    jenkins:
      proto: http
      addr: 8080

• 문제 : 파일 내용이 위와 같은 YAML 형식이 아니라면(예: ngrok authtoken ..같은 명령어 자체가 텍스트로 저장됨), 파일 손상

2. ngrok.yml 파일 수정 또는 재설정

• 방법 1: 파일 직접 수정
  • ngrok.yml 파일을 열어 모든 내용을 삭제하고 최소한 다음 내용만 입력
     

    authtoken: <당신의-authtoken>

    <당신의-authtoken>은 ngrok 대시보드에서 복사한 실제 authtoken으로 교체
  • 파일을 저장
• 방법 2: authtoken 재설정
  • ngrok.yml 파일을 완전히 삭제하거나 이름을 변경해 백업하세요:
     

    C:\Users\esc0\.ngrok2\ngrok.yml

    예: ngrok.yml.bak으로 이름 변경.
  • PowerShell에서 다음 명령어로 authtoken을 다시 설정

    .\ngrok.exe authtoken <당신의-authtoken>

    이 명령은 새로운 ngrok.yml 파일을 자동으로 생성
  • authtoken이 없으면 ngrok 대시보드에서 복사

3. ngrok 실행 테스트

• PowerShell에서 ngrok을 다시 실행해 오류가 해결되었는지 확인하세요:

  .\ngrok.exe http 8081

   

  .\ngrok.exe http http://192.168.56.1:8081

• 성공적으로 실행되면 ngrok이 공개 URL(예: https://abcd1234.ngrok-free.app)을 표시
• 이 URL은 로컬 Jenkins(192.168.56.1:8081)로 요청을 전달합니다. URL을 복사해두세요.

4. 파일 권한 문제 확인

• Windows에서 파일 권한 문제로 ngrok.yml을 읽지 못할 수 있다.
• C:\Users\esc0\.ngrok2 폴더와 ngrok.yml 파일에 현재 사용자 계정(esc0)이 읽기/쓰기 권한 확인
  • 파일 탐색기에서 폴더를 우클릭 > 속성 > 보안 탭에서 확인
  • 필요하면 권한 추가

5. ngrok 재설치 (선택 사항)

• 위 방법으로 해결되지 않으면 ngrok을 재설치
  • 기존 ngrok.exe 삭제
  • ngrok 다운로드 페이지에서 Windows용 최신 ngrok을 다운로드해 E:\study에 저장.
  • C:\Users\esc0\.ngrok2 폴더를 삭제해 이전 설정을 초기화.
  • authtoken 설정부터 다시 진행

---

Jenkins와 GitHub Webhook 연동

1. Jenkins 설정 확인

• Jenkins 접속: 브라우저에서 http://192.168.56.1:8081 접속 Jenkins가 정상적으로 실행 확인.
• GitHub 플러그인 설치:
  • Manage Jenkins > Manage Plugins로 이동.
  • Available 탭에서 GitHub Integration 플러그인을 설치하고 Jenkins를 재시작.
• 작업 설정:
  • 새로운 작업(Job)을 만들거나 기존 작업을 편집.
  • Source Code Management에서 Git을 선택하고 GitHub 저장소 URL(예: https://github.com/username/repository.git) 입력.
  • Build Triggers에서 GitHub hook trigger for GITScm polling 체크.

2. GitHub Webhook 설정

• Webhook 추가:
  • GitHub 저장소로 이동 > Settings > Webhooks > Add webhook.
  • Payload URL: ngrok 공개 URL 뒤에 /github-webhook/ 추가.
    • 예: https://abcd1234.ngrok-free.app/github-webhook/
  • Content type: application/json.
  • Secret (선택): 비밀 키 설정 시 Jenkins에서도 동일한 키 입력 필요.
  • Events: Push events 선택.
  • Active 체크 후 Add webhook 클릭.
• Webhook 테스트:
  • Recent Deliveries에서 테스트 요청을 보내 상태 코드 200 OK 확인.
  • 오류 시 ngrok 웹 인터페이스(http://localhost:4040)로 요청 로그 확인.

3. 연동 테스트

• GitHub 저장소에 테스트 커밋 푸시.
• Jenkins 작업의 Build History에서 빌드가 트리거되었는지 확인.

---

추가 문제 해결

• ngrok 실행 문제:
  • Docker 네트워크 설정 확인: Jenkins 컨테이너가 -p 8080:8080으로 포트 매핑되었는지 확인.
     

    docker ps
    docker inspect <컨테이너-이름>

• Webhook 실패:
  • Jenkins 로그(Manage Jenkins > System Log) 또는 ngrok 로그(http://localhost:4040) 확인.
  • github-webhook/ 경로가 정확한지 확인.
• 무료 ngrok 제한:
  • 세션 만료 시 URL이 바뀌므로 GitHub Webhook 설정 업데이트 필요.

---