Asana and GitHub: how to link commits to tasks

Asana has its own GitHub app, and for plenty of teams it is the right answer. It attaches pull requests and branches to tasks and can move tasks along when a pull request merges. If that covers what you need, use it.

Astogi solves a narrower problem. Put a task number in a commit message, push, and the commit lands as a comment on that Asana task. No pull request has to exist yet, and nobody has to paste a task link into a branch name. This guide covers how it works and where it differs.

Asana's GitHub app or Astogi?

They are not mutually exclusive, but they work differently.

	Asana's GitHub app	Astogi commit tracking
Links by	Pasting a task URL or ID into a pull request, branch or commit	A task number in the commit message
Shows on the task	Pull requests and branches	The commit message, author and a link to the commit
Needs	An Asana and GitHub connection per user	Task numbering on the Asana project
Also works with Bitbucket	No	Yes

The short task number is the point. A reference like #AB-0042 is quick to type, easy to read in git log, and unambiguous. It comes from automatic task numbering, which writes the number into the task name itself.

How it works

When you push to a repository Astogi is tracking, GitHub sends a webhook. Astogi reads the head commit of that push, checks the Asana projects linked to the repository, and looks for tasks whose number appears in the commit message. Each match gets a comment on the Asana task with the commit message, the author's name and a link to the commit on GitHub.

One comment is posted per push, built from the head commit, not one per commit. Pushing five commits at once gives the task one readable update. That also means the task number has to be in the message of the last commit in the push for it to be picked up, so a push of several commits should put the reference on the final one or on all of them.

Setting it up

1. Turn on automatic task numbering for the Asana project. Astogi matches commits against task numbers, and a task only has one once numbering is running.
2. Invite the numbering user to the Asana project.
3. In Astogi, open the Repositories section of your dashboard.
4. Connect your GitHub account. You are sent to GitHub to authorise access, then back to Astogi.
5. Pick the repository to track and link it to the relevant Asana project or projects.
6. Push a commit whose message contains a task number and check the task in Asana.

Authorising Astogi asks GitHub for repository access and permission to manage repository webhooks, which is how it can create the webhook for you. It reads the push payload GitHub sends. It does not open pull requests or change your code.

Commit message syntax

There is no special keyword. Astogi looks for the task number as plain text anywhere in the commit message.

Numbers are built from settings on the project: a start character such as #, a short project code such as AB, a divider such as -, and the number with optional zero padding. A task might read #AB-0042: Fix the login redirect in Asana.

git commit -m "#AB-0042 handle expired refresh tokens"
git commit -m "Handle expired refresh tokens (#AB-0042)"
git commit -m "#AB-0042 #AB-0051 rework the token refresh path"

The last one posts to both tasks.

Two details catch people out. Astogi ignores a match when the next character is a digit, so #AB-4 never hits #AB-42. And if your project pads numbers, #AB-42 does not match #AB-0042, so nothing is posted. Copy the number from the task name instead of typing it from memory.

Branches, pull requests and squash merges

Matching works on push events, so branch names do not matter. A commit on a feature branch posts to the task the same way a commit on main does, which means progress is visible while work is still in flight.

Squash merges need a thought. The squash commit message is what lands on the target branch, and that is what Astogi reads. If your individual commits carried the number but the squash message does not, nothing is posted. Putting the number in the pull request title fixes it, since GitHub seeds the squash message from the title by default.

Pull request status is not tracked. Astogi reports commits, not whether a pull request is open, approved or merged.

Multiple repositories and monorepos

A repository can be linked to several Asana projects, and a project can have several repositories. A monorepo works without special handling: link it to each relevant project and every commit reaches the task it names. A task that spans three repositories collects commits from all three in one thread.

GitHub and Bitbucket can be connected side by side, including to the same project. See the Asana and Bitbucket guide if part of your team is on Bitbucket.

Troubleshooting

Nothing appeared on the task. Check the task name has a number. No number means numbering is not running on that project, and tasks created before numbering was switched on do not get one retroactively.

The number does not match exactly. Zero padding is the usual cause. #AB-42 and #AB-0042 are different strings.

Only the last commit in a push is checked. If the reference sits in an earlier commit of a multi-commit push, add it to the final commit message too.

The repository is not linked to that project. Matching only covers projects the repository is connected to. Check the link in the Repositories section.

The Astogi user was removed from the Asana project. Comments are posted as that user, so removing it stops everything. It is a common reason a setup that worked for months suddenly goes quiet.

The webhook is not firing. In GitHub, open the repository settings, then Webhooks, and look at the recent deliveries. No deliveries means the webhook is missing, and reconnecting the repository recreates it.

Frequently asked questions

Does this work with private repositories? Yes. Astogi works from webhooks rather than reading your code, and private repositories send webhooks like public ones.

Does it work with GitHub organisations? Yes, repositories in organisations you have access to can be listed and tracked. If an organisation restricts third-party OAuth apps, an owner has to approve Astogi first.

Do I have to use task numbering? Yes. It is what creates the numbers commits are matched against.

Is GitHub Enterprise Server supported? Astogi connects to GitHub.com. If you are self-hosted, tell us on the custom integration page.

Does it post pull request status? No, commits only.

Next steps

The Git commit tracking integration page has the feature detail, and task numbering is the companion you need alongside it. Using a different provider, or need something this does not cover? Tell us on the custom integration page.

Back to all guides