🚀 영어 학습 AI Agent 만들기 & 무료 배포 완벽 가이드 (2) GitHub Actions로 배포

📌 목차

1. 프로젝트 개요
2. 텔레그램 봇 생성
3. 방법 1: GitHub Actions로 배포
4. 방법 2: Render로 배포

🎯 프로젝트 개요

만들 봇의 기능

• ✅ 특정 시간마다 영어 표현 자동 전송
• ✅ 표현, 의미, 영어 예문, 한국어 예문 제공
• ✅ 24개의 다양한 영어 표현 순환
• ✅ 명령어로 제어 가능 (/start, /stop, /now)
• ✅ 무료로 24/7 운영

배포 방법 비교

특징	GitHub Actions	Render
비용	완전 무료	유료 (1분/ $0.00016)
실행 방식	24/7 서버 상시 실행	24/7 서버 상시 실행
설정 난이도	⭐⭐⭐	⭐⭐
상호작용	❌ (일방향)	✅ (명령어 사용 가능)
서버 관리	불필요	자동 관리
추천 대상	단순 알림봇	인터랙티브 봇

🔧 방법 1: GitHub Actions로 배포

장점

• ✅ 완전 무료 (무제한)
• ✅ 설정이 간단
• ✅ 별도 서버 불필요
• ✅ GitHub에서 모든 것 관리

단점

• ❌ 명령어 사용 불가 (일방향 알림만)
• ❌ 스케줄링에 Delay가 있음
• ❌ 상호작용 없음

---

📁 Step 1: GitHub 저장소 생성 및 Git 설치
                  

GitHub란 코드 저장소 및 협업 플랫폼입니다. 
지금은 GitHub Actions로 스케줄링 된 작업 즉, 영어 표현을 매일 봇으로 배포 하기 위해 GitHub를 사용합니다. 

• GitHub 계정 로그인
  • github.com 접속
• 새 저장소 생성
  
  1) 좌측 상단  → Repositories 클릭 
  2) 우측 상단  → New repository 클릭

 

     3) Repository (저장소) 이름 정하기
         저는 Telegram_Language_Bot_Github_Actions라는 이름의 Repository를 설정했습니다. 

   

    4) Public 또는 Private 선택 (둘 다 무료)

    5) Create repository 클릭

 

 

    6) 아래와 같은 화면으로 넘어간다면 Repository가 잘 생성되었습니다. 

   7) Git이 없는 분들은  아래 링크에서 Git를 설치해주셔야 GitHub에 코드를 올려 실습을 진행할 수 있습니다. 

https://git-scm.com/install/windows

Git - Install for Windows

 

💻 Step 2: 코드 준비

직접 아래 단계를 따로오셔도 되고 시간이 부족하신 분들은 

아래에 실행하기 위한 코드를 압축파일로 업로드 해두었으니 참고 부탁드립니다. 

 

Telegram_Language_Bot_Github_Actions.zip

0.01MB

 

2-1. 로컬에 폴더 생성 후 GitHub와 연동

원하는 경로에서 우클릭하여 직접 폴더를 생성해도 되고 

CLI (Command Line Interface) 작업을 통해 폴더를 생성해도 됩니다. (CMD 창)

mkdir Telegram_Language_Bot_Github_Actions # mkdir는 폴더 생성명령어 (make directory)
cd Telegram_Language_Bot_Github_Actions    # cd는 경로 이동 명령어 (change directory)

 

아래 처럼 폴더가 생성된 것을 확인할 수 있습니다.  

 

그럼 이제 GitHub와 연동해보겠습니다.  
Step 1에서 Repository 생성 후 창에 아래와 같은 명령어들이 적혀져 있었습니다. 
아래 명령어들을 차례차례 CMD창에 입력해보겠습니다. (이때 CMD의 Path가 GitHub와 연동할 폴더의 위치인지 확인!!)

 

 

1) echo "# Telegram_Language_Bot_Github_Actions" >> README.md
    README 파일을 생성하고 내용으로 "# Telegram_Language_Bot_Github_Actions"를 삽입합니다. (생략 가능)

 

2) git init
    git 초기화 (폴더에 .git 파일이 생깁니다.) (숨김 파일로 생성되어 안보여도 정상입니다.)

 

