GitHub-ContriBot 2.0

Overview

GitHub-ContriBot is a GitHub Actions based automation project that performs a complete contribution lifecycle inside your repository.

Each successful bot cycle can:

create a new issue
assign the issue to your account
create a temporary update branch from main
modify contribution_log.txt
commit and push the branch
create a pull request into main
assign the pull request to your account
submit a review
merge the pull request
close the issue through the PR body
delete the temporary branch
The current design is built specifically to avoid workflow loops. The automation runs only from scheduled triggers and manual workflow dispatches. It does not run on push, so bot-created merges do not recursively trigger new runs.

Architecture

The project has three main parts:

Automator.py: the Python automation script
.github/workflows/main.yml: the GitHub Actions workflow
.bot_state.json: the persistent daily quota state
The workflow checks out the repository, installs dependencies, configures git, and runs Automator.py.

The Python script is responsible for:

tracking the current day's quota
deciding whether another cycle should run
creating the issue / branch / PR / review / merge sequence
updating the state after a successful cycle
Daily Quota System
The bot no longer relies on fixed morning and night execution windows.

Instead, it uses a daily random target:

at the start of a new UTC day, the bot selects a random daily_target from 1 to 25
each workflow run performs at most one complete contribution lifecycle
after each successful lifecycle, the bot increments completed
once completed == daily_target, later runs for that day exit without making changes
Example:

{
"date": "2026-03-19",
"daily_target": 17,
"completed": 4
}
This means the bot will continue producing one new issue -> PR -> merge cycle per scheduled run until it reaches 17 for that day.

Workflow Behavior

The GitHub Actions workflow is configured with:

schedule
workflow_dispatch
concurrency
Why concurrency matters
It prevents two bot runs from executing at the same time. This avoids branch collisions, duplicated PR creation, and quota race conditions.

Why there is no push trigger
This is the key fix for the looping problem.

When the bot merges a pull request into main, that merge creates a new commit in the repository. If the workflow listened to push, the merge would trigger the bot again and create an automation loop.

By using only scheduled and manual triggers:

merges to main do not trigger the bot
only the scheduler or a manual run can start a new cycle
Full Bot Lifecycle
During one successful execution, the bot performs the following:

Sync local checkout to the latest main
Read .bot_state.json
If it is a new day, generate a new random target between 1 and 25
If the day's quota is already complete, exit cleanly
Create a fresh branch such as update-20260319093000-5
Append a new entry to contribution_log.txt
Commit the change
Push the branch to GitHub
Create an issue
Assign that issue to the configured GitHub user
Create a PR from the temporary branch to main
Assign the PR to the configured user
Submit a review
Merge the PR into main
Delete the temporary branch
Update .bot_state.json with the new completed count
Review Behavior
GitHub does not allow a user to approve their own pull request.

Because of that, the bot uses this logic:

first it tries to submit an approval review
if GitHub rejects it because the PR author and reviewer are the same account, it falls back to a review comment
This keeps the workflow running successfully in a single-account setup.

If you want actual approval reviews, you need:

a second GitHub account, or
a separate token belonging to another reviewer identity

GitHub-ContriBot 1.0

Overview

Release Summary
Version 1.0 introduced the first stable release of GitHub-ContriBot, focused on automating GitHub contribution activity through
daily commits and optional issue creation. This release established the core automation workflow using GitHub Actions, making it
possible to keep repository activity active without requiring a local machine to stay online.

Key Features

1. Automated Daily Commits
   Version 1.0 introduced automatic daily contribution generation by creating a random number of commits directly in the repository.
   Each run could generate between 1 and 10 commits, helping simulate ongoing activity and keeping the contribution graph populated.

2. Random Issue Creation
   To make repository activity look more dynamic, Version 1.0 added optional issue generation.
   On each run, the bot had a 20% chance of creating a new issue automatically using the GitHub API.

3. GitHub Actions Integration
   The release was built to run entirely on GitHub Actions.
   This allowed the automation to execute in the cloud without depending on the user’s local machine, making the bot easier to
   maintain and more reliable for daily execution.

4. Scheduled Workflow Execution
   Version 1.0 included a scheduled GitHub Actions workflow configured to run automatically every day at 02:30 UTC.
   This ensured that contribution activity could continue without manual intervention once the repository was configured.

5. Manual Workflow Trigger Support
   In addition to scheduled execution, Version 1.0 supported manual triggering through the GitHub Actions interface.
   This allowed users to test the workflow immediately or generate contributions on demand.

6. Local Execution Support
   The bot could also be run manually on a local system using Python.
   This made it possible to test or use the automation outside GitHub Actions, provided the required environment variables were
   configured.

7. Simple Setup Experience
   Version 1.0 was designed to be easy to start with:

• fork the repository
• enable GitHub Actions
• configure the required secrets
• allow the workflow to run automatically

8. Configurable Behavior
   Users could customize the bot’s behavior by editing Automator.py, including:

• commit frequency through random.randint(1, 10)
• issue creation probability through if random.random() < 0.2

Workflow Behavior

In Version 1.0, the automation flow was straightforward:

1. The GitHub Actions workflow started on schedule or manual dispatch.
2. Python dependencies were installed.
3. Git identity was configured using repository secrets.
4. The script updated contribution_log.txt.
5. A random number of commits was created locally.
6. The workflow pushed those commits back to the repository.
7. In some runs, a GitHub issue was also created.

Setup Requirements

Version 1.0 required:

• GitHub Actions enabled in the repository
• COMMIT_USERNAME secret
• COMMIT_EMAIL secret
• GITHUB_TOKEN / repository context for issue creation in Actions
• GITHUB_TOKEN and GITHUB_REPOSITORY environment variables for local issue creation

Purpose of Version 1.0

Version 1.0 was created as an entry-level automation system for:

• maintaining visible repository activity
• experimenting with GitHub Actions automation
• generating consistent contribution patterns
• demonstrating automated commit and issue workflows

Important Notes

• Version 1.0 focused on direct commit automation, not pull request lifecycle automation.
• It was intended primarily for demonstration, testing, and contribution graph activity generation.
• This version served as the foundation for later releases that introduced branch, PR, review, and merge-based workflows.