Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.akua.dev/llms.txt

Use this file to discover all available pages before exploring further.

Akua’s GitHub integration connects your GitHub accounts and organizations to your workspace using a GitHub App. The app provides secure, scoped access to your repositories without storing personal access tokens. All workspace members can use connected installations for collaboration.

​
How it works

When you connect a GitHub account or organization, Akua requests permission to install the GitHub App. This creates a secure connection without requiring personal access tokens. You choose which repositories to make available: all repositories, selected repositories, or public repositories only. Once connected, all workspace members can:
  • Deploy applications from connected repositories.
  • Access repository contents for building and deployment.
  • View repository metadata and commit history.

​
Personal accounts and organizations

You can connect both personal GitHub accounts and GitHub organizations to your workspace. Personal accounts are useful for individual projects, side projects, open source contributions, and experimentation. Organizations enable team collaboration and access to shared repositories. This suits agencies connecting multiple client organizations, companies accessing internal tools, and consulting work managing different client repositories.

​
Multiple installations

Akua supports multiple GitHub App installations within a single workspace:
  • Add different team members’ personal accounts.
  • Connect various client or company organizations.
  • Combine personal and organizational repositories.
Once an installation is added to a workspace, all workspace members can use it. Any workspace member can deploy from those repositories, even if they don’t have direct GitHub access. This is by design for collaboration.

​
Security and permissions

The GitHub App maintains security through scoped permissions.
  • Repository contents: used for building and deployment.
  • Repository metadata: name, description, language, and structure.
  • Commit history: for deployment tracking and versioning.
  • Branch information: to understand repository structure.
  • Private repository contents (unless explicitly granted access).
  • User personal information: email, profile data, or private details.
  • Organization settings: billing, member management, or admin settings.
  • Other applications: other GitHub Apps or integrations.
  • Repository access: only repositories you explicitly grant.
  • Read-only by default: Akua cannot modify your code or settings.
  • Short-lived tokens: temporary access tokens for security.
  • Revocable: you can revoke access at any time.

​
Repository deployments

Once GitHub accounts are connected, you can deploy applications directly from repositories. Akua automatically detects your application type and build configuration for supported languages and frameworks, including Node.js, Python, Go, Ruby, Java, Rust, and PHP.

​
Private container images

If your GitHub Actions workflow builds and pushes images to GitHub Container Registry (GHCR) as a private repository, you need to configure registry credentials:
  1. Go to Settings → Registries in your workspace.
  2. Add GitHub Container Registry credentials with a PAT that has read:packages scope.
  3. Akua pulls your private images through its registry proxy automatically.
See private container registries → for details.

​
Best practices

  • Grant access only to necessary repositories.
  • Periodically review connected accounts and permissions.
  • Remove access for team members who leave the workspace.
Leaving a workspace does not automatically uninstall the GitHub App from your GitHub profile or organization. To remove the GitHub App installation, go to your GitHub settings and uninstall it manually.

​
Troubleshooting

Verify the repository is included in the GitHub App installation, the repository is not private unless explicitly granted, and the GitHub App has the necessary permissions. Try reconnecting the GitHub account if the issue persists.
Check that your repository has a supported language or framework, all dependencies are properly declared, and review build logs for specific error messages. Consider adding a Dockerfile for custom build requirements.
Verify you have access to the repository, the GitHub App installation is still active, and the repository has not been moved or deleted. Try refreshing the GitHub connection.

Private container registries

Pull private images from GHCR and other registries.

Workspaces

Workspace organization and roles.

Deployments

How applications are installed from repositories.

Security

How Akua protects credentials and access.