Set Up the Service

Like other Oracle Cloud services, you must create an instance of DevCS before you can start using it. You can create only one instance in an identity domain. After creating the instance, set up connections to Compute and Object Storage services on Oracle Cloud Infrastructure (OCI) or Oracle Cloud Infrastructure Classic (OCI Classic).

Create the DevCS Instance

You can create only one DevCS instance in an Oracle Cloud account. Before you attempt to create an instance make sure there's no existing DevCS instance in your account.

1. In a web browser, go to https://cloud.oracle.com/sign-in.
   To view the list of supported browsers, see https://docs.cloud.oracle.com/iaas/Content/GSG/Tasks/signingin.htm#supported_browsers.
2. On the Sign-In page, in Account, enter your account name, and click Next.
3. On the Oracle Cloud Account sign-in page, enter your Oracle Cloud account credentials, and click Sign In.
   The Oracle Cloud Console, also called as the OCI Console, opens.
4. On the OCI Console, click Navigation Bar in the top-left corner.
5. Under More Oracle Cloud Services, select Platform Services, and then select Developer.
6. In the Instances tab, click Create Instance.
7. On the Create New Instance page, in Instance enter a unique name. In Description, enter a description.
   The name helps you to identify the service instance.
8. Click Next.
9. On the Service Details page, click Next.
10. On the Confirmation page, click Create.

Once the service instance is created, you can open the service console by clicking Action , and then selecting Access Service Instance.

The DevCS Organization page opens. Click the OCI Credentials link or the OCI Account tab to configure OCI connections before you create a project.

Connect to OCI or OCI Classic

You need to connect to the Oracle Cloud Infrastructure Compute (OCI Compute) or Oracle Cloud Infrastructure Compute Classic (OCI Compute Classic) because they provide the virtual machines (VMs) on which DevCS runs its builds.

You need to connect to Oracle Cloud Infrastructure Object Storage (OCI Object Storage) or Oracle Cloud Infrastructure Object Storage Classic (OCI Object Storage Classic) because they are used to store build and Maven artifacts for DevCS projects. Note that this feature is not available to DevCS users in the Traditional identity domain, who run builds using shared build executors, not virtual machines (VMs).

If you're an OCI user, set up connections to OCI Compute and OCI Object Storage. DevCS runs its builds on OCI Compute VMs, and stores build and Maven artifacts on the OCI Object Storage buckets.

If you're an OCI Classic user, set up connections to OCI Compute Classic and OCI Object Storage Classic. DevCS runs its builds on OCI Compute Classic VMs, and stores build and Maven artifacts on the OCI Object Storage Classic containers.

Set Up the OCI Connection

Before you set up the connections, set up your OCI account to host DevCS resources. They allow DevCS to manage necessary resources, such as VMs for your builds and storage buckets for your project data.

To set up the OCI account, open the OCI console and create a compartment, a group and a user to access the compartment, and a policy that defines access to the compartment.

You can use the root compartment and the tenancy user that was created when the OCI account was created, but it's recommended to create a dedicated compartment to host DevCS resources. This allows you to organize DevCS resources better as they aren't mixed with the other resources of your tenancy. You can also restrict users and control read-write access to the compartment without affecting other resources. To learn more about compartments, see Understanding Compartments.

After setting up your OCI account, share the compartment's and the created user's details with the DevCS Organization Administrator to set up the OCI connection in DevCS.

Set Up the OCI Account

1. On the OCI Console, click in the top-left corner.
2. Under Governance and Administration, select Identity, and then select Compartments.
3. On the Compartments page, create a compartment to host DevCS resources.
   1. To create the compartment in the tenancy (root compartment), click Create Compartment.
   2. In the Create Compartment dialog box, fill in the fields, and click Create Compartment.

      Here's an example:

      
   To learn more about compartments, see Working with Compartments.
4. Create a user to access the DevCS compartment.
   1. In the left navigation bar, under Governance and Administration, go to Identity and click Users.
   2. Click Create User.
   3. In the Create User dialog box, fill in the fields, and click Create.

      Here's an example:

      
   To learn more about OCI users, see Working with Users.
5. On your computer, generate a private-public key pair in the PEM format.
   To find out how to generate a private-public key pair in the PEM format, see How to Generate an API Signing Key.

   Here's an example of private-public key files on a Windows computer:

   
