Publicer en brugerdefineret GitHub-handling

  • 6 minutter

Her får du mere at vide om, hvordan du vælger den rette synlighed for din handling, bedste praksis for at dokumentere og versionere din handling, og hvordan du publicerer din handling på GitHub Marketplace.

Vælg en placering til din handling

diagram, der viser de to synlighedsindstillinger for en handling: offentlig eller privat.

Når du opretter en handling, er det vigtigt først at beslutte, hvor handlingen skal placeres, og synligheden af den pågældende handling, uanset om det er public eller private. Handlingens synlighed bestemmer, hvilke anbefalinger og krav der er nødvendige for at frigive den pågældende handling. Lad os se nærmere på disse to synlighedsindstillinger.

Offentlig

Arbejdsprocesser i et hvilket som helst lager kan bruge offentlige handlinger. Hvis du udvikler en handling med det formål at gøre den åben kildekode eller gøre den offentligt tilgængelig via GitHub Marketplace, anbefaler vi (og i de fleste tilfælde er det påkrævet), at handlingen har sit eget lager i stedet for at bundte den med anden programkode. Dette giver dig mulighed for at version, spore og frigive handlingen på samme måde som ethvert andet stykke software. Det gør det nemmere for GitHub-community'et at finde handlingen, begrænser omfanget af kodebasen for udviklere, der løser problemer og udvider handlingen, og adskiller handlingens versionering fra versionering af anden programkode.

Privat

Når en handling er i et privat lager, er det kun arbejdsprocesser i det samme lager, der kan bruge handlingen. Med private handlinger kan du gemme handlingens filer på en hvilken som helst placering i dit lager. Hvis du planlægger at kombinere handlings-, arbejdsproces- og programkode i et enkelt lager, anbefaler vi, at du gemmer handlingen i mappen .github. Du kan f.eks. .github/actions/action-a og .github/actions/action-b.

Dokumentér din handling

Det kan være meget frustrerende at bruge et nyt værktøj eller program, når dokumentationen er vag eller endda mangler. Det er vigtigt at inkludere god dokumentation sammen med din handling, så andre kan se, hvordan det fungerer, uanset om du planlægger at gøre den offentlig eller privat. Den første ting, du skal gøre, er at oprette en god README.md fil til din handling.

Den README.md fil er ofte det første sted, som udviklere kigger på for at se, hvordan handlingen fungerer. Dette er et godt sted at inkludere alle de vigtige oplysninger om handlingen. Følgende er en ikke-udtømmende liste over ting, der skal inkluderes:

  • En detaljeret beskrivelse af, hvad handlingen gør.
  • Obligatoriske input- og outputargumenter.
  • Valgfri input- og outputargumenter.
  • Hemmeligheder, som handlingen bruger.
  • Miljøvariabler, som handlingen bruger.
  • Et eksempel på, hvordan du bruger din handling i en arbejdsproces.

Som hovedregel skal den README.md fil indeholde alt, hvad en bruger skal vide for at bruge handlingen. Hvis du mener, at det kan være nyttige oplysninger, skal du medtage dem i README.md.

Udgiv og udgiv din handling

Hvis du udvikler en handling, som andre kan bruge, uanset om det er offentligt eller privat, skal du definere en strategi for udgivelsesadministration for at styre, hvordan opdateringer distribueres. Overordnede versionsopdateringer, herunder nødvendige kritiske rettelser og sikkerhedsrettelser, der påvirker kompatibiliteten, skal dokumenteres tydeligt.

Gode fremgangsmåder i forbindelse med udgivelses- og versionsstyring

En god strategi til styring af udgivelser bør omfatte anbefalinger til versionering. Brugerne bør ikke referere til en handlings standardgren med handlingen. Det skyldes, at den standardgren, der sandsynligvis indeholder den nyeste kode (som måske eller måske ikke er stabil), kan resultere i, at arbejdsprocessen brydes. Vi anbefaler i stedet, at brugerne angiver en overordnet version, når de bruger handlingen, og kun sender dem til en mere specifik version, hvis der opstår problemer. De kan gøre dette ved at konfigurere deres Arbejdsproces for GitHub-handlinger for at målrette et mærke, en bekræftelses SHA eller en bestemt forgrening, der er navngivet for en udgivelse. Lad os se nærmere på disse udgivelsesindstillinger.

