Resources

Connecting GitHub to WayFinder to include source control and CICD pipeline data.

In order to get Lead Time, Deployment Frequency and Change Failure Rate metrics, you need to add source control and CICD Pipeline data sources for your product in WayFinder.

Connecting your GitHub repositories and GitHub Actions workflows can provide this data. There are two items you will need:

• GitHub fine-grained Personal Access Token (PAT)
• CICD pipeline production deployment stage names

Least Privilege and Least Data

We aim to ingest only the minimum data possible to provide you with metrics. For GitHub you remain in control of this by providing WayFinder with a GitHub fine-grained PAT. By using a fine-grained PAT you define both the accessible repositories and the access permissions for those repositories.

This fine-grained PAT can be used for connecting both Source Control and CICD Pipeline data sources to WayFinder. If you have previously created a PAT for WayFinder can skip this section and reuse the token you previously created. If you no longer have a copy of that token, just create a new one but do not delete or regenerate the previous token or the other data source will stop working.

Creating a Fine-Grained PAT

Follow the instructions from GitHub for creating-a-fine-grained-personal-access-token.

Resource Owner

Select the most appropriate resource owner (the owner of the repositories). If the resource owner is an organisation, make sure to get the PAT approved before using it.

Which repositories should I include?

Only include access to the repositories that are relevant to the product you have registered in WayFinder. Metrics for the product are aggregated in WayFinder across all the repositories accessible to the PAT.

What permissions are needed?

We aim to use least privilege and therefore only the following permissions are needed to be added to the fine-grained PAT:

• Repository.metadata:read
• Repository.actions.read
• Repository.pull_requests:read

Please note that WayFinder ignores public repositories in you GitHub account, if you need a public repository included in your project please contact us at contact@wayfinder.ninja

Typically in a CICD pipeline there are multiple stages, for example: 'build', 'deploy-non-prod', 'deploy-prod'. For calculating the metrics we need to know the production deployment stage names. In your GitHub Actions workflow yaml template you may have a section like:

```

jobs:
deploy-prod:
name: “Deploy to prod env”
runs-on: ubuntu-latest
steps:
- run: echo “Deploying to Prod environment”
- run: ...

```

In GitHub workflows, the job name is the stage name.

• If, as per the example above, you have defined name: for the job then this is the production deployment stage name, e.g. “Deploy to prod env”.
• However if you have not defined a name: for the job then the production deployment stage name is the job identifier, e.g. “deploy-prod”

In WayFinder we have a grouping called a “Product”. When organisations are developing a product or service there are typically multiple repositories and multiple CICD pipelines.

For example there may be a frontend repository and a backend repository and each may have it’s own CICD pipeline for deployment. The metrics for the "Product" are aggregated to include all the associated repositories and their CICD pipelines.