With the GitHub integration you see pull requests, GitHub Actions runs, environments and commits right on your tasks in FeatValue. Your clients learn in plain words whether their change is in progress, on staging for testing or live.
What the GitHub integration is for
Software companies and web agencies keep getting the same question: “Is this online yet?” With the integration, FeatValue answers it on the task:
- Branches, commits and pull requests with the task ID appear on the matching task.
- GitHub Actions runs and deployments show whether the change has been tested and which environment it has reached.
- FeatValue writes important steps as comments to the task history.
- For each project you decide what your clients see of it.
- You re-run failed runs right from FeatValue.
For an overview, see the page about the GitHub integration.
Requirements
- a FeatValue account for your company with at least one client and project (see Creating projects)
- an account or organization on github.com
- the right to install apps on this account or organization. In organizations, these are the owners. Other members can request the installation, and an owner then approves it in GitHub.
Connect GitHub
-
Open the app
Click
Apps in the left sidebar, choose
GitHub and click
Install (see
Connecting apps).
-
Connect with GitHub
Click
Connect with GitHub. A short note lists the permissions the app requests (see
GitHub App permissions). Click
Continue to GitHub.
-
Sign in to GitHub
Sign in to GitHub and authorize the FeatValue app.
-
Install the app or choose organizations
If the app is not installed anywhere yet, GitHub opens the installation right away: choose your account or an organization, then All repositories or the repositories FeatValue may see under Only select repositories, and click Install. If the app is already installed in several organizations, you choose the organizations to connect on a selection page. You then return to FeatValue.
Only grant access to the repositories you want to link to FeatValue projects. You can change the selection at any time in GitHub for the FeatValue app: on a personal account under Settings › Applications › Installed GitHub Apps, in an organization under Organization settings › Third-party Access › GitHub Apps.
GitHub App permissions
The FeatValue app requests these permissions from GitHub:
- Metadata: read: names and basic data of the repositories you grant access to
- Contents: read: commits and branch comparisons
- Pull requests: read: pull requests with title, status and branch
- Actions: read & write: read GitHub Actions runs, write only to re-run a run
- Deployments: read: deployments and environments
The GitHub App requests read access to repository contents (Contents: read) because GitHub only provides commits and branch comparisons with this permission. FeatValue uses it to read commit data (message, author, time) and branch comparisons only, never your source code, and it does not store any files.
Link a repository to a project
Each repository belongs to exactly one FeatValue project. Only linked repositories reach FeatValue.
-
Open Link repositories
Open
Settings › Company › Integrations & apps and choose
GitHub (see
Connected apps). The page is called
Link repositories.
-
Find the repository
The repositories you granted the app access to are listed under Repositories in GitHub. Use Search repository to narrow the list.
-
Choose a project and link
Next to the repository, choose the FeatValue project and click Link. FeatValue catches up on the last few days. You do not need to create a webhook; events arrive through the FeatValue app.
All links are listed under Linked repositories. The column Updates shows Instantly via webhook. Use Change to pick a different project, and Unlink to remove the link.
Several organizations in one connection
One FeatValue connection can use the app from every GitHub organization and account where it is installed and that you have access to when connecting, for example your own organization and your clients' organizations. The list on the Link repositories page is grouped by organization.
-
Add an organization
Open Settings › GitHub (the Link repositories page) and click Add organization.
-
Choose the organization
Choose an organization where the app is already installed. If it is missing, click Install in another organization and install the app there in GitHub.
-
Link repositories
The organization's repositories appear in the list. Link them as described above.
Several FeatValue companies may use the same installation, for example your agency and your client with their own FeatValue account.
Using the task ID correctly
Every task in FeatValue has an ID, for example abc123-4. You find it on the task. Put this ID in one of these places:
| Where |
Example |
| Branch name |
abc123-4-contact-form |
| Commit message |
abc123-4 Make phone number required |
| Title or description of the pull request |
Contact form: make phone number required (abc123-4) |
- Upper and lower case do not matter, and a leading
# is allowed.
- If the ID is in the branch name, only the commits that exist solely on this branch count. Commits from the default branch that come along when branching off do not appear on the task.
- Commits on other branches only appear if the ID is in their commit message.
- The ID only applies within the linked project. FeatValue never assigns repositories that are linked to another project or not linked at all.
- GitHub Actions runs and deployments belong to the task if they run for one of its branches, commits or pull requests.
What appears on the task
The task shows the Development section with one compact line, for example: PR #12 merged · Workflow passed · Deployed to Staging. Click Show details to expand:
- Workflows: the GitHub Actions runs, for example CI #57, with their jobs and status
- Environments from your deployments with a link to open them, for example Staging and Production
- Pull requests, Branches and Commits
What appears in the project
In the project, the Development section shows the environments with their latest deployment and the latest run on the default branch. Click Show all workflow runs to see the Latest workflow runs. This is also where you find the project's Settings.
What do clients see?
In the Settings of the Development section in the project, choose under What do clients see?:
| Setting |
Your client sees |
| Nothing |
no information from GitHub |
| Simple status |
one sentence without technical terms: In progress, Rolled out to Staging with the link test it here, or Live with the link take a look |
| Details |
the sections you tick under Details for clients: commits, branches, pull requests, workflows, environments and history comments |
People in your company who may edit the project can change this setting. How your client then tests and approves is explained under Review and acceptance.
FeatValue writes important steps as comments to the task history. Under Activity comments on the task you choose for each project which events create a comment:
- Pull request merged
- Workflow passed
- Workflow failed (with failed jobs)
- Deployed to environment
Deselected events still update the status on the task but no longer create a comment. Whether your client sees the comments depends on the setting under What do clients see?.
Re-run failed runs
Starter
When a GitHub Actions run fails or is cancelled, you re-run it right in FeatValue. For a failed run, GitHub re-runs only the failed jobs; for a cancelled run, the whole run. This is available from the Starter plan (see Plans).
-
Allow workflows
In the project, open the Settings of the Development section. Under Re-run workflows from FeatValue you find the workflows for which GitHub has reported a failed run so far, for example CI. Tick the workflows that should appear in FeatValue and click Save.
-
For clients too
If your client should be able to re-run the selected workflows, tick Clients may re-run the selected workflows too.
-
Re-run
A failed run of an allowed workflow appears with the button Re-run. After the click, FeatValue shows Re-run started, and you follow the rest on the run.
Security
- Only granted and linked repositories: The FeatValue app only sees the repositories you grant access to during installation. FeatValue only assigns task IDs in repositories you have linked to a project, and only within that project.
- No source code: FeatValue only reads commit data and branch comparisons, never your source code, and does not store any files from your repository. This is why the app requests Contents: read (see GitHub App permissions).
- Verified webhooks: GitHub signs every delivery to FeatValue. FeatValue only accepts calls with a valid signature.
- Few write permissions: The only thing the app may change is re-running GitHub Actions runs, and only for the workflows you have allowed.
- Unlink at any time: Unlink removes a link. If you uninstall the app in GitHub, FeatValue automatically unlinks the repositories of that organization.
Disconnect and uninstall the app
If you disconnect GitHub in FeatValue, FeatValue only deletes the repository links. Everything already shown on tasks stays. The app remains installed in GitHub until you uninstall it there:
- Organization: In GitHub, open Organization settings › Third-party Access › GitHub Apps, click Configure next to the FeatValue app and then Uninstall at the very bottom.
- Personal account: Open Settings › Applications › Installed GitHub Apps, click Configure next to the FeatValue app and then Uninstall.
After the app is uninstalled, FeatValue automatically unlinks the repositories of that organization.
Troubleshooting
My repository is missing from the list
FeatValue only shows repositories you granted the app access to. In GitHub, open Settings › Applications › Installed GitHub Apps, choose the FeatValue app and add the repository under Repository access. For an organization, you find this in the organization's settings.
The installation is waiting for approval
If you are not an owner of the organization, GitHub sends the installation request to the owners. Once an owner approves it, connect GitHub in FeatValue again.
Nothing appears on the task
- Is the repository linked to the project the task belongs to?
- Is the full task ID in the branch name, the commit message or the pull request?
- If a delivery from GitHub gets lost, FeatValue catches up within 10 minutes.
A run cannot be re-run
Re-running is available from the Starter plan. The workflow also has to be allowed in the project settings, and the run must have failed or been cancelled. If Could not be re-run appears, check in GitHub whether the app is still installed and may see the repository.
An organization is missing from the selection
FeatValue only shows organizations where the app is installed and that your GitHub account has access to. Install the app with Install in another organization or ask an owner of the organization to do it.