Oracle Cloud Infrastructure Documentation

Getting Started with DevOps

Learn how to get started with the DevOps service, and the prerequisites for using it.

Prerequisites

Before you begin using the DevOps service, you must meet the following prerequisites:

  • You must have access to an Oracle Cloud Infrastructure tenancy.
  • Each service in Oracle Cloud Infrastructure (OCI) integrates with Identity and Access Management (IAM) for authentication and authorization, for all interfaces (the Console, SDK and CLI, and REST API). Access permissions are provided to users within a particular compartment. You can create a compartment or reuse an existing one. See Managing Compartments.
  • An administrator in your organization needs to set up groups, compartments , and policies  that control which users can access which services, and which resources, and the type of access they have. See Authentication and Authorization.

Setting up Groups and Users

  1. Create a group or use an existing group in your tenancy.

    Users of this group are allowed to manage the DevOps service.

  2. Create users and add them to the group, or add existing users to the group.
  3. Generate an auth token for each user using Git to interact with your code repositories. You can also use API signing keys.

    Auth tokens are a form of user credentials. They are Oracle-generated token strings, which you can use to authenticate with third-party APIs that do not support OCI's signature-based authentication. The auth token is used for authenticating to OCI on the command line when performing Git operations. Administrators can create and distribute auth tokens to other users. Auth tokens do not expire. Each user can have up to two auth tokens at a time. For more information, see Managing User Credentials.

Setting up Access for DevOps Resources

To grant users permission to access the various DevOps resources such as build pipelines, deployment pipelines, artifacts, and code repositories you have to create dynamic groups and IAM policies. See Managing Dynamic Groups and Getting Started with Policies.

For creating dynamic groups and policies, refer the following examples:

For more details, see DevOps IAM Policies.

Integrating with External Code Repositories

With the OCI DevOps service you can create a connection to external repositories such as GitHub, GitLab, Bitbucket Cloud, Bitbucket Server, GitLab Server, and Visual Builder Studio. Following are the ways to integrate:

  • GitHub, GitLab, GitLab Server, and Visual Builder Studio: You have to retrieve a personal access token (PAT) from those providers and store your PAT securely in an OCI vault. For instructions, see Build Source Integration.
  • Bitbucket Cloud: You need your Bitbucket username and create an app password, then store the app password in an OCI vault. See Generating an App Password for Bitbucket Cloud.
  • Bitbucket Server: You must create HTTP access token and then store the access token in an OCI vault.
Note

This process is required only for integrating with third-party code repositories and not with the OCI DevOps code repository.

Setting up Notifications and Topics

Project notifications keep you apprised of important events and the latest DevOps project status. They also alert you if you need to take any necessary action such as approving a workflow. You must create a topic  and add subscription  to the topic. For creating a topic, see Creating a Topic. The topic is required when creating your DevOps project.

Setting up Repository

The DevOps service uses an OCI Container Registry repository or an Artifact Registry repository for containing the completed build artifacts. You can create either of these repositories.

Creating an Auth Token

Auth tokens are a form of user credentials. They are Oracle-generated token strings, which you can use to authenticate with third-party APIs that do not support Oracle Cloud Infrastructure's signature-based authentication. Auth token is required for using Git to interact with your code repositories.

Learn how to create an auth token by using the Oracle Cloud Console.

  1. If you're creating an auth token for yourself:
    • Sign in to the Console.
    • In the top-right corner of the Console, open the Profile menu and click User Settings.
  2. If you're an administrator creating an auth token for another user:
    • Open the navigation menu and click Identity & Security.
    • Under Identity, click Users.
    • Locate the user in the list, and then click the user's name to view their details.
  3. Under Resources, click Auth Tokens.
  4. Click Generate Token.
  5. Enter a description that indicates what this token is for, for example, Anne's auth token for use with DevOps code repository. Avoid entering confidential information.

  6. Click Generate Token.

    The new token string is displayed. For example, Dm___________6MqX.

  7. Copy the auth token immediately to a secure location from which you can retrieve it later, because you won't see the auth token again in the Console.
  8. Close the Generate Token dialog box.

For more information, see Working with Auth Tokens.

Build Source Integration

Learn how to integrate your OCI code repositories with third-party code repositories like GitHub, GitLab, and Visual Builder Studio.

  1. Retrieve a personal access token (PAT) from the hosting service of the third-party code repository as follows:
  2. Store the retrieved PAT securely in an OCI vault.
    You can reuse existing vaults in your tenancy, or create a vault, master encryption key, and secret. For instructions, see Storing PAT in Vault.
    Note

    Each tenancy has a limit of 10 vaults and each vault can store multiple secrets.

    Vault variables cannot be dynamically replaced. Only Oracle Cloud IDs (OCIDs) of the vault secret is supported.

  3. Create a vault secret policy in the root compartment to allow the dynamic group to manage secrets. See Overview of Vault and Managing Secrets. For example: 
    Allow dynamic-group <dynamic_group_name> to manage secret-family in tenancy
    Note

    This process is required only for integrating with third-party code repositories and not with the OCI DevOps code repository.

