libnudget bot

A programmable GitHub bot for automated commits.

The goal of this project is to provide a single, auditable automation identity for the libnudget organization. Instead of hardcoding bot credentials across multiple repositories, this repo centralizes the bot configuration and provides reusable actions.

This bot is designed for students learning about GitHub Actions and automation. It demonstrates how to create a reusable commit action that can be consumed by any repository.

Table of Contents

• OVERVIEW
• IDENTITY
• HOW IT WORKS
• USAGE
  • GitHub Action
  • Local Scripts
• CONFIGURATION
• FILES
• AVATAR
• PRIVACY

OVERVIEW

libnudget bot is an automated commit identity for the libnudget organization. It allows repositories to make commits using a consistent bot identity without hardcoding credentials.

Key features:

• Reusable GitHub Action for commits
• Configurable bot identity via environment variables
• Custom avatar support through Gravatar
• No infrastructure required
• Single source of truth for bot behavior

IDENTITY

The bot uses the following identity:

Field	Value
Name	libnudget[bot]
Email	$BOT_EMAIL (configurable)

The identity is set in each script:

git config user.name "libnudget[bot]"
git config user.email "$BOT_EMAIL"

This ensures all commits from the bot are consistent and traceable.

HOW IT WORKS

The system works in two ways:

GitHub Actions

When used as a GitHub Action:

1. Repository configures BOT_EMAIL in GitHub secrets/variables
2. Workflow calls the reusable action
3. Action sets git config using the email
4. Commit is made with bot identity
5. GitHub links email to Gravatar, displaying the avatar

- uses: libnudget/bot/actions/commit@v1
  with:
    message: "chore: update dependencies"

Local Scripts

For local development:

1. Set BOT_EMAIL environment variable
2. Run configuration script
3. Make commits normally

export BOT_EMAIL="your@email.com"
./scripts/configure-git.sh
git commit -m "chore: update file"

USAGE

GitHub Action

Add to your workflow:

name: automated commit

on:
  workflow_dispatch:

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

      - uses: libnudget/bot/actions/commit@v1
        with:
          message: "chore: automated update"
        env:
          BOT_EMAIL: ${{ vars.BOT_EMAIL }}

Requires setting BOT_EMAIL in repository settings.

Local Scripts

Configure Git

export BOT_EMAIL="your@email.com"
./scripts/configure-git.sh

Make a Commit

./scripts/commit.sh "chore: your message"

Create a Release

./scripts/release.sh v1.0.0

CONFIGURATION

GitHub Repository

1. Go to repository Settings
2. Navigate to Secrets and variables → Actions
3. Add new variable:
   • Name: BOT_EMAIL
   • Value: your Gravatar email

Environment Variable

Variable	Required	Description
BOT_EMAIL	Yes	Email for commit identity and avatar

Set locally:

export BOT_EMAIL="your@email.com"

FILES

bot/
├── .github/workflows/
│   └── bot-self-test.yml    # Self-test workflow
├── actions/commit/
│   ├── action.yml           # Action definition
│   ├── entrypoint.sh       # Action logic
│   └── README.md           # Action documentation
├── scripts/
│   ├── configure-git.sh    # Set bot identity
│   ├── commit.sh           # Make commits
│   └── release.sh          # Create releases
├── docs/
│   └── IDENTITY.md        # Identity documentation
├── PRIVACY.md              # Privacy policy
└── README.md               # This file

AVATAR

The bot avatar is fetched from Gravatar using the commit email.

Setup

1. Register at gravatar.com
2. Add the email you configured as BOT_EMAIL
3. Upload your desired avatar

How It Works

GitHub links commits to Gravatar using the email address:

commit email → Gravatar lookup → display avatar

This means any email registered with Gravatar will display that avatar on commits.

PRIVACY

This bot only performs automated commits on behalf of the libnudget organization.

What the bot does

• Creates commits in repositories where it is configured
• Uses a dedicated identity for all automated actions
• Does not collect, store, or process any personal data

Data handling

• All activity is limited to git commits within the organization
• No external data collection
• No third-party services receive data from this bot

Questions

For any questions about this bot's behavior, please open an issue in the repository.

AFTERWORD

This project is designed for educational purposes. Students can learn how to:

• Create reusable GitHub Actions
• Configure automated commit identities
• Set up Gravatar integration
• Build automation tooling

Feel free to fork and modify for your own use cases!