6. Upload the public key to the user's details page.
   1. Open the public key file in a text editor and copy its contents.
   2. In the left navigation bar of the OCI dashboard, click under Governance and Administration, go to Identity and click Users.
   3. Click the user's name created in Step 3.
   4. In the User Details page, click Add Public Key.

      Here's an example:

      
   5. In the Add Public Key dialog box, paste the contents of the public key file, then click Add.
   To learn more about uploading keys, see How to Upload the Public Key.
7. On the Groups page, create a group for the user who can access the DevCS compartment and add the user to the group.
   1. In the left navigation bar, under Governance and Administration, go to Identity and click Groups.
   2. Click Create Group.
   3. In the Create Group dialog, fill in the fields and click Submit.

      Here's an example:

      
   4. On the Groups page, click the group's name.
   5. On the Group Details page, click Add User to Group.
   6. In the Add User to Group dialog box, select the user created in Step 3, and click Add.

      Here's an example:

      
   To learn more about groups, see Working with Groups.
8. In the root compartment, not the DevCS compartment, create a policy to allow the group created in step 6 to access the DevCS compartment.
   1. In the left navigation bar, under Governance and Administration, go to Identity and click Policies.
   2. On the left side of the Policies page, from the Compartment list, select the root compartment.
   3. Click Create Policy.
   4. In Name and Description, enter a unique name and a description.
   5. In Policy Statements, add these statements.
      • allow group <group-name> to manage all-resources in compartment <compartment-name>

        This grants all permissions to the DevCS group users to manage all resources within the DevCS compartment.

      • allow group <group-name> to read all-resources in tenancy

        This grants read permissions to the DevCS group so that its users can read—but not use, create or modify—all resources inside and outside the DevCS compartment. The group users can't use, create, or modify the resources. This statement is optional.

      Here's an example:

      
   6. Click Create.
   To learn more about policies, see Working with Policies.

Get the Required OCI Input Values

Every Oracle Cloud Infrastructure resource has an Oracle-assigned unique ID called an Oracle Cloud Identifier (OCID). To connect to OCI, you need the account's tenancy OCID, home region, the compartment's OCID that hosts DevCS resources, and the OCID and fingerprint of the user who can access the DevCS compartment. To connect to OCI Object Storage, you need the Storage namespace. You can get these values from the OCI Console pages.

This table describes how to get the OCI input values required for the connection.

To get these values ...	Do this:
Tenancy OCID, Home Region, and Storage Namespace	On the OCI console, from the left navigation bar, select Administration > Tenancy Details. The Tenancy Information tab displays the tenancy OCID in OCID, home region in Home Region, and the storage namespace in Object Storage Namespace. Here's an example: Description of the illustration oci_tenancyinformation.png
User OCID and Fingerprint	On the OCI console, from the left navigation bar, under Governance and Administration, select Identity > Users. The User Information tab displays the user OCID in OCID. Click the Copy link to copy it to the clipboard. Here's an example of devcs.user: Description of the illustration oci_userinformation.png To get the fingerprint of the public key associated with your OCI account, scroll down to the API Keys section and copy the fingerprint value. Description of the illustration oci_apikeys.png
Compartment OCID	On the OCI console, from the left navigation bar, select Identity > Compartments. The Compartments list displays the compartments with the compartment OCID in the OCID field. Click the Copy link to copy it to the clipboard. Here's an example: Description of the illustration oci_compartments.png

Set Up the OCI Connection in DevCS

To connect to OCI, get the DevCS compartment's details, user details, and the required OCID values. Then, create an OCI connection from DevCS. If you're not the OCI administrator, get the details from the OCI administrator.

1. In the navigation bar, click Organization .
2. Click the OCI Account tab.
3. Click Connect.
   
4. In Account Type, select OCI.
5. In Tenancy OCID, enter the tenancy's OCID copied from the Tenancy Details page.
6. In User OCID, enter the OCID of the user who can access the DevCS compartment.
7. In Home Region, select the home region of the OCI account.
8. In Private Key, enter the private key of the user who can access the DevCS compartment.
   The private key file was generated and saved on your computer when you created the private-public key pair in the PEM format. See Step 4 in Set Up the OCI Account.
