Mengelola persetujuan permintaan pull dengan CODEOWNERS

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Panduan ini menjelaskan struktur, sintaksis, dan penerapan fitur CODEOWNERS, yang memungkinkan Anda mengontrol persyaratan persetujuan Permintaan Tarik (PR) secara fleksibel.

Pengantar

Fitur CODEOWNERS Secure Source Manager menggunakan file dalam codebase Anda untuk menetapkan pemberi persetujuan tingkat file. Hal ini menawarkan kontrol yang lebih terperinci daripada aturan cabang lainnya karena Anda dapat menetapkan pemilik tertentu ke file tertentu dan menentukan serangkaian pemberi persetujuan yang independen.

Fitur CODEOWNERS menawarkan kemampuan berikut:

• Tentukan pengguna yang dapat menyetujui permintaan pull untuk file, direktori, dan cabang.
• Konfigurasi berbagai set pemilik kode untuk melindungi berbagai cabang.
• Pastikan perubahan pada file ditinjau oleh pemilik yang ditetapkan.

Mengaktifkan Peninjauan Pemilik Kode

Untuk mengaktifkan dan menerapkan aturan CODEOWNERS, administrator perlindungan cabang harus memperbarui Aturan cabang di setelan repositori Anda menjadi Wajibkan Peninjauan Pemilik Kode pada Permintaan Tarik. Pilih opsi ini di setelan aturan cabang. Jika setelan ini nonaktif, sistem akan mengabaikan file CODEOWNERS untuk penggabungan ke cabang target. Jika Anda memilih opsi ini, sistem akan memblokir push dan penggabungan ke cabang hingga pemilik kode meninjau dan menyetujui permintaan pull.

Catatan: Setelan lain, seperti Jumlah Peninjau yang Diperlukan (N Reviewers Required) atau Jumlah Pemberi Persetujuan yang Diperlukan (N Approvers Required), adalah persyaratan tambahan yang independen. Jika Anda adalah pemilik kode dan memiliki izin repositories.approvePullRequests, Anda dapat memenuhi kedua persyaratan dengan satu peninjauan.

Lokasi dan Prioritas File CODEOWNERS

Secure Source Manager mendukung dua opsi untuk menentukan file CODEOWNERS:

1. File bertingkat: File CODEOWNERS di direktori mana pun kecuali direktori .securesourcemanager. File CODEOWNERS bertingkat hanya memengaruhi direktorinya sendiri (termasuk subdirektori), dan jalur file di dalamnya harus ditentukan relatif terhadap direktori tempat file CODEOWNERS berada. Ini adalah pendekatan yang direkomendasikan untuk sebagian besar kasus penggunaan.

2. File khusus tunggal: Jika Anda perlu membedakan file CODEOWNERS Secure Source Manager dari file CODEOWNERS lainnya yang digunakan oleh alat lain (misalnya, .gitlab/CODEOWNERS), Anda dapat menggunakan satu file yang terletak di .securesourcemanager/CODEOWNERS di root repositori Anda. Jika file ini ada, Secure Source Manager akan mengabaikan semua file CODEOWNERS lainnya di cabang yang sama, termasuk yang bertingkat. Direktori .securesourcemanager hanya dikenali di root repositori.

Interaksi dengan Permintaan Pull dan Persetujuan

Saat pull request dibuat, atau saat cabang sumbernya diperbarui dengan commit baru, sistem hanya menggunakan file CODEOWNERS dari cabang dasar (cabang yang akan Anda gabungkan) untuk menentukan persyaratan persetujuan. Sistem mengabaikan perubahan pada file CODEOWNERS dalam kode pendorongan untuk verifikasi tersebut.

Sintaksis dan struktur CODEOWNERS

File CODEOWNERS terdiri dari komentar, baris aturan, dan penanda bagian. Komentar dimulai dengan # dan diabaikan oleh sistem.

Format garis aturan

Format standar untuk garis aturan adalah:

[BRANCH_GLOB] PATH_GLOB [OWNERS...]