Generating a GitHub PAT

  1. In the GitHub home page, click the profile picture in the upper right corner and then click Settings.
  2. In the left-side menu, click Developer settings.
  3. In the left-side menu, click Personal access tokens and then click Tokens (classic).
  4. Click Generate a personal access token link.
  5. Note the reason for generating the token.
  6. Select expiration period for the token from the given options.
  7. For scopes, to enable the DevOps service to read code from the private repositories, select Full control of private repositories.

    To access code from only public repositories, select public_repo scope.

  8. Click Generate token.

    Copy the token immediately to a secure location, because you can't retrieve the token again after you navigate away from the page.

Generating a GitLab PAT

  1. In the GitLab home page, click the profile picture in the upper right corner and then click Edit profile.
  2. In the left-side menu, click Access Tokens.
  3. Enter a name and optional expiry date for the token.
  4. For scopes, select read_api.
  5. Click Create personal access token.

    Copy the token immediately to a secure location, because you can't retrieve the token again after you navigate away from the page.

Generating an App Password for Bitbucket Cloud

Learn how to integrate with Bitbucket Cloud and establish the connection to use Bitbucket repositories in the build pipeline.

  1. In your Bitbucket home page, click your profile in the top-right corner and then click Personal settings.
  2. In the Bitbucket profile settings, note your username.
  3. In the left-side menu, click App passwords and then click Create app password.
  4. Enter a Label (name) for the password.
  5. Select the following check boxes for Permissions:
    • Account: Read
    • Workspace membership: Read
    • Projects: Read
    • Pull requests: Read
    • Webhooks: Read and write
  6. Click Create.

    Copy the app password immediately to a secure location, because you cannot retrieve it again after you navigate away from the page.

You must store the app password in an Oracle Cloud Infrastructure (OCI) vault. OCI Vault is a managed service that lets you centrally manage the encryption keys that protect your data and the secret credentials that you use to securely access resources.

You can reuse existing vaults in your tenancy, or create a vault, master encryption key, and secret.
Note

Each tenancy has a limit of 10 vaults and each vault can store multiple secrets.

Storing PAT in Vault

Before you begin, retrieve a personal access token (PAT) from the hosting service of the third-party code repository.

  1. Open the navigation menu in Oracle Cloud Console, click Identity & Security, and then click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to create the vault.
  3. Click Create Vault and enter a display name for the vault.
  4. When you're finished, click Create Vault.
  5. To create the master encryption key that is used to encrypt the PAT, click the name of the vault you created in step 4.
  6. Click Master Encryption Keys, and then click Create Key.
    You can import the key materials and key versions that you already have to the vault you created in step 4. The key must be a symmetric key as you can't encrypt vault secrets with asymmetric keys. For more information, see Managing Keys.
  7. To create a secret that is used to store the PAT, click the name of the vault you created in step 4.
  8. Enter a name for the secret.
  9. Choose the master encryption key that you created in step 5 to encrypt the secret contents.
  10. Specify the format of the secret contents that you're providing by choosing a template type from the Secret Type Template list.
    You can provide secret contents in plain-text when you use the Console to create a vault secret or vault secret version, but secret contents do need to be base64-encoded before they're sent to the service. The Console automatically encodes plain-text secret contents for you. For more information, see Managing Secrets.
  11. Click Secret Contents, and then enter the PAT contents.
  12. When you're finished, click Create Secret.
The PAT is securely stored in the OCI vault.

Using the DevOps Service

After you complete the prerequisites, perform the following steps to use the DevOps service for continuous integration, delivery, and deployment of your software to OCI compute platforms:

  1. Create a DevOps project for grouping the resources needed to implement your continuous integration and deployment (CI/CD) application.
  2. Create an OCI code repository or integrate with external code repositories such as GitHub, GitLab, and Bitbucket Cloud. See Mirroring a Repository.
  3. Create a build pipeline that contains the stages that define the build process for successfully compiling, testing, and running software applications before deployment.
  4. Add a Managed Build stage to your build pipeline to test your software application.

    Select either OCI code repository or an external code repository (GitHub, GitLab, Bitbucket Cloud, Bitbucket Server, and GitLab Server) as the primary code repository for the build.

  5. To store the Managed Build stage output, you need an OCI Container Registry repository or an Artifact Registry repository.

    DevOps supports applications stored in OCI Container Registry and Artifact Registry repositories. In Container Registry repository, Docker images and Helm charts are stored and in Artifact Registry repository, you can store generic software packages.

  6. Create a DevOps artifact to point to the repository location containing the build output.

    A parameter in the artifact URI defines the software application version that is delivered to the OCI code repository.

  7. Add a Deliver Artifacts stage to your build pipeline after adding the Managed Build stage.

    The Deliver Artifacts stage maps the build outputs from the Managed Build stage with the version to deliver to a DevOps artifact resource, and then to the OCI code repository.

  8. Start the build process by manually running a DevOps build pipeline.

    Manual run uses the latest commit to the code repository that was added to the build. You can run the build based on specific commit by noting the commit details.

    You can also automatically trigger a build run when you commit your changes to the code repository.

  9. Create a target environment supported by DevOps, if it doesn't exist in the Oracle Cloud Console. Supported environments are Kubernetes Engine clusters, compute instances (Oracle Linux and CentOS only), and Function applications.
  10. Create reference to the target environment for deployment.
  11. Create a deployment pipeline to deliver the build output to the target environment.

    DevOps supports deployment to Kubernetes clusters, instance groups, and Functions.

  12. Add a Trigger Deployment stage to automatically trigger a deployment from the build pipeline or run the deployment pipeline.