Skip to content

Prepare Spoke Integrations (Azure DevOps and GitHub)

A spoke can create an Azure DevOps repository and service connection, or a GitHub repository with federated credentials, for its team (Spoke integrations). Both are optional. If no spoke file has an azdo block or an enabled GitHub extension, skip this page.

Do the preparation once per organization, before the first spoke that uses the integration.

Azure DevOps

The identity that runs the spoke pipeline must be allowed to create repositories and service connections in the projects of the teams.

Pipeline settings

  1. Open the project that holds the spoke deployment pipeline, Project settings, Pipelines, Settings.
  2. Switch off:
    • Limit job authorization scope to current project for non-release pipelines
    • Protect access to repositories in YAML pipelines
  3. If the options are greyed out, switch them off in the organization settings first. Then the project settings can be changed.

Permissions

The build service account (Project Collection Build Service) needs permissions on the projects where repositories and service connections are created. Grant them at project level for each project, or once at organization level with a script.

Project level. In every project (new and existing):

  • Project settings, Repositories, Security, Project Collection Build Service: set Advanced Security: manage settings and Create repository to Allow.
  • Service connections, the menu of a service connection, Security, Add, Project Collection Build Service: role Creator.

Organization level. Granular permissions cannot be set at organization level in the web interface. The spoke canvas code repository includes a script, Scripts\Configure-AzureDevOpsPermissions.ps1. It creates a group in Azure DevOps, gives it the permissions above, and adds the build service account to the group:

.\Scripts\Configure-AzureDevOpsPermissions.ps1 -organization_name <organization>

Run it once with an account that is allowed to manage permissions in the organization.

Federated credentials

With useFederatedCredentials: true the service connection uses workload identity federation. The spoke deployment creates the federated credential on the app registration of the spoke service principal, so you only need the spoke identity permission to manage applications (Prepare identity).

GitHub

GitHub App

The spoke deployment manages repositories through a GitHub App. Create one, or reuse the app of the platform workflows (Prepare GitHub):

  1. Create or choose a GitHub App installed in the organization (GitHub.com or GitHub Enterprise Server). Give it a name and description that say it is used by the platform workflows.
  2. Store the app ID as the organization variable cloud_platform_gh_app_id and the private key as the organization secret cloud_platform_gh_app_private_key.
  3. Limit access to these two to the configuration repositories only.
  4. The workflows create a short-lived installation token with actions/create-github-app-token and pass it to Terraform as TF_VAR_github_token.

The app needs these permissions for the extension:

Level Permission
Repository Metadata: Read. Actions, Actions variables, Administration, Code, Environments, Repository hooks, Secrets, Workflows: Read and Write.
Organization (when repositories are created in an organization) Actions variables: Read. Organization hooks: Read. Organization secrets: Read. Administration: Read and Write.
Repository access Only the configuration repositories for the variable and the secret above

More than the platform workflows need

Prepare GitHub lists a smaller set for the platform workflows. The extension creates repositories, environments, secrets and hooks, so it needs the larger set. If you share one app, give it the larger set. If you want the smaller set on the platform app, create a second app for the extension.

If the spoke's repository is in a different organization than the platform, the app must also be installed there (the spoke deployment has a separate installation ID input for the workload organization).

GitHub Enterprise Server

For GitHub Enterprise, set the instance in the common settings, or per spoke in the spoke file (Spoke common settings):

locals {
  ghinfo = {
    OrganizationName = "<organization>"
    OidcIssuer       = "https://<github host>/_services/token"
    BaseUrl          = "https://<github host>/"
  }
}

For GitHub.com, the issuer is https://token.actions.githubusercontent.com and the base URL https://github.com/.

The spoke deployment also downloads Terraform modules from repositories on GitHub Enterprise. The agent must be able to authenticate for that: Module source access.

Check

  • [ ] The organization variable and secret exist and are limited to the configuration repositories
  • [ ] The app is installed with the permissions above
  • [ ] ghinfo (or the per-spoke values) point to the right instance and issuer
  • [ ] A test spoke with the extension creates the repository, and a workflow in it signs in (Use it in a workflow)