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