Jenkins Build periodically: cron 문법과 H 기호

Jenkins의 Build periodically 트리거와 Declarative Pipeline의 triggers { cron('…') }는 cron의 다섯 필드(MINUTE HOUR DOM MONTH DOW)에 H 기호를 더해 받습니다. H는 작업 이름의 해시로 범위 안에서 고정된 값을 골라, 예약된 작업들이 한꺼번에 시작하지 않게 합니다. H 20 * * *는 하루에 한 번 오후 8시대의 고정된 분에 빌드하고, 0 20 * * *는 정확히 오후 8:00에 빌드합니다.

Jenkins 관련 내용은 파이프라인 문법과 Jenkinsfile 사용하기 문서, 그리고 Jenkins 소스에 있는 Build periodically 도움말에서, Sume 관련 내용은 Format 호출하기 (영문), 실행과 결과 (영문), 인증에서 가져왔습니다. 모두 2026-09-28에 확인했습니다. Sume에는 Jenkins 플러그인이 없으며, 빌드가 curl로 HTTPS를 직접 호출합니다.

Jenkins cron 문법은 어떻게 되나요?

공백이나 탭으로 구분한 다섯 필드입니다. 분(0–59), 시(0–23), 일(1–31), 월(1–12), 요일(0–7, 0과 7은 일요일) 순서입니다. 각 필드에는 *, 범위, 간격(step), 목록을 쓸 수 있습니다. Build periodically 입력란에는 한 줄에 스케줄을 하나씩 쓰며, #으로 시작하는 줄은 주석입니다. 다른 스케줄러는 필드 수가 다르며, cron 표현식 6자리에서 비교합니다.

Jenkins cron 표현식에서 H는 무슨 뜻인가요?

H는 해시(hash)를 뜻합니다. Jenkins는 주기적인 작업이 부하를 고르게 내도록 가능한 한 H를 쓰라고 권합니다. 매일 도는 작업 열두 개에 0 0 * * *를 쓰면 자정에 부하가 크게 몰리지만, H H * * *는 각 작업을 여전히 하루에 한 번 실행하면서도 모두 같은 시각에 실행하지는 않습니다. 무작위는 아닙니다. 값은 작업 이름의 해시이므로 한 프로젝트에서는 늘 같은 값으로 유지됩니다.

H는 범위와 간격도 받습니다. 일 필드에서는 해시가 1–28 범위에서 정해지므로, H/3은 월말에 3일에서 6일의 간격을 남길 수 있습니다. @yearly, @monthly, @weekly, @daily, @midnight, @hourly 별칭도 같은 해싱을 씁니다.

Build periodically는 어떤 타임존을 쓰나요?

기본적으로 Jenkins 컨트롤러 JVM의 타임존을 씁니다. 바꾸려면 H 8 * * * 위에 TZ=Europe/London을 두는 것처럼, 스케줄을 TZ= 줄과 타임존 ID로 시작하세요. 쓸 수 있는 ID는 Jenkins가 실행되는 Java 런타임에 따라 다릅니다.

예약된 빌드에서 유료 API는 어떻게 호출하나요?

Sume 문서는 키를 둘 수 있는 곳으로 CI 시크릿 저장소를 꼽으므로, 키를 Secret text 자격 증명으로 저장하고 environment 블록에서 credentials('sume-api-key')로 바인딩하세요. 값이 출력되면 Jenkins는 ****를 표시하는데, Jenkins는 이것이 실수로 노출될 위험을 줄일 뿐이라고 말합니다. sh 스크립트는 작은따옴표로 감싸서 셸이 $SUME_API_KEY를 확장하게 하세요. Jenkins는 Groovy 문자열 보간이 시크릿을 ps 같은 도구로 볼 수 있는 프로세스 인수에 복사한다고 경고합니다. 요청 키는 빌드 날짜로 만들고, 본문은 하루 종일 같게 유지하세요.

pipeline {
  agent any
  triggers { cron('H 20 * * *') }
  environment { SUME_API_KEY = credentials('sume-api-key') }
  stages {
    stage('Start the nightly video') {
      steps {
        sh '''
          curl -sS --fail-with-body --max-time 30 --retry 3 \
            https://api.sume.com/v1/formats/acme/nightly-recap/runs \
            -H "Authorization: Bearer $SUME_API_KEY" \
            -H "Content-Type: application/json" \
            -H "Idempotency-Key: nightly-recap-$(date -u +%F)" \
            -d '{"input":{"feed_url":"https://example.com/nightly.json"},"communication":{"webhook_url":"https://example.com/hooks/sume"}}'
        '''
      }
    }
  }
}

빌드가 재시도되거나 두 번 실행되면 어떻게 되나요?

새로 청구되는 것은 없습니다. options { retry(3) }은 실패한 Pipeline을 다시 실행하고, 같은 UTC 날짜에 나중에 수동으로 돌린 빌드도 같은 날짜 키를 보냅니다. Sume는 같은 키와 본문에 원래 실행과 idempotency_hit: true를 담은 200으로 응답합니다. 두 번째 실행도, 두 번째 청구도 없습니다. 두 빌드가 같은 순간에 돌면 그중 하나가 409 idempotency_key_in_use를 받으며, 약 일 초 뒤에 재시도할 수 있습니다. 같은 날짜에 일부러 두 번째 영상을 만들려면 -v2로 끝나는 키처럼 새 키가 필요합니다.

빌드가 영상을 기다려야 하나요?

기다릴 필요는 없습니다. 생성 요청은 즉시 영수증으로 응답하고 실행 자체는 몇 분이 걸리며, 본문의 communication.webhook_url은 실행이 완료되거나 실패할 때 서명된 POST를 한 번 받습니다. 빌드가 대신 폴링해야 한다면 읽기 간격을 두 배씩 늘려 최대 일 분까지 늘리고, options { timeout(time: 2, unit: 'HOURS') }를 실행 마감보다 길게 설정하세요. 실행 마감은 생성 시점으로부터 최대 90분입니다. Jenkins 타임아웃은 실행이 아니라 빌드를 중단합니다. 폴링 루프를 포기해도 실행이나 그 비용은 멈추지 않습니다. 이런 루프는 GitLab 파이프라인 스케줄: 매일 밤 AI 영상 작업 실행에서 보여 줍니다.