Dengan:

• BRANCH_GLOB: Pola glob opsional yang menentukan cabang tempat aturan diterapkan. Jika Anda tidak menentukan glob cabang, aturan akan berlaku untuk cabang mana pun tempat file CODEOWNERS di-check in (jika cabang tersebut mengaktifkan CODEOWNERS dalam aturan cabangnya). Contoh:

  • main hanya cocok dengan cabang main.
  • dev-* cocok dengan cabang yang diawali dengan dev-.
  • *-glob cocok dengan cabang yang diakhiri dengan -glob.
  • my-*-glob cocok dengan cabang seperti my-feat-glob.
  Tips: Meskipun file CODEOWNERS hanya melindungi cabangnya sendiri, mempertahankan konten CODEOWNERS yang berbeda di seluruh cabang dapat menyebabkan konflik penggabungan. Dengan menggunakan kolom cabang, Anda dapat menggunakan konten CODEOWNERS yang sama di setiap cabang, sekaligus menetapkan pemilik kode khusus cabang.

• PATH_GLOB: Pola glob wajib yang menentukan jalur file yang akan diterapkan aturannya. Sintaksis Secure Source Manager didasarkan pada pola gitignore.

  • Jika pola tidak berisi /, atau hanya berisi / sebagai karakter di akhir, pola tersebut adalah glob yang cocok di direktori mana pun.
    • *.js cocok dengan file JavaScript di mana pun.
    • build/ cocok dengan direktori bernama build di mana saja.
  • Jika pola berisi / di mana saja selain di akhir, pola tersebut akan diperlakukan sebagai jalur relatif ke lokasi file CODEOWNERS.
    • docs/* mencocokkan file di docs/ relatif terhadap file CODEOWNERS.
    • /*.js cocok dengan file JavaScript di direktori yang sama dengan file CODEOWNERS, tetapi tidak cocok dengan file JavaScript bertingkat.
  • Pola yang berakhiran / hanya mencocokkan direktori dan kontennya secara rekursif. Misalnya, build-*/ cocok dengan direktori seperti build-app/ dan build-tool/ di mana saja.
  • Jika menggunakan .securesourcemanager/CODEOWNERS, jalur bersifat relatif terhadap root repositori.

• OWNERS: Daftar alamat email pemilik opsional, yang dipisahkan oleh spasi. Jika dihilangkan, aturan ini akan bertindak sebagai pengecualian jalur.

  Catatan: Anda harus menentukan alamat email pengguna individual dalam file CODEOWNERS. Google Grup tidak didukung untuk menentukan pemilik.

Kepemilikan khusus cabang

Kolom BRANCH_GLOB opsional di awal baris aturan memungkinkan Anda menerapkan kontrol pemilik kode khusus cabang.

• Jika Anda tidak menentukan BRANCH_GLOB di awal aturan, aturan tersebut akan berlaku untuk semua cabang.
• Sistem mengabaikan baris apa pun dengan glob cabang yang tidak cocok dengan cabang saat ini.

Dasar-dasar sintaksis

• Interpretasi kolom: Kolom dipisahkan dengan spasi.
  • Kolom yang berisi @ diidentifikasi sebagai alamat email pemilik.
  • Jika ada satu kolom tanpa @ sebelum alamat email pemilik, kolom tersebut akan diperlakukan sebagai PATH_GLOB. Misalnya, di *.js [e-mail], *.js adalah PATH_GLOB.
  • Jika dua kolom tanpa @ mendahului alamat email pemilik, kolom pertama adalah BRANCH_GLOB dan kolom kedua adalah PATH_GLOB. Misalnya, dalam main *.js [e-mail], main adalah BRANCH_GLOB dan *.js adalah PATH_GLOB.
  • Logika yang sama berlaku jika tidak ada pemilik yang ditentukan: satu kolom adalah PATH_GLOB, dan dua kolom adalah BRANCH_GLOB PATH_GLOB.
