Een aangepaste GitHub-actie publiceren

Voltooid

Hier vindt u informatie over het kiezen van de juiste zichtbaarheid voor uw actie, aanbevolen procedures voor het documenteren en versiebeheer van uw actie en het publiceren van uw actie naar GitHub Marketplace.

Kies een locatie voor uw actie

Wanneer u een actie maakt, is het belangrijk om eerst te bepalen waar u wilt dat die actie actief is en de zichtbaarheid van die actie, ongeacht of deze wel public of private. De zichtbaarheid van de actie bepaalt welke aanbevelingen en vereisten nodig zijn om die actie vrij te geven. Laten we deze twee zichtbaarheidsopties nader bekijken.

Openbaar

Werkstromen in elke opslagplaats kunnen openbare acties gebruiken. Als u een actie ontwikkelt met de bedoeling deze open source te maken of deze openbaar beschikbaar te maken via GitHub Marketplace, raden we aan (en in de meeste gevallen is dit vereist) dat de actie een eigen opslagplaats heeft in plaats van deze te bundelen met andere toepassingscode. Hiermee kunt u de actie versieren, bijhouden en vrijgeven, net zoals elk ander stukje software. Dit maakt het voor de GitHub-community eenvoudiger om de actie te detecteren, beperkt het bereik van de codebasis voor ontwikkelaars die problemen oplossen en de actie uitbreiden, en scheidt de versiebeheer van de actie van de andere toepassingscode.

Privé

Wanneer een actie zich in een privéopslagplaats bevindt, kunnen alleen werkstromen in dezelfde opslagplaats de actie gebruiken. Met privéacties kunt u de bestanden van de actie opslaan op elke locatie in uw opslagplaats. Als u van plan bent actie, werkstroom en toepassingscode in één opslagplaats te combineren, raden we u aan de actie op te slaan in de .github map. Bijvoorbeeld .github/actions/action-a en .github/actions/action-b.

Uw actie documenteer

Het kan erg frustrerend zijn om een nieuw hulpprogramma of een nieuwe toepassing te gebruiken wanneer de documentatie vaag of zelfs ontbreekt. Het is belangrijk om goede documentatie op te nemen met uw actie, zodat anderen kunnen zien hoe het werkt, of u het nu openbaar of privé wilt maken. Het eerste wat u moet doen, is het maken van een goed README.md bestand voor uw actie.

Het README.md bestand is vaak de eerste plek waar ontwikkelaars naar kijken om te zien hoe de actie werkt. Dit is een geweldige plek om alle belangrijke informatie voor de actie op te nemen. Hier volgt een niet-volledige lijst met zaken die u moet opnemen:

• Een gedetailleerde beschrijving van wat de actie doet
• Vereiste invoer- en uitvoerargumenten
• Optionele invoer- en uitvoerargumenten
• Geheimen die door de actie worden gebruikt
• Omgevingsvariabelen die door de actie worden gebruikt
• Een voorbeeld van het gebruik van uw actie in een werkstroom

In de regel moet het README.md bestand alles bevatten wat een gebruiker moet weten om de actie te gebruiken. Als u denkt dat het nuttige informatie kan zijn, neemt u deze op in de README.md.

Uw actie vrijgeven en versien

Als u een actie ontwikkelt die anderen kunnen gebruiken, ongeacht of het openbaar of privé is, moet u een strategie voor releasebeheer definiëren om te bepalen hoe updates worden gedistribueerd. Belangrijke versie-updates, waaronder noodzakelijke essentiële oplossingen en beveiligingspatches die van invloed zijn op de compatibiliteit, moeten duidelijk worden gedocumenteerd.

Goede procedures voor release- en versiebeheer

Een goede strategie voor releasebeheer moet aanbevelingen voor versiebeheer bevatten. Gebruikers mogen niet verwijzen naar de standaardvertakking van een actie met de actie, omdat de standaardvertakking die waarschijnlijk de meest recente code bevat (die mogelijk of niet stabiel is) en kan leiden tot fouten in uw werkstroom. In plaats daarvan raden we gebruikers aan een primaire versie op te geven wanneer ze de actie gebruiken en om ze alleen naar een specifiekere versie te leiden als ze problemen ondervinden. Ze kunnen dit doen door hun GitHub Actions-werkstroom te configureren om een tag, de SHA van een doorvoer of een specifieke vertakking te richten die is benoemd voor een release. Laten we deze releaseopties eens nader bekijken.

