Connecting to GitLab
If you authorize Appcircle to access your repositories on GitLab, you can select the repository that you want to connect in the next screen.
After you click on GitLab, the following screen will appear. This will let you choose between selecting a repository that you are already authorized to do with Appcircle or asking your consent about authorizing more repositories.
When you successfully authorize your account, the following screen will appear to let you select one for connection:
After the connection is successful, you can view your newly created profile and start building!
Connecting to GitLab Cloud Repository
To connect to a GitLab Cloud repository using either OAuth or Personal Access Token,
- OAuth Connection
Clicking on Get Repositories from GitLab Cloud for the first time will require application access to Appcircle, and this access will require these permissions in order to work properly.
- PAT (Personal Access Token) Connection
Clicking on Connect to a GitLab server, which can be selected to connect to self-hosted and PAT connections, will require a token. Generating a PAT for Appcircle will require a list of permissions down below.
OAuth Permissions for GitLab Integration
The following table details the OAuth permissions required for Appcircle to connect with GitLab. These permissions grant read access to projects, repositories, pull requests, and webhooks, ensuring proper functionality when integrating with GitLab via OAuth.
| Scope | Description |
|---|---|
| api | Grants complete read and write access to the scoped project API, including the container registry, the dependency proxy, and the package registry. |
| read_api | Grants read access to the scoped project API, including the package registry. |
| read_user | Grants read-only access to the authenticated user’s profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users. |
| read_repository | Grants read-only access to repositories on private projects using Git-over-HTTP (not using the API). |
| Grants read-only access to the user’s primary email address using OpenID Connect. |
Connecting to GitLab Self Hosted Repository
The overall process is similar to a private repository connection through SSH, but Appcircle allows you to directly connect through GitLab Self Hosted URL.
GitLab's version must be 13.12.9 or higher.
First, select GitLab and then Connect to a Self-Managed GitLab Instance through the menu:
Fill the relevant information about your GitLab self-hosted module. If you are not sure what those are, contact your system administrator.
Outbound Requests
When you connect to a GitLab repository by creating a profile on Appcircle, Appcircle tries to create webhooks on the GitLab repository.
If your Appcircle server has a local IP address like 10.10.140.20, you may get an error while connecting to the repository.
To solve this issue, the IP or the Appcircle API subdomain name should be allowed for outbound requests on the GitLab admin panel.
You can follow the steps below to update outbound requests:
- You must get access to the Admin Area of the GitLab server.
- Expand the "Settings" button at the bottom left.
- Click on the "Network" button to access network settings.
- Expand the "Outbound" requests.
- Add the IP address or the
apisubdomain of the Appcircle server.
For example, if you are accessing to the Appcircle server dashboard via
my.appcircle.spacetech.com
then, for default server configuration, the api domain should be
api.appcircle.spacetech.com
Connection Notice
For Appcircle to connect to the Self Hosted GitLab Instance, your connection must be reachable over the network.
Is your self-hosted GitLab instance under enterprise firewall? Learn which IP addresses and ports Appcircle uses to function under the whitelist documentation:
Accessing Repositories in Internal Networks (Firewalls)
Token Creation
GitLab has two kinds of token at their Self Hosted instance:
Both works to connect your repository through Appcircle. That being said, Project Access Token is used to authorize a single project(repository) and Personal Access Token is used to authorize every repository the user has access to.
Appcircle needs admin permission to function properly. The admin permission is needed to create relevant WebHooks automatically.
Check Token
You can follow the steps below to check if your token is valid.
- Open the terminal and issue the following command
curl "http://YOUR_GITLAB_HOST/api/v4/projects?private_token=YOUR_TOKEN"
Above command should print out your projects. If you don't see an output, please check your token and GitLab address.
Please also make sure that the output doesn't show any reference to localhost. If you see localhost, you need to configure GitLab and put the correct address of your GitLab instance.
Webhook SSL Verification
When integrating GitLab with your self-hosted Appcircle server using HTTPS, webhooks are sent securely over an encrypted connection (HTTPS). To establish this connection, GitLab must trust the SSL certificate of your Appcircle server. This requires the GitLab to trust the SSL certificate of the Appcircle server.
If you encounter a "self-signed certificate in certificate chain" error during integration, you have two options to resolve the issue:
1. Trust the SSL Certificate (recommended)
To establish a secure connection between your self-hosted Appcircle server and the GitLab server, you need to trust either the SSL certificate of the Appcircle server or the issuer certificate of the server's certificate in your GitLab configuration.
For detailed instructions on how to install custom public certificates and configure trust in GitLab, refer to GitLab's documentation: Install Certificates.
2. Disable the SSL verification (not recommended)
Alternatively, you can choose to disable SSL verification for your AppCircle server's webhook connection in GitLab. While this means that GitLab will not attempt to validate the certificate, it is important to note that webhooks will still be sent over an encrypted HTTPS connection but in an insecure way.
This approach can create security vulnerabilities such as man-in-the-middle (MITM) attacks.
Take the following steps to disable the SSL verification of the webhook:
- Go to the Git repository that you have connected to the Appcircle.
- Open the webhook settings of that Git repository.
- Click on the Edit button next to the webhook.
- Scroll down to see the SSL verification setting.
- Deselect the Enable SSL verification checkbox.
Need help?
Get help from Appcircle's support team, or see how others are using Appcircle by joining our Slack Channel.
