A run needs a repository to work in: it reads the code there, pushes a branch and opens a pull request. A project can have several repositories, for example a backend and a frontend; a task can then work on one, some or all of them.
Connecting, changing and removing repositories requires being an organization admin or the project's owner.
Connect a repository
Open the project, go to Settings → Repositories and click Connect Repository.
- Select your Git provider: GitHub, GitLab or Bitbucket.
- Connect in one of two ways:
- With your account (recommended). Click Authorize with GitHub (or GitLab, Bitbucket). You are sent to your git host to grant access and then come back. Pick the repository under Select a repository; private repositories are marked Private.
- With a token. Click Use a personal access token instead. Enter the Repository URL (the HTTPS address) and, for a private repository, a Personal Access Token. The wizard shows how to create a token for your provider. The token is stored encrypted and never shown again. A public repository needs no token.
- Branch: enter the Default branch (usually
main). If the project lives in a folder of the repository rather than its root, fill in Subdirectory (optional), for examplebackend/. - Review your settings and click Connect Repository.
The token needs permission to read and push code and to open pull requests: repo scope on GitHub, api scope on GitLab, or an app password with repository read/write access on Bitbucket.
The repository card
Each connected repository shows its provider, URL and default branch, with these actions:
- Default branch - click Change to set another branch. The connection is checked again after the change. Tasks work on the default branch unless you choose other branches.
- Check connection - checks that CodeLynq can reach the repository, read it and push to it, and shows the result of each check. If the repository's own default branch differs from the one set here, you can switch with one click (Use followed by the branch name).
- Use connected account - switches a repository connected with a token over to your authorized account.
- Remove - stops CodeLynq from working with this repository. Nothing is deleted in your git host, and no tasks are removed.
- Maintained branches - for repositories that keep one branch per version or release. See Maintained branches.
- CI webhook - see below.
Set up the CI webhook
The CI webhook lets your git host tell CodeLynq when CI fails, when a reviewer requests changes and when a pull request is merged. It is needed for Auto-iterate until green, for automatic deployments on merge, and for tasks to move to Done by themselves once their pull requests are merged. It works for GitHub, GitLab and Bitbucket.
- On the repository card, under CI webhook, copy the Webhook URL. It is specific to the repository's git host.
- Think of a long random secret, enter it under Webhook secret and click Save. The badge changes from Not configured to Configured.
- Add the webhook in your git host:
- GitHub: the repository's Settings → Webhooks → add a webhook. Payload URL: the webhook URL. Content type:
application/json. Secret: the same secret. Events: choose the individual events Check runs, Check suites, Workflow runs, Pull request reviews and Pull requests. - GitLab: the project's Settings → Webhooks → add a webhook. URL: the webhook URL. Secret token: the same secret. Trigger: Merge request events and Pipeline events.
- Bitbucket: Repository settings → Webhooks → add a webhook. URL: the webhook URL. Secret: the same secret. Triggers: under Pull request Merged and Changes request created, under Repository Build status updated.
- GitHub: the repository's Settings → Webhooks → add a webhook. Payload URL: the webhook URL. Content type:
- Save the webhook.
To stop using the webhook, click Clear next to the secret.
When something does not work
- The connection check fails on push. The token or account can read but not write. Create a token with write access and connect again, or click Use connected account.
- Runs fail right at the start. Click Check connection first. It shows which part fails - for example an expired token, or a default branch that no longer exists.
- A repository is missing from the list after authorizing. Make sure the account you authorized has access to it, or connect it with a token instead.