Integrating a project with a Git repository
Connect a project to a Git repository to save configurations there. By doing so, you can use your repository and the CI and CD tools of your choosing to automate pipelines on configurations in a project.
This is an experimental feature that is available for evaluation and testing purposes and might change without notice.
Pipelines and toolchains are customizable, so you can automate many actions between your Git repository and your project by using projects API methods or CLI commands. For example, you can create a pipeline to trigger an update in your project when configuration changes are merged to the main branch in your repository. For more information, see Automating projects actions in your Git repository.
Connecting a project to a Git repository works best with a new project that doesn't contain any configurations. If your project contains configurations, those configurations aren't saved to your repository. In a project, draft configurations can
be saved to any branch in your repository. However, you can validate and deploy draft configurations only after they are merged to the branch in your repository that manages your CD pipelines. You must also sync the updates from your repository
into your project by updating configurations before you can validate and deploy those configurations. You can automate this update by using the project.config.update API method or by
using the ibmcloud project config-update CLI command.
Before you begin
-
Make sure you have the Editor role on the IBM Cloud Projects service to manage Git repository integrations.
-
Save an access token as a secret to connect to your Git repository. The access token needs write access to the branches that you want to use and to create commits in your repository. The access token also needs the ability to list branches and read them.
-
Create a Secrets Manager service instance in your IBM Cloud account. To create a secret, you must have the Writer role or higher on the Secrets Manager service.
-
After you create your secret instance, make sure that you select Other secret type to add an arbitrary secret. For information about creating an arbitrary secret, see Creating arbitrary secrets in the UI. Your arbitrary secret must contain the access token for your Git repository.
-
Connecting a project to a Git repository
Connect your Git repository to your project. By doing so, configuration changes are saved to your repository, as opposed to the project JSON file. Because your project needs to save configurations to your repository, you must provide an access token to authenticate with the repository from your project.
Connecting a project to a Git repository works best with a new project that doesn't contain any configurations. If your project contains configurations, those configurations aren't saved to your repository.
- In the IBM Cloud console, click the Navigation menu icon
> Projects and select a project. - From the Manage tab, select Integrations.
- In the Git repository integration section, click Connect.
- From the Repository type menu, select the type of repository that you want to use to manage your configurations. Typically, this repository is the one you use to manage your pipelines and toolchains. You can select GitHub, GitLab, or GitHub Enterprise.
- Enter the URL to the repository.
- Optionally, specify a folder within the repository. Consider specifying a folder if you want to integrate your repository with multiple projects. Each project can have its own folder.
- Hover or click the access token field, then click the Secrets icon
to select the secret that contains your access token. - Click Save.
Next steps
Now that your Git repository is connected with your project, you're ready to customize pipelines and toolchains. To learn how to create a pipeline that automatically updates configurations in your project when changes are merged to your main branch, see Automating projects actions in your Git repository.