tarumt-calendar-sync

ICS File Webpage

📅 Auto-Updating TARUMT Timetable Generator

License GitHub stars GitHub forks

Automatically sync your TARUMT class schedule to any calendar app with daily auto-updates!

English 简体中文

This tool generates your TARUMT timetable as a subscribable .ics file that automatically updates daily. Once set up, your calendar apps (iPhone, Google Calendar, Outlook, etc.) will always show your latest class schedule.

✨ Features:

🚀 Quick Start Guide

Step 1: Fork This Repository

  1. Click the Fork and Star (if you like this repo) button at the top right of this page

  2. This creates your own copy of the repository

    1762412372269

Step 2: Configure GitHub Secrets

Your TARUMT credentials need to be stored securely in GitHub:

  1. Go to your forked repository on GitHub
  2. Click Settings → Secrets and variables → Actions
  3. Click New repository secret

  4. Add the following two secrets:

    Secret Name Value
    TARUMT_USERNAME Your TARUMT student ID (e.g : 2500001)
    TARUMT_PASSWORD Your TARUMT portal password (e.g : password)

    How to add a secret:

    • Click “New repository secret”
    • Name: TARUMT_USERNAME
    • Secret: Your actual TARUMT username
    • Click “Add secret”
    • Repeat for TARUMT_PASSWORD

⚠️ Security Note: Your credentials are encrypted and never exposed. They’re only used by GitHub Actions to fetch your timetable.

17624124392191762412524803

Step 3: Enable GitHub Pages

This makes your timetable file publicly accessible for calendar subscriptions:

  1. In your repository, go to Settings → Pages
  2. Under Source, select:
    • Deploy from a branch
    • Branch: main
    • Folder: / (root)
  3. Click Save
  4. Wait ~1 minute for deployment

1762412670899

Step 4: Get Your Subscription URL

After GitHub Pages is enabled, your calendar subscription URL will be:

https://YOUR_GITHUB_USERNAME.github.io/tarumt-calendar-sync/timetable.ics

Example: If your GitHub username is johnsmith, the URL would be:

https://johnsmith.github.io/tarumt-calendar-sync/timetable.ics

Step 5: Test the Workflow

Before subscribing, let’s make sure everything works:

  1. Go to the Actions tab in your repository
  2. Click on Update Timetable Daily workflow
  3. Click Run workflow → Run workflow
  4. Wait for it to complete (green checkmark ✅)

  5. Check that timetable.ics file appears in your repository

    1762412750395

📱 Subscribe to Your Timetable

Once the workflow runs successfully, subscribe in your calendar app:

Apple Calendar (iPhone/Mac)

iPhone/iPad:

  1. Open Settings → Calendar → Accounts
  2. Tap Add Account → Other → Add Subscribed Calendar
  3. Paste your subscription URL
  4. Tap Next → Save

Mac:

  1. Open Calendar app
  2. File → New Calendar Subscription
  3. Paste your subscription URL
  4. Click Subscribe
  5. Set auto-refresh to Every hour

Google Calendar

  1. Open Google Calendar
  2. On the left sidebar, click the + next to “Other calendars”
  3. Select From URL
  4. Paste your subscription URL
  5. Click Add calendar

Note: Google Calendar may take up to 24 hours to sync

Microsoft Outlook

Outlook Desktop:

  1. File → Account Settings → Account Settings
  2. Internet Calendars tab → New
  3. Paste your subscription URL → Add
  4. Give it a name and click OK

Outlook.com:

  1. Click Add calendar → Subscribe from web
  2. Paste your subscription URL
  3. Name your calendar and click Import

⚙️ How It Works

Automatic Updates

The GitHub Action workflow runs automatically:

Your calendar apps will automatically refresh and show the latest schedule including exams!

Manual Updates

You can also trigger an update manually:

  1. Go to Actions tab
  2. Select Update Timetable Daily
  3. Click Run workflow → Run workflow

🛠️ Local Development (Optional)

If you want to test or generate the timetable locally:

Setup

  1. Clone your forked repository:

    git clone https://github.com/YOUR_USERNAME/tarumt-calendar-sync.git
cd tarumt-calendar-sync

  2. Install dependencies:

    npm install

  3. Create a .env file in the project root:

    TARUMT_USERNAME=your_student_id
TARUMT_PASSWORD=your_password

Commands

# Generate combined timetable (classes + exams)
npm run generate

# Legacy: Generate exam timetable only
npm run generate-exam

The generated .ics files will open automatically on macOS.

Note: The main timetable.ics file now includes BOTH classes and exams, so you typically only need to subscribe to one calendar!

📂 Generated Files

File Description
timetable.ics Main file - Combined class schedule AND exam timetable (subscribe to this!)
exam_timetable.ics Legacy exam-only file (generated separately if you runnpm run generate-exam)

🔧 Troubleshooting

Workflow fails in GitHub Actions

Check credentials:

No timetable data:

Calendar not updating

Apple Calendar:

Google Calendar:

Outlook:

Can’t access subscription URL

Check GitHub Pages:

Repository must be public:

💡 Tips & Best Practices

  1. Keep your repository public - Required for free GitHub Pages
  2. Don’t share your credentials - They’re encrypted in GitHub Secrets
  3. Check Actions tab periodically - Ensure daily updates are working
  4. Refresh calendar apps manually - If you need immediate updates after a manual workflow run
  5. Fork, don’t clone - Forking makes it easier to get updates from the original repository

🤝 Sharing with Classmates

Your classmates can fork this repository and follow the same steps to create their own auto-updating timetable!

Or, if you want to share your timetable with others:

https://YOUR_USERNAME.github.io/tarumt-calendar-sync/timetable.ics

They can subscribe to this URL to see your schedule (useful for group projects or study sessions).

🔒 Privacy & Security

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

What this means:

🆘 Need Help?

Made with ❤️ for TARUMT students

This site is open source. Improve this page.