3) git add . 
    현재 폴더에 있는 파일들을 GitHub에 올릴 변경사항을 추가 해주는 단계
    1)단계를 했으면 README.md 파일만 있으므로 git add README.md 명령어를 입력해도 됩니다. 

 

4) git commit -m "첫 커밋"
    변경사항을 저장 하는 단계 이고 -m 옵션을 써서 변경사항에 메시지를 붙여 관리가 용이하도록 할 수 있습니다. 

 

5) git branch -M main
    branch(프로젝트의 독립적인 작업 공간)의 이름을 main으로 설정하는 단계 입니다. 

6) git remote add origin [내 repository 주소]
    원격저장소(GitHub repository)와 로컬 저장소를 연결하는 단계입니다.
    주소는 GitHub repository에서 복사 가능합니다. 

 

 

7) git push -u origin main
    로컬 branch를 원격 branch에 업로드 하는 단계입니다. 

Git을 처음 써보신다면 이해하는 어려울 수 있지만 위의 단계들이
로컬의 폴더를 GitHub의 폴더(repository)와 연동시키는 단계였다고 이해해주시면 됩니다. 

2-2. 파일 구조

Telegram_Language_Bot_Github_Actions/
├── .github/
│   └── workflows/
│       └── telegram-bot.yml                  #GitHub Actions를 설정하기 위한 파일
├── send_expression.py
├── requirements-github.txt
└── README.md
└── Data
    └── expressions.json

 

2-3. 각 파일 생성

파일 1: .github/workflows/telegram-bot.yml

이 파일이 GitHub Actions를 설정합니다.

name: Send English Expression

on:
  schedule:
    - cron: "*/5 * * * *"  # 매 5분마다 실행
  workflow_dispatch: # 수동 실행 가능

jobs:
  send-expression:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Send expression to Telegram
        env:
          TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
        run: python send_expression.py

 

파일 2: requirements-github.txt

requests==2.32.3

 

파일 3: send_expression.py

import json
import os
import random
import requests

TELEGRAM_BOT_TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
TELEGRAM_CHAT_ID = os.environ["TELEGRAM_CHAT_ID"]

DATA_PATH = os.path.join(os.path.dirname(__file__), "data", "expressions.json")


def load_expressions():
    with open(DATA_PATH, "r", encoding="utf-8") as f:
        return json.load(f)


def format_message(expr):
    return (
        f"📚 *오늘의 영어 표현*\n"
        f"\n"
        f"💬 *{expr['expression']}*\n"
        f"📖 뜻: {expr['meaning']}\n"
        f"✏️ 예문: _{expr['example']}_"
    )


def send_telegram_message(text):
    url = f"https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage"
    payload = {
        "chat_id": TELEGRAM_CHAT_ID,
        "text": text,
        "parse_mode": "Markdown",
    }
    response = requests.post(url, json=payload)
    response.raise_for_status()
    return response.json()


def main():
    expressions = load_expressions()
    expr = random.choice(expressions)
    message = format_message(expr)
    result = send_telegram_message(message)
    print(f"Sent expression #{expr['id']}: {expr['expression']}")
    print(f"Telegram response OK: {result['ok']}")


if __name__ == "__main__":
    main()

파일 4: experssions.json
           이 파일에서 표현을 직접 추가 및 수정 가능합니다. 글이 너무 길어지니 10개만 작성해 보겠습니다.
           업로드 파일에는 100개 작성해두었습니다~ 

