깃허브 이슈·README에 GIF 넣는 법 (10MB 제한과 맞추는 요령)

2026년 11월 11일 4m

제가 GIF를 붙이는 곳의 절반은 깃허브예요. 버그를 올릴 때, PR에서 “이렇게 바뀌었어요”를 보여 줄 때, README 맨 위에 데모를 걸 때요. 그런데 처음엔 GIF를 끌어다 놨는데 아무 반응이 없거나, 올라갔는데 README에서 엄청 느리게 뜨는 일이 몇 번 있었습니다. 그때 알게 된 것들을 정리해 둘게요.

이슈·PR·댓글에 붙이기

이슈나 PR의 글쓰기 칸에 GIF 파일을 끌어다 놓거나 붙여 넣으면 됩니다. 업로드가 끝나면 칸 안에 이런 줄이 자동으로 들어가요.

![화면 기록](https://github.com/user-attachments/assets/...)

미리 보기 탭을 누르면 GIF가 바로 움직이는 걸 확인할 수 있어요. 따로 설정할 건 없습니다.

크기 제한: 이미지·GIF는 10MB

깃허브 문서 기준으로 첨부 파일 크기 제한은 이렇습니다.

종류	제한
이미지·GIF	10MB
동영상	10MB (유료 플랜이거나 조직 저장소면 100MB)
그 밖의 파일	25MB

GIF가 10MB를 넘으면 올라가지 않아요. 생각보다 금방 넘습니다. 제가 비교용으로 만든 4.5초짜리 GIF(가로 900픽셀, 45장)가 14MB였거든요. 화면 녹화는 일반 영상보다는 작게 나오지만, 전체 화면을 10초 넘게 찍으면 10MB는 쉽게 넘깁니다.

10MB를 넘었을 때 줄이는 순서

GIF 용량 줄이는 법에서 같은 영상으로 설정을 바꿔 가며 14번 만들어 봤는데, 그 결과로 정한 순서는 이래요.

길이 줄이기. 장수에 그대로 비례해서 줄고 화질 손해가 없어요. 앞뒤로 마우스를 찾는 시간을 GIF 자르기로 잘라 내세요. 버그 재현은 보통 3~5초면 충분합니다.
가로 크기 줄이기. 가장 효과가 커요. 가로를 900에서 720으로만 줄여도 35%, 540이면 63%가 줄었어요. 이슈 본문은 폭이 넓지 않아서 900픽셀을 꽉 채워 보일 일도 드뭅니다.
품질을 80~70으로. 100에서 70으로 내리면 32%가 줄었는데, 2배로 키워 봐야 차이가 보이는 정도였어요.
초당 장수 줄이기. 클릭하고 메뉴가 열리는 정도라면 초당 10장이면 충분해요. 더 줄이면 움직임이 끊겨 보이니 마지막에 씁니다.

변환기에서는 영상을 넣으면 길이와 해상도에 맞춰 설정이 자동으로 정해지고, 결과 아래에 용량이 나와요. 10MB를 넘으면 화질 눈금을 한 칸 낮추거나, ‘직접 설정’에서 크기를 줄여서 다시 만들면 됩니다.

README에 데모 GIF 넣기

README는 방법이 두 가지예요.

방법 1: 저장소에 GIF 파일을 넣기

docs/demo.gif처럼 저장소 안에 파일을 커밋하고, 상대 경로로 부르는 방법입니다.

![데모](docs/demo.gif)

파일이 저장소와 같이 움직여서 링크가 깨질 걱정이 없어요. 대신 GIF를 바꿀 때마다 저장소 기록에 큰 파일이 계속 쌓입니다. 저는 자주 바뀌지 않는 대표 데모 하나만 이렇게 넣어요.

방법 2: 이슈에 올린 주소를 쓰기

아무 이슈나 PR 글쓰기 칸에 GIF를 끌어다 놓고, 생긴 user-attachments 주소만 복사해서 README에 붙이는 방법이에요. 글은 저장하지 않아도 업로드는 끝나 있어서 주소를 쓸 수 있습니다. 저장소가 무거워지지 않는 게 장점이에요.

다만 비공개 저장소에서 올린 첨부 파일은 권한이 있는 사람만 볼 수 있어요. 공개 README에 쓸 거라면 공개 저장소에서 올리는 게 안전합니다.

크기를 조절하고 싶을 때

마크다운 ![]()로는 크기를 정할 수 없어서, 표시 크기를 바꾸고 싶으면 HTML 태그를 씁니다.

<img src="docs/demo.gif" alt="데모" width="600">

이건 보이는 크기만 바꿔요. 파일 용량은 그대로라서, README가 느리게 뜨면 GIF 자체를 작게 다시 만들어야 합니다. README는 저장소에 들어온 사람이 가장 먼저 보는 화면이라, 저는 데모 GIF를 3~5MB 안으로 맞추려고 해요.

GIF 대신 동영상을 올려도 될 때

깃허브는 이슈와 PR에 MP4 같은 동영상도 바로 올릴 수 있고, 페이지 안에서 재생도 됩니다. 길이가 길거나 소리가 필요하면 동영상이 낫고, 짧은 동작을 자동으로 반복해서 보여 주고 싶으면 GIF가 나아요. 동영상은 눌러야 재생되지만 GIF는 열자마자 움직이거든요. 둘 중에 고르는 기준은 GIF로 만들까, 동영상으로 둘까?에 더 자세히 적어 두었습니다.

정리

이슈·PR에는 끌어다 놓기만 하면 됨, 이미지·GIF는 10MB까지
넘으면 길이 → 가로 크기 → 초당 장수 순서로 줄이기
README는 저장소에 파일 넣기 또는 이슈에 올린 주소 쓰기
width는 보이는 크기만 바꾸니, 느리면 GIF를 다시 작게 만들기

화면을 GIF로 찍는 방법부터 필요하시면 화면 녹화를 GIF로 만드는 법을 먼저 보세요.