How to Use the Message Broker

1. Setting Up Your GitHub Token

A GitHub personal access token is required to interact with GitHub APIs, such as accessing Discussions in your repositories. Follow these steps to create one:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic).
2. Click Generate new token (classic).
3. Enter a Note to describe the token (e.g., "App Token").
4. Select an Expiration period (e.g., 30 days or No expiration).
5. Under Select scopes, check:
   • repo: Grants full control over both private and public repositories, including Discussions.
   • write:discussion: Specifically allows creating and updating GitHub Discussions.
   • read:user: Allows read-only access to your user profile (found under the "user" section of scopes).
6. Click Generate token and copy the token (starts with ghp_).
7. Security Tip: Store the token securely and never share it publicly. You won’t see it again after leaving the page.

2. Enabling GitHub Discussions in Repositories

Your application interacts with repositories where GitHub Discussions are enabled. Here’s how to set it up:

1. Open your repository on GitHub (e.g., https://github.com/username/repo).
2. Go to Settings → General.
3. Scroll to the Features section.
4. Check the box for Discussions to enable it.
5. Verify by navigating to the Discussions tab in your repository. You should see options to create new discussions.
6. Repeat for each repository you want to use with this application.

3. Creating an Application

You must be signed in to create an app. If you don’t have an account, Sign Up or Sign In.

Create an app on the Create App page to configure your Discussion bot:

1. Navigate to /app/create or press Create App from the Home page.
2. Fill in the form:
   • Name: Enter a unique name (e.g., "Discussion Bot").
   • GitHub Token: Paste the token you generated (it’s masked for security).
   • Prompt: Write instructions for your app’s behavior.
3. Click Create to save the app.

Writing Effective Prompts:

• Be clear and specific (e.g., “Monitor GitHub Discussions in my repository and summarize new posts daily.”).
• Include context (e.g., “Act as a bot that responds to questions in Discussions with helpful answers.”).
• Avoid ambiguity (e.g., instead of “Do something with Discussions,” say “Post a welcome message in new Discussions.”).
• Example Prompt: “You are a GitHub Discussions assistant. For each new discussion in my repository, post a reply: ‘Thanks for starting this discussion! I’ll help answer your questions.’ Use the provided GitHub token to access the repo.”

4. Adding a GitHub Actions Workflow

To automate your app’s interaction with Discussions, add a GitHub Actions workflow to your repository’s (project's) root. This script runs your app’s logic (e.g., posting in Discussions).

1. In your repository (project), create a directory: .github/workflows/.
2. Create a new file (e.g., discussion-bot.yml) in .github/workflows/.
3. Copy the workflow script below into the file.
4. Add secrets in GitHub:
   • Go to Settings → Secrets and variables → Actions → New repository secret.
   • Add APP_TOKEN (copy from the app details page at /app/view).
   • Add SERVER_URL (https://message-broker.atai-mamytov.click).
5. Commit the file to your repository’s main branch.

git add .

git commit -m "Your commit"

git push -u origin main

6. Go to the Actions tab in your repository to verify the workflow runs.

Workflow Script:

name: Notify Server

on:
  push:
    branches:
      - main

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Notify Server with Retries
        env:
          SERVER_URL: ${{ secrets.SERVER_URL }}
        run: |
          MAX_RETRIES=5
          RETRY_DELAY=5
          COUNTER=0

          while [ $COUNTER -lt $MAX_RETRIES ]; do
            RESPONSE=$(curl -s -o response.txt -w "%{http_code}" -X POST "$SERVER_URL/api/forward?appToken=${{ secrets.APP_TOKEN }}&repositoryName=${{ github.repository }}¤tCommit=${{ github.sha }}&prevCommit=${{ github.event.before }}&pusherName=${{ github.actor }}")

            if [ "$RESPONSE" -eq 200 ]; then
              echo "Notification sent successfully!"
              exit 0
            else
              echo "Failed to notify server (HTTP $RESPONSE), response: $(cat response.txt)"
              echo "Retrying in $RETRY_DELAY seconds..."
              sleep $RETRY_DELAY
              COUNTER=$((COUNTER + 1))
            fi
          done

          echo "Failed to notify server after $MAX_RETRIES attempts. Final response: $(cat response.txt)"
          exit 1

Notes:

• Store your app’s token in GitHub Secrets (Settings → Secrets and variables → Actions → New repository secret).
• Ensure Discussions are enabled, or the workflow won’t trigger.
• Keep your GitHub token scopes minimal — only select what’s necessary (e.g., repo, write:discussion, read:user). Avoid granting more permissions than required.