demo-gitlab-mirror/docs/index.html

<!doctype html>
<html lang="vi">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Mirror GitLab sang GitHub</title>
  <meta name="description" content="Hướng dẫn thiết lập push mirror từ GitLab sang GitHub, kèm repository demo.">
  <style>
    :root {
      --bg: #fbfbfa; --fg: #1f2328; --muted: #59636e; --line: #d8dee4;
      --accent: #c2410c; --code-bg: #f0f1f2; --note-bg: #fff7ed;
    }
    @media (prefers-color-scheme: dark) {
      :root {
        --bg: #16181b; --fg: #e6e8eb; --muted: #9aa4af; --line: #30363d;
        --accent: #fb923c; --code-bg: #22262b; --note-bg: #2a2118;
      }
    }
    * { box-sizing: border-box; }
    body {
      margin: 0; background: var(--bg); color: var(--fg);
      font: 17px/1.65 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
    }
    main { max-width: 760px; margin: 0 auto; padding: 48px 16px 72px; }
    h1 { font-size: 2rem; line-height: 1.25; margin: 0 0 8px; }
    h2 { font-size: 1.3rem; margin: 2.4em 0 .6em; padding-top: 1em; border-top: 1px solid var(--line); }
    h3 { font-size: 1.05rem; margin: 1.6em 0 .4em; }
    .lead { color: var(--muted); margin: 0 0 24px; }
    a { color: var(--accent); }
    code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: .9em; }
    code { background: var(--code-bg); padding: .1em .35em; border-radius: 4px; overflow-wrap: anywhere; }
    pre { background: var(--code-bg); padding: 12px 14px; border-radius: 6px; overflow-x: auto; }
    pre code { padding: 0; background: none; }
    img { display: block; max-width: 100%; height: auto; margin: 16px 0; border: 1px solid var(--line); border-radius: 6px; }
    li { margin: .25em 0; }
    .links { display: flex; flex-wrap: wrap; gap: 8px 20px; padding: 12px 16px; border: 1px solid var(--line); border-radius: 6px; }
    .note { background: var(--note-bg); border-left: 3px solid var(--accent); padding: 12px 16px; border-radius: 0 6px 6px 0; }
    footer { margin-top: 56px; color: var(--muted); font-size: .9rem; }
  </style>