• Sintaksis gaya glob: Secure Source Manager menggunakan sintaksis gaya glob standar (gaya .gitignore) untuk ekspresi jalur.
• Detail karakter pengganti:
  • ** cocok dengan urutan karakter apa pun, termasuk /.
  • * cocok dengan urutan karakter apa pun, kecuali /.
  • ? cocok dengan satu karakter apa pun, kecuali /.
• Kepekaan huruf besar/kecil: File CODEOWNERS peka huruf besar/kecil.
• Identifikasi pemilik: Sistem mengidentifikasi pemilik berdasarkan alamat email. Karakter @ membedakan kolom pemilik.
• Di alamat email pemilik, hanya space dan backslash yang perlu di-escape.
• Karakter yang dicadangkan: Sistem mencadangkan karakter berikut. Anda harus melakukan escape dengan garis miring terbalik (\) dalam ekspresi cabang dan jalur: [, ], , @, *, ?, \, {, }, dan !.
• Jika ** dicampur dengan karakter non-garis miring, sistem akan memperlakukannya sebagai karakter pengganti biasa. Misalnya, /**/*.py cocok dengan file Python kedalaman apa pun, /**.py diperlakukan seperti /*.py dan hanya cocok dengan file di direktori root.

Bagian untuk beberapa set persetujuan

Menggunakan [Section] baris mengelompokkan aturan ke dalam persetujuan wajib yang independen. Setelan ini berguna untuk mewajibkan peninjauan dari tim yang berbeda, misalnya, Tim Keamanan atau QA.

• Definisi bagian: Gunakan baris dalam format [Section Name] (gunakan nama bahasa alami apa pun).
• Jumlah persetujuan: Bagian dapat menyertakan sufiks opsional [<approverCount>] untuk menentukan jumlah persetujuan selain 1. Jumlah 0 menandakan pemilik opsional. Misalnya, Anda dapat menggunakannya untuk menampilkan pakar pada file tertentu untuk tujuan informasi tanpa memerlukan peninjauan mereka.
• Penghentian bagian: Bagian berlaku untuk semua aturan yang mengikutinya hingga bagian berikutnya dimulai.
• Aturan yang tidak dikelompokkan: Sistem memperlakukan aturan yang muncul sebelum definisi [Section] sebagai satu bagian terpadu, yang memerlukan satu persetujuan secara default.
• Penggabungan: Sistem memperlakukan bagian dengan nama yang sama yang tidak peka huruf besar/kecil, bahkan di beberapa file CODEOWNERS bertingkat, sebagai satu bagian terpadu, mengikuti aturan prioritas standar.

Pengecualian jalur

Untuk mengecualikan jalur tertentu dari klausul yang lebih luas sebelumnya, tetapkan nol pemilik untuk jalur tersebut. Jika Anda menentukan aturan tanpa pemilik, sistem akan menghapus pemilik untuk jalur tersebut yang ditetapkan oleh aturan sebelumnya, dan jalur tidak memerlukan persetujuan pemilik.

Pencocokan direktori hanya berfungsi jika diakhiri dengan / atau tidak berisi karakter pengganti di bagian akhir.

Misalnya, *.py tidak akan cocok dengan direktori tersembunyi .py/; *.py/ akan cocok.

Resolusi dan prioritas konflik

Jika file .securesourcemanager/CODEOWNERS ada, semua file CODEOWNERS lainnya akan diabaikan. Jika jalur dicocokkan oleh dua baris yang berbeda di bagian yang sama, hanya baris terakhir yang akan diterapkan. Jika garis berada di bagian yang berbeda, keduanya akan diterapkan.

Sistem menggunakan aturan prioritas berbasis lokasi untuk file bertingkat:

• Aturan dalam file CODEOWNERS yang memiliki tingkat ke dalaman lebih tinggi (lebih lokal) akan menggantikan aturan yang cocok dalam file yang memiliki tingkat ke dalaman lebih rendah.
• File direktori root CODEOWNERS selalu memiliki prioritas terendah.

Contoh file CODEOWNERS

Berikut adalah contoh file CODEOWNERS, yang menunjukkan sintaksis CODEOWNERS:

# Un-sectioned rules; 1 approve required from any of owners of last matching line.
# Format: [BRANCH_GLOB] PATH_GLOB [OWNERS...]

# Make repo-admin the owner of all files of the current branch.
*   [e-mail]      # No slash prefix; matches in sub-dirs too.
/**/* [e-mail]      # Slash-prefix equivalent of prior line.

