Sync Git issues to Microsoft Planner tasks, and back, with automatic category mapping, assignee resolution and attachment handling. Built for teams that track work in GitHub, Gitea, Forgejo or GitLab and plan it in Microsoft 365.
GitHub / GitHub Enterprise ┐ ┌ tasks, buckets, labels
Gitea / Forgejo / Codeberg ├── git2planner sync ──┤ assignees, checklists
GitLab.com / self-managed ┘ (one way or both) └ links and files
- Four providers: GitHub (and GitHub Enterprise Server), Gitea, Forgejo (including Codeberg) and GitLab (including nested groups and self-managed instances).
- One way or both ways:
git-to-planner,planner-to-gitorboth. Pick it per repository or for a single run with--direction. - Edits stay where they were made: git2planner remembers what it last
wrote on each side and compares every field with that baseline. Only real
edits cross over, so values it wrote itself never come back as changes. When
both sides edit the same field, a
conflictspolicy decides which one wins. - Category mapping: labels become Planner labels (
category1–category25). Missing labels are created on the fly, using the free slot whose colour is closest to the Git label's colour. Explicit mappings and exclusions are also supported. - Assignee resolution: explicit mapping, public Git e-mail, or
<login>@your-domain. Results are checked against the plan's Microsoft 365 group, with optional fallback assignees. - Attachments: the issue and the files uploaded to it are added as task links. Optionally the files are copied into the group's SharePoint document library.
- Kanban: buckets can mirror the columns of a project board (GitHub Projects, Gitea, GitLab issue boards) in both directions. They can also be one fixed bucket, or one per label or per milestone, plus a "closed" bucket. Missing buckets are created automatically.
- Rich tasks: title template, plain-text description with a link back to the issue, Markdown task lists turned into Planner checklists, priority from labels, due date from the issue or its milestone.
- Safe to run anywhere: dry run, incremental fetching, ETag handling, throttling and retry support, an atomic state file with locking, and re-linking of existing tasks when the state file is lost.
- Runs where you already work: CLI, Docker image, GitHub Action, and examples for Gitea/Forgejo Actions and GitLab CI.
pip install git2planner
# or straight from a release tag
pip install "git2planner @ git+https://github.com/francescodifilippo/git2planner@v1.0.0"-
Register an app in Microsoft Entra ID and grant it Planner permissions. docs/azure-setup.md walks through it in five minutes.
-
Create a configuration file and edit it:
git2planner init --provider github # or gitea, forgejo, gitlab -
Provide the secrets as environment variables:
export AZURE_TENANT_ID=... AZURE_CLIENT_ID=... AZURE_CLIENT_SECRET=... export GITHUB_TOKEN=... # GITEA_TOKEN, FORGEJO_TOKEN or GITLAB_TOKEN
-
Find your plan id, check the setup, preview, then run:
git2planner plans --group <microsoft-365-group-id> git2planner validate git2planner sync --dry-run git2planner sync
graph:
auth: auto # client_secret, federated, github_oidc, device_code, access_token
defaults:
direction: both # git-to-planner | planner-to-git | both
conflicts: git # who wins when both sides changed the same field
buckets: {default: To do, closed: Done}
categories: {mode: auto, exclude: [priority/high]}
priority: {mapping: {priority/high: important}}
assignees: {email_domain: contoso.com, mapping: {octocat: mona@contoso.com}}
attachments: {mode: upload}
syncs:
- name: backend
source: {provider: github, repository: acme/backend}
plan_id: xqQg5FS2LkCp935s-FIFm2QAFkHM
- name: website
source: {provider: gitlab, repository: acme/web/site}
plan_id: xqQg5FS2LkCp935s-FIFm2QAFkHM
filters: {labels: [planner]}
- name: infra
source: {provider: forgejo, url: https://codeberg.org, repository: acme/infra}
plan_id: 9rRG4mjJS0ac3C6G2Qex-WQAEXX1
planner_to_git: {create_issues: true, buckets: [Inbox]}Every option is described in docs/configuration.md.
| Git issue | Planner task | Back to Git (planner-to-git) |
|---|---|---|
| Title | Title (title_template) |
Title, with the template prefix removed |
| Open / closed | 0 % / 100 % complete, "closed" bucket | Ticking a task or moving it to "closed" closes the issue |
| Labels | Planner labels (categories) | Added/removed labels |
| Priority labels | Priority (urgent, important, …) | Priority label |
| Label / milestone | Bucket | Bucket label (label strategy) |
| Project board column | Bucket (board strategy) |
Card moved to the matching column |
| Assignees | Assignments | Assignees |
| Due date / milestone due date | Due date | Due date (Gitea, Forgejo, GitLab) |
| Body | Description (plain text + link) | Optional (fields: [description]) |
- [ ] task list |
Checklist | Ticks and new checklist items |
| Issue URL, uploaded files | Links (references), SharePoint files | – |
| – | New task (create_issues: true) |
New issue |
For every issue–task pair, git2planner stores a baseline: the values it last wrote, in Planner terms. On each run it compares both sides with that baseline, field by field:
| Changed in Git | Changed in Planner | Result |
|---|---|---|
| no | no | nothing is sent |
| yes | no | Planner is updated |
| no | yes | the issue is updated |
| yes | yes | the conflicts side wins (git by default) |
With direction: both, each run first pulls Planner edits into Git, then
pushes Git changes into Planner. Because of the baseline, the title prefix,
the description footer and the links that git2planner adds to a task are
never sent back to Git as if they were user edits. Edits made in Planner to
fields that are synced one way only are kept until the issue itself changes.
If you would rather alternate, keep direction: git-to-planner in the
configuration and run the other direction when you need it:
git2planner sync --direction planner-to-gitMore details are in docs/sync-model.md.
on:
schedule: [{cron: "*/30 * * * *"}]
issues:
workflow_dispatch:
permissions:
issues: write # read is enough for git-to-planner
id-token: write # only for graph.auth: github_oidc
jobs:
sync:
runs-on: ubuntu-latest
concurrency: git2planner
steps:
- uses: actions/checkout@v5
- uses: actions/cache@v5
with:
path: .git2planner
key: git2planner-${{ github.run_id }}
restore-keys: git2planner-
- uses: francescodifilippo/git2planner@v1
env:
AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
GITHUB_TOKEN: ${{ github.token }}The cache keeps the state file between runs. Without it git2planner still works: it re-links existing tasks through their issue links. It just cannot tell Planner edits apart from its own writes, so Git wins on every field. More examples, for Gitea/Forgejo Actions, GitLab CI, Docker and cron, are in examples/.
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" \
-e AZURE_TENANT_ID -e AZURE_CLIENT_ID -e AZURE_CLIENT_SECRET -e GITHUB_TOKEN \
ghcr.io/francescodifilippo/git2planner:1 sync| Command | Purpose |
|---|---|
git2planner init |
write an annotated configuration file |
git2planner validate |
check the configuration, credentials and permissions |
git2planner sync |
run the configured syncs |
git2planner plans --group ID |
list the plans of a Microsoft 365 group |
git2planner describe-plan ID |
show the buckets and labels of a plan |
git2planner login / logout |
device-code sign-in for delegated permissions |
Useful sync options: --dry-run, --direction, --only NAME,
--issue NUMBER, --full (re-read all closed issues), --force (rewrite
every synced field), --reconcile (link existing tasks), --watch SECONDS,
--json.
Exit codes: 0 success, 1 some items failed, 2 configuration error,
3 authentication error.
| Purpose | Application permission (client secret / federated) | Delegated (device code) |
|---|---|---|
| Read and write Planner | Tasks.ReadWrite.All |
Tasks.ReadWrite |
| Verify group membership | GroupMember.Read.All |
GroupMember.Read.All |
| Resolve users | User.Read.All |
User.ReadBasic.All |
| Upload attachments (optional) | Sites.ReadWrite.All |
Files.ReadWrite.All |
Git tokens need read access to issues, plus write access for planner-to-git:
- GitHub: a fine-grained token with Issues (read/write) and Metadata (read), or
github.tokenin Actions. For project boards, add theprojectscope (classic token) or the organisation Projects permission. - Gitea / Forgejo:
read:issue(orwrite:issue),read:repositoryandread:user. - GitLab:
read_api(orapifor writes).
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
ruff check . && ruff format --check . && mypy && pytestSee CONTRIBUTING.md and the changelog.
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.