9. In Passphrase, enter the passphrase used to encrypt the private key. If no passphrase was used, leave the field empty.
10. In Fingerprint, enter the fingerprint value of the private-public key pair.
11. In Compartment OCID, enter the compartment's OCID copied from the Compartments page.
12. In Storage Namespace, enter the storage namespace copied from the Tenancy Details page.
13. To agree to terms and conditions, select the terms and conditions check box.
14. To validate the connection details, click Validate.
15. After validating the connection details, click Save.

Here's an example of an OCI Account tab filed with required OCI details.

Set Up the OCI Classic Connection

To connect to OCI Classic, you need the credentials of a user with the Compute.Compute_Operations and Storage.Storage_Administrator identity domain roles along with the service ID and Authorization URL of OCI Object Storage Classic.

The Compute.Compute_Operations role enables you to create, update, and delete VMs on OCI Compute Classic. The Storage.Storage_Administrator role enables you to store artifacts on OCI Object Storage Classic.

Before you create the OCI Compute Classic connection, you must check the Compute_Operations Role: Terms of Use and get the Service ID and the authorization URL of OCI Object Storage Classic:

Get OCI Object Storage Classic Input Values

1. Open the Oracle Cloud Dashboard.
2. In the Storage Classic tile, click Action, and select View Details.

   If the Storage Classic tile isn’t visible, click Customize Dashboard. Under Infrastructure, find Storage Classic, click Show, and then close the Customize Dashboard window.

3. On the Service Details page, in the Additional Information section of the Overview tab, note the values of the Auth V1 Endpoint URL and the last part of the REST Endpoint URL.

   If you’re using an Oracle Cloud traditional account, the fields shown in this graphic might differ from the fields on your Service Details page.

   
   Description of the illustration storage_cloud_console.png

Create an OCI Classic Connection from DevCS

After you have the required values, create an OCI Classic connection from DevCS.

You must be the Organization Administrator to create the connection.

1. Sign in to DevCS.
2. In the navigation bar, click Organization .
3. Click the OCI Account tab.
4. To create a connection, click Connect. To edit the connection details, click Edit.
5. In Account Type, select OCI Classic.
6. In the OCI Object Storage Classic section, fill in the required details.
   1. In Service ID, enter the value copied from the last part of the REST Endpoint URL field of the Service Details page.
      For example, if the value of REST Endpoint URL is https://demo12345678.storage.oraclecloud.com/v1/Storage-demo12345678, then enter Storage-demo12345678.
   2. In Username and Password, enter the credentials of the user assigned the Storage.Storage_Administrator identity domain role.
   3. In Authorization URL, enter the URL copied from the Auth V1 Endpoint field of the Service Details page.
      Example: http://storagetria01234-usoracletria12345.storage.oraclecloud.com/auth/v1.0.
   4. Click Validate.
7. In the OCI Compute Classic section, fill in the required details.
   1. In Username and Password, enter the username and password of the user who’s assigned the Compute.Compute_Operations identity domain role.
   2. To agree to terms and conditions, select the terms and conditions check box.
   3. Click Validate.
8. Click Save.

Compute_Operations Role: Terms of Use

Here are some special legal terms and guidance that apply to the usage of the Compute_Operations role for DevCS.

In addition to these DevCS terms, you should follow security best practices in maintaining the security of the username and password.

• You must create a dedicated username and password for use by DevCS. When creating a username, avoid including personal names or personal information (like birthdays). Your password should always be complex and impossible to guess.

• You understand that a user with the Compute_Operations role can view, create, update and delete OCI Compute Classic resources such as VM instances, storage volumes, security rules, and security IP lists. Your failure to maintain security best practices to secure the username and password of the user with the Compute_Operations role may create a high risk for you and your organization.

• You should assign the Compute_Operations role privileges only to the username created for DevCS.

• Notwithstanding DevCS terms, you acknowledge that Oracle isn’t responsible or liable for any action you take in accessing or creating access to the DevCS or OCI Compute Classic.

Add Users to the Identity Domain

To add users to your organization and projects, make sure they are added to your identity domain and assigned appropriate identity domain roles. An organization is the top-most entity in the project structure of DevCS. All users of the identity domain are available in your organization and then can be added to projects.

To add a user to the identity domain, invite the user to join Oracle Cloud. See Add Users and Assign Roles in Getting Started with Oracle Cloud. You must be assigned the Identity Domain Administrator (TenantAdminGroup) role to send an invite and assign the identity domain roles.