# Match all py files (including sub-dirs). Note repo-admin must be re-added.
*.py  [e-mail] [e-mail]

# With repo-admin not included here, repo-admin no longer owns README.
/README.md [e-mail]

/scratchpad.txt             # Can also override a path to have zero owners (path exclusion).

# Branch-specific syntax.
# Note that since un-sectioned rules are independent of sectioned rules,
# the above [Section] rules will still apply to this branch if they
# aren't modified to add e.g. `main ` as a prefix.
dev-* *             # Remove all owners reqs on dev branches.
dev-* /experimental/ [e-mail]   # dev-specific owners.

# Make repo admin own all CODEOWNERS files, regardless of any prior rules.
CODEOWNERS [e-mail]

# Section; 1 approval required *in addition* to owners outside this section.
[Security Team]
/secure-directory/ [e-mail] [e-mail]
/**/*secure\ me* [e-mail] [e-mail]

# Section w/ req approval count of 2 instead of 1.
[Doc Team][2]
/docs [e-mail] [e-mail]
*.md [e-mail] [e-mail]

Kompatibilitas dengan pengelola kode sumber lainnya

Secure Source Manager menyediakan sintaksis yang sudah dikenal dan portabel dengan Source Code Manager lainnya. Sintaksis CODEOWNERS Secure Source Manager kompatibel dengan sintaksis CODEOWNERS GitHub, dan sebagian kompatibel dengan sintaksis CODEOWNERS GitLab, termasuk jumlah persetujuan per bagian seperti [Section Name][2].

Penerapan Secure Source Manager untuk CODEOWNERS tidak mendukung sintaksis !path GitLab untuk negasi jalur. Untuk mengetahui informasi tentang negasi jalur di Secure Source Manager, lihat Pengecualian Jalur. Secure Source Manager juga tidak mendukung pemilik default di header bagian—misalnya, [Section Name] @owner1 @owner2.

Validasi dan Penanganan Error

Saat melihat file CODEOWNERS, UI akan menampilkan statusnya, serta peringatan atau informasi tingkat baris (misalnya, baris yang tidak cocok dengan cabang ini). Nomor baris atau baris yang disorot dapat diakses dengan mengarahkan kursor ke atasnya untuk melihat detail tambahan.

Penegakan

Pemeriksaan pra-commit menerapkan pemeriksaan error sintaksis di cabang tempat Anda mengaktifkan aturan cabang pemilik kode. Tindakan ini mencegah Anda melakukan check in file CODEOWNERS yang rusak secara tidak sengaja.

Penanganan Error Sintaksis

Pemeriksaan pra-pengiriman hanya berjalan di cabang tempat Wajibkan Peninjauan Pemilik Kode pada Permintaan Penarikan diaktifkan. Jika file CODEOWNERS yang tidak valid secara sintaksis di-commit ke cabang, dan peninjauan pemilik kode diaktifkan untuk cabang tersebut di kemudian hari, sistem akan menangani error dengan baik:

• Sistem mengabaikan baris yang tidak dapat diuraikan menjadi definisi bagian, baris aturan, atau format komentar.
• Jika jumlah persetujuan negatif, sistem akan memperlakukannya sebagai 0.
• Sistem akan terus mengurai dan menerapkan baris yang valid seperti biasa.

Langkah berikutnya

• Ringkasan perlindungan cabang
• Mengonfigurasi perlindungan cabang
• Menangani masalah dan permintaan pull
• Menghubungkan ke Cloud Build