Developer Quickstart

0 What's Different

1 Web Login

1. Go to https://git.progroupco.com
2. Click "Sign in with entra" (Microsoft SSO)
3. Authenticate with your ProGroup Entra credentials (MFA handled by Entra)

2 Create a Personal Access Token

Git clone/push via HTTPS uses a Gitea access token (separate from your Entra credentials). Treat it like a password.

1. Go to Settings → Applications → Access Tokens (top-right avatar → Settings)
2. Click Generate New Token
3. Name it (e.g., git-push)
4. Select scope: read:repository + write:repository
5. Copy the token immediately (shown only once)

3 Configure Git Credential Caching

So you only enter the token once per machine, configure Git to remember your credentials:

# Option A: Store permanently (creates ~/.git-credentials):
git config --global credential.helper store

# Option B: Cache in memory for 1 hour (more secure):
git config --global credential.helper 'cache --timeout=3600'

# GCM is the default in Git for Windows. If it's not active, enable it:
git config --global credential.helper manager

# If you need the older wincred helper:
git config --global credential.helper wincred

4 Clone Your Repo

All company repos live under the ProGroup CI organization (URL slug: ci). Replace your-repo with your actual repository name.

git clone https://git.progroupco.com/ci/your-repo.git
cd your-repo
# Username: lowercase part of your email before the @ (e.g., mchildress)
# Password: paste the token from Step 2

git clone https://git.progroupco.com/ci/your-repo.git
cd your-repo
# If using Git Credential Manager, a popup appears:
#   Username: lowercase part of your email before the @
#   Password: paste the token from Step 2

5 Update Existing Local Clones

If you already have a local clone pointing at GitHub, repoint it to Gitea:

cd ~/projects/your-repo
git remote set-url origin https://git.progroupco.com/ci/your-repo.git
git fetch origin
git branch --set-upstream-to=origin/main main
# If your default branch is 'master':
# git branch --set-upstream-to=origin/master master

cd C:\Users\you\projects\your-repo
git remote set-url origin https://git.progroupco.com/ci/your-repo.git
git fetch origin
git branch --set-upstream-to=origin/main main
# If your default branch is 'master':
# git branch --set-upstream-to=origin/master master

Branch Naming (Critical)

# Correct: prefix with feature/ or chore/
git checkout -b feature/add-login
git checkout -b chore/update-deps

# Wrong: no prefix — CI will NOT run on push
git checkout -b fix-bug         # no CI
git checkout -b my-experiment   # no CI

Your First Pull Request

How a typical feature goes from branch to merged PR:

1. Branch: git checkout -b feature/your-feature from main
2. Commit & push: git push origin feature/your-feature — this triggers lint-fix and generate-tests on the branch. If lint fixes are needed, the bot auto-commits them.
3. Open a PR in the Gitea UI (repo → Pull Requests → New). Target main as the base.
4. Wait ~1–2 minutes. The following fire automatically on the PR:
   • review AI posts a structured code review comment with severity tags
   • coverage Diff coverage report posted as a comment
   • pr-summary Human-readable summary of what the PR does
   • commit-message Suggested conventional commit message
   • labeler Labels applied based on changed file paths
5. Address any high-severity findings from the review — these fail the check and block merge. Push fixes to the same branch; the review re-runs on synchronize.
6. Merge when the check is green. On merge (push to main), build-docker fires and tags :latest if the repo has a Dockerfile.

Troubleshooting

Creating a New Repository

1. Go to https://git.progroupco.com/ci
2. Click New Repository (top-right of the org page)
3. Set the name and visibility (Private recommended)
4. Check "Use template" → select ci/ci-template — copies the full CI workflow set (workflows, scripts, prompts) into your new repo automatically
5. Click Create Repository
6. Clone it as described in Step 4

Migrating an existing repo from GitHub

Ask your admin to run the migration script, which:

1. Migrates Git history (no issues/PRs/wiki — those stay on GitHub)
2. Overlays .gitea/ from ci/ci-template (workflows + scripts)
3. Commits + pushes the CI template files
4. Triggers an initial code review + test generation

Or migrate manually:

# Clone from GitHub (bare — preserves all branches + tags)
git clone --mirror https://github.com/yourorg/your-repo.git
cd your-repo.git

# Push everything to Gitea
git push --mirror https://git.progroupco.com/ci/your-repo.git

# Then overlay .gitea/ from ci/ci-template (ask admin)

Secrets

Org-level secrets (managed by admin)

These are set at the ProGroup CI organization level and inherited by every repo under ci/. They're injected into workflow jobs automatically — no per-repo configuration needed.

Repo-level secrets (when you need your own)

If a workflow needs a secret specific to your repo (e.g., a third-party API key, a deployment token):

1. Go to your repo → Settings → Actions → Secrets
2. Click Add Secret
3. Name it (uppercase, underscores: e.g., DEPLOY_TOKEN)
4. Paste the value, click Add Secret

Repo-level secrets override org-level secrets with the same name. Reference them in workflow YAML with ${{ secrets.YOUR_SECRET }}.

Workflows

All workflows live in .gitea/workflows/ and are included automatically when your repo is created from the CI template.

Manually Triggering a Workflow

Many workflows can be triggered manually from the Gitea UI:

1. Go to your repo → Actions tab
2. Click the workflow name (e.g., opencode-review)
3. Click Run Workflow (top-right of the run list)
4. Select the branch and fill in any inputs
5. Click Run

Dispatch Inputs Reference

Checking Workflow Results

FAQ

# If using credential.helper store:
rm ~/.git-credentials

# Or clear the cache:
git credential reject <<EOF
protocol=https
host=git.progroupco.com
EOF

# Delete the stored credential via Credential Manager:
cmdkey /delete:git:https://git.progroupco.com

# Or open the GUI:
# Control Panel → Credential Manager → Windows Credentials
# Find "git:https://git.progroupco.com" → Remove

Need Help?