Publiser en egendefinert GitHub-handling

Fullført

Her lærer du hvordan du velger riktig synlighet for handlingen, anbefalte fremgangsmåter for å dokumentere og versjonskontrollere handlingen, og hvordan du publiserer handlingen til GitHub Marketplace.

Velg en plassering for handlingen

Når du oppretter en handling, er det viktig å først bestemme hvor du vil at denne handlingen skal leve og synligheten til denne handlingen, enten den skal være public eller private. Handlingens synlighet bestemmer hvilke anbefalinger og krav som kreves for å frigi denne handlingen. La oss ta en nærmere titt på disse to synlighetsalternativene.

Offentlig

Arbeidsflyter i et hvilket som helst repositorium kan bruke offentlige handlinger. Hvis du utvikler en handling med den hensikt å gjøre den åpen kildekode eller gjøre den offentlig tilgjengelig via GitHub Marketplace, anbefaler vi (og i de fleste tilfeller er det nødvendig) at handlingen har sitt eget repositorium i stedet for å bunte den med annen programkode. Dette gjør at du kan versjon, spore og slippe handlingen akkurat som alle andre typer programvare. Dette gjør det enklere for GitHub-fellesskapet å oppdage handlingen, begrenser omfanget av kodebasen for utviklere som løser problemer og utvider handlingen, og skiller handlingens versjonskontroll fra versjonskontrollen av annen programkode.

Privat

Når en handling er i et privat repositorium, kan bare arbeidsflyter i samme repositorium bruke handlingen. Med private handlinger kan du lagre handlingens filer hvor som helst i repositoriet. Hvis du planlegger å kombinere handling, arbeidsflyt og programkode i ett enkelt repositorium, anbefaler vi at du lagrer handlingen i .github katalogen. For eksempel .github/actions/action-a og .github/actions/action-b.

Dokumenter handlingen

Det kan være veldig frustrerende å bruke et nytt verktøy eller program når dokumentasjonen er vag eller mangler. Det er viktig å inkludere god dokumentasjon med handlingen, slik at andre kan se hvordan det fungerer, enten du planlegger å gjøre det offentlig eller privat. Det første du må gjøre er å opprette en god README.md fil for handlingen.

Den README.md filen er ofte det første stedet utviklere vil se på for å se hvordan handlingen fungerer. Dette er et flott sted å inkludere all viktig informasjon for handlingen. Følgende er en ikke-uttømmende liste over ting som skal inkluderes:

• En detaljert beskrivelse av hva handlingen gjør.
• Obligatoriske inndata- og utdataargumenter.
• Valgfrie inndata- og utdataargumenter.
• Hemmeligheter handlingen bruker.
• Miljøvariabler handlingen bruker.
• Et eksempel på hvordan du bruker handlingen i en arbeidsflyt.

Som en generell regel bør README.md-filen inkludere alt en bruker bør vite for å bruke handlingen. Hvis du tror det kan være nyttig informasjon, kan du ta den med i README.md.

Frigi og versjon av handlingen

Hvis du utvikler en handling som andre kan bruke, enten den er offentlig eller privat, bør du definere en strategi for utgivelsesadministrasjon for å kontrollere hvordan oppdateringer distribueres. Viktige versjonsoppdateringer, inkludert nødvendige kritiske løsninger og sikkerhetsoppdateringer som påvirker kompatibiliteten, må dokumenteres tydelig.

Gode fremgangsmåter for utgivelse og versjonsbehandling

En god strategi for utgivelsesadministrasjon bør inneholde anbefalinger for versjonskontroll. Brukere bør ikke referere til en handlings standardgren med handlingen. Dette er fordi standardgrenen som sannsynligvis inneholder den nyeste koden (som kanskje eller kanskje ikke er stabil) kan føre til at arbeidsflyten brytes. I stedet anbefaler vi at brukere angir en hovedversjon når de bruker handlingen, og at de bare skal dirigere dem til en mer spesifikk versjon hvis de støter på problemer. De kan gjøre dette ved å konfigurere GitHub Actions-arbeidsflyten til å målrette mot en kode, sha-en for utføring eller en bestemt gren som er navngitt for en utgivelse. La oss ta en nærmere titt på disse lanseringsalternativene.

Tags

Merker kan være en god måte å administrere utgivelser for en handling på. Ved hjelp av merker kan brukere enkelt skille mellom hovedversjoner og underordnede versjoner. Følgende er en liste over nyttige fremgangsmåter du bør vurdere når du oppretter utgivelser:

• Opprett og valider en utgivelse på en utgivelsesgren (for eksempel release/v1) før du oppretter utgivelseskoden (for eksempel v1.0.2).
• Bruk semantisk versjonskontroll.
• Flytt hovedversjonskoden (for eksempel v1, v2) for å peke til Git-ref for den gjeldende versjonen.
• Introduser en ny hovedversjonskode (v2) for endringer som vil bryte eksisterende arbeidsflyter.
• Gi ut hovedversjoner med en betakode for å angi statusen deres. for eksempel v2-beta. Du kan fjerne -beta-koden når utgivelsen er klar.

Her er noen eksempler på hvert alternativ.

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

Bruk sha-en for en utføring

Koder er nyttige og mye brukt, men én ulempe med å bruke koder er at de kan slettes eller flyttes. Med Git mottar hver utføring en beregnet SHA-verdi, som er unik og ikke kan endres. Hvis du bruker en utførings-SHA for versjonskontroll, får du den mest pålitelige og sikre måten å versjons- og bruke en handling på. Ofte i Git kan du imidlertid forkorte SHA-hash-koden til de første tegnene, og Git gjenkjenner referansen. Hvis du bruker utføringens SHA for utgivelsesadministrasjon, må du bruke den fullstendige SHA-verdien og ikke den forkortede verdien.

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

Publisere en handling til GitHub Marketplace

Når du er klar til å dele handlingen med GitHub-fellesskapet, kan du publisere den til GitHub Marketplace og nå ut til millioner av GitHub-brukere. Handlinger som publiseres til GitHub Marketplace, publiseres umiddelbart hvis alle kravene oppfylles. Handlinger som ikke oppfyller kravene, må gjennomgås av GitHub før de publiseres. Du må sørge for at repositoriet bare inneholder metadatafilen, koden og filene som er nødvendige for handlingen. Hvis du oppretter ett enkelt repositorium for handlingen, kan du merke, frigi og pakke koden i én enkelt enhet. GitHub bruker også handlingens metadata på GitHub Marketplace-siden.

Nedenfor følger kravene for å publisere en handling til GitHub Marketplace. De gjelder for både Docker-beholderbaserte handlinger og JavaScript-baserte handlinger:

• Handlingen må være i et offentlig repositorium.
• Hvert repositorium må inneholde én enkelt handling.
• Handlingens metadatafil (action.yml eller action.yaml) må være i rotkatalogen for repositoriet.
• Den name i handlingens metadatafil må være unik på GitHub Marketplace.
  • Navnet kan ikke samsvare med en bruker eller organisasjon på GitHub, med mindre brukeren eller eieren av organisasjonen publiserer handlingen. Bare GitHub-organisasjonen kan for eksempel publisere en handling med navnet github.
  • name kan ikke samsvare med en eksisterende GitHub Marketplace-kategori.
  • name kan ikke samsvare med en eksisterende GitHub-funksjon.

Du kan legge til handlingen du har opprettet i GitHub Marketplace, ved å merke den som en ny utgivelse og deretter publisere den. Det finnes noen veiledede trinn i GitHub som lar deg publisere en utgivelse av handlingen. Du finner mer informasjon om disse trinnene i Sammendrag-delen på slutten av denne modulen.