Tags

Tags kunnen een goede manier zijn om releases voor een actie te beheren. Met behulp van tags kunnen gebruikers eenvoudig onderscheid maken tussen primaire en secundaire versies. Hier volgt een lijst met nuttige procedures waarmee u rekening moet houden bij het maken van releases:

• Maak en valideer een release op een releasebranch (zoals release/v1) voordat u de releasetag maakt (bijvoorbeeld v1.0.2).
• Gebruik semantische versiebeheer.
• Verplaats de primaire versietag (zoals v1, v2) om te verwijzen naar de Git-ref van de huidige release.
• Introduceer een nieuwe primaire versietag (v2) voor wijzigingen die bestaande werkstromen breken.
• Release primaire versies met een bètatag om hun status aan te geven; bijvoorbeeld v2-beta. U kunt de -beta tag verwijderen wanneer de release gereed is.

Hier volgen enkele voorbeelden van elke optie.

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

De SHA van een doorvoer gebruiken

Tags zijn nuttig en veel gebruikt, maar een nadeel van het gebruik van tags is dat ze kunnen worden verwijderd of verplaatst. Met Git ontvangt elke doorvoer een berekende SHA-waarde, die uniek is en niet kan worden gewijzigd. Als u een doorvoer-SHA gebruikt voor versiebeheer, krijgt u de meest betrouwbare en veilige manier om een versie uit te voeren en een actie te gebruiken. Vaak kunt u in Git echter de SHA-hash verkorten tot de eerste verschillende tekens, en Git herkent de verwijzing. Als u de SHA van de doorvoer gebruikt voor releasebeheer, moet u de volledige SHA-waarde en niet de verkorte waarde gebruiken.

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

Een actie publiceren naar De GitHub Marketplace

Wanneer u klaar bent om uw actie te delen met de GitHub-community, kunt u deze publiceren naar de GitHub Marketplace en contact opnemen met miljoenen GitHub-gebruikers. Acties die naar de GitHub Marketplace worden gepubliceerd, worden onmiddellijk gepubliceerd als aan alle vereisten wordt voldaan. Acties die niet voldoen aan de vereisten, moeten worden gecontroleerd door GitHub voordat ze worden gepubliceerd. U moet ervoor zorgen dat de opslagplaats alleen het metagegevensbestand, de code en de bestanden bevat die nodig zijn voor de actie. Door één opslagplaats voor de actie te maken, kunt u de code in één eenheid taggen, vrijgeven en verpakken. GitHub gebruikt ook de metagegevens van de actie op uw GitHub Marketplace-pagina.

Hieronder volgen de vereisten voor het publiceren van een actie naar De GitHub Marketplace. Ze zijn van toepassing op acties op basis van docker-containers en op JavaScript gebaseerde acties:

• De actie moet zich in een openbare opslagplaats bevindt.
• Elke opslagplaats moet één actie bevatten.
• Het metagegevensbestand (action.yml of action.yaml) van de actie moet zich in de hoofdmap van de opslagplaats bevinden.
• Het name metagegevensbestand van de actie moet uniek zijn op de GitHub Marketplace.
  • De naam kan niet overeenkomen met een gebruiker of organisatie op GitHub, tenzij de eigenaar van de gebruiker of organisatie de actie publiceert. Alleen de GitHub-organisatie kan bijvoorbeeld een actie met de naam githubpubliceren.
  • De name kan niet overeenkomen met een bestaande GitHub Marketplace-categorie.
  • De name functie kan niet overeenkomen met een bestaande GitHub-functie.

U kunt de actie die u hebt gemaakt toevoegen aan de GitHub Marketplace door deze te taggen als een nieuwe release en deze vervolgens te publiceren. Er zijn enkele begeleide stappen in GitHub waarmee u een release van uw actie kunt publiceren. U vindt meer informatie over deze stappen in de sectie Samenvatting aan het einde van deze module.