Avaza's native GitHub integration links commits, branches and pull requests to the Avaza task they belong to. Project managers see development progress on the task, and developers don't have to update two tools.

The integration is available on every Avaza plan. An Administrator connects it once for the whole account.

Set up the integration

You need the Administrator role in Avaza. In GitHub, you need permission to install GitHub Apps on the personal account or organisation that owns the repositories.

  1. Go to Settings › App Marketplace, select GitHub and click Connect.

  2. Click Grant Access to Avaza. If you aren't an Administrator, Avaza stops here with a message about permissions.

  3. On the GitHub app's Settings tab, click Connect to GitHub and sign in to GitHub. Install the GitHub app on your account or organisation, for all repositories or only the ones you choose.
    The account appears under Installed Apps. Click Install App to add another account or organisation.

  4. Click Add Repository, tick the repositories your team works in, and click Add.

  5. Optional: restrict a repository to projects. Click Edit next to it, tick the projects, and click Add.
    The Project Restrictions column shows how many projects each repository is limited to. No Project Restriction means every project can use it.

  6. Optional: set the branch name format under Auto-generated branch name format, and click Save (see below).

  7. Show the integration on tasks. In the App Marketplace, open Additional Options and switch on Display Task Integrations. Then tick the roles who can see the tab: Portfolio Manager, Project Manager, Project Collaborator (Team Member) and Project Collaborator (External Contact). Administrators always see it. Changes save straight away.

    Additional Options in the App Marketplace, with the Display Task Integrations switch, still Off

There are no webhooks to set up: once the GitHub app is installed, GitHub sends new activity to Avaza by itself.

To install the app on another account later, or to reconnect, sign in to GitHub with the same login that first connected. Otherwise you'll see "The current GitHub login does not match the login that is used to connect this integration".

Branch name format

Avaza suggests this name when someone creates a branch from a task. The default is :taskId:_:taskName:_:username::

  • :taskId: is the task's number;
  • :taskName: is the task title;
  • :username: is the person's first and last name, joined with a dash.

Spaces become underscores. For example, Sofia Alvarez creating a branch for task 60398, Design landing page, gets 60398_Design_landing_page_Sofia-Alvarez. She can edit it before creating the branch. A branch created from a task is linked to it straight away, so its name doesn't need the AZT- prefix described below.

Put the task ID, with the AZT- prefix, into GitHub. For example, AZT-60398. Avaza links:

  • a branch whose name contains the ID, when the branch is created on GitHub;
  • a commit whose message contains the ID, when it's pushed;
  • a pull request whose title contains the ID, when it's opened. Avaza then updates its status when it's closed, merged or reopened.

To find a task's ID, open the task's GitHub tab (see below) and click Help. It shows the Avaza Task ID, a suggested branch name, and the git commands to create that branch and to link a single commit.

If activity doesn't appear on the task, check these:

  • AZT- is in capitals and the number follows straight after it. Only the first task ID in a name, message or title counts.
  • The repository is added in Avaza, and the task's project is allowed to use it.
  • The activity happened after the repository was added. Earlier work isn't picked up.
  • The pull request had the ID in its title when it was opened. Adding it later doesn't link it: use Link Pull Request instead.

A branch that's deleted on GitHub disappears from the task.

Work with GitHub from a task

Open the task, click the plug icon (Task Integrations), then click GitHub. The first time, Avaza asks you to grant access and to connect your GitHub account.

The GitHub popup has three tabs, each with a count:

  • Pull Requests: title, repository, source and target branch, author, reviewer and status. New Pull Request creates one on GitHub and links it: check the suggested title, choose the repository and the source and target branches, add a description, and click Create Pull Request. Link Pull Request links an existing one.
  • Branches: each linked branch, with its linked commits listed under it. The copy icon copies the branch name. Create Branch creates a branch from a source branch and links it. Link Branch links an existing one.
  • Commits: title, date, repository, branch, author and the number of files. Link Commits links an existing commit: choose the repository, branch and commit.

Click a title to open it on GitHub. Unlink removes the link from the task and changes nothing on GitHub.

At the moment, only Administrators get the create and link buttons on the tab. People in the other roles you chose see the linked items and can unlink them. Anyone who works in the repository can still link work from GitHub with the task ID.

"No GitHub repository is available for this project." means no repository is allowed for the task's project. An Administrator can add one, or add the project to a repository's restrictions.

Disconnect

  • Your own GitHub account: in the task's GitHub popup, click Help, then Disconnect GitHub.
  • One GitHub account or organisation: on the app's Settings tab, click Remove next to it under Installed Apps. Remove next to a repository takes it out of Avaza.
  • The whole integration: on the Settings tab, click Disconnect from GitHub. This uninstalls the GitHub app from every installed account and disconnects the GitHub login the integration uses. Then click Disconnect on the GitHub app in the App Marketplace.