[
  {
    "id": 1,
    "expression": "Break the ice",
    "meaning": "어색한 분위기를 깨다",
    "example": "He told a joke to break the ice at the meeting."
  },
  {
    "id": 2,
    "expression": "Hit the nail on the head",
    "meaning": "정확히 맞추다, 핵심을 찌르다",
    "example": "You hit the nail on the head with that analysis."
  },
  {
    "id": 3,
    "expression": "Piece of cake",
    "meaning": "아주 쉬운 일",
    "example": "The exam was a piece of cake."
  },
  {
    "id": 4,
    "expression": "Cost an arm and a leg",
    "meaning": "매우 비싸다",
    "example": "That new car cost an arm and a leg."
  },
  {
    "id": 5,
    "expression": "Under the weather",
    "meaning": "몸이 안 좋다",
    "example": "I'm feeling a bit under the weather today."
  },
  {
    "id": 6,
    "expression": "Beat around the bush",
    "meaning": "돌려 말하다",
    "example": "Stop beating around the bush and tell me the truth."
  },
  {
    "id": 7,
    "expression": "Burn the midnight oil",
    "meaning": "밤늦게까지 일하다/공부하다",
    "example": "She burned the midnight oil to finish the project."
  },
  {
    "id": 8,
    "expression": "Once in a blue moon",
    "meaning": "아주 드물게",
    "example": "He only visits once in a blue moon."
  },
  {
    "id": 9,
    "expression": "Spill the beans",
    "meaning": "비밀을 누설하다",
    "example": "Don't spill the beans about the surprise party."
  },
  {
    "id": 10,
    "expression": "A blessing in disguise",
    "meaning": "전화위복, 인생만사 새옹지마",
    "example": "Losing that job was a blessing in disguise."
  }
]

🔐 Step 3: GitHub Secrets 설정

send_expression.py에 bot token과 chat id를 넣기 않았는데요. 
GitHub에 올릴 코드인데 bot token과 chat id가 적혀있으면 누구라도 나의 bot에 접근할 수 있어 위험하겠죠.
따라서 보안을 위해 토큰을 직접 코드에 넣지 않고 GitHub Secrets를 사용합니다.

    1. GitHub 저장소 페이지로 이동

    2. Settings 탭 클릭

   3. 좌측 메뉴에서 "Secrets and variables" → "Actions" 클릭

 

    4. "New repository secret" 버튼 클릭

 

         첫 번째 Secret 추가

         Name: TELEGRAM_BOT_TOKEN

         Value: BotFather에서 받은 토큰 (예: 1234567890:ABCdef...)

         Add secret 클릭

        두 번째 Secret 추가

        Name: TELEGRAM_CHAT_ID

        Value: 쉼표로 구분된 Chat ID (예: 123456789,987654321)

        Add secret 클릭

        TELEGRAM_BOT_TOKEN과 TELEGRAM_CHAT_ID 없는 분들은 아래 발행 글을 참조해주세요.
       2026.02.06 - [Claude Code Project] - 🚀 텔레그램 영어 학습 봇 만들기 & 무료 배포 완벽 가이드 (1) 텔레그램 봇 생성

 

📤 Step 4: 코드 푸시

        이제 로컬 저장소에 있는 파일들을 원격 저장소(GitHub)와 동기화 시켜야 합니다. 
        2-1단계에서 이미 로컬 저장소와 원격 저장소를 연결 시켰기에 아래 명령어 만으로 동기화가 가능합니다. 

git add .
git commit -m "폴더 동기화"
git push

       1) git add . 
           변경사항을 추가 (원격 저장소에 올리기 위한 준비)
           아래 warning은 무시해도 되는 경고입니다.  

       2) git commit -m "폴더 동기화"
           변경사항을 저장합니다. 

       3) git push
           원격 저장소와 로컬 저장소를 동기화 합니다. 

        4) Repository에 로컬 저장소의 폴더 및 파일들이 동기화 됐다면 성공!!!

✅ Step 5: 워크플로우 활성화 및 테스트

        1) Actions 탭으로 이동

           GitHub 저장소에서 "Actions" 탭 클릭

 

        2) 워크플로우 확인

            "Send English Expression" 워크플로우 확인

       

         3) 수동 실행으로 테스트

            - 워크플로우 이름 클릭

            - 우측 "Run workflow" 버튼 클릭

            - 녹색 "Run workflow" 버튼 클릭

 

         4) Actions tab에서 실행 결과 확인

             아래와 같은 메시지가 나오면 test 성공!!!

         5) 텔레그램 실행 결과 확인

              봇으로부터 영어 표현 메시지 수신 확인

 

 

맨 위에 단점에 GitHub Actions는 스케줄링에 Delay가 있다고 했는데 실제로 지금 5분마다 메시지가 날아오도록 설정했지만
날아오는 주기를 보면 30분 1시간이 넘어갈 때도 있어서 아쉬운 부분이 있었습니다. 

Render를 이용한다면 스케줄링이 완벽하게 되는 것을 확인했으니까 
다음 실습에서는 Render를 이용해 보자구요. 감사합니다~