# GitHub Actions

:::info

Official Roam GitHub Actions are available in the public repository [WonderInventions/actions](https://github.com/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](https://github.com/WonderInventions/actions/tree/master/post-message)

#### Usage

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

#### Inputs

| Input | Required | Description |
|-------|----------|-------------|
| `api-key` | Yes | Your Roam API key (store as a GitHub secret) |
| `chat-id` | Yes | The chat ID to post to (group or channel) |
| `text` | Yes | Message 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

```yaml
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

```yaml
- 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
```

## Related

- [Send Message API](/docs/roam-api/send-message) - API reference for the underlying endpoint