Tags

Mærker kan være en god måde at administrere udgivelser for en handling på. Ved hjælp af mærker kan brugerne nemt skelne mellem overordnede og underordnede versioner. Følgende er en liste over nyttige fremgangsmåder, du skal overveje, når du opretter udgivelser:

  • Opret og valider en udgivelse på en udgivelsesgren (f.eks. release/v1), før du opretter udgivelseskoden (f.eks. v1.0.2).
  • Brug semantisk versionsstyring.
  • Flyt den overordnede versionskode (f.eks. v1, v2) for at pege på Git-referencen for den aktuelle version.
  • Præsenter en ny overordnet versionskode (v2) for ændringer, der ødelægger eksisterende arbejdsprocesser.
  • Udgiv overordnede versioner med et betamærke for at angive deres status. v2-betaf.eks. . Du kan fjerne mærket -beta, når udgivelsen er klar.

Her er nogle eksempler på hver indstilling.

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

Brug en bekræftelses SHA

Mærker er nyttige og bruges i vid udstrækning, men en ulempe ved at bruge mærker er, at de kan slettes eller flyttes. Med Git modtager hver bekræftelse en beregnet SHA-værdi, som er entydig og ikke kan ændres. Hvis du bruger en bekræftelses-SHA til versionering, får du den mest pålidelige og sikre måde at versionere og bruge en handling på. Men ofte i Git kan du forkorte SHA-hashen til de første flere tegn, så genkender Git referencen. Hvis du bruger bekræftelsens SHA til udgivelsesstyring, skal du bruge den fulde SHA-værdi og ikke den forkortede værdi.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Publicer en handling på GitHub Marketplace

Gengivelse, hvor der står GitHub Marketplace, værktøjer til at bygge videre på og forbedre din arbejdsproces.

Når du er klar til at dele din handling med GitHub-community'et, kan du publicere den på GitHub Marketplace og nå ud til millioner af GitHub-brugere. Handlinger, der publiceres på GitHub Marketplace, publiceres med det samme, hvis alle kravene er opfyldt. Handlinger, der ikke opfylder kravene, skal gennemses af GitHub, før de publiceres. Du skal sikre dig, at lageret kun indeholder den metadatafil, kode og filer, der er nødvendige for handlingen. Når du opretter et enkelt lager til handlingen, kan du mærke, udgive og pakke koden i en enkelt enhed. GitHub bruger også handlingens metadata på din GitHub Marketplace-side.

Følgende er kravene til at publicere en handling på GitHub Marketplace. De gælder for både Docker-objektbeholderbaserede handlinger og JavaScript-baserede handlinger:

  • Handlingen skal være i et offentligt lager.
  • Hvert lager skal indeholde en enkelt handling.
  • Handlingens metadatafil (action.yml eller action.yaml) skal være i rodmappen for lageret.
  • Den name i handlingens metadatafil skal være entydig på GitHub Marketplace.
    • Navnet kan ikke matche en bruger eller organisation på GitHub, medmindre brugeren eller organisationens ejer publicerer handlingen. Det er f.eks. kun GitHub-organisationen, der kan publicere en handling med navnet github.
    • name kan ikke matche en eksisterende GitHub Marketplace-kategori.
    • name kan ikke matche en eksisterende GitHub-funktion.

Du kan føje den handling, du har oprettet, til GitHub Marketplace ved at mærke den som en ny version og derefter publicere den. Der er et par guidede trin i GitHub, der giver dig mulighed for at publicere en version af din handling. Du kan finde flere oplysninger om disse trin i afsnittet Oversigt i slutningen af dette modul.