Skip to content

docs: add GitHub Actions guide #1872

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: master
Choose a base branch
from
Open

docs: add GitHub Actions guide #1872

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
abb53c7
docs: add github actions guide
Aahil13 Apr 28, 2025
e45d481
Merge branch 'master' into Github-Actions
thulieblack Apr 29, 2025
444d30e
Update docs/onboarding-guide/github-actions.md
Aahil13 Apr 30, 2025
48893ac
Update docs/onboarding-guide/github-actions.md
Aahil13 Apr 30, 2025
1a5ddd6
Update docs/onboarding-guide/github-actions.md
Aahil13 Apr 30, 2025
ffeb22d
Merge branch 'asyncapi:master' into Github-Actions
Aahil13 Apr 30, 2025
053821f
docs: fix duplicates and redundancy
Aahil13 Apr 30, 2025
344f28d
Update docs/onboarding-guide/github-actions.md
Aahil13 May 8, 2025
0e0d2bc
Merge branch 'asyncapi:master' into Github-Actions
Aahil13 May 8, 2025
44f63ae
docs: reorganize global workflows content
Aahil13 May 8, 2025
85880c3
Merge branch 'master' into Github-Actions
thulieblack May 15, 2025
99e6e94
Merge branch 'master' into Github-Actions
thulieblack May 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 157 additions & 0 deletions docs/onboarding-guide/github-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
---
title: 'Utilizing GitHub Actions'
weight: 120
---

## Table of Contents

- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [Types of GitHub Actions workflows](#types-of-github-actions-workflows)
- [Local workflows](#local-workflows)
- [Global workflows](#global-workflows)
- [Global workflows overview](#global-workflows-overview)
- [Basic requirements to use global workflows](#basic-requirements-to-use-global-workflows)
- [How to opt in or out of global workflows](#how-to-opt-in-or-out-of-global-workflows)
- [Global replicator workflow](#global-replicator-workflow)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Question 1: Same here. Can this section be a child of the Global workflows ?
  • Question 2: Why did you choose this particular (and not any other from the list below) workflow to describe in detail? What's so special about it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because the Global replicator workflow is an action responsible for distributing other workflows in whatever repository we want. So it's important to go over all the jobs under this workflow.

Also, most of the structure of this document was decided a while ago by the community based on this thread

- [Semantic release and automation](#semantic-release-and-automation)
- [Slash commands](#slash-commands)

## Overview

[GitHub Actions](https://docs.github.com/actions) is a continuous integration and continuous delivery (CI/CD) platform that automates software development workflows directly within a GitHub repository.

At AsyncAPI, GitHub Actions is crucial for maintaining consistency, efficiency, and quality across our projects by handling repetitive tasks automatically.
Comment on lines +22 to +24
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Third duplication. Basically the same concepts are described again in slightly different words.
I would suggest combining all the introductory information into the "Introduction" or "Overview" section after the Table of Contents. A short intro before TOC looks strange


This document outlines how AsyncAPI utilizes GitHub Actions to automate and optimize workflows. It provides a comprehensive guide for maintainers and contributors, explaining global and local workflows, common commands, repository setup, and best practices.

## Types of GitHub Actions workflows

At AsyncAPI, there are two types of workflows: [local](#local-workflows) and [global](#global-workflows).

### Local workflows

Local workflows are specific to a repository. They are stored in the `.github/workflows` directory and typically handle:

- Running tests on pull requests (PRs).
- Linting code.
- Building and deploying applications.

A few key points about local workflows in AsyncAPI:

- Multiple workflows can be triggered for a single PR.
- Not all workflows are required to pass for a PR to be merged.
- Some workflows are marked as required; if these fail, the PR will be blocked.
- External workflows can sometimes affect local checks.

You can view these workflows under the **Actions** tab or at the bottom of each PR page.

### Global workflows

Global workflows are shared across multiple repositories and maintained centrally in the [AsyncAPI `.github` repository](https://github.com/asyncapi/.github).

They help:

- Enforce consistent configurations.
- Automate releases.
- Synchronize files across repositories.

Changes made to global workflows can automatically propagate to opted-in repositories.

#### Global workflows overview

The table below provides an overview of all the global workflows available in the AsyncAPI organization:

| Workflow Name | Description |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would be the process of maintaining this table up-to-date once any workflow gets changed?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same question from my side

it is already not very accurate, as there is no workflow names "PTAL command" but "Please take a Look" (https://github.com/asyncapi/.github/blob/master/.github/workflows/please-take-a-look-command.yml)

imho better in overview explain how to learn about each workflow, on an example

and for good docs, rather put comments inside YAML files - the advantage is that if there is a good docs in yaml, it will be easier to maintain, and also anyone seeing a copy of such workflow in their repo - they can easily learn what it does directly from the YAML file copy

|:--------------|:------------|
| **Add Good First Issue** | Labels issues automatically with `good first issue` and area labels to an issue when a contributor comments `/gfi` or `/good-first-issue [area]`. |
| **Automerge for Humans(Add Ready to Merge or Do Not Merge)** | Enables merging PRs via slash commands such as `/rtm`, `/dnm`, `/au` to mark them as ready to merge, block them from merging, or enable automatic updates. |
| **Automerge for Humans Merging** | Enables automatic merging of pull requests once all checks pass and a maintainer has approved it, as long as the PR has the `ready-to-merge` label and no `do-not-merge` label. |
| **Automerge for Humans(remove ready to merge label on edit)** | Acts as a safeguard by automatically removing the `ready-to-merge` label if a pull request is changed (either synchronized or its title is edited) after the label was applied. |
| **Automerge Orphan** | Runs daily to identify pull requests opened by bots like `asyncapi-bot` or `dependabot` that failed to automerge. |
| **Automerge** | Automatically approves and merges pull requests created by trusted bots like `asyncapi-bot` or `dependabot`. |
| **Autoupdate** | Ensures that autoapproved pull requests with the `autoupdate` label in upstream AsyncAPI repositories are always up-to-date with their target branches. |
| **Bounty Program Commands** | Allows only authorized users to assign or unassign bounties using comments like `/bounty` or `/unbounty`. |
| **Bump** | Bumps version dependencies across AsyncAPI repos after a release commit is merged into `master`. |
| **Global Remover** | Deletes specific files from multiple repositories in the AsyncAPI organization. It runs when changes are pushed to the `.github/workflows` directory, or when manually triggered. |
| **Global Replicator** | Syncs various important files across multiple repositories in the AsyncAPI organization. |
| **Help Command** | Lists available slash commands when `/help` is used. |
| **If Docker PR testing** | Runs on pull request activity and tests whether a Docker image can be built from the project **only if a `Dockerfile` is present** in the repository root. |
| **If Go PR testing** | Runs on pull request activity and, if the project contains a `go.mod` file, it lints and tests the Go code across Linux, macOS, and Windows environments—while skipping checks for automated bot PRs. |
| **If Node.js PR Testing** | Runs on pull request events and, if a `package.json` file is found, it installs dependencies, runs tests, and performs linting for Node.js projects across Linux, macOS, and Windows. |
| **If Node.js Release** | Automates the release process for Node.js projects by running tests across OSes when conventional commit messages are used and the repo is under `asyncapi/`. |
| **If Node.js Version Bump** | Bumps the version in a Node.js project's `package.json` right after a GitHub release is published. |
| **Issue and PR Notifications** | Sends Slack notifications on issue and PR activity. |
| **Lint PR Titles** | Enforces Conventional Commits for PR titles. |
| **Notify TSC Mentions** | Notifies the TSC via Slack and email whenever `@asyncapi/tsc_members` is mentioned in issues, PRs, discussions, or their comments. |
| **PTAL Command** | Listens for `/please-take-a-look` or `/ptal` comments on PRs and pings any requested reviewers who haven’t reviewed yet, helping prompt attention from the right people. |
| **Release Announcements** | Announces new releases by notifying a Slack channel for every release and tweeting about major or minor releases, including contributor recognition. |
| **Stale Issues Management** | Marks inactive issues and PRs as stale after 120 days of inactivity and closes them if there's still no activity, while allowing exceptions via labels. |
| **Transfer Issues** | Allows users to transfer open issues between AsyncAPI repos by commenting `/transfer-issue <repo>` or `/ti <repo>`, validating the target repo first. |
| **Update Docs** | Regenerates docs PRs on `docs:` commits. |
| **Update MAINTAINERS Trigger** | Triggers an update to the `MAINTAINERS.yaml` file in the community repo whenever a `CODEOWNERS` file is changed on the `master` branch. |
| **Update PR** | Listens for PR comments with `/update` or `/u`, and if the PR is updateable (e.g., it's behind the base branch but has no conflicts), it automatically merges the latest changes from the base into the PR branch—even for forks (unless they're in different orgs or lack permissions). |
| **Validate Workflow Schema** | Lints and validates GitHub Actions YAMLs. |
| **Welcome First Time Contributors** | Posts a welcome message for first-time contributors. |

(For a detailed breakdown of each, see [AsyncAPI Global Workflows](https://github.com/asyncapi/.github/tree/master/.github/workflows)).

#### Basic requirements to use global workflows

Before a repository can start using the global workflows managed through the `.github` repository, a few setup steps are required. This ensures that bots can properly push and merge workflow files. Without these steps, the automation will not work as expected.

The basic requirements are:

- **Add the bots team as maintainers**: In the repository settings, under *Collaborators and Teams*, add the bots team with maintainer permissions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

provide team name

@asyncapi/bots

- **Add Eve to code owners**: Ensure that the Eve bot account is listed as a code owner to allow automatic approval of bot-generated pull requests.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

provide the name so people knwo what to put in CODEOWNERS file

@asyncapi-bot-eve

and yeah, explain that code owner means someone in CODEOWNER

- **Trigger initial setup**: Reach out to the maintainers of the `.github` repository and ask them to manually run the "Global Workflow to Rule Them All" action, providing your repository name.
- **Manually approve initial PRs**: The first set of workflow-related pull requests must be manually merged, as the automation for merging only becomes available after the necessary workflows are installed.

Once these steps are complete, the repository will start automatically receiving and merging global workflow updates as expected.

#### How to opt in or out of global workflows

**Opt-in**

To opt in to a global workflow managed in the AsyncAPI `.github` repository, you can either add a specific topic to your repository (via GitHub settings or the GitHub CLI) or ask a maintainer to trigger it manually for you.

To do this, reach out on Slack or open an issue, and a maintainer can run the “Global workflow to rule them all” from the **Actions** tab, optionally targeting your repo by name.

**Opt-out**

Some workflows are applied automatically to all repositories. If you’d like to opt out of one of those, your repository must be added to the `repos_to_ignore` list in the relevant job. This change has to be made in the global workflow by a maintainer, so just ask in Slack or open an issue if you'd like to be excluded.

## Global replicator workflow

The [Global Replicator Workflow](https://github.com/asyncapi/.github/blob/master/.github/workflows/global-replicator.yml) keeps key files in sync across AsyncAPI repositories.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not so sure it is good idea to have this table.

even now it is not up to date with what is in https://github.com/asyncapi/.github/blob/master/.github/workflows/global-replicator.yml file - long term it might event get worse

wouldn't it be better to make sure https://github.com/asyncapi/.github/blob/master/.github/workflows/global-replicator.yml has proper comments and descriptions inside YAML, and here in docs, it is explaned that there are different jobs, and how and where to find more details?


| **Job Name** | **Description** | **Replicated Files** | **Target** |
|----------------------------------|---------------------------------------------|------------------------------------------------|-------------------------------|
| `replicate_coc` | Syncs `CODE_OF_CONDUCT.md` | `CODE_OF_CONDUCT.md` | All AsyncAPI repos |
| `replicate_contributing` | Syncs `CONTRIBUTING.md` | `CONTRIBUTING.md` | All AsyncAPI repos |
| `replicate_go_workflows` | Pushes Go PR testing workflows | `.github/workflows/if-go-pr-testing.yml` | Repos with `golang` topic |
| `replicate_nodejs_workflows` | Pushes Node.js PR testing workflows | `.github/workflows/if-nodejs-pr-testing.yml` | Repos with `nodejs` topic |
| `replicate_nodejs_release_workflows`| Pushes Node.js release workflows | `if-nodejs-release.yml`, `if-nodejs-version-bump.yml` | Node release repos |
| `replicate_generic_workflows` | Pushes utility workflows like stale labeling| Multiple `.github/workflows/*.yml` | All AsyncAPI repos |
| `replicate_docker_workflows` | Pushes Docker PR testing workflows | `.github/workflows/if-docker-pr-testing.yml` | Repos with `docker` topic |
| `replicate_validate_workflow_schema`| Adds YAML validation workflows | `.github/workflows/validate-workflow-schema.yml`| Repos with validation topic |

## Semantic release and automation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this be here? especially that semantic release is no longer the only standard here, we also use changeset in some monorepos


Semantic release automatically creates and publishes new package versions based on commit messages following [Conventional Commits](https://www.conventionalcommits.org/).

By merging a pull request with a properly formatted title, a release is automatically triggered without needing manual intervention.

When you opt in to the Node.js release workflows, you also agree to use Semantic Release and Conventional Commits across your repository. This setup enables full automation of the release process: once code is merged to `master`, the appropriate version is published to npm, and a GitHub release is created. It even supports advanced cases like pre-releases.

There are two separate jobs in the AsyncAPI global workflow: one to replicate the Node.js release workflows, and another to replicate the standard `.releaserc` configuration file. Some projects, especially more complex setups like monorepos, may need a custom release configuration instead of the default one, and in those cases, maintainers can opt out of using the shared `.releaserc` file.

## Slash commands

Thanks to the shared workflows, repositories that opt in automatically get support for issue and pull request commands.

These commands allow users to type a slash command (like `/something`) directly into an issue or PR to trigger helpful actions through a bot, reducing manual work.

To make it easy, the most important command to remember is `/help`, which shows a list of all available commands whenever you need it.

For example, the `/rtm` command lets you merge a PR without worrying about manually adjusting the commit message.