Skip to main content

Use GitHub Actions

info

Official Roam GitHub Actions are available in the public repository WonderInventions/actions.

Overview​

Use Roam GitHub Actions to integrate your CI/CD pipelines with Roam. Post build notifications, deployment status updates, or any other workflow events directly to Roam channels.

Available Actions​

post-message​

Send a message to a Roam chat from your GitHub Actions workflow.

Repository: WonderInventions/actions/post-message

Usage​

- uses: WonderInventions/actions/post-message@master
  with:
    api-key: ${{ secrets.ROAM_API_KEY }}
    chat-id: ${{ vars.DEVOPS_CHAT_ID }}
    text: "Build completed successfully!"

Inputs​

InputRequiredDescription
api-keyYesYour Roam API key (store as a GitHub secret)
chat-idYesThe chat ID to post to (group or channel)
textYesMessage content (supports Markdown)

Setup​

1. Create an API Key​

  1. Go to Roam Administration > Developer > API Keys
  2. Create a new key with the chat:send_message scope
  3. Copy the key

2. Configure GitHub Secrets​

  1. In your GitHub repository, go to Settings > Secrets and variables > Actions
  2. Add a new secret named ROAM_API_KEY with your API key
  3. Optionally, add a variable DEVOPS_CHAT_ID with your target chat/group ID

3. Find Your Chat ID​

To find a group's chat ID:

  1. Open the group in Roam
  2. Click the group name to open settings
  3. Copy the Group ID (format: G-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Examples​

Build Notification​

name: Build and Notify

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm run build

      - name: Notify Roam
        if: always()
        uses: WonderInventions/actions/post-message@master
        with:
          api-key: ${{ secrets.ROAM_API_KEY }}
          chat-id: ${{ vars.DEVOPS_CHAT_ID }}
          text: |
            **Build ${{ job.status }}** for `${{ github.repository }}`

            Branch: `${{ github.ref_name }}`
            Commit: `${{ github.sha }}`
            [View Run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})

Deployment Status​

- name: Notify Deployment
  uses: WonderInventions/actions/post-message@master
  with:
    api-key: ${{ secrets.ROAM_API_KEY }}
    chat-id: ${{ vars.DEVOPS_CHAT_ID }}
    text: |
      :rocket: **Deployed to production**

      Version: `${{ github.ref_name }}`
      Environment: Production