</head>
<body>
<main>
  <h1>Mirror repository từ GitLab sang GitHub</h1>
  <p class="lead">Code được cập nhật trên GitLab, GitHub tự động nhận bản mới nhất. Chính repository này là bản demo: source nằm trên GitLab và được push mirror sang GitHub.</p>

  <div class="links">
    <a href="https://gitlab.com/tiennm99/demo-gitlab-mirror">Source trên GitLab</a>
    <a href="https://github.com/tiennm99/demo-gitlab-mirror">Mirror trên GitHub</a>
    <a href="https://miti99.com/post/2025/03/26/">Bài viết gốc</a>
  </div>

  <p>Khi tạo repository mới trên GitHub, GitHub cho phép <a href="https://github.com/new/import">import repository</a> từ nguồn git khác.</p>
  <img src="img/1.png" alt="Màn hình import repository của GitHub" loading="lazy">
  <p>Tuy nhiên import chỉ chạy một lần. Nếu vẫn muốn làm việc trên GitLab mà GitHub luôn có code mới nhất, hãy dùng push mirror của GitLab theo các bước dưới đây.</p>

  <h2>1. Tạo GitHub Personal Access Token</h2>
  <ul>
    <li>Vào <code>GitHub Settings</code> &gt; <code>Developer settings</code> &gt; <code>Personal access tokens</code> &gt; <code>Fine-grained tokens</code>: <a href="https://github.com/settings/personal-access-tokens">github.com/settings/personal-access-tokens</a></li>
    <li>Bấm <code>Generate new token</code>.</li>
    <li>Đặt tên cho token và chọn quyền:
      <ul>
        <li><code>Expiration</code>: nên đặt thời hạn nhất định.</li>
        <li><code>Repository access</code>: tốt nhất chọn <code>Only select repositories</code>, chỉ cấp quyền cho repository thực sự cần. Nếu setup cho nhiều repository cùng owner và không muốn sửa lại về sau, có thể chọn <code>All repositories</code>.</li>
        <li><code>Permissions</code>: mục <code>Contents</code> chọn <code>Access: Read and write</code>. Nếu repository có file trong <code>.github/workflows/</code>, thêm <code>Workflows: Read and write</code>, nếu không GitHub sẽ từ chối push các file đó.</li>
      </ul>
    </li>
    <li>Copy token vừa tạo. Token chỉ hiển thị một lần.</li>
  </ul>
  <img src="img/2.png" alt="Tạo fine-grained token trên GitHub" loading="lazy">
  <img src="img/3.png" alt="Chọn quyền Contents read and write" loading="lazy">

  <h3>1.1. Nếu repository thuộc Organization</h3>
  <ul>
    <li>Vào <code>Settings</code> của organization, mục <code>Personal access tokens</code>, tab <code>Fine-grained tokens</code>. VD: <code>https://github.com/organizations/ORG/settings/personal-access-tokens</code></li>
    <li>Ở <code>Fine-grained personal access tokens</code> chọn <code>Allow access via fine-grained personal access tokens</code>.</li>
    <li>Ở <code>Require approval of fine-grained personal access tokens</code>:
      <ul>
        <li><code>Require administrator approval</code>: PAT tạo ra cần được admin duyệt.</li>
        <li><code>Do not require administrator approval</code>: không cần duyệt.</li>
      </ul>
    </li>
    <li>Bấm <code>Save</code> ở mỗi mục, sau đó quay lại tạo PAT ở bước 1.</li>
  </ul>
  <img src="img/5.png" alt="Cài đặt fine-grained token cho organization" loading="lazy">

  <h2>2. Thiết lập mirror trên GitLab</h2>
  <ul>
    <li>Vào project trên GitLab, chọn <code>Settings</code> &gt; <code>Repository</code>.</li>
    <li>Mở rộng phần <code>Mirroring repositories</code>. VD: <a href="https://gitlab.com/tiennm99/demo-gitlab-mirror/-/settings/repository#js-push-remote-settings">gitlab.com/tiennm99/demo-gitlab-mirror/-/settings/repository</a></li>
    <li>Bấm <code>Add new</code> (dấu <code>+</code>) và điền:
      <ul>
        <li><code>Git repository URL</code>: <code>https://github.com/GROUP/PROJECT.git</code>, thay <code>GROUP</code> và <code>PROJECT</code> bằng tên trên GitHub. VD: <code>https://github.com/tiennm99/demo-gitlab-mirror.git</code></li>
        <li><code>Username</code>: username của GitHub account.</li>
        <li><code>Password</code>: personal access token đã tạo ở bước 1.</li>
      </ul>
    </li>
    <li>Bấm <code>Mirror repository</code>.</li>
  </ul>
  <img src="img/4.png" alt="Form Mirroring repositories trên GitLab" loading="lazy">

  <h2>3. Kiểm tra trạng thái</h2>
  <p>Sau khi thiết lập, mirror được liệt kê với URL dạng:</p>
  <pre><code>https://*****:*****@github.com/&lt;your_github_group&gt;/&lt;your_github_project&gt;.git</code></pre>
  <p>Để kiểm tra mirror hoạt động:</p>
  <ul>
    <li>Push một commit mới lên GitLab.</li>
    <li>Đợi khoảng 5 phút (hoặc 1 phút nếu bật <code>Only mirror protected branches</code>).</li>
    <li>Kiểm tra trên GitHub xem commit đã được sync chưa.</li>
    <li>Muốn sync ngay thì bấm <code>Update now</code> (nút retry).</li>
  </ul>

  <h2>Lưu ý</h2>
  <div class="note">
    <ul>
      <li>Mirror tự động sync các commit mới từ GitLab sang GitHub. Đừng commit thẳng lên GitHub, nếu không branch sẽ bị diverge.</li>
      <li>Branch đã merge vào default branch và bị xoá ở GitLab sẽ bị xoá ở mirror trong lần push tiếp theo.</li>
      <li>Branch còn thay đổi chưa merge sẽ được giữ lại.</li>
      <li>Nếu branch bị diverge, phần <code>Mirroring repositories</code> sẽ hiển thị lỗi.</li>
      <li>Khi token hết hạn, mirror sẽ báo lỗi xác thực; tạo token mới rồi cập nhật lại password của mirror.</li>
    </ul>
  </div>

  <h2>Tham khảo</h2>
  <ol>
    <li><a href="https://meesvandongen.nl/posts/mirror-gitlab-github">meesvandongen.nl/posts/mirror-gitlab-github</a></li>
    <li><a href="https://docs.gitlab.com/user/project/repository/mirror/push/#set-up-a-push-mirror-from-gitlab-to-github">GitLab Docs: Set up a push mirror from GitLab to GitHub</a></li>
  </ol>

  <footer>Trang này được build từ thư mục <code>docs/</code> và publish đồng thời lên GitLab Pages và GitHub Pages.</footer>
</main>
</body>
</html>