GHCR 프라이빗 이미지 배포

GitHub Container Registry(GHCR)의 프라이빗 이미지를 Deplite로 배포하는 공식 패턴이에요.
Deplite는 registry credential을 저장하지 않아요.
대신 GitHub Actions가 배포할 때마다 단명 GITHUB_TOKEN을 트리거 params로 실행 시점에만 전달해요.

흐름은 다음과 같아요.

GitHub Actions가 이미지를 빌드해서 GHCR에 푸시해요.
GitHub Actions가 Deplite 트리거를 호출하면서 GITHUB_TOKEN을 params로 넘겨요.
디바이스의 Agent가 그 토큰으로 docker login → pull → logout을 수행하고 컨테이너를 올려요.

GITHUB_TOKEN은 Actions job이 끝나면 만료되기 때문에, 장기 credential이 디바이스에도 Deplite에도 남지 않아요.
장기 PAT를 디바이스에 docker login으로 영구 저장하는 방식은 권장하지 않아요.

1. 디바이스 워크플로우 작성

Agent의 워크플로우 디렉토리에 다음 YAML을 추가해주세요.

workflows/deploy-myapp.yaml


name: deploy-myapp
timeout-minutes: 15
params:
  - name: image
    type: string
    required: true
  - name: ghcr_user
    type: string
    required: true
  - name: ghcr_token
    type: string
    required: true
steps:
  - name: deploy
    run: |
      echo "$DEPLITE_PARAM_GHCR_TOKEN" | docker login ghcr.io -u "$DEPLITE_PARAM_GHCR_USER" --password-stdin
      docker pull "$DEPLITE_PARAM_IMAGE"
      docker logout ghcr.io
      IMAGE="$DEPLITE_PARAM_IMAGE" docker compose -f /opt/myapp/docker-compose.yml up -d

트리거로 넘어온 params는 DEPLITE_PARAM_<KEY>(대문자) 환경변수로 step에 주입돼요.
compose 파일의 image:가 전달받은 태그를 쓰도록 image: ${IMAGE} 형태로 구성하는 걸 권장해요.

params를 선언한 워크플로우는 선언된 키만 트리거 호출을 통과해요.
선언되지 않은 키가 들어오거나 required 키가 빠지면 호출이 거절돼요.

토큰 값($DEPLITE_PARAM_GHCR_TOKEN)을 echo 등으로 로그에 출력하지 않도록 주의해주세요.
--password-stdin처럼 값을 표준 입력으로 넘기는 방식을 사용하는 걸 권장해요.
GITHUB_TOKEN은 Actions job이 끝나면 만료되기 때문에, 만에 하나 로그에 노출되더라도 위험 노출 기간은 짧아요.

2. Deplite 설정

트리거 생성

대시보드에서 Webhook 트리거를 만들어주세요.

옵션	권장값	이유
`scopeType`	`agent`	한 트리거로 해당 Agent의 여러 배포 워크플로우를 호출할 수 있어요
`responseMode`	`sync`	배포 성공/실패가 CI step에 바로 반영되고, CI job이 살아 있는 동안(= `GITHUB_TOKEN`이 유효한 동안) 실행이 끝나는 걸 보장해요
`responseTimeoutMs`	이미지 크기에 맞게 여유 있게 (예: `300000`)	기본값 30000ms는 큰 이미지 pull에 부족할 수 있어요

async로 호출하면 CI job이 먼저 끝나면서 GITHUB_TOKEN이 만료될 수 있고, 그 뒤에 디바이스가 pull을 시도하면 실패해요.
이 패턴에서는 sync를 권장해요.

API 토큰 발급

대시보드 API 토큰에서 trigger scope의 토큰을 발급해주세요.
GitHub repo의 Settings → Secrets에 DEPLITE_API_TOKEN으로 저장하고, 트리거 ID는 Variables에 DEPLITE_TRIGGER_ID로 저장해주세요.

3. GitHub Actions 워크플로우 작성

배포 job에는 packages: read 권한이 필요해요.

.github/workflows/deploy.yml


name: deploy
on:
  push:
    branches: [main]
 
permissions:
  contents: read
  packages: read
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: Deplite/trigger-action@v1
        with:
          api-token: ${{ secrets.DEPLITE_API_TOKEN }}
          trigger-id: ${{ vars.DEPLITE_TRIGGER_ID }}
          workflow-name: deploy-myapp
          wait: sync
          params: >-
            {
              "image": "ghcr.io/${{ github.repository }}:${{ github.sha }}",
              "ghcr_user": "${{ github.actor }}",
              "ghcr_token": "${{ secrets.GITHUB_TOKEN }}"
            }

agent-scope 트리거이므로 workflow-name이 필수예요.
이미지 빌드·푸시를 같은 job에서 한다면 packages: write가 필요해요.
wait: sync라서 배포가 실패하면 이 step도 실패해요.

GHCR 이미지 이름은 소문자만 허용돼요.
저장소나 소유자 이름에 대문자가 있다면 소문자로 변환해서 사용해주세요.

REST API로 직접 호출하기

액션 대신 curl로 직접 호출할 수도 있어요.


      - name: Deplite로 배포 트리거
        run: |
          curl -fsS -X POST "https://api.deplite.io/v1/triggers/${{ vars.DEPLITE_TRIGGER_ID }}/run" \
            -H "Authorization: Bearer ${{ secrets.DEPLITE_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -H "Idempotency-Key: gha-${{ github.run_id }}-${{ github.run_attempt }}" \
            -d '{
              "workflowName": "deploy-myapp",
              "params": {
                "image": "ghcr.io/${{ github.repository }}:${{ github.sha }}",
                "ghcr_user": "${{ github.actor }}",
                "ghcr_token": "${{ secrets.GITHUB_TOKEN }}"
              }
            }'

Idempotency-Key를 붙이면 같은 실행이 재시도돼도 중복 배포가 생기지 않아요.

한계와 주의사항

항상 온라인인 디바이스에 적합해요. GITHUB_TOKEN은 CI job이 끝나면 만료되기 때문에, 오래 꺼져 있다가 나중에 접속하는 디바이스는 그 시점에 pull이 실패해요.
다른 repo·org의 이미지에는 GITHUB_TOKEN 권한이 닿지 않을 수 있어요. 그 경우에 한해 read:packages 최소 권한의 PAT 사용을 권장해요.
이 경로는 이미지 전달 패턴이에요. 릴리스 버전 추적·오프라인 기기 수렴이 필요하다면 App Deploy (OTA)를 참고해주세요.